Chapter 3. JMX Application Development
Prev   Next

Chapter 3. JMX Application Development

Table of Contents

3.1. Application Structure
3.2. Connecting MBean Servers
3.2.1. Using JEUS Utility
3.2.2. Using JNDI
3.2.3. Using JMX Remote API
3.3. Security Setting
3.4. MBean Object Names

This chapter describes how to develop and install JEUS JMX client applications for the JEUS monitoring service.

3.1. Application Structure

Various application structures are available to meet various needs. JEUS JMX client application has a general structure and runs according to its structure.

The following shows the execution structure and process of JMX client application.

  1. Environment configuration (optional)

    Configures an environment for JMX client application, before connecting to MBeanServer. Can query the MBean, and obtain the results. For detailed information about the basic environment configurations, refer to "Chapter 2. JMX Manager Configuration"

  2. MBeanServer connection

    Connection to MBeanServer can be made in the following three ways.

    • Use the JEUS utility registered with jeus.management.RemoteMBeanServerFactory.

    • Use the reference registered with JNDI.

    • Use the JMX Remote javax.management.remote.JMXServiceURL to obtain javax.management.remote.JMXConnector.

    For more information about the methods, refer to the corresponding section.

  3. Query

  4. Query result handling

Furthermore, this chapter discusses how to set security for JEUS monitoring service, and how JEUS JMX creates an instance of ObjectName. JEUS monitoring can be performed using SNMP, and for more information, refer to "JEUS SNMP Guide".

Note

In order to fully understand what is explained in this chapter, basic knowledge of JMX Remote API 1.0 and Java EE management specification is required. For details about JMX remote API, refer to J2EE JMX remote API 1.0 specification provided by Oracle, and the JMX remote API.

3.2. Connecting MBean Servers

This section explains how to connect to MBean servers.

3.2.1. Using JEUS Utility

This section describes how the JEUS utility class, jeus.management.RemoteMBeanServerFactory, is used for JMX application to monitor JEUS. Note that the connection to MBeanServer is made using a different method.

See the following example of client using JEUS utility.

package jmxclient;

import java.util.Set;
import java.util.Iterator;
import java.util.Hashtable;
import javax.management.ObjectName;
import javax.management.MBeanServerConnection;
import javax.naming.Context;

/**
 * JMX Client which uses JEUS utility (RemoteMBeanServerFactory) class.
 */
public class JMXClientUsingJeusUtility {

    public static void main(String args[]) throws Exception {
        if(args.length < 3) {
            System.out.println("Required arguments: hostname username password");
            return;
        }
        
        // Step 1. Setting Environments
        String hostname = args[0];
        String username = args[1];
        String password = args[2];

        Hashtable env = new Hashtable();
        env.put(Context.INITIAL_CONTEXT_FACTORY, "jeus.jndi.JNSContextFactory");
        env.put(Context.PROVIDER_URL, hostname);
        env.put(Context.SECURITY_PRINCIPAL, username);
        env.put(Context.SECURITY_CREDENTIALS, password);

        // Step 2. Getting MBeanServer
        MBeanServerConnection mbeanServer 
            = jeus.management.RemoteMBeanServerFactory.getMBeanServer(env);

        // Step 3. Query
        ObjectName jeusScope = new ObjectName("JEUS:*");
        Set objectNames = mbeanServer.queryNames(jeusScope, null);

        // Step 4. Handling the Query Result
        for(Iterator i = objectNames.iterator(); i.hasNext();) {
            System.out.println("[MBean] " + i.next());
        }
    }
}

The jeus.management.RemoteMBeanServerFactory class is used to connect to MBeanServer, the JEUS utility class provided by JEUS. Using the class, MBeanServerConnection object can easily be obtained.

When connecting to the JEUS server after compiling and executing the previous example file, the list of MBeans whose object name is in the form of "JEUS:*" will be displayed. Three arguments are passed to the program. The first argument is the server's hostname and the second and third are JEUS username and password.

user1@host1:~$ java -classpath .:$JEUS_HOME/lib/client/jclient.jar jmxclient.JMXClientUsingJeusUtility 127.0.0.1 administrator jeus

