Java Management Extensions API (JMX)

The Java™ Management Extensions API (JMX) is used for resource monitoring and management.

JMX is a Java framework and API that provides a way of exposing your application's internals using a widely accepted implementation, allowing it to be picked up and used by any tool that conforms to that implementation, JConsole for example. It does this using managed beans (MBeans), non-static Java classes with public constructors. Get and set methods of the Bean are exposed as 'attributes', whilst all other methods are exposed as 'operations'.

The monitor-1.0 feature provides a host of MBeans that allow you to understand exactly what is going on with your application and Liberty JVM server. You can connect to JMX in a Liberty JVM server to view the attributes and operations of these MBeans, both locally and from a remote machine. A local connection will require the localConnector-1.0 feature to your server.xml and allows you to connect from within the same JVM server. Adding the restConnector-1.0 feature to your server.xml allows you to connect via a RESTful interface, which provides remote access to JMX.

Using WebSphere MBeans to monitor your applications

To begin, you must acquire a reference to your MBeanServer. This example looks for the 'JvmStats' MBean using the 'findMBeanServer' method to check which server the MBean is registered to.

// Create an ObjectName object for the MBean that we're looking for.
ObjectName beanObjName = new ObjectName("WebSphere:type=JvmStats");   

// Obtain the full list of MBeanServers.   
java.util.List servers = MBeanServerFactory.findMBeanServer(null);
MBeanServer server = null;     

// Iterate through our list of MBeanServers and attempt to find the one that we want.   
for (int i = 0; i < servers.size(); i++) 
{      
   // Check if the MBean domain matches what we're looking for.       
   if (((MBeanServer)servers.get(i).isRegistered(beanObjName)) 
   {
     server = (MBeanServer)servers.get(i);     
   }   
}

With the reference to the correct MBeanServer object, you can obtain reference to your MBean and get data back from the attributes that it exposes. This example looks for the 'UpTime' attribute of the 'JvmStats' MBean.
```
Object attributeObj = server.getAttribute(beanObjName, "UpTime");
System.out.println("UpTime of JVM is: " + attributeObj + ".");
```

Remote connectivity to JMX in Liberty

Remote connectivity to JMX in a Liberty JVM server requires use of an SSL connection and JEE role authorization. The client code then obtains a reference to the remote MBean using a JMXServiceURL.

All the JMX MBeans accessed through the REST connector are protected by a single JEE role named 'administrator'. To provide access to this role edit the server.xml and add the authenticated user to the administrator role.
```
<administrator-role
    <user>myuserid</user>
    <group>group1</group>
</administrator-role>
```
For further details on using JEE roles refer to topic JEE application role security.
A remote restful JMX client must access the Liberty JVM server using SSL. To configure SSL support for a Liberty JVM server, refer to topic Configuring SSL (TLS) for a Liberty JVM server. In addition the JMX client will require access to the restConnector client side jar file and an SSL client keystore containing the server's signing certificate. The restConnector.jar comes as part of the CICS® WLP install, which is available at &USSHOME;/wlp/clients

In the client side code you need to create a JMXServiceURL object. This allows you to obtain a reference to the remote MBeanServerConnection object. See call example where <host> and <httpsPort> match those of your server:

JMXServiceURL url = new JMXServiceURL("service:jmx:rest://<host>:<httpsPort>/IBMJMXConnectorREST");    
JMXConnector jmxConnector = JMXConnectorFactory.connect(url, environment);    
MBeanServerConnection mbsc = jmxConnector.getMBeanServerConnection();

Once you have successfully obtained the connection, the MBeanServerConnection object provides the same capability and set of methods as a local connection from the MBeanServer object.

For more information about the MBeans that are provided by WebSphere®, see Liberty profile: List of provided MBeans.

Note: If you want to use the monitor-1.0 feature but do not have APAR PI25503, you will need to add the following JAR file to your JVM profile:

-javaagent:<USSHOME>/wlp/bin/tools/ws-javaagent.jar

where <USSHOME> is the location of the CICS USSHOME directory.