Develop an administrative client program

This page contains examples of key features of an administrative client program that utilizes WebSphere Application Server administrative APIs and Java Management Extentions (JMX). WAS administrative APIs provide control of the operational aspects of your distributed system as well as the ability to update your configuration. This page also demonstrates examples of operational control. For information, view the Administrative Javadoc , theJMX Javadoc , or the MBean Javadoc .

  1. Create an AdminClient instance. An administrative client program needs to invoke methods on the AdminService object that is running in the deployment manager (or the appserver in the base installation). The AdminClient class provides a proxy to the remote AdminService object through one of the supported JMX connectors. The following example shows how to create an AdminClient instance

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

  2. Find an MBeanOnce you obtain an AdminClient instance, you can use it to access managed resources in the administration servers and appservers. 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 WAS, 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.
    name The name identifier for the individual instance of the MBean.
    cell The name of the cell that the MBean is executing.
    node The name of the node that the MBean is executing.
    process The name of the process that the MBean is executing.

    You can locate an MBean 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 the MBeans provided by the WAS, you can find information about the interfaces they support in the MBean javadoc.The following example invokes one of the operations available on the NodeAgent MBean that we located above. The following example will start the servername application server

    String opName = "launchProcess";
    String signature[] = { "java.lang.String" };
    String params[] = { "servername" };
    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 API also supports application monitoring for specific administrative events. Certain events produce notifications, for example, when a server starts. Administrative applications can register as listeners for these notifications. The WAS provides a full implementation of the JMX notification model, and provides additional function so you can receive notifications in a distributed environment. For a complete list of the notifications emitted from WebSphere Application Server MBeans, refer to the com.ibm.websphere.management.NotificationConstants class in the Javadoc.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 will result 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 which any event receiver must implement. 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("***************************************************");
    }
    

 

See Also

Creating a custom Java administrative client program using WAS administrative Java APIs
Administrative client program example