|
|
|
|
|
|
Developing Management Applications
The following sections describe how to create WebLogic Collaborate management applications that monitor run-time activity on WebLogic Collaborate nodes:
Standard and Custom Management Tools
The WebLogic Collaborate Administration Console provides run-time monitoring of WebLogic Collaborate activities. Developers who want additional tools can create custom management applications that provide the same monitoring information displayed by the WebLogic Collaborate Administration Console.
Custom management applications may be desirable, for example, if you want 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 WebLogic Collaborate. In addition, custom applications can perform certain administrative tasks programmatically, such as shutting down a particular delivery channel or WebLogic Server, or leaving or terminating a particular conversation.
Note: To configure the repository, use one of the following tools. Note that custom management applications cannot configure the repository.
About Management Applications
The following sections describe management applications in WebLogic Collaborate:
MBeans and the MBean Server
WebLogic Collaborate provides the application programming interfaces (APIs) needed to create custom management applications that monitor run-time activity on WebLogic Collaborate nodes. The WebLogic Collaborate 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 MBeanServer 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 com.bea.b2b.management package for creating custom management applications. This package provides WebLogic Collaborate MBeans used for creating management applications that monitor run-time activity on server nodes. It also provides the ManagementException class for handling errors that occur in a run-time management application. For detailed information about this package, see the BEA WebLogic Collaborate Javadoc.
In this release, all MBeans are implemented as Standard MBeans, which make up a class that implements its own MBean interface. WebLogic Collaborate MBeans are not implemented as remote MBeans. This means that all management applications must reside on the server being monitored.
MBean Server Implementation
WebLogic Collaborate registers the MBean with the MBeanServer instance that is created when a WebLogic Server instance starts. For more information on the WebLogic Server MBeanServer, see the BEA WebLogic Server Administration Guide at the following URL:
http://download.oracle.com/docs/cd/E13222_01/wls/docs61/adminguide/index.html
MBeans
The com.bea.b2b.management package contains all of the WebLogic Collaborate MBeans, which are described in the following table.
Note: For WebLogic Collaborate Release 2.0, all MBeans are centralized in this package. In previous releases, these MBeans were 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.0 MBeans and Release 2.0 MBeans.
Programming Steps for Management Applications
To access WebLogic Collaborate MBeans using the JMX API, a Java application must perform the following steps:
The WebLogic Collaborate Administration Console uses the JMX API and WebLogic Collaborate MBeans to monitor running WebLogic Collaborate instances.
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.
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 Collaborate uses the MBeanServer that is instantiated when an instance of WebLogic Server is started. To get a reference to the MBeanServer, the MBeanHome of that server is required. The MBeanHome of the MBeanServer 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.management.MBeanHome.ADMIN_JNDI_NAME
The underlying MBeanServer 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 MBeanServer 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 uniquely identified by object names inside the MBeanServer. The ObjectName class represents an object name.
For WebLogic Collaborate Release 2.0, only WLCMBean is registered with the MBeanServer; all other MBeans can be retrieved from WLCMBean. WLCMBean has 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 MBeanServer 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.:
Step 4: Query the MBean Server
After constructing an object name expression, an application queries the MBeanServer 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 MBeanServer 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()
Once 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 MBeanServer. For more information see the JMX specification at the following URL:
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 Collaborate Javadoc.
Step 7: Handle Exceptions
If an error occurs while a WebLogic Collaborate management application is being run, 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);
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|