3 Developing a WebLogic Thin T3 Client

This chapter describes how to develop and use WebLogic thin t3 clients.

Understanding the WebLogic Thin T3 Client

The WebLogic Thin T3 Client jar (wlthint3client.jar) is a light-weight, high performing alternative to the wlfullclient.jar and wlclient.jar (IIOP) remote client jars. The Thin T3 client has a minimal footprint while providing access to a rich set of APIs that are appropriate for client usage. As its name implies, the Thin T3 Client uses the WebLogic T3 protocol, which provides significant performance improvements over the wlclient.jar, which uses the IIOP protocol.

The Thin T3 Client is the recommended option for most remote client use cases. There are some limitations in the Thin t3 client as outlined below. For those few use cases, you may need to use the full client or the IIOP thin client.

The Thin T3 client can be used in stand-alone applications, and is also designed for applications running on foreign (non-WebLogic) servers. One common use case is integration with WebLogic JMS destinations.

Features

This release supports the following:

  • Oracle WebLogic's T3/T3S protocol for Remote Method Invocation (RMI), including RMI over HTTP (HTTP tunneling). For more information on WebLogic T3 communication, see "Using WebLogic RMI with T3 Protocol" in Programming RMI for Oracle WebLogic Server.

  • Access to JMS, JMX, JNDI, and EJB resources available in WebLogic Server.

  • Transaction initiation and termination (rollback or commit) using JTA.

  • WebLogic client JMS features, including Unit-of-Order, Unit-of-Work, message compression, XML messages, JMS automatic client reconnect, and Destination Availability Helper APIs.

  • Client-side clustering allowing a client application to participate in failover and load balancing of a WebLogic Server instance. See "Clustered RMI Applications" in Programming RMI for Oracle WebLogic Server.

  • JAAS authentication and JSSE SSL. See Security.

Limitations

This release does not support the following:

  • RMI over HTTPS (HTTP Tunneling over SSL).

  • JMS SAF clients, Mbean-based utilities (such as JMS Helper, JMS Module Helper), and JMS multicast are not supported. You can use JMX calls as an alternative to "mbean-based helpers."

  • JDBC resources, including WebLogic JDBC extensions.

  • Running a WebLogic RMI server in the client.

  • Network class loading.

Interoperability

This release of the WebLogic Thin T3 client has the following interoperability support:

Prior WebLogic Server Releases

For information on WebLogic Thin T3 client support for communicating with previous WebLogic releases, see "Protocol Compatibility" in Understanding Oracle WebLogic Server.

Foreign Application Servers

The WebLogic Thin T3 client jar is supported on the following application servers:

  • GlassFish: version 3.1 and higher

  • Oracle OC4J: version 10g and higher

  • IBM WebSphere Application Server: Version 6.x and 7.x

  • Red Hat JBoss Application Server: Version 5.x and 6.x

Security

For general information on client security see:

Connection Considerations

The WebLogic Thin T3 client uses JDK classes to connect to the host. If your host has multiple addresses (Dual-Stack) available, your client may connect to the wrong IP addresss if the host is not configured properly.

Developing a Basic WebLogic Thin T3 Client

Use the following steps to create a basic WebLogic Thin T3 client:

  1. Obtain a reference to the remote object.

    1. Get the initial context of the server that hosts the service using a T3 URL in the form of t3://ip address:port or t3s://ip address:port.

    2. Obtain an instance of the service object by performing a lookup using the initial context. This instance can then be used just like a local object reference.

  2. Call the remote objects methods.

  3. Place the wlthint3client.jar in your client classpath. It is located in the WL_HOME\server\lib directory of your WebLogic Server installation.

    Note:

    Oracle does not support combining clients to create extended feature sets. Never add the wlfullclient.jar, wlthint3client.jar, or wlclient.jar to a WebLogic Server classpath or a classpath that references the weblogic.jar file in a full WebLogic install. The behavior is undefined. WebLogic Server applications already have full access to WebLogic client functionality.

Sample code to for a basic WebLogic Thin T3 client is provided in Example 3-1.

Example 3-1 Creating and Using a WebLogic Initial Context

Hashtable env = new Hashtable();
env.put("java.naming.factory.initial",
  "weblogic.jndi.WLInitialContextFactory");
env.put("java.naming.provider.url","t3://host:7001");
env.put("java.naming.security.principal","user");
env.put("java.naming.security.credentials","password");
Context ctx = new InitialContext(env);
try {
  Object homeObject =
    context.lookup("EmployeeBean");
//use the EmployeeBean
}
catch (NamingException e) {
// a failure occurred
}
finally {
  try {ctx.close();}
  catch (Exception e) {
// a failure occurred
}
}

