Introduction

WebSphere^TM Application Server V5 has at its core a Java^TM Management Extensions (JMX) MBeanServer that provides a standard interface to manage the application server components that are defined by the set of MBeans shipped with the product. These MBeans are adequate for administering the features that are included in WebSphere Application Server. But what if you have a new WebSphere application that requires new administration functions that you would like to integrate with the existing WebSphere administration functions shipped with the product? That is the subject of Part 4 in this article series on System Administration for WebSphere Application Server V5.

Back to top

Accessing the embedded JMX MBeanServer

As mentioned in Part 1 and Part 2 of this series, WebSphere Application Server V5 administration is built around the JMX specification. Every WebSphere Application Server process includes an embedded JMX Agent. The main aspect of the JMX Agent is the MBeanServer that serves as a registry of the management interfaces (MBeans) that are available within the local JVM. Figure 1 shows this internal JMX architecture for a single Java Virtual Machine. The embedded JMX MBeanServer for WebSphere processes can be accessed and used to register your own MBeans directly.

The following is an example of how code, running within a WebSphere Application Server process, can access the embedded MBeanServer and register its own MBean:

In this example, myObjectReference is a variable holding a reference to the implementation of your MBean, and myObjectName is the JMX ObjectName that this MBean will be registered to, and by which it will be identified. The registerMBean method is just the standard method defined by the JMX specification. Note that a reference to the embedded WebSphere MBeanServer can also be obtained by using the standard JMX MBeanServerFactory findMBeanServer API.

While this approach of accessing the embedded JMX MBeanServer and using its standard API is the most simple to implement, it is not the recommended approach for extending the WebSphere administration infrastructure for reasons that will be discussed later in this article.

Back to top

Java 2 security requirements

If you run WebSphere Application Server with Java 2 Security enabled, the code sample above will throw an exception because the embedded JMX code is protected against use by any non-privileged code base. What this means is that in order to use JMX code in a WebSphere Application Server process (indeed, in order to use any WebSphere administration APIs at all), you must grant your code the necessary permissions in a policy file read by the Java 2 Security infrastructure. The JMX code in WebSphere Application Server is protected by two layers of permissions:

• WebSphere management permissions that include com.ibm.websphere.security.WebSphereRuntimePermission "AdminPermission" . Without AdminPermission , your code cannot execute the method on the AdminServiceFactory to obtain a reference to the MBeanFactory instance for this server, as shown in the example above.
• Tivoli^TM TMX4J permissions, which include com.tivoli.jmx.MBeanServerPermission "MBeanServer.*" and "MBeanServerFactory.*" .

The following is an example of a policy stanza that you could add to the was.policy file for your application, if it contained code that accessed the embedded JMX MBeanServer.

Back to top

WebSphere-specific ObjectName key properties

The WebSphere Application Server administration infrastructure provides some important extensions to the standard, single JVM architecture specified by JMX. In addition to greater security protections, one of the ways WebSphere extends standard JMX is by providing multi-node, multi-process, distributed MBean request routing and event notification. Part of what makes this distributed extension work is a convention for some special key properties in the ObjectName to be assigned to every MBean registered in the MBeanServer used by WebSphere Application Server.

The table below shows the special key properties that the WebSphere Application Server infrastructure uses, and expects to exist in the ObjectName for an MBean. If these key properties are not set in the MBean ObjectName, the MBean can still be registered in the MBeanServer, but no distributed services provided by WebSphere will be usable for this MBean. Without these key properties the MBean will only be accessible within the JVM where it is registered.

You can create the ObjectName for your MBean to include these key properties with their values set appropriately. Or, you can leverage the components of the WebSphere AdminService to create and register the MBean ObjectName on your behalf, as do all of the runtime MBeans shipped with WebSphere Application Server.

