RMI Access to the WebLogic JAM Gateway

A Remote Method Interface (RMI) configuration subsystem allows you to monitor and control the WebLogic JAM Gateway by a remote Java application. WebLogic JAM provides such administrative capabilities through the com.bea.jam.Admin utility. Using the features in the RMI subsystem, referred to as the JAM Deployed Configuration feature, you can develop your own custom administrative capabilities.

This section discusses the following topics:

JAM Deployed Configuration Feature

The JAM Deployed Configuration feature is comprised of several of RMI-based interfaces which are advertised in the JNDI tree of a WebLogic Server hosting the WebLogic JAM Gateway. These objects are constructed, at server boot time, based on the WebLogic JAM configuration information specified in the Administration Server of the WebLogic JAM domain. Information about the CRM, Links, and Services is maintained in the jamconfig.xml file. Update this file using the WebLogic Administration Console.

The following objects are provided for remote gateway access:

These remote objects are arranged in a hierarchy within the WebLogic Server node as follows:

The GatewayBootstrap object is bound into the JNDI tree of each WebLogic Server hosting a WebLogic JAM Gateway. There is a single GatewayBootstrap object per WebLogic Server ("pinned" object) and its JNDI name, com.bea.jam.bootstrap, is the same on all server instances. This JNDI name is available via the named constant GatewayBootstrap.JNDI_NAME to eliminate literal hardcoding.

The following code listing demonstrates obtaining the GatewayBootstrap object from a WebLogic Server accessible via the URL t3://dynamo1:7001:

Listing D-1 Obtaining the GatewayBootstrap Object

Properties prop = new Properties();
prop.setProperty(Context.INITIAL_CONTEXT_FACTORY,
	     weblogic.jndi.WLInitialContextFactory.class.getName());
prop.setProperty(Context.PROVIDER_URL, "t3://dynamo1:7001");
prop.setProperty(Context.SECURITY_PRINCIPAL, "UserId");
prop.setProperty(Context.SECURITY_CREDENTIALS, "Password");

Context ctx = new InitialContext(prop);
GatewayBootstrap gwBoot;
gwBoot = (GatewayBootstrap) ctx.lookup(GatewayBootstrap.JNDI_NAME);

This example obtains a JNDI Initial Context to the server in question and then looks up the GatewayBootstrap object using the predefined constant object name.

Following are the methods offered by the GatewayBootstrap object:

com.bea.jam.cluster.GatewayBootstrap

Implements java.rmi.Remote

JAM Gateway bootstrap class is used to allow the creation and/or retrieval of Gateways on WebLogic Server nodes. This object is a singleton per WebLogic Server node and is registered in the JNDI tree as a local (i.e. REPLICATE_BINDINGS=false) object. It is created by the WebLogic JAM server startup task and remains available for the life of the server.

Methods

The following methods are available with the com.bea.jam.cluster.GatewayBootstrap object to retrieve Gateway information:

Fields

DeployedGateway Object

The DeployedGateway object is bound into the WebLogic JNDI tree using a name that is constructed of a literal prefix, DeployedGateway.JNDI_PREFIX, and suffixed by the name of the WebLogic JAM Gateway represented by the object. For example, the JNDI name of a WebLogic JAM Gateway named MyJAM would be:

DeployedGateway.JNDI_PREFIX+"MyJAM".

The DeployedGateway object for a WebLogic JAM Gateway may be obtained either from a GatewayBootstrap object or directly via a JNDI lookup.

The following code listing demonstrate three different ways of obtaining a DeployedGateway object named JAM1 from WebLogic Server t3://dynamo1:7001.

Following are the methods offered by the DeployedGateway object:

com.bea.jam.cluster.DeployedGateway

Implements java.rmi.Remote

This is the remote interface for the deployed gateway object. One DeployedGateway object exists for each configured WebLogic JAM Gateway. The DeployedGateway is placed in the JNDI tree under the name com.bea.jam.gateway. GatewayName where GatewayName is the configured name of the Gateway.

Methods

The following methods are available with the com.bea.jam.cluster.DeployedGateway object to retrieve Gateway information:

Fields

public static final JNDI_PREFIX

JNDI prefix used by all DeployedGateway objects.

DeployedCRM Object

The DeployedCRM object is obtained via the DeployedGateway.getCRM() method. This object is a read-only wrapper providing the information used to configure the CRM being used by this WebLogic JAM Gateway.

com.bea.jam.cluster.DeployedCRM

Implements java.io.Serializable

Methods

The following methods are available with the com.bea.jam.cluster.DeployedCRM object.

DeployedLink Object

The DeployedLink object is obtained via the DeployedGateway.getLink() or DeployedGateway.getLinks() methods. It is a read-only wrapper providing information about a particular CRM mainframe link. Following are the methods offered by this object:

com.bea.jam.cluster.DeployedLink

Implements java.io.Serializable

This is the interface for the deployed link object. DeployedLink objects are created by their parent Gateways and are used to the services offered on each Gateway link.

Methods

The following methods are available with the com.bea.jam.cluster.DeployedLink object.

DeployedService Object

The DeployedService object represents a WebLogic JAM outbound service currently being offered by a CRM mainframe region link. The DeployedService object may be obtained via the DeployedGateway.getService() method. It may also be obtained directly via a JNDI lookup using a literal prefix and the name of the service as a key. The following code listing demonstrates obtaining the DeployedService object for an outbound service named NewEmployee.

Properties prop = new Properties();
prop.setProperty(Context.INITIAL_CONTEXT_FACTORY,
    weblogic.jndi.WLInitialContextFactory.class.getName());
prop.setProperty(Context.PROVIDER_URL, "t3://dynamo1:7001");
prop.setProperty(Context.SECURITY_PRINCIPAL, "UserId");
prop.setProperty(Context.SECURITY_CREDENTIALS, "Password");

Context ctx = new InitialContext(prop);
DeployedService svc = (DeployedService) ctx.lookup(
                DeployedService.JNDI_PREFIX + "NewEmployee");

Following are the methods offered by the DeployedService object:

com.bea.jam.cluster.DeployedService

Implements java.rmi.Remote

This is the remote interface for the deployed service object. There is one service object defined on each WebLogic Server node for each unique service name. The service object is responsible for the following:

Methods

The following methods are available with the com.bea.jam.cluster.DeployedService object.

Fields

public static final JNDI_PREFIX

JNDI prefix used by all replicated DeployedService objects.

ActivityCounts Object

The ActivityCounts object contains a number of long integer fields representing various statistics for a WebLogic JAM service. This object may be obtained for a particular service via the DeployedService.getServiceActivity() or DeployedGateway.getLocalServiceActivity() methods. In addition, the ActivityCount objects for all services offered by a Gateway may be obtained via the DeployedGateway. getGatewayActivity() method.

Following are the data fields available from the ActivityCounts object:

com.bea.jam.cluster.ActivityCounts

Implements java.io.Serializable

Statistics container. Holds a set of activity counts.

Constructors

public ActivityCounts()

Fields

DeployedSession Object

The DeployedSession object may be obtained via a DeployedService remote object. It represents a WebLogic JAM session which may be used to invoke the associated service on the mainframe. Following are the methods offered by this object:

com.bea.jam.cluster.DeployedSession

Implements java.rmi.Remote

This is the remote interface for the deployed session object. This object wraps a jcrmSession object allowing remote access via the DeployedService object. This object is not bound into the JNDI tree and is not clusterable. A DeployedSession object is obtained by calling the DeployedService.getSession() method.

See Also

DeployedService

Methods

The following methods are available with the com.bea.jam.cluster.DeployedSession object.

Sample JAM Administration Utility

The following code presents a simple command line Java application which uses some of the RMI interfaces to control/monitor a JAM Gateway. This utility requires the weblogic.jar and jam.jar files to be listed in the CLASSPATH at runtime. For example, assuming that this utility was contained in a JAR file named jamadmin.jar, the following command line could be used to invoke the program:

set CLASSPATH=$WL_HOME/lib/weblogic.jar;$JAM_HOME/lib/jam.jar;jamadmin.jar 
java com.bea.jam.Admin stop MyGateway MyUser MyPassword t3://MyServer:7001

This code is offered as a sample application, which may be modified by the customer to meet their needs. The program, as presented here, is also delivered in the jam.jar file.

Listing 7-2

/*
        Sample command line administration utility for JAM 5.x
        
                Copyright (c) 2002, BEA Systems, Inc.
                        All Rights Reserved
*/                        

package com.bea.jam;

import java.util.Properties;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

import com.bea.jam.cluster.ActivityCounts;
import com.bea.jam.cluster.GatewayBootstrap;
import com.bea.jam.cluster.DeployedCRM;
import com.bea.jam.cluster.DeployedGateway;

    /**
  * This is a simple command line administration utility for the
  * JAM Gateway.  The supported commands, start/stop/status, allow
  * for starting/stopping the gateway as well as reporting of
  * minimal statistics.
  *
  * @version JAM 5.1 (Kiwi)
  */
public class Admin
{
    public static void main(String[] args) throws Exception
    {
        if (args.length < 1)
        {
            Usage();
            return;
        }
   
        processArgs(args);
        String func = args[0];
        if ("start".equalsIgnoreCase(func))
        {
            startGateway();
            return;
        }
        
        if ("stop".equalsIgnoreCase(func))
        {
            stopGateway();
            return;
        }
        
        if ("status".equalsIgnoreCase(func))
        {
            statusGateway();
            return;
        }
        
 System.out.println();
 System.out.println("*** Unknown function " + func + " - aborting");
 Usage();
}

        /**
         *  Start the JAM Gateway.  If the gateway is not currently
         *  deployed we deploy it first so that the startup will not
        *  be ignored.
        */
    private static void startGateway() throws Exception
    {
        System.out.println("Connecting to host " + url);
        Context ctx = getContext(url, user, psw);
        try
        {
            DeployedGateway gw = getGateway(ctx, name);
            if (!gw.isDeployed())
                gw.deploy(true);
                
            gw.startup();
        }
        finally
        {
            ctx.close();
        }
    }
    
        /**
         * Stop the JAM Gateway.
         */
    private static void stopGateway() throws Exception
    {
        System.out.println("Connecting to host " + url);
        Context ctx = getContext(url, user, psw);
        try
        {
            DeployedGateway gw = getGateway(ctx, name);
            gw.shutdown();
        }
        finally
        {
            ctx.close();
        }
    }
    
        /**
         *  Obtain and display some status information from the
         *  JAM Gateway.  The status of the gateway, enabled or
         *  disabled, is displayed.  If the gateway is enabled
         *  current activity counts are calculated and displayed.
         */
    private static void statusGateway() throws Exception
    {
        System.out.println("Connecting to host " + url);
        Context ctx = getContext(url, user, psw);
        try
        {
            DeployedGateway gw = getGateway(ctx, name);
            boolean enabled = gw.isEnabled();
            System.out.println();
            System.out.println("Gateway " + gw.getName() + " is "
                        + (enabled ? "enabled." : "disabled."));
            if (enabled)
            {
                ActivityCounts[] cnts = gw.getGatewayActivity();
                ActivityCounts tot = new ActivityCounts();
                for (int i = 0; i < cnts.length; ++i)
                {
                    tot.m_successes += cnts[i].m_successes;
                    tot.m_failures += cnts[i].m_failures;
                    tot.m_timeouts += cnts[i].m_timeouts;
                }
                
            System.out.println();
            System.out.println("Gateway statistics:");
            System.out.println("    Successes: " + tot.m_successes);
            System.out.println("   Failures: " + tot.m_failures);
            System.out.println("     Timeouts: " + tot.m_timeouts); 
            }
        }
        finally
        {
            ctx.close();
        }
    }
    
        /**
       *  Obtain a JNDI Context for the requested (or defaulted)
       *  WebLogic Server.  If a user ID and password are provided
       *  they are passed to the InitialContext for authentication.
       *
       *  @param  url     The URL of the WebLogic Server hosting the
       *                  JAM Gateway.
       *  @param  user    The user ID to be passed to WebLogic.  May
       *                  be null if none.
       *  @param  psw     The password to be passed to WebLogic.  May
       *                  be null if none.
       *  @return JNDI Initial Context for the passed URL.
       *  @throws NamingException if JNDI Context creation fails.
       */
private static Context getContext(String url, String user, String psw) 
                                throws NamingException
    {
        Properties prop = new Properties();
        prop.setProperty(Context.INITIAL_CONTEXT_FACTORY,
              weblogic.jndi.WLInitialContextFactory.class.getName());
        prop.setProperty(Context.PROVIDER_URL, url);
        if (null != user)
            prop.setProperty(Context.SECURITY_PRINCIPAL, user);
            
        if (null != psw)
            prop.setProperty(Context.SECURITY_CREDENTIALS, psw);
        
        return(new InitialContext(prop));
    }
    
        /**
         *  Examine command line arguments and save passed information
       *  for use by functional methods.
       */
private static void processArgs(String[] args)
{
        System.out.println();
        if (args.length > 1)
        {
            name = args[1];
            System.out.print("Gateway(" + name + ") ");
        }
            
        if (args.length > 2)
        {
            user = args[2];
            System.out.print("User(" + user + ") ");
        }
            
        if (args.length > 3)
        {
            psw = args[3];
            System.out.print("Password(**secret**) ");
        }
            
        if (args.length > 4)
            url = args[4];
            
        System.out.println("URL(" + url + ")");
     }
    
        /**
         *  Obtain a remote gateway object using the passed JNDI
         *  Context.
         *
         *  @param  ctx     The JNDI Context to be used in obtaining
         *                  the remote gateway object.
         *  @param  name    The name of the gateway to retrieve.  May
         *                  be passed as null to obtain the first
         *                  gateway defined for the server.
         *  @return Returns a DeployedGateway object representing the
         *          requested gateway.
         *  @throws Exception if an error is encountered.
         */
private static DeployedGateway getGateway(Context ctx, String name)
                                throws Exception
    {
        if (null == name)
        {
            GatewayBootstrap boot = (GatewayBootstrap) ctx.lookup(
                                                GatewayBootstrap.JNDI_NAME);
            DeployedGateway[] gw = boot.getGateways();
            if (gw.length > 0)
                return(gw[0]);
                
            throw new Exception("There are no JAM gateways defined
            on this server");
        }
        
        return((DeployedGateway) ctx.lookup(DeployedGateway.JNDI_PREFIX + name));
    }
    
        /**
         *  Display program usage information.
         */
    private static void Usage()
    {
        System.out.println();
        System.out.println("Usage: com.bea.jam.Admin <function> ");
        System.out.println("[<name> <user> <password>] [<URL>]");
        System.out.println("function:   The function to perform.  Supported functions ");
        System.out.println("            are start, stop, status.");
        System.out.println("            start:  Start the JAM Gateway");
        System.out.println("            stop:   Stop the JAM Gateway");
        System.out.println("            status: Report the JAM Gateway status");
        System.out.println();
        System.out.println("name:       The name of the JAM Gateway for the requested ");
        System.out.println("            function.  Default is the 1st gateway defined ");
        System.out.println("            on the selected WebLogic Server.");
        System.out.println();
        System.out.println("user:       The user ID used to authenicate with WebLogic.");
        System.out.println();
        System.out.println("password:   The psw used to authenicate with WebLogic.");
        System.out.println();
        System.out.println("URL:        The URL for the WLS Server hosting the JAM ");
        System.out.println("             Gateway.  The default is t3://localhost:7001.");
        System.out.println();
    }
    
private static String name = null;
private static String user = null;
private static String psw = null;
private static String url = "t3://localhost:7001";
}