Foreign Server Applications

A foreign server hosted application can use the wlthint3client.jar to act as a remote client to a WebLogic Server instance. To provide access to remote services such as JMS, servlets, EJBs, and start-up classes, deploy any necessary application code along with the wlthint3client.jar to your application server.

The following steps provide a guideline to connect to and access WebLogic Server resources from a foreign application server using JNDI:

  1. Include the wlthint3client.jar on the classpath of your client.

  2. In your client application, create a WebLogic initial context and use the context to lookup and use a resource. See Example 3-1, "Creating and Using a WebLogic Initial Context" for more details.

  3. It may be necessary to explicitly set the initial context factory as system property in the client code to the following value:

    env.put("java.naming.factory.initial", "weblogic.jndi.WLInitialContextFactory");

  4. Deploy any necessary application code along with the wlthint3client.jar file to your application server using standard Java EE methods, such as embedding the wlthint3client.jar file in a servlet or using a shared library. See Deployment Considerations.

  5. Start or deploy the client.

The following sections outline specific items to consider when interoperating with a foreign servers.

Deployment Considerations

You can deploy the wlthint3client.jar using standard Java EE methods. However, when determining what deployment method to use, you must account for client footprint, class loading, performance, and tolerance of the risk for code incompatibility. For example:

  • If you embed the wlthint3client.jar in your application, such as a servlet, the application footprint is increased by the size of the wlthint3client.jar but the risk of code incompatibility is limited to the scope of your application.

  • If you deploy the wlthint3client.jar to your lib directory, the application footprint is not affected but the risk of code incompatibility can include the entire foreign server container.

Interoperating with OC4J

Add the wlthint3client.jar file to the classpath of applications running within OC4J that require WebLogic Server resources. See "Installing and Publishing a Shared Library in OC4J" at http://download.oracle.com/docs/cd/E14101_01/doc.1013/e13979/classload.htm#CIHDGJGD.

The following section outlines important considerations when interoperating with the Oracle OC4J application server as a remote client to WebLogic Server resources.

  • Transaction propagation—Propagating transaction context objects between servers is not supported.

  • Security Context propagation—Propagating security/identity information between servers is not supported.

For more information on OC4J, see "Introduction to Oracle WebLogic Server for OC4J Users" in Upgrade Guide for Java EE.

Accessing WebLogic Server Resources

The following section demonstrates how connect to and access WebLogic Server resources from OC4J using JNDI:

  1. In your client application, create a WebLogic initial context and use the context to lookup and use a resource. See Example 3-1, "Creating and Using a WebLogic Initial Context" for more details.

  2. Set the OC4J URL context factory property. See "Enabling the Server-Side URL Context Factory" or "Enabling the Remote Client URL Context Factory" at http://download.oracle.com/docs/cd/E14101_01/doc.1013/e13975/jndi.htm.

  3. Include the wlthint3client.jar on the classpath of your client.

  4. Add the JAR file as an OC4J shared library. See "Creating and Managing Shared Libraries" in http://download.oracle.com/docs/cd/E14101_01/doc.1013/e13980/ascontrol.htm#BABFDHGB.

  5. Start or deploy the client.

JMS Interoperability with WLS

When using ContextScanningResourceProvider resource provider to access WebLogic server JMS destinations users require to use the resource.names property to explicitly set a comma-separated list of JNDI names for the JMS resources that are required from the external server. For more information on using the ContextScanningResourceProvider resource provider to access third-party JMS destinations, see "Using Oracle Enterprise Messaging Service" in http://download.oracle.com/docs/cd/E14101_01/doc.1013/e13975/jms.htm.

Note:

The syntax of resource.names does not support space between the comma and the next JNDI name of the comma-separated list of JNDI names.

The following example demonstrates setting the resource.names property in the orion-application.xml file. The resource.names property is set to TopicOne,QueueOne,TopicTwo. This value represents a list of JNDI names for JMS destinations that the ContextScanningResourceProvider resource provider attempts to lookup from the external WebLogic server.

Example 3-2 Setting the resource.names Property

<resource-provider class="com.evermind.server.deployment.ContextScanningResourceProvider" name="WebLogicRP">
<property name="java.naming.factory.initial"    value="weblogic.jndi.WLInitialContextFactory"/>
<property name="java.naming.provider.url" value="t3://localhost:7001/"/>
<property name="java.naming.security.principal" value="user_name"/>
<property name="java.naming.security.credentials" value="user_password"/>
...
<!-- configure the set of known JMS destinations that are required for this application -->
<property name="resource.names" value="TopicOne,QueueOne,TopicTwo"/>
...
</resource-provider>