The AdminService components that are used for this are the MBeanFactory and an XML file that contains a description of your MBean. You call the activateMBean method of the MBeanFactory and pass it the XML MBean Descriptor file for your MBean. The MBeanFactory takes care of creating an ObjectName with all the necessary key properties in it (and any other key properties you specify), and registering your MBean with that ObjectName in the MBeanServer. After that, your MBean becomes accessible through the network defined by the entire WebSphere distributed cell.

Back to top

WebSphere XML MBean Descriptors

It's worth spending some time at this point to examine the MBean XML Descriptors.

WebSphere MBean Descriptors declare all of the attributes, operations, and notifications for a given MBean type. The format of the MBean Descriptor file must match what is defined in the MbeanDescriptor.dtd file, which can be found in the properties directory under the root install directory of any WebSphere Application Server V5 installation. The MBeanFactory reads and parses an MBean Descriptor, and creates a JMX ModelMBean with the attributes, operations, and notifications declared in the descriptor. The MBeanFactory creates an ObjectName for the MBean, and then calls back to a specific piece of your code (your RuntimeCollaborator, explained later in this article) for any last minute adjustments before registering the MBean with the MBeanServer.

Figures 2 and 3 show two examples of MBean Descriptor files that will be used by examples in this article:

The MBean Descriptor in Figure 2 declares an MBean type of SnoopMBean that we will use to extend the SnoopServlet with administration capabilities. This MBean:

• supports one attribute: idenitification , which is a read-only string attribute.
• declares one operation: snoopy , which takes a single string parameter.

The MBean Descriptor in Figure 3 declares an MBean type of Voter that:

• supports two attributes:
  • identification , a read-only string attribute (read-only because there is no setMethod defined).
  • age , a read-write integer attribute.
• supports one operation: setBallots , which takes two parameters:
  • an agent name string
  • an array of ballot names.

Back to top

The MBeanFactory and runtime collaborators

Your code needs to call the activateMBean method of the MBeanFactory in order for your MBean XML Descriptor to be parsed and for the MBean to be registered. There are several signatures of the activateMBean method for the WebSphere MBeanFactory. The javadoc for the MBeanFactory interface is part of the public javadoc that can be installed with the WebSphere Application Server, and is also available in the InfoCenter (see Resources ). As you can see from the snippet of javadoc in Figure 4, there are three possible ways to call activateMBean .

All forms of activateMBean take the same first three parameters:

• type - the MBean type to be activated
• collaborator - the RuntimeCollaborator instance to be used with this MBean (more on this later)
• configId - an optional string that identifies the configuration information for the MBean, if applicable.

In addition to these three common parameters, two forms of activateMBean take a descriptor parameter, which identifies the name of the MBean XML Descriptor file and its location on the classpath. A third form of activateMBean takes a keyProperties parameter that allows you to optionally add arbitrary key properties to the ObjectName for the MBean.

Let's add some code to the SnoopServlet sample to activate the SnoopMBean so that we can see how all the pieces come together. Figure 5 shows the code that needs to be added to the SnoopServlet in order to activate the SnoopMBean.

To activate the SnoopMBean (Figure 5):

1. Declare an inner class, Collab that extends the RuntimeCollaborator abstract class, and implements the operations and attributes declared for the MBean in the MBean Descriptor (Figure 2).
2. In the service method for the servlet, obtain a reference to the MBeanFactory using the static getMBeanFactory() method. Create an instance of the collab RuntimeCollaborator , and call the activateMBean method, passing in the necessary parameters.
3. Recompile the servlet. Note that you will also need to add a Java import statement for the package com.ibm.websphere.management.* so that the classes referenced in the code can be located. You will also need to ensure that the admin.jar file from WebSphere Application Server is in the classpath.
4. Place the following three files in the classes directory for the deployed Web application
   ( installedApps\<nodename>\DefaultApplication.ear\DefaultWebApplication.war\
WEB-INF\classes ):
   • SnoopServlet.class (recompiled with new activateMBean code)
   • SnoopServlet$Collab.class (inner class newly defined)
   • SnoopMBean.xml (Figure 2).