[2013.05.28 14:56:44][2] [t-1] [NET-0002] Beginning to listen to NonBlockingChannelAcceptor: /127.0.0.1:9756.
[MBean] JEUS:j2eeType=JeusService,jeusType=ThreadPool,JMXManager=adminServer,
J2EEServer=adminServer,name=threadpool.System
[MBean] JEUS:j2eeType=JeusService,jeusType=JEUSMPConnector,JMXManager=adminServer,
J2EEServer=adminServer,name=adminServer
[MBean] JEUS:j2eeType=JeusService,jeusType=JMSDestinationResource,
JMXManager=adminServer,J2EEServer=adminServer,JMSResource=adminServer_jms,
name=ExamplesQueue
[MBean] JEUS:j2eeType=JeusService,jeusType=JeusLogService,JMXManager=adminServer,
J2EEServer=adminServer,name=adminServer
[MBean] JEUS:j2eeType=JeusService,jeusType=ThreadPool_WEBC,JMXManager=adminServer,
WebEngine=adminServer_servlet,J2EEServer=adminServer,WebListener=http1,name=http1
[MBean] JEUS:j2eeType=JeusService,jeusType=SecurityDomain,JMXManager=adminServer,
J2EEDomain=domain1,SecurityService=SecurityService,name=SYSTEM_DOMAIN
[MBean] JEUS:j2eeType=JeusService,jeusType=DeploymentPlanManagementService,
JMXManager=adminServer,J2EEDomain=domain1,name=adminServer
[MBean] JEUS:j2eeType=JeusService,jeusType=JMSConnectionFactoryResource,
JMXManager=adminServer,J2EEServer=adminServer,JMSResource=adminServer_jms,
name=ConnectionFactory
[MBean] JEUS:j2eeType=JeusService,jeusType=JMSEngine,JMXManager=adminServer,
J2EEServer=adminServer,name=adminServer_jms
[MBean] JEUS:j2eeType=JeusService,jeusType=ServerDeploymentService,
JMXManager=adminServer,J2EEServer=adminServer,name=adminServer
. . .

Note

jclient.jar is required to run the example program. In general, it is located under the JEUS_HOME/lib/client directory.

3.2.2. Using JNDI

This section discusses how JNDI is used for JMX application to monitor JEUS. Connection to MBeanServer is made using a different method.

See the following example of client using JNDI.

package jmxclient;

import java.util.Set;
import java.util.Iterator;
import java.util.Hashtable;
import javax.management.MBeanServerConnection;
import javax.management.ObjectName;
import javax.management.remote.JMXConnector;
import javax.naming.Context;
import javax.naming.InitialContext;

/**
 * JMX Client which uses JNDI lookup.
 */
public class JMXClientUsingJndi {

    public static void main(String args[]) throws Exception {
        if(args.length < 4) {
            System.out.println("Required arguments: " 
                + "hostname username password target-name");
            return;
        }
        
        // Step 1. Setting Environments
        String hostname = args[0];
        String username = args[1];
        String password = args[2];

        // targetName could be server name,
        // for example, "adminServer", "server1"
        String targetName = args[3];
        
        Hashtable env = new Hashtable();
        env.put(Context.INITIAL_CONTEXT_FACTORY, "jeus.jndi.JEUSContextFactory");
        env.put(Context.PROVIDER_URL, hostname);
        env.put(Context.SECURITY_PRINCIPAL, username);
        env.put(Context.SECURITY_CREDENTIALS, password);

        // Step 2. Getting MBeanServerConnection
        InitialContext ctx = new InitialContext(env);
        JMXConnector connector = (JMXConnector)ctx.lookup("mgmt/rmbs/" + targetName);
        MBeanServerConnection mbeanServer = connector.getMBeanServerConnection();

        // Step 3. Query
        ObjectName jeusScope = new ObjectName("JEUS:*");
        Set objectNames = mbeanServer.queryNames(jeusScope, null);

        // Step 4. Handling the Query Result
        for(Iterator i = objectNames.iterator(); i.hasNext();) {
            System.out.println("[MBean] " + i.next());
        }
    }
}

The same method can be used to perform a JNDI Lookup regardless of the registered connector type (RMI connector or JMXMP connector). JEUS's default naming method is used for the export name that is used during the lookup. The name format is JNDI context mgmt/rmbs/<server-name>.

When compiling and executing the previous example file and connecting to the JEUS server, the list of MBeans whose object name is in the form of "JEUS:*" will be displayed. Four arguments are passed to the program. The first argument is the server's hostname, the second and third are JEUS username and password, and the last is the server name.

user1@host1:~$ java -classpath .:$JEUS_HOME/lib/client/jclient.jar jmxclient.JMXClientUsingJndi 127.0.0.1 jeus jeus adminServer

[2013.05.28 15:20:24][2] [t-1] [NET-0002] Beginning to listen to NonBlockingChannelAcceptor: /192.168.34.31:9756.
[MBean] JEUS:j2eeType=JeusService,jeusType=ThreadPool,JMXManager=adminServer,
J2EEServer=adminServer,name=threadpool.System
[MBean] JEUS:j2eeType=JeusService,jeusType=JEUSMPConnector,JMXManager=adminServer,
J2EEServer=adminServer,name=adminServer
[MBean] JEUS:j2eeType=JeusService,jeusType=JMSDestinationResource,
JMXManager=adminServer,J2EEServer=adminServer,JMSResource=adminServer_jms,
name=ExamplesQueue
[MBean] JEUS:j2eeType=JeusService,jeusType=JeusLogService,JMXManager=adminServer,
J2EEServer=adminServer,name=adminServer
[MBean] JEUS:j2eeType=JeusService,jeusType=ThreadPool_WEBC,JMXManager=adminServer,
WebEngine=adminServer_servlet,J2EEServer=adminServer,WebListener=http1,name=http1
[MBean] JEUS:j2eeType=JeusService,jeusType=SecurityDomain,JMXManager=adminServer,
J2EEDomain=domain1,SecurityService=SecurityService,name=SYSTEM_DOMAIN
[MBean] JEUS:j2eeType=JeusService,jeusType=DeploymentPlanManagementService,
JMXManager=adminServer,J2EEDomain=domain1,name=adminServer
[MBean] JEUS:j2eeType=JeusService,jeusType=JMSConnectionFactoryResource,
JMXManager=adminServer,J2EEServer=adminServer,JMSResource=adminServer_jms,
name=ConnectionFactory
[MBean] JEUS:j2eeType=JeusService,jeusType=JMSEngine,JMXManager=adminServer,
J2EEServer=adminServer,name=adminServer_jms
[MBean] JEUS:j2eeType=JeusService,jeusType=ServerDeploymentService,
JMXManager=adminServer,J2EEServer=adminServer,name=adminServer
. . .

For RMI connector, a reference export name can be specified if JMXMP connector is loaded separately.

Note

1. The jclient.jar file is required to run the example program. In general, the jclient.jar file is located under the JEUS_HOME/lib/client directory.

2. For more information about RMI connector configurations, refer to "2.3.2. RMI Connector".

3. For more information about JNDI, refer to JEUS Server Guide. "Chapter 4. JNDI Naming Server". If the JMX application is executed from a servlet or EJB, JNDI parameter setting is not required.

3.2.3. Using JMX Remote API

This section describes how JMX remote API is used for JMX application to monitor JEUS. Connection to MBeanServer is made using a different method..

See the following example of client using JMX Remote API.

package jmxclient;

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

/**
 * JMX Client which uses JMX Service URL.
 * RMI Connector should be turned on in JEUS 
 * and the JNDI name of it is required here.
 */
public class JMXClientUsingJmxUrl {

