Designing Manageable Applications

Benefits of Oracle Best Practices

Several viable JMX design patterns and deployment options can make your application more manageable. The design patterns that Oracle recommends are based on the assumption that the instrumentation of your Java classes should:

Use as few system resources as possible; management functions must not interfere with business functions.
Be separate from your business code whenever possible.
Deploy along with the business code and share its life cycle; you should not require the operations staff to take additional steps to enable the management of your application.

Use Standard MBeans

Of the many design patterns that JMX defines, Oracle recommends that you use standard MBeans, which are the easiest to code. To use the simplest design pattern for standard MBeans:

Create an interface for the management properties and operations that you want to expose.
Implement the interface in your Java class.
Create and register the MBean in the WebLogic Server Runtime MBean Server by invoking the Runtime MBean Server's javax.management.MBeanServerConnection.createMBean() method and passing your management interface in the method's parameter.

When you invoke the createMBean() method, the Runtime MBean Server introspects your interface, finds the implementation, and registers the interface and implementation as an MBean.

In this design pattern, the management interface and its implementation must follow strict naming conventions so that the MBean server can introspect your interface. You can circumvent the naming requirements by having your Java class extend javax.management.StandardMBean. See StandardMBean in the Java SE 8 API Specification at http://docs.oracle.com/javase/8/docs/api/javax/management/StandardMBean.html.

Registering Custom MBeans in the WebLogic Server Runtime Bean Server

A JVM can contain multiple MBean servers, and another significant design decision is which MBean server you use to register your custom MBeans.

Oracle recommends that you register custom MBeans in the WebLogic Server Runtime MBean Server. (Each WebLogic Server instance contains its own instance of the Runtime MBean Server. See MBean Servers in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.) As of WebLogic Server 10.3.3, the WebLogic Runtime MBean Server is the JVM's platform MBean server. See Registering MBeans in the JVM Platform MBean Server.

With this option:

Your MBeans exist in the same MBean server as WebLogic Server MBeans. Remote JMX clients need to maintain only a single connection to monitor your application's MBeans and WebLogic Server MBeans.
JMX clients must authenticate and be authorized through the WebLogic Server security framework to access your custom MBeans and WebLogic Server MBeans. See Securing Custom MBeans with Roles and Policies.

The WebLogic Server Runtime MBean Server registers its javax.management.MBeanServer interface in the JNDI tree. See Make Local Connections to the Runtime MBean Server in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.

Registering Custom MBeans in the Domain Runtime MBean Server

If you need to register aggregation-type MBeans whose implementation will invoke on other MBeans located in Managed Servers, register those MBeans in the Domain Runtime MBean Server.

The WebLogic Server Domain Runtime MBean Server registers its javax.management.MBeanServer interface in the JNDI tree. See Make Local Connections to the Domain Runtime MBean Server in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.

Use ApplicationLifecycleListener to Register Application MBeans

If you are creating MBeans for EJBs, servlets within Web applications, or other modules that are deployed, and if you want your MBeans to be available as soon as you deploy your application, listen for notifications from the deployment service. When you deploy an application (and when you start a server on which you have already deployed an application), the WebLogic Server deployment service emits notifications at specific stages of the deployment process. When you receive a notification that the application has been deployed, you can create and register your MBeans.

There are two steps for listening to deployment notifications with ApplicationLifecycleListener:

Create a class that extends weblogic.application.ApplicationLifecycleListener. Then implement the ApplicationLifecycleListener.postStart method to create and register your MBean in the MBean server. The class invokes your postStart() method only after it receives a postStart notification from the deployment service. See Programming Application Life Cycle Events in Developing Applications for Oracle WebLogic Server.
In the weblogic-application.xml deployment descriptor, register your class as an application listener class.

If you do not want to use proprietary WebLogic Server classes and deployment descriptors to register application MBeans, see Registering Application MBeans by Using Only JDK Classes.

Unregister Application MBeans When Applications Are Undeployed

Regardless of how you create your MBeans, Oracle recommends that you unregister your MBeans whenever you receive a deployment notification that your application has been undeployed. Failure to do so introduces a potential memory leak.

If you create a class that extends ApplicationLifecycleListener, you can implement the ApplicationLifecycleListener.preStop method to unregister your MBeans. For information on implementing the preStop method, see Register the MBean.

Place Management Logic for EJBs and Servlets in a Delegate Class

If you want to expose management attributes or operations for any type of EJB (session, entity, message-driven) or servlet, Oracle recommends that you implement the management attributes and operations in a separate, delegate class so that your EJB or servlet implementation classes contain only business logic, and so that their business interfaces present only business logic. See Figure 2-1.

Figure 2-1 Place Management Properties and Operations in a Delegate Class

Description of "Figure 2-1 Place Management Properties and Operations in a Delegate Class"

In Figure 2-1, business methods in the EJB push their data to the delegate class. For example, each time a specific business method is invoked, the method increments a counter in the delegate class, and the MBean interface exposes the counter value as an attribute.

This separation of business logic from management logic might be less efficient than combining the logic into the same class, especially if the counter in the delegate class is incremented frequently. However, in practice, most JVMs can optimize the method calls so that the potential inefficiency is negligible.

If this negligible difference is not acceptable for your application, your business class in the EJB can contain the management value and the delegate class can retrieve the value whenever a JMX client requests it.

