Customize using JMX

Your application or operating environment may have management features that are not accessible in the provided WebSphere Application Server administration facilities. You can incorporate WebSphere Application Server administration into other Java programs by using the Java administrative APIs. Alternatively, you can use the administrative classes and methods to add newly managed objects to WebSphere Application Server administration.

Perform the following steps to develop a Java program using the WebSphere Application Server administrative APIs to access WebSphere Application Server administration:

1. Develop an administrative client program.

   1. Create an AdminClient instance.

      An administrative client program needs to invoke methods on the AdminService object. The AdminClient resides in the application server in a base product installation. It resides in the deployment manager in a Network Deployment installation. The AdminClass class contains interfaces defined in the JMX javax.management.MBeanServer interface. See Interface MBeanServer for more information.

      The following example shows how to create an AdminClient instance that uses the SOAP connector to interface with the AdminService that runs in the application server:

      Properties connectProps = new Properties();
      connectProps.setProperty
       (AdminClient.CONNECTOR_TYPE, AdminClient.CONNECTOR_TYPE_SOAP);
      
      connectProps.setProperty(AdminClient.CONNECTOR_HOST, "localhost");
      connectProps.setProperty(AdminClient.CONNECTOR_PORT, "8880");
      AdminClient adminClient = null;
      try
      {
             adminClient = AdminClientFactory.createAdminClient(connectProps);
      }
      catch (ConnectorException e)
      {
             System.out.println("Exception creating admin client: " + e);
      }
      

   2. Find an MBean.

      Once you obtain an AdminClient instance, you can use it to access managed resources in an application server, a node agent server, or a deployment manager server. Each managed resource registers an MBean with the AdminService through which you can access the resource. The MBean is represented by an ObjectName instance that identifies the MBean. An ObjectName consists of a domain name followed by an unordered set of one or more key properties. For the WebSphere Application Server, the domain name is WebSphere and the key properties defined for administration are as follows:

      • type: The type of MBean. For example: Server, TraceService, JVM. See Public MBean Interfaces for a list of available MBeans.
      • name: The name identifier for the individual instance of the MBean.
      • cell: The name of the cell in which the MBean is running.
      • node: The name of the node in which the MBean is running.
      • process: The name of the process in which the MBean is running.

      You can locate MBeans by querying for them with ObjectNames that match desired key properties. The following example shows how to find the MBean for the NodeAgent of node MyNode:

      String nodeName = "MyNode";
      String query = "WebSphere:type=NodeAgent,node=" + nodeName + ",*";
      ObjectName queryName = new ObjectName(query);
      ObjectName nodeAgent = null;
      Set s = adminClient.queryNames(queryName, null);
      if (!s.isEmpty())
          nodeAgent = (ObjectName)s.iterator().next();
      else
          System.out.println("Node agent MBean was not found");
      

   3. Use the MBean.

      What a particular MBean allows you to do depends on that MBean's management interface. It may declare attributes that you can obtain or set. It may declare operations that you can invoke. It may declare notifications for which you can register listeners. For a list of available MBeans, see Public MBean Interfaces .

      The following example invokes one of the operations available on the NodeAgent MBean that was located above. The following example starts the MyServer application server:

      String opName = "launchProcess";
      String signature[] = { "java.lang.String" };
      String params[] = { "MyServer" };
      try
      {
           adminClient.invoke(nodeAgent, opName, params, signature);
      }
      catch (Exception e)
      {
           System.out.println("Exception invoking launchProcess: " + e);
      }
      

   4. Register for events.

      In addition to managing resources, the JMX APIs also support application monitoring for specific administrative events. Refer to the JMX javadoc for more information on the JMX APIsl. For example, certain events produce notifications when a server starts. Administrative applications can register as listeners for these notifications. The WebSphere Application Server provides a full implementation of the JMX notification model and provides additional function so you can receive notifications in a distributed environment.

      The following is an example of how an object can register itself for event notifications emitted from an MBean using the node agent ObjectName:

      adminClient.addNotificationListener(nodeAgent, this, null, null);
      

      In this example, the null value results in receiving all of the node agent MBean event notifications. You can also use the null value with the handback object.

   5. Handle the events.

      Objects receive JMX event notifications via the handleNotification method, which is defined by the NotificationListener interface, and any event receiver must implement. For details on the JMX javax.management.NotificationListener interface, see Interface NotificationListener .

      The following example is an implementation of handleNotification that reports the notifications that it receives:

      public void handleNotification(Notification n, Object handback)
      {
      System.out.println("***************************************************");
      System.out.println("* Notification received at " + new Date().toString());
      System.out.println("* type      = " + ntfyObj.getType());
      System.out.println("* message   = " + ntfyObj.getMessage());
      System.out.println("* source    = " + ntfyObj.getSource());
      System.out.println("* seqNum    = 
                  " + Long.toString(ntfyObj.getSequenceNumber()));
      System.out.println("* timeStamp = " + new Date(ntfyObj.getTimeStamp()));
      System.out.println("* userData  = " + ntfyObj.getUserData());
      System.out.println("***************************************************");
      }
      

2. Build the administrative client program by compiling it with javac and providing the location of the necessary JAR files in the class path argument.

   If you are not using the Network Deployment product (base product only), a typical command looks like the following example:

   javac -Djava.version=1.3 -classpath
   /QIBM/ProdData/WebAS5/Base/lib/admin.jar;/QIBM/ProdData/WebAS5/Base/lib/wsexception.jar;
    /QIBM/ProdData/WebAS5/Base/lib/jmxc.jar MyAdminClient.java
   

3. Run the administrative client program by setting up the runtime environment so that the program can find all of the necessary requirements.

   Use the /QIBM/ProdData/WebAS5/Base/bin/setupCmdLine script to set up the environment. This example batch file invokes the setupCmdLine script and runs an administrative client program named MyAdminClient:

   . $(/usr/bin/dirname $0)/setupCmdLine
   TRACE=com.ibm.*=all=disabled TRACEFILE=/home/wasclient/logs/client.log
   java ${JAVA_PARM_USER} \
   ${CONSOLE_ENCODING} \
   -Dtrace=$(TRACE) \
   -DtraceFile=$(TRACEFILE) \ 
   com.ibm.ws.bootstrap.WSLauncher \
   MyAdminClient "$@"