    public static void main(String args[]) throws Exception {
        if(args.length < 4) {
            System.out.println("Required arguments: " 
                + "hostname username password connector-exportname");
            return;
        }
        
        // Step 1. Setting Environments
        String hostname = args[0];
        String username = args[1];
        String password = args[2];

        // the JMX RMIConnector export name
        String exportName = args[3];
        
        Hashtable env = new Hashtable();
        env.put(Context.INITIAL_CONTEXT_FACTORY, "jeus.jndi.JNSContextFactory");
        env.put(Context.PROVIDER_URL, hostname);
        env.put(Context.SECURITY_PRINCIPAL, username);
        env.put(Context.SECURITY_CREDENTIALS, password);

        // Step 2. Getting MBeanServer
        JMXServiceURL url = new JMXServiceURL("service:jmx:rmi:///jndi/" + 
         exportName);

        JMXConnector connector = null;
  try {
         connector = JMXConnectorFactory.newJMXConnector(url,env);
         // connect to JMXConnectorServer 
         connector.connect();
         MBeanServerConnection mbeanServer = connector.getMBeanServerConnection();

         // Step 3. Query
         ObjectName jeusScope = new ObjectName("JEUS:*");
         Set objectNames = mbeanServer.queryNames(jeusScope, null);

         // Step 4. Handling the Query Result
         for(Iterator i = objectNames.iterator(); i.hasNext();) {
             System.out.println("[MBean] " + i.next());
         }
  } finally {
   // Always close the JMXConnector
   connector.close();
  }
    }
}

Note

To use JMX remote API, 'RMI Connector' of the JMX Manager should be specified. For more information about RMI connector configuration, refer to "2.3.2. RMI Connector" .

When connecting to the JEUS server after compiling and executing the above example file, the list of MBeans whose object name is in the form of "JEUS:*" will be displayed. Three arguments are passed to the program.

The first argument is the server's hostname, the second and third are JEUS username and password, and the last is RMI Connector ExportName.

The following is an example of configuring 'ExportName' as 'RMIConnector'.

user1@host1:~$ java -classpath .:$JEUS_HOME/lib/client/jclient.jar jmxclient.JMXClientUsingJmxUrl 127.0.0.1 jeus jeus RMIConnector

[2013.05.28 15:21:29][2] [t-1] [NET-0002] Beginning to listen to NonBlockingChannelAcceptor: /192.168.34.31:9756.
[MBean] JEUS:j2eeType=JeusService,jeusType=ThreadPool,JMXManager=adminServer,
J2EEServer=adminServer,name=threadpool.System
[MBean] JEUS:j2eeType=JeusService,jeusType=JEUSMPConnector,JMXManager=adminServer,
J2EEServer=adminServer,name=adminServer
[MBean] JEUS:j2eeType=JeusService,jeusType=JMSDestinationResource,
JMXManager=adminServer,J2EEServer=adminServer,JMSResource=adminServer_jms,
name=ExamplesQueue
[MBean] JEUS:j2eeType=JeusService,jeusType=JeusLogService,JMXManager=adminServer,
J2EEServer=adminServer,name=adminServer
[MBean] JEUS:j2eeType=JeusService,jeusType=ThreadPool_WEBC,JMXManager=adminServer,
WebEngine=adminServer_servlet,J2EEServer=adminServer,WebListener=http1,name=http1
[MBean] JEUS:j2eeType=JeusService,jeusType=SecurityDomain,JMXManager=adminServer,
J2EEDomain=domain1,SecurityService=SecurityService,name=SYSTEM_DOMAIN
[MBean] JEUS:j2eeType=JeusService,jeusType=DeploymentPlanManagementService,
JMXManager=adminServer,J2EEDomain=domain1,name=adminServer
[MBean] JEUS:j2eeType=JeusService,jeusType=JMSConnectionFactoryResource,
JMXManager=adminServer,J2EEServer=adminServer,JMSResource=adminServer_jms,
name=ConnectionFactory
[MBean] JEUS:j2eeType=JeusService,jeusType=JMSEngine,JMXManager=adminServer,
J2EEServer=adminServer,name=adminServer_jms
[MBean] JEUS:j2eeType=JeusService,jeusType=ServerDeploymentService,
JMXManager=adminServer,J2EEServer=adminServer,name=adminServer
. . .

Note

The jclient.jar file is required to run the example program. In general, it is located under the JEUS_HOME/lib/client directory.

3.3. Security Setting

This section describes the security settings for the JEUS monitoring service. JEUS server performs security checks for a user who reads and performs operations on the properties of various MBeans registered with JEUS server using the JMX API. For more information about the permissions required to access each MBean, refer to JEUS API documents.

API documents can be found in the following location.

JEUS_HOME/docs/api

Note

API documents not only provide permission names, but also ObjectNamePattern, attributes, operation information, and etc. required for using MBeans.

