Skip Headers

Oracle® Containers for J2EE Configuration and Administration Guide 10g Release 3 (10.1.3) Part No. B14432-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 12 Using MBeans in OC4J

This chapter describes how the system MBeans provided with OC4J can be used to manage deployed applications, services and other resources within an OC4J instance. It includes the following topics:

- MBeans and Java Management Extensions (JMX) Support in OC4J

- Using the System MBean Browser

- Using JMX Notifications

## MBeans and Java Management Extensions (JMX) Support in OC4J

OC4J provides support for the Java Management Extensions (JMX) 1.2 specification, which allows standard interfaces to be created for managing resources, such as services, applications and resources, in a J2EE environment.

The Oracle Enterprise Manager 10g Application Server Control Console user interface is built on a JMX-compliant client that can be used to completely manage and monitor an OC4J instance. The JMX functionality provided through Application Server Control Console is enabled through Java components known as MBeans, which are discussed in the next section.

JMX manageable resources within OC4J include:

- The OC4J server

- Applications and Web modules running within an OC4J instance

- J2EE services, such as JTA and JMS

- OC4J processes, such as Task Manager

- Data source and security configuration

This section discusses the following topics:

- What Are MBeans?

- Overview of the Top-Level OC4J System MBeans

- When Do Changes Made Via MBeans Take Effect?

- How Is MBean Data Persisted?

### What Are MBeans?

An MBean, or managed bean, is a Java object that represents a JMX manageable resource. MBeans are defined in the J2EE Management Specification (JSR-77), which is part of the J2EE 1.4 specification as published by Sun Microsystems.

Each manageable resource within OC4J is managed through an instance of the appropriate MBean. For example, an instance of the `J2EESWebSite` MBean is created at OC4J startup to represent each Web site configured within the server.

Each system MBean provided with OC4J exposes a management interface that is accessible through the System MBean Browser. An MBean's interface is comprised of:

- Attributes, name/value pairs of any type that the JMX client can get or set remotely. Attributes are analogous to properties set on a JavaBean. For example, the `state` attribute of `J2EEApplication:petstore` MBean indicates whether or not the application is currently running.

- Operations, methods that the JMX client can invoke on the MBean. For example, the `stop` operation can be used to stop the `petstore` application and all of its child applications.

- Notifications that can be generated broadcast errors or specific events, such as when a new account is created. For example, a notification can be sent to alert you that the `petstore` application has stopped.

As noted earlier, the Application Server Control Console application is built on top of the system MBeans. When you set a property or perform a task in the user interface, you are actually setting an attribute or invoking an operation on an underlying MBean.

To provide you with greater flexibility, Application Server Control Console also provides direct access to the system MBeans provided with OC4J through the System MBean Browser component. See "Using the System MBean Browser" for details on using this management tool.

### Overview of the Top-Level OC4J System MBeans

The following table provides an overview of the top-level OC4J system MBeans exposed through the System MBean Browser interface.

Table 12-1 Top-Level OC4J System MBeans

MBean | Description
--- | ---
`J2EEDomain` | Represents a management domain. This is the top-level management object. All other MBeans bound to the domain are visible beneath this node in the System MBean Browser.
`J2EEServer` | Represents a single OC4J instance.
`ClassLoading` | Provides access to all class-loading-related states in an OC4J server instance. Includes an operation to execute the more than 15 built-in queries provided to aid in troubleshooting class-loading issues on a running OC4J instance. This MBean lazily creates instances of the `ClassLoader` MBean, each representing an instantiated classloader.
`EJBCompiler` | Configures the OC4J instance to generate client-side IIOP stubs during EJB deployment. Also used to specify the compiler to use for compiling EJBs.
`J2EEApplication` | Represents a J2EE application deployed into the OC4J instance. Additional MBean instances are visible as child nodes representing the various components of the application: `OC4JWebModule`: Represents the properties set through the OC4J-specific `orion-web.xml` deployment descriptor generated for a Web module deployed as part of the J2EE application. `WebModule`: Represents the properties set through the J2EE `web.xml` deployment descriptor packaged with a WAR file. Instances of the `JSP` and `Servlet` MBeans are created for active JSPs and servlets within the Web module.
`J2EELogging` | Represents a Java Logger component defined in the `j2ee-logging.xml` file. For an overview of the Java logging framework, including log levels, visit Sun's site at `http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html`.
`J2EEWebSite` | Represents a Web site defined within the OC4J server. See Chapter 13, "Managing Web Sites in OC4J" for details on Web site configuration.
`JDBCDriver` | Represents a specific JDBC driver.
`JMSAdministratorResource` | Represents the OC4J JMS server used by the OC4J instance. Includes operations for managing the OC4J JMS server and JMS connection factories, as well as adding/removing destinations.
`JMSResource` | Displays statistics on messages (by type), active handlers and active connections from the JMS server. Child MBeans contain statistics on connection, destination and durable subscriber resources.
`JNDINamespace` | Returns an XML document containing all JNDI bindings for all applications deployed into the OC4J instance.
`JNDIResource` | Returns all JNDI bindings for a specific application.
`JSPConfig` | Configures the OC4J JSP container. See the Oracle Containers for J2EE Support for JavaServer Pages Developer's Guide for documentation of the various configuration values. Note that any changes made to MBean attributes require an OC4J server restart to take effect.
`JTAResource` | Represents a transaction manager instance. Note that invoking the `configureCoordinator` operation on this MBean requires an OC4J server restart for the new two-phase commit-coordinator configuration to take effect.
`JVM` | Describes a Java Virtual Machine that an OC4J instance is running within. Includes an operation to get/set system properties and force garbage collection to start.
`SecurityProvider` | Used to manage security for a specific application. Note that a restart of the corresponding application or the OC4J server is required for some attributes and operations to take effect.
`TaskManager` | Describes an OC4J task manager instance. This MBean can be used to set task manager granularity.
`ThreadPool` | Represents a single instantiated thread pool. Use to set the maximum and minimum number of threads in the pool.
`TimerService` | Represents an instance of the EJB timer. See the Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide for details.