5. Stop and restart the DefaultApplication.
6. Point your browser to the Snoop servlet ( http:// hostname :9080/snoop ). Look in the SystemOut.log file for the server and you should see the trace output that the MBean has been activated:

   [3/12/03 23:12:29:260 CST] 3154ece9 SystemOut O SnoopMBean activated.

7. When the MBean has been activated, you can use the wsadmin program to access and manage the MBean. Start wsadmin and enter the commands below (in bold) to obtain a variable reference for SnoopMBean:

   wsadmin> set snoop [$AdminControl queryNames *:*,type=SnoopMBean] WebSphere:cell=bluehill,name=snoopMBeanId,mbeanIdentifier=snoopMBeanId, type=SnoopMBean,node=bluehill,process=server1 wsadmin> $AdminControl getAttributes $snoop {identification snoopy} wsadmin> $AdminControl invoke $snoop snoopy lookit

   
   

8. After invoking the snoopy operation on the MBean, look back in the SystemOut.log file for the server and you will see:

   [3/12/03 23:14:13:850 CST] 26856cef SystemOut O paramater is: lookit

   which shows that the string lookit , which was passed to the invoke call in wsadmin , was received and used by the SnoopMBean code that implements the snoopy operation.

This example above shows how to activate an MBean implemented in your J2EE application code. Before taking this approach, consider that your MBean will not be registered until some application client (browser or EJB client code) makes the first client request on your application. This may be okay, depending on your scenario, but rather than waiting for the first client request, it is often desireable for the MBean to be activated at server startup time. If this is preferable in your case, the following example shows one way this can be accomplished.

Back to top

ExtensionMBean Providers

An ExtensionMBeanProvider is a code library that supplies a WebSphere MBean Descriptor and its associated code to implement the functions declared in the MBean Descriptor. Adding the configuration information for an ExtensionMBeanProvider library to a WebSphere Application Server will help the server's MBeanFactory locate the MBean descriptor file so it can be loaded and parsed.

Follow these general steps to add the ExtensionMBeanProvider configuration and the actual Extension MBean:

1. The link to the admin console page for defining an ExtensionMBeanProvider is in the Additional Properties section of the server's Administration Services console page (Figure 6).

1. Select the Extension MBean Providers link. There are no Extension MBean Providers defined by default, so this page will initially be empty. To define a new Extension MBean Provider, select New . The information you will enter to define the new provider is:
   • Classpath (optional, but recommended) - This allows the classloader used by the MBeanFactory to locate the classes and XML MBean Descriptor file, if your code is not already placed in one of the default locations on the server's classpath (such as the /classes directory under the installation root).
   • Description (optional) - Any useful text that can help distinguish this Extension MBean Provider from others.
   • Name (required) - the name to use for identifying this specific Extension MBean Provider within the configuration. This name does not have to be related to the actual MBean type or name itself, since this name only identifies the Extension MBean Provider configuration data.
2. Figure 7 shows the Extension MBean Provider, named VoterMBeanProvider , being defined for this example. Our example MBean code and WebSphere XML MBean Descriptor file are stored in the JAR file located at /build/newmbean/newmbean.jar .

1. Select Apply to store this new Extension MBean Provider definition in your temporary configuration workspace. You can Save the definition from your temporary workspace to the master configuration repository after applying it, or you can wait until you have completed defining the Extension MBean that is supplied by this provider.
2. Once the Extension MBean Provider definition has been applied (whether saved to the master repository or not), it will show up in the Extension MBean Providers page for this server (Figure 8). You can now create the actual MBean definition. To do this, click on the link for the newly defined provider to return to the configuration page.

1. Figure 9 shows the Extension MBean Provider page for the new Voter MBean Provider. Select the ExtensionMBeans link at the bottom of the page to define the Voter MBean that this provider supports.

1. The list of Extension MBeans that displays will initially be empty. Select New to define a new MBean for this provider. See Figure 10.

1. An Extension MBean definition requires two pieces of information:
   • descriptorURI - the location, relative to the provider classpath, where the MBean XML Descriptor file is located. Since we will put the descriptor file in the root of our JAR file, the value for our example is simply the name of the file, VoterMBean.xml .
   • type - the type to be used for registering this MBean. This must match the type declared in the MBean descriptor file which, in our example, is Voter .
2. Select Apply to add the new MBean definition to your temporary configuration workspace, and then Save the change to the master configuration repository. Once the changes have been saved, the definition of the new Extension MBean should look like Figure 11.

1. The result of adding the new Extension MBean Provider and Extension MBean definition will be an entry in the server.xml file that looks like the following:

Now that the configuration data for the Extension MBean Provider and Extension MBean have been added, the code that calls the WebSphere MBeanFactory to activate this MBean will not need to make sure that the XML MBean descriptor file is in the classpath for the process. However, there still needs to be code on the server that calls the activateMBean method in the first place. There are several possible approaches for activating the Extension MBean:

• You could simply put it in your J2EE application code and wait until an application client request first comes in for your application.
• You could employ a startup servlet or startup bean with your application, so that the Extension MBean is activated when your application is started.
• You can also use a WebSphere CustomService to extend the server run time itself with a piece of code that activates the MBean. In fact, the CustomService could even be the implementation of your MBean if that arrangement fits your situation.

The next section illustrates an example of using a CustomService to activate the Extension MBean.

Back to top

CustomServices and JMXManageable interfaces

A CustomService is a piece of code that extends the WebSphere Application Server run time, regardless of whether this piece of code has a JMX MBean to represent its management interface. CustomServices were supported in WebSphere Application Server, Version 4.0, and have been enhanced for easier JMX support in V5. To develop a CustomService, you need to create a class that implements the com.ibm.websphere.runtime.CustomService interface. This interface has two methods:

• initialize - called by the server run time during startup
• shutdown - called by the server run time during normal shutdown processing.

The CustomService interface is very simple, as illustrated below.

When you add the definition of your CustomService to a server configuration, the server run time will call the initialize method of your CustomService during server startup (call the shutdown method of your CustomService during server shutdown). Your CustomService code effectively becomes an extension of the server run time.

Using a CustomService is a good way to add an MBean to the system. The logic in a CustomService is executed during server startup and can activate an MBean without requiring some external application client to make a request to the server. To make the use of JMX even easier for CustomServices, WebSphere Application Server V5 supports the JMXManageable interface. If the class that implements the CustomService interface also claims to implement the JMXManageable interface, then much of the loading and activating of your MBean will be automatic.

To set up a CustomService:

1. First, you must define the new CustomServices. On the WebSphere Application Server admin console, select the Custom Services link from the Additional Properties section (Figure 12).
2. Select New on the Custom Services page to create a new CustomService definition. Figure 13 shows the CustomService configuration settings for this example.

1. The important configuration values for Custom Services:
   • Startup - very important; unless this box is checked, the Custom Service will not be initialized during server startup.
   • External Configuration URL - optional URL to a file that contains configuration data for this Custom Service. This data can be in any format you want, depending on the implementation of your Custom Service logic.
   • Classname (required) - Provides the fully-qualified package name and class name for the class that implements the CustomService interface. The server will load this name during startup and invoke this name to initialize.
   • Display Name (required) - Identifies the configuration of this service.
   • Description - Any text that is useful to distinguish this Custom Service from others.
   • Classpath (required) - The location of the JAR file containing the implementation code for this Custom Service.

1. Select Apply to add this new Custom Service definition to the configuration, then Save to save the change to the master configuration repository. When you return to the Custom Services page for this server, you should see a new Custom Service, as shown in Figure 14.

Back to top

Example code: Distributed WebSphere Extension MBean

The configuration for our CustomService and Extension MBean is now complete. It is now time time to look at the implementation code.

Here's a general explanation of the code flow:

• Lines 1 through 10: package, import, and class declaration statements.
• Lines 12 through 21: implement the two methods defined by the CustomService interface. In this example, they simply print out a trace to show that the code is actually executed during server startup and shutdown.
• Lines 22 through 33: implement the two methods defined by the JMXManageable interface. The type of this MBean has been declared as Voter so that is what the getType method returns.
• Lines 35 through 40: implement the getter method for the read-only identification MBean attribute declared in the MBean Descriptor shown earlier.
• Lines 41 through 50: implement the getter and setter methods for the read-write age attribute.
• Lines 52 through 57: implement trivial logic for the setBallots operation declared for this MBean.

After this code is compiled and packaged in the JAR file (located at /build/newmbean/newmbean.jar , as specified in the example configuration), start up the server that is configured to include this extension. After the server has completed initialization, look in the server's SystemOut.log file. You should see the following trace from the CustomService initialization:

Now, execute the wsadmin WebSphere administrative scripting program to prove that the system has been extended with a new MBean, and to manage that MBean using WebSphere administration tools. From the wsadmin prompt, enter:

An ObjectName for your Voter Extension MBean should be returned:

Store that ObjectName in a Tcl variable:

You should see the same long ObjectName returned from this command as the previous one. Now, check to see what the wsadmin built-in $Help function can tell us about this new MBean. Enter:

You should see something like the following:

Name: "WebSphere:cell=bluehill,Identification=voter1,name=Voter Service,mbeanIde
ntifier=cells/bluehill/nodes/bluehill/servers/server1/server.xml#CustomService_1
,type=Voter,node=bluehill,process=server1"
Description: null
Class name: javax.management.modelmbean.RequiredModelMBean

AttributeTypeAccess
identification java.lang.String RO
ageint RW

Operation
java.lang.String getIdentification()
int getAge()
void setAge(int)
void setBallots(java.lang.String, [Ljava.lang.String;)

Notifications
jmx.attribute.changed

Constructors

What this means is that the meta information about the MBean declared in the MBean Descriptor file was successfully parsed and registered with the system. Note that the identification attribute is read-only and the age attribute is read-write. Now let's manipulate the live MBean executing in the server.

You should see the two attributes for the MBean:

To alter an attribute in the running memory of the MBean dynamically:

Check that the change took effect:

You can continue to use wsadmin to manage the new Extension MBean. Look in the SystemOut.log file again to see the traces from the various MBean implementation methods being called as a result of wsadmin commands:

You have now extended the WebSphere Application Server V5 administration infrastructure with a new MBean that was implemented as a server extension CustomService. There are many directions you can go in from here, enhancing the features of this Extension MBean.

Back to top

Conclusion

In this article, we covered the details involved in extending the WebSphere administrative system with your own JMX MBean. Whether the new administrative logic is associated with a J2EE application or some other server extension, such as a CustomService, the use of JMX by WebSphere Application Server V5 makes the system accessible and easy to extend in a standard way.

Please continue to look for other articles in this series on WebSphere Application Server administration. Planned future topics include:

• How to use the WebSphere 5.0 ConfigService APIs.
• How to programmatically install and manage your applications.
• How to use Jython as the scripting language for wsadmin .

Let us know what subjects you would like to see covered in a future article.

Back to top

Download

Name	Size	Download method
newmbean.ZIP	0.1 MB	FTP|HTTP

Information about download methods

Resources

• WebSphere Application Server V5 InfoCenter
  • WebSphere Application Server javadoc
  • JMX javadoc (from Tivoli's TMX4J JMX implementation)
  • WebSphere MBean javadoc
  
  
  
• Java Management Extensions home page
  
  
• Tivoli TMX4J JMX implementation
  
  
• JMX books:
  • JMX: Managing J2EE with Java Management Extensions
  • Java Management Extensions
  
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Accessing the embedded JMX MBeanServer
• Java 2 security requirements
• WebSphere-specific ObjectName key properties
• WebSphere XML MBean Descriptors
• The MBeanFactory and runtime collaborators
• ExtensionMBean Providers
• CustomServices and JMXManageable interfaces
• Example code: Distributed WebSphere Extension MBean
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers