Accessing IBM Streams information with JMX APIs

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

1. Supply the necessary environment parameter value. The package name for the IBM Streams connector client provider must be provided as an environment parameter. The connector client provider is in the IBM 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 either by supplying an IBM Streams user ID and password, or by providing a client certificate.

   • 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);

   • Client certificate authentication option

     Complete the following steps:

     1. Set up client certificate authentication.

     2. Provide access to the certificate through an additional environment parameter or system environment variable.
        • Environment parameter option
          Supply a value for the jmx.remote.x.certificate environment parameter. The value of the parameter can either be a java.security.cert.X509Certificate object or an absolute path to the X.509 client certificate file, or the PKCS #12 file that contains the client certificate, on the system where the JMX application runs. For example, the following Java code sets the environment parameter:

          HashMap<String,Object> env = new HashMap<String,Object>();
          env.put("jmx.remote.x.certificate", "c:\\streamscertificates\\streamsuser.pem");

        • Environment variable option
          Set the STREAMS_X509CERT environment variable on the system where the JMX application runs, and set it to the absolute path of the X.509 client certificate file or the PKCS #12 file that contains the client certificate.

          • Linux system example:

            export STREAMS_X509CERT=/streamscertificates/streamsuser.pem 

          • Microsoft Windows system example:

            set STREAMS_X509CERT=c:\streamscertificates\streamsuser.pem 

     3. If the certificate is contained in a PKCS #12 file, you must provide the PKCS #12 file password and alias of the certificate. In this case, the certificate alias and PKCS #12 file password are the credentials.
        Supply the credentials as a string array for the jmx.remote.x.certificate.credentials environment parameter. The first element contains the certificate alias and the second element contains the certificate password. The following example shows how to supply these values in a Java application:

        HashMap<String,Object> env = new HashMap<String,Object>();
        String [] creds = {alias, password};
        env.put("jmx.remote.x.certificate.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", "SSL_TLSv2");

4. Optional: Specify the locale that determines the language in which messages are returned from JMX calls. If you do not specify a locale, messages are returned in the language of the JMX process locale.

   To specify the locale, supply either a java.util.Locale object or a string representation of the locale for the jmx.remote.locale environment property. If you use a string representation, it must be in the format that is documented for the java.util.Locale.toString() method.

   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.locale", Locale.ENGLISH);

   Supported languages:

   • Brazilian Portuguese (pt_BR)
   • English (en)
   • French (fr)
   • German (de)
   • Italian (it)
   • Japanese (ja)
   • Korean (ko)
   • Russian (ru)
   • Simplified Chinese (zh_CN)
   • Spanish (es)
   • Traditional Chinese (zh_TW)
   Note: If you start an instance on IBM Streams that is earlier than version 4.2.1, messages from those instances will be returned in English regardless of the locale that you specify.
5. Establish a JMX connection.

   The IBM 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 using 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(); 

   Note: If the management API service restarts, the JMX URL might no longer be valid for establishing a new connection. If the jmx.port domain property is set to find an available port when the service starts, a different port might be used each time that the service starts. The service might also start on a different resource. Use the streamtool getjmxconnect command to determine the new JMX URL after the service starts. Alternatively, specify a port number for the jmx.port domain property, so that the same port is used each time that the service starts. To designate which resources you want to run the service, use the following tag: jmx. For more information, see Assigning tags to resources in a domain.
6. Obtain access to an IBM 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 DomainMXBean.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 domainObjName = ObjectNameBuilder.domain(domainId);
   DomainMXBean domain = JMX.newMXBeanProxy(mbsc, domainObjName, DomainMXBean.class, true);

7. 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 domain status and the list of instances in the domain:

   System.out.println("Status: " + domain.getStatus());
   System.out.println("Instances: " + domain.getInstances());

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.domain.DomainMXBean;
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 
//   Client service:jmx:jmxmp://server:9975 domainA 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 user = args[2];    // use streamtool setacl or streamtool setdomainacl to assign required permissions
      String password = args[3];
            
      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.domain(domainName);
      DomainMXBean domain = JMX.newMXBeanProxy(mbsc, objName, DomainMXBean.class, true);

      System.out.println("Status: " + domain.getStatus());
      System.out.println("Instances: " + domain.getInstances());
    }
    catch (Exception e) {
     e.printStackTrace();     
    }   
  }
}