WebLogic Server

Both OC4J and WebLogic have a provider specific descriptor that, in conjunction with the standard ejb-jar.xml descriptor, integrates MDBs with the container and provides inbound configuration that identifies the source destination and related information.  This source destination may share the same instance as the MDB, be from a different instance, or even a different JMS provider.    This discussion will focus on the configuration approaches of OC4J and WebLogic and offer what needs to be considered when migrating an existing MDB deployed to OC4J to a WebLogic server.

OC4J and WebLogic MDB Configuration Approaches

MDB Migration Considerations

Resource References

XA Support

<ejb-jar>
 <enterprise-beans>
 <message-driven>
 <transaction-type>Container</transaction-type>

 <assembly-descriptor>
 <container-transaction>
 <method>
 <ejb-name>...</ejb-name>
 <method-name>onMessage()</method-name>
 </method>
 <trans-attribute>Required</trans-attribute>

Translating OC4J JMS MDB ActivationSpec Properties

When the Destination is Remote

For more information regarding WebLogic and MDB Integration

• JMS Information Roadmap
  
• Design Message-Driven BeansTuning Message-Driven Beans
• weblogic-ejb-jar.xml Deployment Descriptor Reference
• Information describing WebLogic JMS features such as redelivery delay, delivery limits, etc can be found in Managing Your Applications.
• Integrating Remote JMS Providers FAQ
  

Summary

Upgrading an OC4J Java EE application in order to deploy to Weblogic server may require one of several upgrade paths, depending upon the component being upgraded.  Remote clients that rely on the Application Client Container will require deployment changes in order to access resources on Weblogic Server.  One use case for remote clients will require some extra steps in order to upgrade successfully.  That case is the subject of this blog posting. 

OC4J's JNDI implementation allows a standalone client to take advantage of some features of the application client in Java EE without running in a Java EE Application Client Container.  A client can use the

"oracle.j2ee.naming.ApplicationClientInitialContextFactory"

InitialContextFactory implementation in order to access this functionality.  As long as the client includes a "META-INF/application-client.xml" deployment descriptor in the client jar, this initial context factory will create a JNDI context that can support Java EE resources that are typically used in an application client (EJB references, Resource References, Environment entries, etc).  This context factory will use the application-client.xml and the proprietary orion-application-client.xml in order to map JNDI bindings to logical Java EE reference names.  This level of application client support does not include Java EE 1.5-style annotations/dependency injection. 

Please refer to the following for more information on OC4J's Application Client support:

Looking Up Objects from J2EE Application Clients

While not required by the Java EE specification, this type of remote client can be very useful when a customer wishes to use the Java EE standard resource mapping types in order to use logical names for resources such as EJBs, Datasources, and JMS destinations.  Using an application client deployment descriptor has the advantage of allowing resources to change without having to change the client code itself, and can be considered useful even if not running in the Application Client Container. 

Customers using this feature of the ApplicationClientInitialContextFactory in OC4J will need to port their application client to run in the Weblogic Server Application Client Container. 

Upgrade Steps

The steps required to upgrade an OC4J application client to run in the Weblogic Application Client Container are as follows:

1. Add a "Main-Class" entry to the client jar's manifest.  This entry should specify the entry point class for the application client.  This class, according to the Java EE standard, must include a "public static void main(String[] args)" method, and also include a no-arguments constructor. 

An example of the proper manifest entry would look as follows:

            Manifest-Version: 1.0

     Ant-Version: Apache Ant 1.6.5

     Created-By: 1.5.0_06-b05 (Sun Microsystems Inc.)

     Main-Class: oracle.ejb30.HelloWorldClient

2. Modify the jndi.properties file in this client (or the source code that sets the JNDI properties directly) to refer to the Oracle WebLogic Server JNDI Provider.

An example of the jndi.properties file would look as follows:

            java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory

java.naming.provider.url=t3://localhost:7001

The jndi.properties file may also require a username/password.  These JNDI properties should be modified to use the principal and credentials created on the Weblogic Server. 

3. For every element in orion-application-client.xml, create a corresponding element in weblogic-application-client.xml to map any Java EE references to the resources bound in Oracle WebLogic Server.

4. Modify the classpath of the client to include the Oracle WebLogic Server client jars.  The jars required for the classpath are determined by the protocol that the customer wishes to use for this client. 

Please refer to the following Weblogic Server documentation to determine the appropriate client jar to use:

Client Types and Features

5. Modify any application client startup scripts to use the Oracle WebLogic Server application client launcher.

The following is an example of a typical command line for launching a Weblogic Application Client:

java weblogic.demo.DemoClient myclient.jar t3://localhost:7001

The following links will be helpful when attempting to upgrade an application client from OC4J to Weblogic Server:

"WLS - Programming Standalone Clients"

Programming Stand-alone Clients

"Oracle Fusion Middleware Upgrade"

Oracle Fusion Middleware Upgrade

Our goal is to implement a simple WebLogic JMX client that can be used as a starting point to write any WebLogic JMX client. We will look at the client's code. The classpath used to compile and run the code. The different WebLogic MBeanServers and associated JMX URI's the JMX Client can connect to.

Let's directly dive in the client's code below:

package blog.wls.jmx.client;

import javax.management.MBeanServerConnection;
import javax.management.ObjectName;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXServiceURL;
import javax.management.remote.JMXConnectorFactory;
import java.util.Hashtable;
import java.util.Set;

