bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming Management Applications

Developing Management Applications

The following sections describe how to create a management application that monitors run-time activity on a WebLogic Integration B2B engine:

- Working with Management Tools

- Working with MBeans and the MBean Server

- Programming Management Applications

Working with Management Tools

The WebLogic Integration B2B Console provides run-time monitoring of B2B integration activities. If you want additional tools, you can create custom management applications that provide the same monitoring information displayed by the B2B Console.

For example, custom management applications may be desirable for the following reasons:

- 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 B2B integration

- Some administrative tasks, such as shutting down a particular delivery channel or WebLogic Server, or leaving or terminating a particular conversation

Note: Custom management applications cannot update the WebLogic Integration repository. To update the repository, use one of the following tools:

- WebLogic Integration B2B Console, as described in the Online Help for the WebLogic Integration B2B Console

- Bulk Loader, as described in Working with the Bulk Loader in Administering B2B Integration

Working with MBeans and the MBean Server

WebLogic Integration provides the application programming interfaces (APIs) needed to create custom management applications that monitor run-time activity on B2B engines. The B2B Console 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 Package

WebLogic Integration provides the com.bea.b2b.management package for creating custom management applications. This package provides the following:

- MBeans that enable you to monitor run-time activity on B2B engines

- The ManagementException class for handling errors that occur in a run-time management application

For detailed information about this package, see the BEA WebLogic Integration Javadoc.

In this release, all MBeans are implemented as Standard MBeans, which make up a class that implements its own MBean interface. WebLogic Integration MBeans are not implemented as remote MBeans. Therefore all management applications must reside on the B2B engine being monitored.

MBeans

The following table describes the WebLogic Integration MBeans.

Table 2-1 WebLogic Integration MBeans

Label | Description
--- | ---
WLCMBean | Represents an instance of B2B integration. Used for monitoring that instance at run time.
DeliveryChannelMBean | Represents a delivery channel. Used for monitoring delivery channels on a B2B integration system at run time.
ConversationMBean | Represents a business conversation managed by the Transaction Manager on the B2B integration instance. Used for monitoring active transactions within a delivery channel.
TradingPartnerSession MBean | Represents a session with a trading partner. Used for monitoring trading partners.
MessageMBean | Represents a message in a conversation. Used for monitoring messages.
CollaborationAgreementMBean | Represents a collaboration agreement. A collaboration agreement represents a technical agreement between two parties on how they plan to communicate with each other using a specific protocol.

Note: For WebLogic Integration Releases 2.1 and 7.0, and BEA WebLogic Collaborate 2.0, all MBeans are centralized in this package. In previous versions of WebLogic Collaborate, MBeans are split between the c-hub and c-enabler packages. If you are upgrading from WebLogic Collaborate 1.0 or 1.0.1, you must modify any management applications you have written to make use of the new MBeans. The following table outlines changes between Release 1.x MBeans and Release 2.x MBeans.

Table 2-2 MBean Labels

Release 1.x Label | Release 2.x Label
--- | ---
EnablerMBean | WLCMBean
HubMBean | WLCMBean
CSpaceMBean | DeliveryChannelMBean
ConversationMBean | ConversationMBean
GlobalConversationMBean | ConversationMBean
EnablerSessionMBean | TradingPartnerSessionMBean
CollaboratorMBean | TradingPartnerSessionMBean
MessageMBean | MessageMBean

MBean Server Implementation

When your applications uses an MBean, WebLogic Integration registers the MBean with the MBean Server instance that is created when a WebLogic Server instance starts. For more information about the WebLogic Server MBean Server, see Using WebLogic Server JMX Services at the following URL:

>     http://e-docs.bea.com/wls/docs70/jmx/index.html

Programming Management Applications

To access WebLogic Integration MBeans using the JMX API, a Java application must perform the following steps:

- Step 1: Import the Necessary Packages

- Step 2: Get a Reference to the MBeanServer 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

If you If you want to find info, you need an app that loops through all the nodes in the cluster. Each indiv node should function as standalone node. You have to do iterating

Note: If you are deploying your management application in a multinode cluster, you application needs logic that loops through all the nodes individually. Regarding management applications, each machine continues to function as a a standalone node.

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 2-3 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 packages are required: javax.naming.Context javax.naming.InitialContext
com.bea.b2b.management.* | Required for all management applications.
weblogic.management.* | Required for all management implementations. Gets MBeanServer and MBeanHome.

The code in the following listing imports the necessary packages for a management application.

Listing 2-1 Importing Packages for a Management Application

