16 Making Communication Services Manageable

Once you have created your extension Communication Service, any OAM functions that you have designed - read/write attributes and/or operations - must be exposed in a way that allows them to be accessed and manipulated, either through the Oracle Communications Services Gatekeeper Administration Console extension, or through other management tools. The following chapter provides a description of the mechanism that Oracle Communications Services Gatekeeper uses to accomplish this.

Overview

Oracle Communications Services Gatekeeper uses the Java Management Extensions (JMX) 1.2 standard, as it is implemented in JDK 1.6. The JMX model consists of three layers, Instrumentation, Agent, and Distributed Services. As a Communication Service developer, you work in the Instrumentation layer. You create managed beans (MBeans) that expose your Communication Service management functionality as a management interface. These MBeans are then registered with the Agent, the Runtime MBean Server in the WebLogic Server instance, which makes the functionality available to the Distributed Services layer, management tools like the Oracle Communications Services Gatekeeper Administration Console. Finally, because configuration information needs to be persisted, you store the values you set using Oracle Communications Services Gatekeeper's Configuration Store, which provides a write-through database cache. In addition to persisting the configuration information, the cache also provides cluster-wide access to the data, updating a cluster-wide store whenever there is a change in globally relevant configuration data.

For more information on the JMX model in general in relation to WebLogic Server, see Oracle Fusion Middleware Developing Manageable Applications With JMX for Oracle WebLogic Server at:

http://download.oracle.com/docs/cd/E15523_01/web.1111/e13729/toc.htm

Create Standard JMX MBeans

Creating standard MBeans is a three step process.

Create an MBean Interface
Implement the MBean
Register the MBean with the Runtime MBean Server

Configuration settings should be persisted, see "Use the Configuration Store to Persist Values".

Create an MBean Interface

The first thing you need to do is to create an interface file that describes getter and setter methods for each class attribute that is to be exposed through JMX (getter only for read-only attributes; setter only for write-only) and a wrapper operation for each class method to be exposed. The attribute names should be the case-sensitive names that you wish to see displayed in the UI of the Console extension.

For each read-write attribute define a get and set method that follows this naming pattern: getattribute_name, setattribute_name where attribute_name is a case-sensitive name that you want to expose to JMX clients.
For each read-only attribute define only an is or a get method. For each write-only attribute, define only a set method.
The JavaDoc will be rendered in the console as a description of an attribute or operation. It will render exactly as in the JavaDoc. For example:
```
/**
   * Connects to the simulator
   * @throws ManagementException An exception if the connection failed
   */
  public void connect() throws ManagementException;
```
Will render as:

Description of the illustration exampleopjavadoc.png

Any internal operation or attribute should be annotated with @Internal annotation. This attribute or method will not be shown in the console. Example:
```
@Internal
public String resetStatistics();
```

Indicate optional parameters for the operation by using the @OptionalParam annotation. In the JavaDoc for the operation, explicitly specify which parameters are optional. Example:

/**
    * Gets the alarms matching the specified criteria from the database
    * @param Identifier EDR Identifier
    * @Param Source server name (optional)
    * @Param Severity 0 - Critical, 1- Major, 2 -Minor
    * @Param maxEntries max number of entries
    */
    AlarmData[] getAlarms(long identifier, 
                          @OptionalParam('source')String source,
                          int severity, 
                          int maxEntries) throws ManagementException;

The interface should be named ServiceNameMBean.java. The interface for the example Communication Service provided with the Platform Development Studio is named ExampleMBean.java.

Implement the MBean

Once you have defined the interface, it must be implemented.

You must name your class ServiceNameMBeanImpl.java, based on the interface name. The implementation must extend WLNGMBeanDelegate. This class takes care of setting up notifications and MBean descriptions and all MBean implementation classes must extend it. All MBean implementations must also be public, non-abstract classes and have at least one public constructor. The MBean implementation for the example Communication Service provided with the Platform Development Studio is named ExampleMBeanImpl.java.

The MBean implementation must be a public, non abstract class
The MBean must have at least one public constructor
The MBean must implement its corresponding MBean interface and extend WLNGMBeanDelegate

Register the MBean with the Runtime MBean Server

The MBean must be registered with the Runtime MBean Server in the local WebLogic Server instance. Oracle Communications Services Gatekeeper provides a proxy class for MBean registration:

com.bea.wlcp.wlng.api.management.MBeanManager

The MBean implementation is registered using an ObjectName, and a DisplayName:

registerMBean(Object mBeanImpl, ObjectName objectName, String displayName)

Construct the ObjectName using:

constructObjectName(String type, String instanceName, HashMap properties)

There should be no spaces in the InstanceName or Type. Object names are case-sensitive

If the MBean is a regular MBean, use the conventions as illustrated in Table 16-1.

Table 16-1 MBean ObjectName

The ObjectName convention for extensions	Description
type	Fully qualified MBean Name. MBeanObj.class.getName()
instanceName	Unique name that identifies the instance of the MBean. For example, it can be obtained from serviceContext.getName() The unique name of the MBean. If this is a plug-in that potentially is used on the same server with multiple plug-in instances this should be unique per plug-in instance. It is recommended to use managedPlugin.getId().
properties	HashMap that contains objectName key and value pairs ObjectNameConstants class has set of constants that can be used as keys. Null for non-hierarchical MBeans.

The ObjectName convention for extensions

Description

type

Fully qualified MBean Name.

MBeanObj.class.getName()

instanceName

Unique name that identifies the instance of the MBean. For example, it can be obtained from serviceContext.getName()

The unique name of the MBean. If this is a plug-in that potentially is used on the same server with multiple plug-in instances this should be unique per plug-in instance. It is recommended to use managedPlugin.getId().

properties

HashMap that contains objectName key and value pairs ObjectNameConstants class has set of constants that can be used as keys.

Null for non-hierarchical MBeans.

Example

com.bea.wlcp.wlng:AppName= wlng_nt_sms_px21#5.1,InstanceName= Plugin_px21_short_messaging_smpp, Type=com.bea.wlcp.wlng.plugin.sms.smpp.management.SmsMBean

If the MBean is an MBean that should be the child of a regular MBean, use the conventions as illustrated in Table 16-2.

Table 16-2 MBean ObjectName with hierarchy

The ObjectName convention for extensions	Description
type	Fully qualified MBean Name of the parent MBean. Parent MBeanObj.class.getName()
instanceName	Unique name that identifies the instance of the parent MBean.
properties.key=ObjectNameConstants.LEVEL1_INSTANCE_NAME	properties.value is a unique name that identifies the instance of the MBean
properties.key=ObjectNameConstants.LEVEL1_TYPE	Fully qualified MBean Name: MBeanObj.class.getName()
properties.key=ObjectNameConstants.LEVEL2_INSTANCE_NAME	properties.value is a unique name that identifies the instance of the MBean
properties.key=ObjectNameConstants.LEVEL2_TYPE	Fully qualified MBean Name: MBeanObj.class.getName()

Example

A child MBean, for example HeartBeatConfiguration, can register with the same Level1InstanceName for all instances of the Plug-in (since it is a child, its MBean name depends on the parent's instance:

com.bea.wlcp.wlng:AppName= wlng_nt_sms_px21#5.1,InstanceName= Plugin_px21_short_messaging_smpp, Type=com.bea.wlcp.wlng.plugin.sms.smpp.management.SmsMBean,Level1InstanceName=HeartBeatManager,Level1Type=com.bea.wlcp.wlng.heartbeat.management.HeartbeatMBean

com.bea.wlcp.wlng:AppName= wlng_nt_multimedia_messaging_px21#5.1,InstanceName Plugin_px21_multimedia_messaging_mm7, Type= com.bea.wlcp.wlng.plugin.multimediamessaging.mm7.management.MessagingManagementMBean,Level1InstanceName=HeartBeatManager,Level1Type=com.bea.wlcp.wlng.heartbeat.management.HeartbeatMBean

Use the Configuration Store to Persist Values

The Oracle Communications Services Gatekeeper Configuration Store API provides a cluster-aware write-through database cache. Parameters stored in the Configuration Store are both cached in memory and written to the database. The store works in two modes: Local and Global. Values stored in the Local store are of interest only to a single server instance, whereas values stored in the Global store are of interest to all servers cluster-wide. Updates to a value in the Global store update all cluster nodes. The example Communication Service provides a handler class, ConfigurationStoreHandler, that gives an example of both usages of the Configuration Store API.

Note:

The configuration store supports only Boolean, Integer, Long, and String values.