Use Open MBean Data Types

If a remote JMX client will access your custom MBeans, Oracle recommends that you limit the data types of your MBean attributes and the data types that your operations return to those defined in javax.management.openmbean.OpenType. All JVMs have access to these basic types. See OpenType in the Java SE 7 API Specification at http://docs.oracle.com/javase/7/docs/api/javax/management/openmbean/OpenType.html.

If your MBeans expose other data types, the types must be serializable and the remote JMX clients must include your types on their class paths.

Emit Notifications Only When Necessary

Each time an MBean emits a notification, it uses memory and network resources. For MBean attributes whose values change frequently, such memory and resource uses might be unacceptable.

Instead of configuring your MBeans to emit notifications each time its attributes change, Oracle recommends that you use monitor MBeans to poll your custom MBeans periodically to determine whether attributes have changed. You can configure the monitor MBean to emit a notification only after an attribute changes in a specific way or reaches a specific threshold.

See Best Practices: Listening Directly Compared to Monitoring in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.

Additional Design Considerations

In addition to Oracle best practices, bear in mind the following considerations when designing manageable applications.

Registering MBeans in the JVM Platform MBean Server

In this release of WebLogic Server, the WebLogic Runtime MBean Server is the JVM platform MBean server. As such, JMX clients can monitor your custom MBeans, WebLogic Server MBeans, and the JVM's platform MXBeans through a single MBean server. With this option:

Local applications can access all of the MBeans through the MBeanServer interface that java.lang.management.ManagementFactory.getPlatformMBeanServer() returns.
If you want to enable remote JMX clients to access custom MBeans, platform MXBeans, and WebLogic Server MBeans, consider the following configuration:
- By the default, the WebLogic Server Runtime MBean Server is configured to be the platform MBean server.
- Remote access to the platform MBean server is not enabled.
- Remote JMX clients access platform MXBeans by connecting to the Runtime MBean Server.

See Using the Platform MBean Server in the Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.

Registering Application MBeans by Using Only JDK Classes

Using Oracle's ApplicationLifecycleListener is the easiest technique for making an MBean share the life cycle of its parent application. If you do not want to use proprietary WebLogic Server classes and deployment descriptor elements for managing a servlet or an EJB, you can do the following:

For a servlet, configure a javax.servlet.Filter that creates and registers your MBean when a servlet calls a specific method or when the servlet itself is instantiated. See Filter in the Java EE 7 API Specification at http://docs.oracle.com/javaee/7/api/javax/servlet/Filter.html.
For an EJB, implement its javax.ejb.EntityBean.ejbActivate() method to create and register your MBean. For a session EJB whose instances share a single MBean instance, include logic that creates and registers your MBean only if it does not already exist. See EntityBean in the Java EE 7 API Specification at http://docs.oracle.com/javaee/7/api/javax/ejb/EntityBean.html.

Organizing Managed Objects and Business Objects

While you might design one managed object for each business object, there is no requirement for how your management objects should relate to your business objects. One management object could aggregate information from multiple business objects or conversely, you could split information from one business object into multiple managed objects.

For example, if a servlet uses multiple helper classes and you want one MBean to represent the servlet, each helper class should push its management data into a single MBean implementation class.

The organization that you choose depends on the number of MBeans you want to provide to the system administrator or operations staff contrasted with the difficulty of maintaining a complex management architecture.

Packaging and Accessing Management Classes

If you package your management classes in an application's APP-INF directory, all other classes in the application can access them. If you package the classes in a module's archive file, then only the module can access the management classes.

For example, consider an application that contains multiple Web applications, each of which contains its own copy of a session EJB named EJB1. If you want one MBean to collect information for all instances of the session EJB across all applications, you must package the MBean's classes in the APP-INF directory. If you want each Web application's copy of the EJB to maintain its own copy of the MBean, then package the MBean's classes in the EJB's JAR file. (If you package the classes in the EJB's JAR, then you distribute the MBean classes to each Web application when you copy the JAR to the Web application.)

Securing Custom MBeans with Roles and Policies

If you register your MBeans in the WebLogic Server Runtime MBean Server, in addition to limiting access only to users who have authenticated and been authorized through the WebLogic Server security framework, you can further restrict access by creating roles and polices. A security role, like a security group, grants an identity to a user. Unlike a group, however, membership in a role can be based on a set of conditions that are evaluated at run time. A security policy is another set of run-time conditions that specify which users, groups, or roles can access a resource.

Note the following restrictions to securing custom MBeans with roles and policies:

Your MBean's object name must include a "Type=value" key property.
You must describe your roles and policy in a XACML 2.0 document and then use the WebLogic Scripting Tool to add the data to your realm.
If your XACML document describes authorization policies, your security realm must use either the WebLogic Server XACML Authorization Provider or some other provider that implements the weblogic.management.security.authorization.PolicyStoreMBean interface.
If your XACML document describes role assignments, your security realm must use either the WebLogic Server XACML Role Mapping Provider or some other provider that implements the weblogic.management.security.authorization.PolicyStoreMBean interface.

For information about creating XACML roles policies and adding them to your realm, see Using XACML Documents to Secure WebLogic Resources in Securing Resources Using Roles and Policies for Oracle WebLogic Server.