>     import javax.management.*;
>     import javax.naming.Context;
>     import javax.naming.InitialContext;
>     import com.bea.b2b.management.*;
>     import weblogic.management.*;

Step 2: Get a Reference to the MBeanServer Object

WebLogic Integration uses the MBeanS erver that is instantiated when an instance of WebLogic Server is started. To get a reference to the MBean Server, the MBeanHome of that server is required. The MBeanHome of the MBean Server is available from the server's JNDI tree at:

>     weblogic.management.MBeanHome.JNDI_NAME.serverName

An administration server publishes an MBeanHome for each server in the domain on its JNDI tree. The administration MBeanHome is available only from the JNDI tree of the administration server at:

>     weblogic.manageme nt.MBeanHome.ADMIN_JNDI_NAME

The underlying MBean Server for any MBeanHome can be obtained by invoking the getMBeanServer() method on that MBeanHome.

The following code shows an example of a JNDI lookup for the administration server MBeanHome.

Listing 2-2 Getting a Reference to the MBean Server Object

>     import javax.naming.Context;
>     import javax.naming.NamingException;
>     import javax.naming.AuthenticationException;
>     import javax.naming.CommunicationException;
>     import weblogic.jndi.Environment;          ...
>     import weblogic.management.MBeanHome;
>              ...
>         MbeanHome home = null;
>         try {
>           Environment env = new Environment();
>           ctx = env.getInitialContext();
>           home = (MBeanHome) ctx.lookup(MBeanHome.ADMIN_JNDI_NAME);
>           RemoteMBeanServer server = home.getMBeanServer();
>         }
>         catch (AuthenticationException e) {
>             ... //Error handling
>         } catch (CommunicationException e) {
>             ... //Error handling
>         } catch (NamingException e) {
>             ... //Error handling
>         }

Step 3: Construct an ObjectName Object

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

For WebLogic Integration Releases 7.0 and 2.1, and WebLogic Collaborate 2.0, only WLCMBean is registered with the MBean Server; all other MBeans can be retrieved from WLCMBean. WLCMBean has three attributes: a name, a type, and a domain. These attributes are reflected in the MBean's JMX Object Name. The Object Name is the unique identifier for a given MBean across all domains, and has the following structure:

>     domain name:Name=name,Type=type[,attr=value]...

The value of name is unique for a given domain and a given type. For example:

>     mydomain:Name=WLC,Type=WLC
>     ObjectName objectName = new ObjectName("WLC", "WLC", "mydomain");

For MBeans, object names can also be used for query operations in which object name expressions are used. 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.

Step 4: Query the MBean Server

After constructing an object name expression, an application queries the MBean Server by passing the ObjectName object corresponding to the expression. To retrieve the set of registered MBeans, the names of which 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; they are not direct references to the MBeans themselves.

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 of the MBean type. To read the attributes of an MBean, use the following method, passing the ObjectName object as a parameter:

>     javax.management.MBeanServer.getAttribute()

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

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

Listing 2-3 Retrieving Conversation Attributes

>     MBeanHome home = Admin.getMBeanHome();
>     server = home.getMBeanServer();
>     ObjectName objectName = new ObjectName("WLC", "WLC", "mydomain");
>     beans = server.queryNames(objectName, null);
>     Iterator it = beans.iterator();
>     while (it != null && it.hasNext())
>     {
>      //Should be only one
>       obj = (ObjectName)it.next();
>       break;
>     }
>     if (obj != null)
>     {
>       Date startTime = (Date)server.getAttribute(obj, "ActiveSince");
>       Date lastTime = (Date)server.getAttribute(obj, "LastMessageSentTime");
>       ConversationMBean[] convs = (Conversation[]) server.getAttribute(obj,
>          "ActiveConversations");
>        if (convs != null)
>        {
>          for (int ii=0; ii< convs.length; ii++)
>          {
>             String protocol = convs[ii].getBusinessProtocolName();
>           }
>         }
>      }
>     ...

All the attributes shown in the preceding code listing can be retrieved by calling getAttribute. To invoke a method such as shutDown on WLCMBean, call the MBean Server. For more information see the JMX specification at the following URL:

http://java.sun.com

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 exact MBean types. For example, the WLCMBean.getActiveDeliveryChannels() method returns an array of type DeliveryChannelMBean that represents all the active delivery channels in the system. Similarly, the TradingPartnerSessionMBean.getActiveConversations() method returns an array of type ConversationMBean that represents all the active conversations in this session.

For detailed information about these methods, see the BEA WebLogic Integration Javadoc.

Step 7: Handle Exceptions

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

Listing 2-4 Handling ManagementExceptions in Management Applications

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