You can extend the WebSphere Application Server administration
system by supplying and registering new Java Management Extensions
(JMX) MBeans (see JMX 1.x Specification for details) in one of the
WebSphere processes.
About this task
JMX MBeans represent the management interface for a particular
piece of logic. All of the managed resources within the standard WebSphere
infrastructure are represented as JMX MBeans. There are a variety
of ways in which you can create your own MBeans and register them
with the JMX MBeanServer running in any WebSphere process. For more
information, view the
MBean API documentation.
- Create custom JMX MBeans.
You have some alternatives
to select from, when creating MBeans to extend the WebSphere administrative
system. You can use any existing JMX MBean from another application.
You can register any MBean that you tested in a JMX MBean server outside
of the WebSphere Application Server environment in a WebSphere Application
Server process, including standard MBeans, dynamic MBeans, open MBeans,
and model MBeans.
In addition to any existing JMX MBeans, and
ones that were written and tested outside of the WebSphere Application
Server environment, you can use the special distributed extensions
provided by WebSphere and create a WebSphere ExtensionMBean provider.
This alternative provides better integration with all of the distributed
functions of the WebSphere administrative system. An ExtensionMBean
provider implies that you supply an XML file that contains an MBean
Descriptor based on the DTD shipped with the WebSphere Application
Server. This descriptor tells the WebSphere system all of the attributes,
operations, and notifications that your MBean supports. With this
information, the WebSphere system can route remote requests to your
MBean and register remote Listeners to receive your MBean event notifications.
All
of the internal WebSphere MBeans follow the Model MBean pattern. Pure
Java classes supply the real logic for management functions, and the
WebSphere MBeanFactory class reads the description of these functions
from the XML MBean Descriptor and creates an instance of a ModelMBean
that matches the descriptor. This ModelMBean instance is bound to
your Java classes and registered with the MBeanServer running in the
same process as your classes. Your Java code now becomes callable
from any WebSphere Application Server administrative client through
the ModelMBean created and registered to represent it.
- Optionally
define an explicit MBean security policy.
If
you do not define an MBean security policy, WebSphere Application
Server uses the default
security policy.
- Register the new MBeans. There are various ways
to register your MBean.
You can register your MBean with the WebSphere
Application Server administrative service.
You can register
your MBean with the MBeanServer in a WebSphere Application Server
process. The following list describes the available options in order
of preference:
- Go through the MBeanFactory class. If you want the greatest possible
integration with the WebSphere Application Server system, then use
the MBeanFactory class to manage the life cycle of your MBean through
the activateMBean and deactivateMBean methods of the MBeanFactory
class. Use these methods, by supplying a subclass of the RuntimeCollaborator
abstract superclass and an XML MBean descriptor file. Using this approach,
you supply a pure Java class that implements the management interface
defined in the MBean descriptor. The MBeanFactory class creates the
actual ModelMBean and registers it with the WebSphere Application
Server administrative system on your behalf.
This option is recommended
for registering model MBeans.
- Use the JMXManageable and CustomService interface. You can make
the process of integrating with WebSphere administration even easier
by implementing a CustomService interface that also implements the
JMXManageable interface. Using this approach, you can avoid supplying
the RuntimeCollaborator. When your CustomService interface is initialized,
the WebSphere MBeanFactory class reads your XML MBean descriptor file
and creates, binds, and registers an MBean to your CustomService interface
automatically. After the shutdown method of your CustomService is
called, the WebSphere Application Server system automatically deactivates
your MBean.
- Go through the AdminService interface. You can call the registerMBean()
method on the AdminService interface and the invocation is delegated
to the underlying MBeanServer for the process, after appropriate security
checks. You can obtain a reference to the AdminService using the getAdminService()
method of the AdminServiceFactory class.
This option is recommended
for registering standard, dynamic, and open MBeans. Implement the
UserCollaborator class to use the MBeans and to provide a consistent
level of support for them across distributed and z/OS platforms.
- Get MBeanServer instances directly. You can get a direct reference
to the JMX MBeanServer instance running in any WebSphere Application
Server process, by calling the getMBeanServer() method of the MBeanFactory
class. You get a reference to the MBeanFactory class by calling the
getMBeanFactory() method of the AdminService interface.
When a custom MBean is registered directly with the
MBean server, the MBean object name is enhanced with the cell, node
and process name keys by default. This registration allows the MBean
to participate in the distributed features of the WebSphere Application
Server administrative system. You can turn off the default behavior
by setting the com.ibm.websphere.mbeans.disableRouting custom
property.
See Administration services custom properties for
more information on how to set and use the com.ibm.websphere.mbeans.disableRouting
custom property.
Results
Regardless of the approach used to create and register your
MBean, you must set up proper
Java 2 security permissions for your new MBean
code. The WebSphere AdminService and MBeanServer are tightly protected
using Java 2 security permissions and if you do not explicitly grant
your code base permissions, security exceptions are thrown when you
attempt to invoke methods of these classes. If you are supplying your
MBean as part of your application, you can set the permissions in
the
was.policy file that you supply as part of your application
metadata. If you are using a CustomService interface or other code
that is not delivered as an application, you can edit the
library.policy file
in the node configuration, or even the
server.policy file
in the
properties directory for a specific installation.