Developing Management Applications

 

The following sections describe how to create WebLogic Collaborate management applications that monitor run-time activity on c-hub and c-enabler nodes:

• About Management Applications

• Programming Steps for Management Applications

The WebLogic Collaborate C-Hub Administration Console and the C-Enabler Administration Console tools provide run-time monitoring of c-hub and c-enabler activities. In addition to these standard tools, developers can create custom management applications that provide the same monitoring information that appears in the administration console tools.

These custom management applications can provide read-only access to real-time statistics, such as the number of messages exchanged in a particular conversation or the number of messages received by the c-hub. In addition, these custom applications can perform certain administrative tasks programmatically, such as shutting down a particular c-space or the c-hub (in c-hub management applications) or leaving or terminating a particular conversation (in c-enabler management applications).

Note: Configuring the c-hub repository requires the C-Hub Administration Console. Custom management applications cannot perform configuration tasks.

 

---

About Management Applications

The following sections describe management applications in WebLogic Collaborate:

• MBeans and the MBean Server

• C-Hub MBeans

• C-Enabler MBeans

• Configuration Requirements

MBeans and the MBean Server

WebLogic Collaborate provides developers with the application programming interfaces (APIs) needed to create custom management applications that monitor run-time activity on c-hub and c-enabler nodes. The C-Hub Administration Console and the C-Enabler Administration Console tools also use these APIs to provide real-time monitoring information.

These APIs consist of sets of Java Management Extensions (JMX) Managed Beans, or MBeans, which are special JavaBeans with attributes and methods for management operations. For more information about JMX, particularly the use of the JMX API (including the MBean Server and MBeans), see the Java Management Extensions Specification published by Sun Microsystems, Inc., at the following URL:

http://www.java.sun.com/products/JavaManagement/index.html

MBean Packages

WebLogic Collaborate provides the following packages for creating custom management applications.

Table 5-1 Packages for WebLogic Collaborate Management Applications

Package	Description
com.bea.b2b.management	Provides the ManagementException class for handling errors that occur when running a management application.
com.bea.b2b.management.hub.runtime	Provides c-hub MBeans used for creating management applications that monitor run-time activity on c-hub nodes.
com.bea.b2b.management.enabler.runtime	Provides c-enabler MBeans used for creating management applications that monitor run-time activity on c-enabler nodes.

 

For detailed information about these packages, see the Javadoc on the WebLogic Collaborate documentation CD or in the classdocs subdirectory of your WebLogic Collaborate installation.

Note: In this release, all MBeans are implemented as Standard MBeans, which is a class that implements its own MBean interface.

MBean Server Implementation

WebLogic Collaborate provides an implementation of the JMX MBean Server component that serves as a repository for MBeans.

• The c-hub MBeans are registered with the MBean Server running inside the c-hub. When c-hub MBeans are created, WebLogic Collaborate populates their attributes from settings in the c-hub repository.

• The c-enabler MBeans are registered with the MBean server running inside the c-enabler. When c-enabler MBeans are created, WebLogic Collaborate populates their attributes from settings in the c-enabler XML configuration file.

At run time, WebLogic Collaborate updates the MBean attributes to reflect the state of the running system.

Note: C-enablers that are co-located with the c-hub or with other c-enablers share the same MBean Server instance. If a c-enabler runs in WebLogic Server without a co-located hub, it will have its own local MBean server.

C-Hub MBeans

The com.bea.b2b.management.hub.runtime package contains the WebLogic Collaborate c-hub MBeans, which are described in the following table.

Table 5-2 Managed Beans in the C-Hub MBeans

Label	Description
HubMBean	Represents a c-hub. Used for monitoring a c-hub at run time.
CSpaceMBean	Represents a c-space. Used for monitoring c-spaces on the c-hub at run time.
GlobalConversationMBean	Represents an instance of a global conversation managed by the Conversation Manager on the c-hub. Used for monitoring active conversations within a c-space.
CollaboratorMBean	Represents a trading partner in a c-space. Used for monitoring trading partners in the c-space.
MessageMBean	Represents a message in a conversation. Used for monitoring messages in the c-space.

 

