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 Network Gatekeeper Console extension, or through other management tools. The following chapter provides a description of the mechanism that Network Gatekeeper uses to accomplish this.

Overview

WebLogic Network Gatekeeper uses the Java Management Extensions (JMX) 1.2 standard, as it is implemented in JDK 1.5. The JMX model consists of three layers, Instrumentation, Agent, and Distributed Services. As an 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 Network Gatekeeper Management Console. Finally, because configuration information needs to be persisted, you store the values you set using Network 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.

Create Standard JMX MBeans

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: get<Attribute name>, set<Attribute 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:

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 @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 <ServiceName>MBean.java. The interface for the example Communication Service provided with the Platform Development Studio is named ExampleMBean.java.

Implement the MBean

You must name your class <ServiceName>MBeanImpl.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.

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

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

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 9-1

Table 9-1 MBean ObjectName
The ObjectName convention for extensions
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.

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

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

Table 9-2 MBean ObjectName with hierarchy
The ObjectName convention for extensions
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()

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#4.0,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#4.0,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 Network 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.

Platform Development Studio - Developer’s Guide