Accessing Teracloud Streams information with JMX APIs

To access Teracloud Streams information by using the JMX API, you must supply the necessary environment parameter values, establish a JMX connection, obtain access to an Teracloud Streams JMX bean proxy, and call bean methods through the proxy.

1. Supply the necessary environment parameter value. The package name for the Teracloud Streams connector client provider must be provided as an environment parameter. The connector client provider is in the Teracloud Streams product.

   The package name is com.ibm.streams.management, and it must be supplied as the value for the jmx.remote.protocol.provider.pkgs property.

   For example, the following Java™ code sets the environment parameter:

   HashMap<String,Object> env = new HashMap<String,Object>();
   env.put("jmx.remote.protocol.provider.pkgs", "com.ibm.streams.management");

2. Complete the setup for authenticating to the JMX server.

   To establish a JMX connection, you must authenticate by supplying a Teracloud Streams user ID and password.

   • User ID and password option
     Supply these values as a string array for the jmx.remote.credentials environment parameter. The following example shows how to supply these values in a Java application:

     HashMap<String,Object> env = new HashMap<String,Object>();
     String [] creds = {user, password};
     env.put("jmx.remote.credentials", creds);

3. If required, specify the cryptographic protocol to use for the JMX connection. This step is required only if the jmx.sslOption configuration property is set to a value other than the default value.

   To specify the cryptographic protocol to use, supply a value for the jmx.remote.tls.enabled.protocols environment property. The specified value must match the value of the jmx.sslOption property. To retrieve this value, run the streamtool getdomainproperty jmx.sslOption command.

   The following example shows how to supply this value in a Java application:

   HashMap<String,Object> env = new HashMap<String,Object>();
   env.put("jmx.remote.tls.enabled.protocols", "TLSv1.2");

4. Establish a JMX connection.

   The Teracloud Streams JMX connector is part of the management API service. To establish a connection to the JMX connector, call the JMXConnectorFactory.connect() method. You must supply the environment parameters that are described in the previous steps and the JMX URL.

   You can determine the JMX URL by calling the streamtool getjmxconnect command. After you establish a connection to the JMX connector, retrieve a connection to the managed bean server by calling the getMBeanServerConnection() method on the returned JMXConnector object.

   For example, the following Java code establishes a JMX connection:

   JMXConnector jmxc = JMXConnectorFactory.connect(new JMXServiceURL(jmxUrlString), env);
   MBeanServerConnection mbsc = jmxc.getMBeanServerConnection(); 

5. Obtain access to a Teracloud Streams JMX bean proxy.

   The easiest way to access the attributes and operations of a JMX bean is through a proxy object. To obtain the proxy object for a JMX bean, you need to know the class name of the bean (for example InstanceMXBean.class) and the object name for the specific bean to access. You can use the com.ibm.streams.management.ObjectNameBuilder class to help construct the object name. Alternatively, you can use the MBeanServerConnection.queryMBeans() method to query the object name.

   For example, the following Java code uses the com.ibm.streams.management.ObjectNameBuilder class to construct the object name and access a JMX bean proxy:

   ObjectName instanceObjName = ObjectNameBuilder.instance(domainId, instanceId);
   InstanceMXBean instance = JMX.newMXBeanProxy(mbsc, instanceObjName, InstanceMXBean.class, true);

6. Call the bean methods through the proxy. After you obtain a proxy for the bean, you can access the bean attributes and operations by calling methods on the proxy. For example, the following Java code uses methods to obtain the instance status and get the list of jobs in the instance:

   System.out.println("Status: " + instance.getStatus());
   System.out.println("Jobs: " + instance.getJobs());

import java.util.HashMap;

import javax.management.JMX;
import javax.management.MBeanServerConnection;
import javax.management.ObjectName;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;

import com.ibm.streams.management.instance.InstanceMXBean;
import com.ibm.streams.management.ObjectNameBuilder;

// javac -cp com.ibm.streams.management.jmxmp.jar:com.ibm.streams.management.mx.jar Client.java
// java -cp .:com.ibm.streams.management.jmxmp.jar:com.ibm.streams.management.mx.jar:jmxremote_optional.jar:glassfish-corba-omgapi-[version].jar:commons-cli-[version].jar 
//   Client service:jmx:jmxmp://server:9975 domainA instanceA user password
// Note: It is important to include com.ibm.streams.management.jmxmp.jar in the class path before jmxremote_optional.jar
public class Client {
  public static void main(String [] args) {
    try { 
      String jmxUrl = args[0];  // use streamtool getjmxconnect to find
      String domainName = args[1];
      String instanceName = args[2];
      String user = args[3];    // use streamtool setacl to assign required permissions
      String password = args[4];
            
      HashMap<String,Object> env = new HashMap<String,Object>();
      String [] creds = {user, password};
      env.put("jmx.remote.credentials", creds);
      env.put("jmx.remote.protocol.provider.pkgs", "com.ibm.streams.management");

      JMXConnector jmxc = JMXConnectorFactory.connect(new JMXServiceURL(jmxUrl), env);
      MBeanServerConnection mbsc = jmxc.getMBeanServerConnection();

      ObjectName objName = ObjectNameBuilder.instance(domainName, instanceName);
      InstanceMXBean instance = JMX.newMXBeanProxy(mbsc, objName, InstanceMXBean.class, true);

      System.out.println("Status: " + instance.getStatus());
      System.out.println("Jobs: " + instance.getJobs());
    }
    catch (Exception e) {
     e.printStackTrace();     
    }   
  }
}