C-Enabler MBeans

The com.bea.b2b.management.enabler.runtime package contains the WebLogic Collaborate c-enabler MBeans, which are described in the following table.

Table 5-3 Managed Beans in the C-Enabler MBeans

Label	Description
EnablerMBean	Represents a c-enabler. Used for monitoring the c-enabler at run time.
ConversationMBean	Represents a conversation. Used for monitoring active conversations in which the c-enabler is involved.
EnablerSessionMBean	Represents a c-enabler session. Used for monitoring active c-enabler sessions on the c-enabler.
MessageMBean	Represents a message in a conversation. Used for monitoring messages in the c-enabler.

 

Configuration Requirements

To use the WebLogic Collaborate MBeans, make sure that the following file is included in the CLASSPATH:

lib\jmxri.jar

Note: Be sure to use the Javasoft implementation of this file.

 

---

Programming Steps for Management Applications

The steps for using MBeans to develop management applications for c-hubs and c-enablers are nearly identical. To access WebLogic Collaborate MBeans using the JMX API, a Java application must complete the following steps:

• Step 1: Import the Necessary Packages

• Step 2: Get a Reference to the MBean Server Object

• Step 3: Construct an ObjectName Object

• Step 4: Query the MBean Server

• Step 5: Read the Attributes of the MBean

• Step 6: Navigate Across MBeans

• Step 7: Handle Exceptions

The C-Hub and C-Enabler Administration Consoles use the JMX API and WebLogic Collaborate MBeans to monitor running c-hubs and c-enablers, respectively.

Step 1: Import the Necessary Packages

To work with MBeans, a management application must import the necessary packages. At a minimum, the application must import the packages described in the following table.

Table 5-4 Packages that Must Be Imported

Label	Description
javax.management.*;	Required for JMX MBeans, as mandated in the Java Management Extensions Specification published by Sun Microsystems, Inc.
javax.naming.*;	Required for retrieving the MBean server object using JNDI lookup. Only the following are required: javax.naming.Context javax.naming.InitialContext
com.bea.b2b.management.ManagementException	Required for handling exceptions in all management applications.
com.bea.b2b.management.hub.runtime.*	Required for c-hub management applications.
com.bea.b2b.management.enabler.runtime.*	Required for c-enabler management applications.

 

C-Hub Example

The code in the following listing imports the necessary packages for c-hub management applications.

Listing 5-1 Importing Packages for C-Hub Management Applications

import javax.management.*;
import javax.naming.Context;
import javax.naming.InitialContext;
import com.bea.b2b.management.ManagementException;
import com.bea.b2b.management.hub.runtime.*;

C-Enabler Example

The code in the following listing imports the necessary packages for c-enabler management applications.

Listing 5-2 Importing Packages for C-Enabler Management Applications

import javax.management.*;
import javax.naming.Context;
import javax.naming.InitialContext;
import com.bea.b2b.management.ManagementException;
import com.bea.b2b.management.enabler.runtime*;

Step 2: Get a Reference to the MBean Server Object

To get a reference the MBean server object, a management application calls the findMBeanServer method on the MBeanServerFactory object, as shown in the following listing.

Listing 5-3 Getting a Reference to the MBean Server Object

MBeanServer server = null;
ArrayList mbsList = MBeanServerFactory.findMBeanServer("WLC"); 
if (mbsList.size() > 0) { 
      server = (MBeanServer)mbsList.get(0); 
}

Step 3: Construct an ObjectName Object

MBeans are uniquely identified by object names inside the MBean server. The ObjectName class represents an object name.

Object Names

An object name consists of two parts:

• Domain Name. For all MBeans in WebLogic Collaborate, the domain name is the same:

  WLC