### When Do Changes Made Via MBeans Take Effect?

Changes can be made to a managed component via an MBean while the component is either stopped or running.

In general, changes made to a managed component - values set in an attribute or the results of an operation - are available immediately in the OC4J runtime.

In some cases, however, new attribute values or operation results will require a restart - of the OC4J server, of the affected application or even of the MBean - before becoming available in the OC4J runtime. In these cases, the MBean and the Application Server Control Console will display the "new" value; however, the "old" value will continue to be used in the OC4J runtime until the required restart is completed.

For example, suppose you change the value of the `timeout` attribute of the `JSPConfig` MBean from `30` to `15`. The new value of `15` will be displayed both in the MBean and in the JSP Container Properties page in Application Server Control Console. However, because all changes to `JSPConfig` attributes require a restart of the OC4J server, the old value of `30` will continue to be used until the server is restarted.

If a restart is required, the System MBean Browser displays a Required Restart property noting the required actions. Table 12-2 below lists the values for this property.

Table 12-2 Required Restart Property Values

Value | Impact
--- | ---
OC4J Restart | Indicates that the OC4J server instance must be restarted.
Application Restart | Indicates that the J2EE application under which the MBean is registered must be restarted. MBeans that belong to this category are displayed under the `J2EEApplication` node in the navigation pane to the left of the console.
MBean Restart | Indicates that the affected MBean must be restarted.

Change is managed at the individual attribute/operation level, rather than at the MBean level. This means that an MBean might contain attributes that require a restart before a new value is available in the runtime, and other attributes that become available immediately.

### How Is MBean Data Persisted?

Persistent data set via an MBean is written to the appropriate XML configuration file(s). For example, new values set in attributes of the `JSPConfig` MBean are written to the `global-web-application.xml` configuration file.

Whether an MBean persists data is indicated by the Persist Policy property displayed in the System MBean Browser.

Table 12-3 Persist Policy Property Values

Value | Impact
--- | ---
OnUpdate | Any persistent data set on the MBean is written immediately to the appropriate configuration file(s) at the time the attribute change is applied or the operation is invoked.
Never | Data set on the MBean is not persisted but exists only in runtime memory.

## Using the System MBean Browser

The System MBean Browser is a component of the Web-based Oracle Enterprise Manager 10g Application Server Control Console user interface. The console itself is relatively simple to use. To use this feature:

1. Launch the Application Server Control Console.

2. Click the Administration link.

3. Click System MBean Browser.

4. Specific MBean instances are accessed through the navigation pane to the left of the console. Expand a node in the navigation pane and drill down to the MBean you wish to access.

5. Click the Attributes tab in the right-hand pane to access the selected MBean's attributes. If you modify any attribute values, click the Apply Changes button to apply your changes to the OC4J runtime.

   Note: The Apply Changes button will be visible only if the browser page contains at least one attribute with a modifiable value.

6. Click the Operations tab to access the MBean's operations. After selecting a specific operation, click the Invoke button to call it.

## Using JMX Notifications

Many of the system MBeans provided with OC4J include the ability to generate notifications triggered by a state change registered by the MBean. The following section describes how to subscribe to and view MBean-generated notifications.

Note that not all MBeans generate notifications.

### Subscribing to Notifications

You can subscribe to notifications either through the System MBean Browser or the Notification Subscriptions page.

To subscribe to one or more of an MBean's notifications through the System MBean Browser:

1. Click the Administration link in the Application Server Control Console.

2. Click System MBean Browser.

3. Specific MBean instances are accessed through the navigation pane to the left of the console. Expand a node in the navigation pane and drill down to the MBean you wish to access.

4. Click the Notifications tab in the right-hand pane to access the selected MBean's notifications. Note that if this tab is not present, the MBean does not generate notifications.

5. Check the Subscribe box.

6. Click the Apply button.

To subscribe to notifications generated by multiple MBeans through the Notification Subscriptions page.

1. Click the Administration link in the Application Server Control Console.

2. Click the Notification Subscription icon. All MBeans that generate notifications are displayed.

3. Check the Subscribe box for each notification you wish to subscribe to.

4. Click the Apply button.

## Using Application-Specific MBeans

Vendor-supplied MBeans deployed with a J2EE application into OC4J can be accessed via the application's "home page" in the Application Server Control Console user interface. Through the user interface, you can view and set attributes and invoke operations on application-specific MBeans, just as you can with the OC4J system MBeans.

1. Click the Applications link in the Application Server Control Console.

2. Click the name of the application the MBeans belong to. This opens the "home page" for the application.

3. Click the Application Defined MBeans link. The MBeans defined by the application are listed on the page displayed.

4. Click the Attributes tab in the right-hand pane to access the selected MBean's attributes. If you modify any attribute values, click the Apply Changes button to apply your changes to the OC4J runtime.

   Note: The Apply Changes button will only be visible if the browser page contains at least one attribute with a modifiable value.

5. Click the Operations tab to access the MBean's operations. After selecting a specific operation, click the Invoke button to execute.