Oracle® Communications Services Gatekeeper Platform Development Studio Developer's Guide Release 5.1 E37535-01 |
|
|
PDF · Mobi · ePub |
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.
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
Creating standard MBeans is a three step process.
Configuration settings should be persisted, see "Use the Configuration Store to Persist Values".
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:
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.
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
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.
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() |
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
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.