• Key property list. Enables you to assign unique names to the MBeans of a given domain. The WebLogic Collaborate MBeans have the following key properties:

  Table 5-5 Key Properties

  Property	Description
  type	Name of the MBean interface. For c-hub management applications, one of the following values: HubMBean CSpaceMBean CollaboratorMBean GlobalConversationMBean MessageMBean For c-enabler management applications, one of the following values: EnablerMBean EnablerSessionMBean ConversationMBean MessageMBean
  name	Unique identifier of the MBean.
  subsystem	Unique identifier of the subsystem. For c-hubs, use the following format: hub.<hubName> For c-enablers in conjunction with EnablerMBeans and MessageMBeans, use the following format: enabler. For c-enablers in conjunction with EnablerSessionMBeans and ConversationMBeans, use the following format: enabler.<enablerName> The enablerName extension uniquely identifies the specific c-enabler in the conversation. This is needed because a c-enabler can participate in the same conversation in two different roles using two different c-enabler sessions.

   

C-Hub Example

For example, a CSpaceMBean could have the following object name:

WLC:type=CSpaceMBean,* 

C-Enabler Example

Similarly, an EnablerMBean could have either of the following object names:

WLC:type=EnablerMBean,*

WLC:type=EnablerMBean,subsystem=enabler,*

Object Name Expressions

For MBeans, object names can be also used for query operations that use object name expressions. The MBean server uses pattern matching on the object names of the registered MBeans. The matching syntax is consistent with file globing, which is described in the Java Management Extensions Specification published by Sun Microsystems, Inc.:

• An asterisk (*) matches any character sequence.

• A question mark (?) matches a single character.

C-Hub Example

For example, the following object name expression will match the object names of all registered CSpaceMBeans.

WLC:type=CSpaceMBean,name=*

C-Enabler Example

Similarly, the following object name expression will match the object names of all registered EnablerMBeans.

WLC:type=EnablerMBean,name=*

Step 4: Query the MBean Server

After constructing an object name expression, an application queries the MBean server by passing in the ObjectName object corresponding to the expression. To retrieve the set of registered MBeans whose names satisfy an object name expression, use the following method:

javax.management.MBeanServer.queryNames()

The MBean server returns a set of objects that satisfy the query criteria. Note that these are ObjectName objects that represent MBeans, not direct references to the MBeans themselves.

C-Hub Example

The code in the following listing retrieves a set of ObjectName objects that represent the CSpaceMBeans associated with registered c-spaces on the c-hub.

Listing 5-4 Retrieving Registered CSpaceMBeans