public class JMXClient {

public static void main(String[] args) throws Exception {

        JMXConnector jmxCon = null;
 
        try {
            JMXServiceURL serviceUrl = 
                new JMXServiceURL(
         "service:jmx:iiop://127.0.0.1:7001/jndi/weblogic.management.mbeanservers.runtime");

            System.out.println("Connecting to: " + serviceUrl);
 
            Hashtable env = new Hashtable();
            env.put(JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES, 
                         "weblogic.management.remote");
            env.put(javax.naming.Context.SECURITY_PRINCIPAL, "weblogic");
            env.put(javax.naming.Context.SECURITY_CREDENTIALS, "welcome1");

            jmxCon = JMXConnectorFactory.newJMXConnector(serviceUrl, env);
            jmxCon.connect();
            MBeanServerConnection con = jmxCon.getMBeanServerConnection();
 
            Set<ObjectName> mbeans = con.queryNames(null, null);
            for (ObjectName mbeanName : mbeans) {
                System.out.println(mbeanName);
            }
        }
        finally {
            if (jmxCon != null)
                jmxCon.close();
        }
    }
}

Let's take a quick look at the above code.

JMXServiceURL serviceUrl = 
                new JMXServiceURL(
      "service:jmx:iiop://127.0.0.1:7001/jndi/weblogic.management.mbeanservers.runtime");

The JMX service URI identifies the following:

• The protocol used to communicate with the remote WebLogic process. "iiop" in the above example. WebLogic supports "t3", "iiop" and "rmi". We won't touch further on this topic here.

• The WebLogic process to connect to (host & port ). "127.0.0.1:7001" in the above example.

  The port value is available from the <WLS_INSTANCE_HOME>/config/config.xml file:

   <server>
      <name>myServer</name>
      <listen-port>7001</listen-port>
      <listen-address>myhost</listen-address>
    </server>
  

  Make sure you look under the correct server if several servers are defined as part of your config.xml. For instance in the above case we are connecting to the server identified as "myServer".

  The same information is also available from the server log at <WLS_INSTANCE_HOME>/servers/myServer/logs/myServer.log:

  <Sep 22, 2009 12:05:23 PM PDT> <Notice> <Server> <localhost><myServer>
  <[ACTIVE] ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'> 
  <<WLS Kernel>> <> <> <1253585123268> <BEA-002613> <Channel "Default" is now
  listening on myhost:7001 for protocols iiop, t3, ldap, snmp, http.> 
  

• The MBeanServer to connect to: " weblogic.management.mbeanservers.runtime". This identifies WebLogic's "Runtime" MBeanServer. This is the MBeanServer available from any WebLogic process, and that contains both WebLogic and user MBeans.

            Hashtable env = new Hashtable();
            env.put(JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES,
                    "weblogic.management.remote");
            env.put(javax.naming.Context.SECURITY_PRINCIPAL, "weblogic");
            env.put(javax.naming.Context.SECURITY_CREDENTIALS, "welcome1");

The above code specifies properties associated with the connection. "weblogic.management.remote" identifies the package implementing WebLogic's client side connector code. For instance the 't3' or 'iiop' client connector.

"weblogic" and "welcome1" are the login/password associated with the user originating the JMX connection.

In the rest of the code we establish the JMX connection, and then retrieve the ObjectNames for all the MBeans registered in the "Runtime" MBeanServer. The ObjectNames are then displayed on the console. We also make sure we release the connection in a finally block to avoid leaking any resource.

The code doesn't contain any WebLogic specific classes, and can be compiled as follow:

javac -d . blog/wls/jmx/client/JMXClient.java

Executing the code requires to add WebLogic client side classes to the execution ClassPath. We need to include the WebLogic JMX connector client side classes. Remember we specified those in the environment properties passed to the JMXConnectorFactory. Below is the command I used:

java -classpath .:$WL_HOME/server/lib/wljmxclient.jar blog/wls/jmx/client/JMXClient

WL_HOME points to the WebLogic binary install.

The above uses WebLogic's thin client classes. In some cases when you access server side classes, or you want to take full advantage of the t3 protocol, you are required to use WebLogic's thick client classes. To do so, you first need to build wlfullclient.jar as follow:

cd $WL_HOME/server/lib
java -jar wljarbuilder.jar

You can then execute the JMX Client as follow:

java -classpath .:$WL_HOME/server/lib/wlfullclient.jar  blog/wls/jmx/client/JMXClient

You can also bundle wlfulclient.jar with your client code. When using the thin client you cannot just bundle wljmxclient.jar with you client code, as this jar references other jars as part of its manifest Class-Path entry. At the time of this writing, you also need to bundle wlclient.jar

At this point we are now able to connect to WebLogic's "Runtime" MBeanServer. Each WebLogic process contains a "Runtime" MBeanServer in which local WebLogic MBeans and user-defined application MBeans are registered. WebLogic also offers two other MBeanServers that are only available from the Domain "AdminServer" process:

• The "Domain Runtime" MBeanServer. It aggregates the MBeans registered on the domain's "Runtime" MBeanServers. So as long as a managed server is up, its MBeans can be accessed through the "Domain Runtime" MBeanServer. To connect to that MBeanServer, just use the following JMX URI:

  service:jmx:iiop://127.0.0.1:7002/jndi/
  weblogic.management.mbeanservers.domainruntime
  

  "7002" is the iiop port for my "AdminServer" install. Replace with your AdminServer's port as previously explained. Remember; only the AdminServer process runs the "Domain Runtime" MBeanServer.

• The "Edit" MBeanServer. It contains the WebLogic Config MBeans that are used to configure the Domain. To connect to that MBeanServer, just use the following JMX URI:

  service:jmx:iiop://127.0.0.1:7002/jndi/weblogic.management.mbeanservers.edit 
  

  "7002" is the iiop port for my "AdminServer" install. Replace with your AdminServer's port as previously explained. Remember; only the AdminServer process runs the "Domain Runtime" MBeanServer.

Note: One can also use "t3" or "rmi" as protocol in place of "iiop"

The rest of the client's code remains unchanged. Only the JMX URI needs to be changed to connect to different MBeanServers.