JMX applications provide username and password information when connecting to the server to create the MBeanServerConnection object. In general, the following code is used to create MBeanServerConnection object. The code shows that the username and password is included in the environment configuration that is sent to the hash table.

. . .

    JMXServiceURL serviceURL = 
            new JMXServiceURL("service:jmx:jmxmp://127.0.0.1:9999/adminServer");

    Map<String, Object> env = new HashMap<String, Object>();
    env.put(Context.SECURITY_PRINCIPAL, id);
    env.put(Context.SECURITY_CREDENTIALS, password);
    env.put(Context.INITIAL_CONTEXT_FACTORY, "jeus.jndi.JEUSContextFactory");
    env.put("jmx.remote.x.request.timeout", "10");

    JMXConnector connector = JMXConnectorFactory.connect(serviceURL, env);
    MBeanServerConnection connection = connector.getMBeanServerConnection();

. . .

The username, password, and permissions are specified through JEUS security service.

For more information about JEUS security settings, refer to JEUS Security Guide. "2.5. Configuring the Security System User Information" and JEUS Security Guide. "2.6. Configuring Security System Policies".

3.4. MBean Object Names

"ObjectName" is the default object name of an MBean object. The format of the ObjectName is JMX-standard, but the values may vary depending on the vendor because each vendor's JMX implementation is different. The hierarchy of JMX MBeans and the types of MBeans also vary for each vendor.

The syntax of JEUS ObjectName is as follows:

<domain_name>: j2eeType=<j2eeType_value>, name=<name_value>,
    [<parent-j2eeType_value>], [jeusType = <jeusType_value>],
    [isTargetable = <isTargetable_value>],
    JMXManager = <JMXManager_value> [,*]

or

<domain_name>: *

ObjectName must start with the <domain_name> and there is no defined sequence for each name-value pairs.

For example, both of the following ways will retrieve the object names of JEUSManager MBean.

JEUS:j2eeType=J2EEDomain,JMXManager=adminServer, *
JEUS:JMXManager=adminServer, j2eeType=J2EEDomain, *

Each item description is:

  • <domain_name>

    • JEUS domain name. Set to JEUS.

  • j2eeType

    • The J2EE type of MBean, which is described in the J2EE management specifications.

    • Set with one of the following values:

      AppClientModuleEJBModuleEntityBean
      J2EEApplicationJ2EEDomainJ2EEServer
      JAXRResourceJCAConnectionFactoryJCAManagedConnectionFactory
      JCAResourceJDBCDataSourceJDBCDriver
      JDBCResourceJMSResourceJNDIResource
      JTAResourceJVMJavaMailResource
      JeusServiceMessageDrivenBeanResourceAdaptor
      ResourceAdapterModuleServletStatefulSessionBean
      StatelessSessionBeanURLResourceWebModule

  • name

    • The name of MBean. There is a unique name for each MBean object.

      For example, the name of the JVM on which the "adminServer" server runs is "adminServer."

  • parent-j2eeType

    • The J2EE type of the MBean's parent. There is a defined hierarchy for MBeans.

      For example, the parent-j2ee type of "JDBCDriver" is "JDBCDataSource."

  • jeusType

    • Mbeans' type defined in JEUS JMX. Only "JeusService" j2eeType can have several jeusTypes.

    • Set with one of the following values:

      EJBEngineJMSClientResourceJMSConnectionFactoryResource
      JMSDestinationResourceJMSDurableSubscriberResourceJMSEngine
      JMSPersistenceStoreManagerJMSServiceChannelSecurityDomain
      SecurityPolicySecurityServiceSecuritySubject
      SessionContainerSessionContainerCentralSessionContainerP2P
      ThreadPoolThreadPool_WEBCWebEngine
      WebListenerWebServices 

  • isTargetable

    • A boolean type that should be set to true for the MBean on which user AP (e.g. EJB, servlet, and JSP) is deployed and is running as isTargetable.

  • JMXManager

    • The name of the JMXManager that provides MBean service. In general, it is the name of the server that the JMXManager belongs to.

Prev   Next
Chapter 2. JMX Manager Configuration Home Appendix A. JMX Monitoring Examples