if (server != null) {
    ObjectName queryObjName = new ObjectName("WLC:type=HubMBean,*");
    // beans is a set of ObjectName objects
    beans= server.queryNames(queryObjName, null);
  }

  if (null == beans)
    noCsps = true;
  else {
    Iterator it = null;
    it = beans.iterator();
    csps = new ArrayList();
    while (it != null && it.hasNext()) {
      ObjectName objname = (ObjectName)it.next();
      hubObj = objname.toString();
      cspbeans = (CSpaceMBean[])server.getAttribute(objname , "CSpaces");
      for (int c=0; c < cspbeans.length; c++)
        csps.add(cspbeans[c]);
    }

C-Enabler Code Example

The code in the following listing retrieves a set of ObjectName objects that represent active EnablerSessionMBeans on the c-enabler.

Listing 5-5 Retrieving Registered EnablerSessionMBeans

if (server != null)
{
  ObjectName queryObjName = new ObjectName("WLC: subsystem=enabler." + enablerName + ",name=" + sessionName + ",type=EnablerSessionMBean" );
  // beans is a set of ObjectName objects
  beans= server.queryNames(queryObjName, null);
}
Iterator it = beans.iterator();
// Iterate through the EnablerSessionMBeans
while (it.hasNext()){
      ObjectName objName = (ObjectName)it.next();
      // do something 
}

Step 5: Read the Attributes of the MBean

Use the ObjectName instance, obtained in the previous step, to access other MBeans, provided that the ObjectName has one or more attributes whose type is MBean. To read the attributes of an MBean, use the following method, passing the ObjectName object as a parameter:

javax.management.MBeanServer.getAttribute()

Once you call the getAttribute method by passing in the ObjectName object for the first MBean, you can get references directly to other MBean instances.

C-Hub Example

The code in the following listing retrieves a set of attributes associated with a global conversation.

Listing 5-6 Retrieving Conversation Attributes

while ((count < convsPerPage) && (idx < totalConvs)) {
      ObjectName objName = (ObjectName)convs.get(idx);
      String convId = (String) server.getAttribute(objName, "ConversationId");
      CSpaceMBean cspace = (CSpaceMBean) server.getAttribute(objName, "CSpace");
      Protocol protocol = (Protocol)server.getAttribute(objName, "Protocol");
      Date startTime = (Date) server.getAttribute(objName, "ActiveSince");
      Date lastMessage = (Date) server.getAttribute(objName, "LastMessageTime");
      String lastSender = (String) server.getAttribute(objName, "LastSender");
      CollaboratorMBean[] parts = (CollaboratorMBean[]) server.getAttribute(objName, "ActiveCollaborators");
      String checkBoxSuccess = "checkBoxSuccess" + idx;
      String checkBoxFailure = "checkBoxFailure" + idx;
      String regConvId = convId.replace('*','$');
      regConvId = regConvId.replace(':','$');
      regConvId = regConvId.replace('?','$');
      regConvId = regConvId.replace('=','$');
      String checkBoxValue = "WLC:subsystem=hub,name=" + regConvId + ",cspacename=" + cspace.getName() + ",type=GlobalConversationMBean" ;

In this example, server is a reference to the MBean server and objName is a reference to the ObjectName object representing the GlobalConversationMBean.

The application can then iterate through and process the set of GlobalConversationMBean objects as needed. Because it now has direct references to the MBean, the application can use methods on the MBean to retrieve attributes, such as run-time monitoring information.

C-Enabler Example

The code in the following listing retrieves a set of attributes associated with a c-enabler session.

Listing 5-7 Retrieving C-Enabler Session Attributes

Iterator it = beans.iterator();
while (it.hasNext()){
      ObjectName obj = (ObjectName)it.next();
      hubUrl = (String)server.getAttribute(obj, "HubUrl");
      hubProxyHost = (String)server.getAttribute(obj, "ProxyHost");
      hubProxyPort = (String)server.getAttribute(obj, "ProxyPort");
      hubUser = (String)server.getAttribute(obj, "HubUser");
      hubCertField = (String)server.getAttribute(obj, "CertificateFieldName");
      hubCertValue = (String)server.getAttribute(obj, "CertificateFieldValue");
      hubServerCertField = (String)server.getAttribute(obj, "ServerCertificateFieldName");
      hubServerCertValue = (String)server.getAttribute(obj, "ServerCertificateFieldValue");
      enablerUrl = (String)server.getAttribute(obj, "EnablerUrl");
      cSpaceName = (String)server.getAttribute(obj, "CSpaceName");
      tradingPartner = (String)server.getAttribute(obj, "TradingPartnerName");
      certLocation = (String)server.getAttribute(obj, "CertificateLocation");
      privateKeyLoc = (String)server.getAttribute(obj, "PrivateKeyLocation");
}

In this example, server is a reference to the MBean server and objName is a reference to the ObjectName object representing the EnablerSessionMBean.

The application can then iterate through and process the set of EnablerSessionMBean objects as needed. Because it now has direct references to the MBean, the application can use methods on the MBean to retrieve attributes, such as run-time monitoring information.

Step 6: Navigate Across MBeans

MBeans that are logically related have accessor methods to retrieve references to each other. These methods are strongly typed and return an exact MBean type. For example, the CSpaceMBean.getHub() method returns a HubMBean that represents the c-hub associated with that c-space. Similarly, the EnablerSessionMBean.getEnabler() method returns a EnablerMBean that represents the associated c-enabler.

For detailed information about these methods, see the Javadoc on the WebLogic Collaborate documentation CD or in the classdocs subdirectory of your WebLogic Collaborate installation.

Step 7: Handle Exceptions

If an error occurs while running a WebLogic Collaborate management application, a com.bea.b2b.management.ManagementException is thrown. Management applications can catch this exception and process it as appropriate, as shown in the following listing.

Listing 5-8 Handling ManagementExceptions in Management Applications

catch (ManagementException me){
      String msg = "Exception in Management Application: " + me;
      debug(msg);
      throw new Exception(msg);