3 Integrating an External Management System by Using JMX

This chapter gives an overview and examples of how you can use Java Management Extension (JMX) to programmatically access MBeans for the purpose of integrating Oracle Communications Service Broker with an external management system.

This chapter describes accessing the MBeans that are exposed by Processing Servers and Signaling Servers. For a description of accessing MBeans exposed by the Administration Console, see "Configuration MBeans Overview" in Oracle Communications Service Broker Configuration Guide.

• About Integrating Using JMX

• Location of MBean Definitions

• Connecting to a Processing Server or a Signaling Server

• Invoking Operations

• Getting Attribute Values

About Integrating Using JMX

Using JMX, you can access the monitoring MBeans and read-only configuration MBeans that are exposed by the MBean server on each Processing Server and Signaling Server.

Location of MBean Definitions

You need to have access to the Java Archive (JAR) files that define the MBean interfaces and the related classes. The MBean interfaces and classes for a module are provided in the OSGi bundles for the module.

The JARs for the OSGi bundles are located in the directory Oracle_home/axia/admin_console/modules, where Oracle_home is the directory in which Service Broker is installed.

The name of the JAR file for oracle.axia MBeans is provided with the reference information for the MBean. For example, reference information for SnmpConfigTypeMBean is described in Chapter 4, "Monitoring Service Broker with SNMP", which gives the JAR file name, oracle.axia.snmp-1.0.0.0.jar.

Include the relevant JARs in your class path.

Connecting to a Processing Server or a Signaling Server

Processing Servers and Signaling Servers are run with SSL enabled by default. Connecting to a server that has SSL enabled requires the following:

• Your administration client needs access to the server certificate and the server needs access to the client certificate. You generate these certificates when you configure the public key infrastructure (PKI). For information about security and setting up a PKI, see "Configuring Security" in Oracle Communications Service Broker System Administrator's Guide.

• Your administration client must be configured to support JMX SSL and JMX SSL Client Authentication. For more information, see:

  http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html

You use JMX operations to connect your management system to an MBean server on a Processing Server or a Signaling Server.

You will need the following information:

• Host name or IP address of the Processing Server or Signaling Server.

• IP port that the MBean server uses. The port corresponds to the JMX port defined for the server in the domain configuration.

• JMX registry port for the MBean server. This port corresponds to the JMX registry port defined for the server in the domain configuration.

• Absolute Java Naming and Directory Interface (JNDI) name of the MBean server. This is constructed as a URL:

  service:jmx:rmi://host:port/jndi/rmi://host:registryPort/jmxrmi

Example 3-1 shows how to connect to an MBean server.

Example 3-1 Connecting to a Processing Server or a Signaling Server using JMX

final JMXConnector connector;
final MBeanServerConnection mbeanServerConnection;
String serverHost = "localhost";
int jmxPort = 10003;
int jmxRegistryPort = 10103;
String url = "service:jmx:rmi://"+serverHost+":"+jmxPort+"/jndi/rmi://"+
              serverHost+":"+jmxRegistryPort+"/jmxrmi";
JMXServiceURL serviceURL;
final HashMap<String, Object> env = new HashMap<String,Object>();
serviceURL = new JMXServiceURL(url);
connector = JMXConnectorFactory.connect(serviceURL,env);
mbeanServerConnection = connector.getMBeanServerConnection();

When an MBean server connection is established, it is used to set and get attributes and invoke operations on specific MBeans.

Invoking Operations

You invoke an operation using invoke(...) on the MBeanServerConnection object. The operation has the signature:

Object invoke(ObjectName name, String operationName, Object[] params, String[] signature)

where:

• name is the object name for the MBean. For example, oracle:type=oracle.axia.api.management.pac.ProtocolAdapterContainerMBean.

• operationName is the operation you are invoking on the MBean. For example, getWorkManagerStatus.

• params is a list of the parameters you want to provide to the operation. For example, Object opParams[] = {"sip"};

• signature is a list of types that corresponds to each parameter. For example, String opSig[] = {String.class.getName()};

Example 3-2 shows how to get the value of the attribute int StartLevel defined in the interface oracle.axia.api.management.agent.ManagementAgentMBean. This attribute defines the start level for the server. The object name is oracle:type=oracle.axia.api.management.agent.ManagementAgentMBean.

Example 3-2 Invoking an MBean Operation

String objNameStr;
ObjectName objectName;
String attrName;
Object returnValue;
Object opParams[];
String opSig[];

objNameStr= "oracle:type=oracle.axia.api.management.pac.ProtocolAdapterContainerMBean";
objName = new ObjectName(objNameStr);
opName = "getWorkManagerStatus";
opParams = new Object[] {"sip"};
opSig = new String[] {java.lang.String.class.getName()};
returnValue =  mbeanServerConnection.invoke(objName, opName, opParams, opSig);

Getting Attribute Values

You get attributes using the operation getAttribute(...) on the MBeanServerConnection object. The operation has the signature:

Object getAttribute(ObjectName name, String attribute)

where:

• name is the object name for the MBean. For example, oracle:type=oracle.axia.api.management.agent.ManagementAgentMBean.

• attribute is the name of the attribute you are to get. For example, StartLevel.

Example 3-3 shows an example of how to get the value of the attribute int StartLevel defined in the interface oracle.axia.api.management.agent.ManagementAgentMBean. This attribute defines the start level for the server. The object name is oracle:type=oracle.axia.api.management.agent.ManagementAgentMBean.

Example 3-3 Getting an MBean Attribute

String objNameStr;
ObjectName objectName;
String attrName;
Object returnValue;
Object opParams[];
String opSig[];

objNameStr = "oracle:type=oracle.axia.api.management.agent.ManagementAgentMBean";
objName = new ObjectName(objNameStr);
attrName = "StartLevel";
returnValue = mbeanServerConnection.getAttribute(objName, attrName);