This chapter explains how to make new communications services manageable by Communications Services Gatekeeper.
Once you have created an extension communication service, you must make it manageable by Services Gatekeeper. You do this by exposing the operations and management (OAM) functions, such as read/write attributes and or operations, in a way that allows them to be accessed and manipulated by the Services Gatekeeper Administration Console extension, or other management tools.
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 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. This makes the functionality available to the Distributed Services layer, management tools like the Services Gatekeeper Administration Console. Finally, because configuration information needs to be persisted, you store the values you set using the Services Gatekeeper 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://docs.oracle.com/cd/E24329_01/web.1211/e24416/designapp.htm
Creating standard MBeans is a three step process.
Configuration settings should be persisted, see "Use the Configuration Store to Persist Values".
You must first create an interface file that describes the 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). Also create 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 user interface 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 is rendered in the console as a description of an attribute or operation. It renders exactly as in the JavaDoc. For example:
/** * Connects to the simulator * @throws ManagementException An exception if the connection failed */ public void connect() throws ManagementException;
Renders as:
Any internal operation or attribute should be annotated with @Internal annotation. This attribute or method will not be shown in the console. For eample:
@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. For 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;
Name the interface ServiceNameMBean.java. The interface for the example communication service provided with the Platform Development Studio is named ExampleMBean.java.
Once you have defined the interface, it must be implemented.
You must name your class ServiceNameMBeanImpl.java, based on the interface name, and 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
The MBean must be registered with the Runtime MBean Server in the local WebLogic Server instance. 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 17-1.
com.bea.wlcp.wlng:AppName= wlng_nt_sms_px21#6.0,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 17-2.
Table 17-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() |
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#6.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#6.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
The 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.
The configuration store supports only Boolean, Integer, Long, and String values.