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 product
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, see MBean Java application
programming interface (API) documentation. In
this documentation, click .
Procedure
- Create custom JMX MBeans.
You have some alternatives
to select from, when creating MBeans to extend the product 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 product 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 product 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 product administrative system. An
ExtensionMBean provider implies that you supply an XML file that contains
an MBean Descriptor based on the DTD shipped with the product. 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.
- 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 product 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 product 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 product 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
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.