| Download Docs | |
|
| bea.com | products | dev2dev | support | askBEA |
|
|
|
 |
| e-docs > WebLogic Java Adapter for Mainframe > Programming Guide > RMI Access to the WebLogic JAM Gateway |
|
Programming Guide
|
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.
Note: For information about updating the jamconfig.xml file, refer to the BEA WebLogic JAM Configuration and Administration Guide.
The following objects are provided for remote gateway access:
Primary access point to the Gateway(s) configured for a given WebLogic Server. This object allows access to Gateways without requiring knowledge of the Gateway name.
This object provides access to all the remote functionality of the WebLogic JAM Gateway. It permits statistics to be gathered, starting/stopping the gateway, and returns information about deployed CRMs, Links, and services. If the Gateway name is known this object may be obtained directly from JNDI.
The following objects are obtained via the DeployedGateway object and provide additional information about the configuration and status of WebLogic JAM:
These remote objects are arranged in a hierarchy within the WebLogic Server node as follows:
GatewayBootstrap Object 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 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:
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);
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.
DeployedGateway gw = gwBoot.getGateway("JAM1");DeployedGateway gw = gwBoot.getGateways()[0];
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);
DeployedGateway gw = (DeployedGateway) ctx.lookup(
DeployedGateway.JNDI_PREFIX + "JAM1");
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. Following are the methods offered by the DeployedService 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);
DeployedService svc = (DeployedService) ctx.lookup(
DeployedService.JNDI_PREFIX + "NewEmployee");
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";
}
|
|
|
|
||
 |
|
|
 |
 |
 |
|
||