Contents

Title and Copyright Information

Preface

Documentation Accessibility

Conventions

1 Introduction and Roadmap

Document Scope and Audience

Guide to this Document

Related Documentation

Samples for the JMX Developer

New and Changed Features in This Release

2 Understanding JMX

What Management Services Can You Develop with JMX?

Creating Management-Aware Applications

When Is It Appropriate to Use JMX?

JMX Layers

Indirection and Introspection

Notifications and Monitor MBeans

How JMX Notifications Are Broadcast and Received

Active Polling with Monitor MBeans

3 Designing Manageable Applications

Benefits of Oracle Best Practices

Use Standard MBeans

Registering Custom MBeans in the WebLogic Server Runtime Bean Server

Registering Custom MBeans in the Domain Runtime MBean Server

Use ApplicationLifecycleListener to Register Application MBeans

Unregister Application MBeans When Applications Are Undeployed

Place Management Logic for EJBs and Servlets in a Delegate Class

Use Open MBean Data Types

Emit Notifications Only When Necessary

Additional Design Considerations

Registering MBeans in the JVM Platform MBean Server

Registering Application MBeans by Using Only JDK Classes

Organizing Managed Objects and Business Objects

Packaging and Accessing Management Classes

Securing Custom MBeans with Roles and Policies

4 Instrumenting and Registering Custom MBeans

Overview of the MBean Development Process

Create and Implement a Management Interface

Modify Business Methods to Push Data

Register the MBean

Package Application and MBean Classes

5 Using the WebLogic Server JMX Timer Service

Overview of the WebLogic Server JMX Timer Service

Creating the Timer Service: Main Steps

Configuring a Timer MBean to Emit Notifications

Creating Date Objects

Example: Generating a Notification Every Five Minutes After 9 AM

Removing Notifications

6 Accessing Custom MBeans

Accessing Custom MBeans from JConsole

Accessing Custom MBeans from WebLogic Scripting Tool

Accessing Custom MBeans from an Administration Console Extension

Oracle® Fusion Middleware

Developing Manageable Applications With JMX for Oracle WebLogic Server

11g Release 1 (10.3.6)

E13729-05

November 2011

This document describes how to use JMX to make your applications manageable.

Oracle Fusion Middleware Developing Manageable Applications With JMX for Oracle WebLogic Server, 11g Release 1 (10.3.6)

E13729-05

Copyright © 2007, 2011, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Preface

This preface describes the document accessibility features and conventions used in this guide—Developing Manageable Applications with JMX.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Conventions

The following text conventions are used in this document:

Convention | Meaning
boldface | Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.
italic | Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.
monospace | Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

1 Introduction and Roadmap

As an application developer, one can greatly reduce the cost of operating and maintaining your applications by building management facilities into your applications. The simplest facility is message logging, which reports events within your applications as they occur and writes messages to a file or other repository. Depending on the criticality of your application, the complexity of the production environment, and the types of monitoring systems your organization uses in its operations center, your needs might be better served by building richer management facilities based on Java Management Extensions (JMX). JMX enables a generic management system to monitor your application; raise notifications when the application needs attention; and change the configuration or runtime state of your application to remedy problems.

This document describes how to use JMX to make your applications manageable.

The following sections describe the contents and organization of this guide—Developing Manageable Applications with JMX.

Document Scope and Audience

Guide to this Document

Related Documentation

Samples for the JMX Developer

New and Changed Features in This Release

Document Scope and Audience

This document is a resource for software developers who develop management services for Java EE applications. It also contains information that is useful for business analysts and system architects who are evaluating WebLogic Server or considering the use of JMX for a particular application.

It is assumed that the reader is familiar with Java EE and general application management concepts.

The information in this document is relevant during the design and development phases of a software project. This document does not address production phase administration, monitoring, or performance tuning topics. For links to WebLogic Server documentation and resources related to these topics, see Related Documentation.

This document emphasizes a hands-on approach to developing a limited but useful set of JMX management services. For information on applying JMX to a broader set of management problems, refer to the JMX specification or other documents listed in Related Documentation.

Guide to this Document

This chapter, Chapter 1, "Introduction and Roadmap," describes the scope and organization of this guide.

Chapter 2, "Understanding JMX," gives an overview of JMX and describes how Java EE application developers can use JMX.

Chapter 3, "Designing Manageable Applications," recommends design patterns for making Java EE applications manageable through JMX.

Chapter 4, "Instrumenting and Registering Custom MBeans," describes how to create your own MBeans (custom MBeans), which enable you to promote your application to the status of a managed object within a larger management system.

Chapter 5, "Using the WebLogic Server JMX Timer Service," describes how to configure your JMX client to carry out a task at a specified time or a regular time interval by using WebLogic Server's implementation of the JMX timer service.

Chapter 6, "Accessing Custom MBeans," describes options for accessing your MBeans (other than through JMX).

Related Documentation

The Oracle Technology Network includes a Web site that provides links to books, white papers, and additional information on JMX: http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html.

To view the JMX 1.2 specification, download it from http://jcp.org/aboutJava/communityprocess/final/jsr003/index3.html.

To view the JMX Remote API 1.0 specification, download it from http://jcp.org/aboutJava/communityprocess/final/jsr160/index.html.

You can view the API reference for the javax.management* packages from: http://download.oracle.com/javase/6/docs/api/overview-summary.html.

For guidelines on developing other types of management services for WebLogic Server applications, see the following documents:

Using Logging Services for Application Logging for Oracle WebLogic Server describes WebLogic support for internationalization and localization of log messages and shows you how to use the templates and tools provided with WebLogic Server to create or edit message catalogs that are locale-specific.

Configuring and Using the Diagnostics Framework for Oracle WebLogic Server describes how system administrators can collect application monitoring data that has not been exposed through JMX, logging, or other management facilities.

For guidelines on developing and tuning WebLogic Server applications, see Developing Applications for Oracle WebLogic Server.

Samples for the JMX Developer

In addition to this document, Oracle provides two JMX code samples in the Avitek Medical Records Application (MedRec). MedRec is an end-to-end sample Java EE application shipped with WebLogic Server that simulates an independent, centralized medical record management system. The MedRec application provides a framework for patients, doctors, and administrators to manage patient data using a variety of different clients.

Note:

The WLS Code Examples and MedRec sample application are not installed by default. To install the code examples and MedRec, you must select a custom installation of WebLogic Server and select to install the Server Examples.

The JMX code in MedRec exemplifies the following management tasks:

Monitoring an application with JMX.

One of the session EJBs in MedRec is instrumented for management through JMX. The EJB keeps track of how many times it writes to the database and exposes this counter as an MBean attribute.

Using JMX to extend a security realm.

A JSP and supporting Java classes in the MedRec application invoke JMX APIs to add a new Administrator user to the MedRec security realm. The JSP provides the interface for collecting the new user information and the supporting classes validate the information and insert the new user into the realm.

For information about the JMX code examples in MedRec, do the following:

Start MedRec server.

MedRec can be started from the WL_HOME/samples/domains/medrec directory, where WL_HOME is the top-level installation directory for WebLogic Server. The administration username and password for the Medical Records domain is weblogic/weblogic.

When MedRec server starts, it displays its home page in a Web browser. On the MedRec home page, click the More Samples link.

MedRec displays the WebLogic Server Code Examples viewer.

In the Code Examples viewer, in the left pane, do either of the following:

Expand Avitek Medical Records Sample Application > Features > JMX. Then select the Monitoring an Application with JMX topic.

Expand Avitek Medical Records Sample Application > Features > Security. Then select the Extending a Realm Using JMX topic.

New and Changed Features in This Release

For new and changed JMX features in this release, see "New and Changed Features in This Release" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server.

For a comprehensive listing of the new WebLogic Server features introduced in this release, see What's New in Oracle WebLogic Server.

2 Understanding JMX

Java Management Extensions (JMX) is a specification for monitoring and managing Java applications. It enables a generic management system to monitor your application; raise notifications when the application needs attention; and change the state of your application to remedy problems. Like SNMP and other management standards, JMX is a public specification and many vendors of commonly used monitoring products support it.

WebLogic Server uses the Java Management Extensions (JMX) 1.2 implementation that is included in JDK 6. The following sections describe how Java applications can use JMX to expose runtime metrics and control points to management systems:

What Management Services Can You Develop with JMX?

Creating Management-Aware Applications

When Is It Appropriate to Use JMX?

JMX Layers

Indirection and Introspection

Notifications and Monitor MBeans

For information about other APIs and utilities that you can use to manage Java EE applications on WebLogic Server, refer to "Overview of WebLogic Server System Administration" in Introduction to Oracle WebLogic Server.

What Management Services Can You Develop with JMX?

When used to monitor and manage applications, JMX typically provides management applications access to properties in your Java classes that collect management data (see Figure 2-1). Often, these class properties are simple counters that keep track of the resources your application is consuming. JMX can also provide access to methods in your Java classes that start or stop processes in the application or reset the value of the class properties. Any class that exposes management data through JMX is called a managed bean (MBean). Class properties that are exposed through MBeans are called attributes and methods that are exposed through MBeans are called operations.

Figure 2-1 JMX Provides Access to Management Properties

Once you provide this type of access to JMX-enabled management utilities, system administrators or the operations staff can integrate the data into their overall view of the system. They can use a JMX management utility to view the current value of an MBean attribute, or they can set up JMX monitors to periodically poll the value of your MBean attributes and emit notifications to the management utility only when the values exceed specific thresholds.

Creating Management-Aware Applications

Instead of placing all management responsibility on system administrators or the operations staff, you can create management-aware applications that monitor MBeans and then perform some automated task. For example:

An application that monitors connection pools and grows or shrinks the pools to meet demand.

A portal application that monitors the set of deployed applications. If a new application is deployed, the portal application automatically displays it as a new portlet.

An application that listens for deployments of connector modules and then configures itself to use newly deployed modules.

When Is It Appropriate to Use JMX?

Any critical Java EE application that is a heavy consumer of resources, such as database or JMS connections or caches, should provide some facility for monitoring the application's resource consumption. For these kinds of applications, which might be writing or reading from a database many times each minute, it is not feasible to use logging facilities to output messages with each write and read operation. Using JMX for this type of monitoring enables you to write management (instrumentation) code that is easy to maintain and that optimizes your use of network resources.

If you want to monitor basic runtime metrics for your application, WebLogic Server already provides a significant number of its own MBeans that you can use (see "Best Practices: Listening for WebLogic Server Events" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server). For example, you can use existing WebLogic Server MBeans to track the hit rate on your application's servlets and the amount of time it takes to process servlet requests.

Although WebLogic Server MBeans can indicate to an operations center the general state of resources, it cannot provide detailed information about how a specific application is using the resources. For example, WebLogic Server MBeans can indicate how many connections are being used in a connection pool, but they do not indicate which applications are using the connection pools. If your domain contains several active applications and you notice that some connections are always in use, consider creating MBeans that monitor when each application session gets and releases a connection. You could also include a management operation that ends sessions that appear to be stuck.

In addition, if your application creates and maintains its own cache or writes to a data repository that is outside the control of the application container, consider creating MBeans to monitor the size of the cache or the amount of data written to the repository.

JMX Layers

Like most of Java EE, JMX is a component-based technology in which different types of software vendors provide different types of components. This division of labor enables each type of vendor to focus on providing only the software that falls within its area of expertise. JMX organizes its components into the following layers:

Instrumentation

Consists of applications that you write, resources, and other manageable objects. In this layer, application developers create managed beans (MBeans), which contain the properties (attributes) and methods (operations) that they want to expose to external management systems.

Agent

Consists of the JVM and application servers such as WebLogic Server. This layer includes a registry of MBeans and standard interfaces for creating, destroying, and accessing MBeans.

The agent layer also provides services for remote clients as well as a monitoring and a timer service. See Chapter 5, "Using the WebLogic Server JMX Timer Service," and "Using Notifications and Monitor MBeans" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server.

Distributed Services

Consists of Management consoles or other Java EE applications. A management application sends or receives requests from the agent layer. Often this layer is available as a plug-in or as an adapter that enables a management console to support a variety of management protocols, such as JMX and SNMP.

Indirection and Introspection

Two key concepts for understanding JMX are indirection and introspection, which enable a JMX application to manage proprietary resources without requiring access to proprietary class definitions.

The general model for JMX is that applications in the distributed services layer never interact directly with classes in the instrumentation layer. Instead, under this model of indirection, the JMX agent layer provides standard interfaces, such as javax.management.MBeanServerConnection, that:

Expose a class management interface to management clients in the distributed services layer

Receive requests from management clients, such as a request to get the value of a property that a class is exposing through JMX

Interact with the class to carry out the request and return the result to the management client

Each class describes to the MBean server the set of properties and methods that it wants to expose through JMX. A property that a class exposes through JMX is called an MBean attribute, and a method that it exposes is called an operation. JMX specifies multiple techniques (design patterns) that a class can use to describe its attributes and operations, and these design patterns are formalized as the following MBean types: standard, dynamic, model, and open.

A class that implements the standard MBean type describes its management interface in way that is most like Java programming: a developer creates a JMX interface file that contains getter and setter methods for each class property that is to be exposed through JMX. The interface file also contains a wrapper method for each class method that is to be exposed. Then the class declares the name of its JMX interface. When you register a standard MBean with the MBean server, the MBean server introspects the class and its JMX interface to determine which attributes and operations it will expose to the distributed services layer. The MBean server also creates an object, MBeanInfo, that describes the interface. Management clients inspect this MBeanInfo object to learn about a class's management interface.

A class that implements the model MBean type describes its management interface by constructing its own MBeanInfo object, which is a collection of metadata objects that describe the properties and methods to expose through JMX. When you register a model MBean with the MBean server, the MBean server uses the existing MBeanInfo object instead of introspecting the class.

Notifications and Monitor MBeans

JMX provides two ways to monitor changes in MBeans: MBeans can emit notifications when specific events occur (such as a change in an attribute value), or monitor MBeans can poll an MBean periodically to retrieve the value of an attribute.

The following sections describe JMX notifications and monitor MBeans:

How JMX Notifications Are Broadcast and Received

Active Polling with Monitor MBeans

How JMX Notifications Are Broadcast and Received

As part of MBean creation, you can implement the javax.management.NotificationEmitter interface, which enables the MBean to emit notifications when different types of events occur. For example, you create an MBean that manages your application's use of a connection pool. You can configure the MBean to emit a notification when the application creates a connection and another notification when the application drops a connection.

To listen for notifications, you create a listener class that implements the javax.management.NotificationListener.handleNotification() method. Your implementation of this method includes the logic that causes the listener to carry out an action when it receives a notification. After you create the listener class, you create another class that registers the listener with an MBean.

By default, an MBean broadcasts all its notifications to all its registered listeners. However, you can create and register a filter for a listener. A filter is a class that implements the javax.management.NotificationFilter.isNotificationEnabled() method. The implementation of this method specifies one or more notification types. (In this case, type refers to a unique string within a notification object that identifies an event, such as vendorA.appB.eventC.) When an event causes an MBean to generate a notification, the MBean invokes a filter's isNotificationEnabled() method before it sends the notification to the listener. If the notification type matches one of the types specified in isNotificationEnabled(), then the filter returns true and the MBean broadcasts the message to the associated listener.

For information on creating and registering listeners and filters, see "Listening for Notifications from WebLogic Server MBeans: Main Steps" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server. For a complete description of JMX notifications, refer to the JMX 1.2 specification. See Related Documentation.

Figure 2-2 shows a basic system in which a notification listener receives only a subset of the notifications that an MBean broadcasts.

Figure 2-2 Receiving Notifications from an MBean

Active Polling with Monitor MBeans

JMX includes specifications for a type of MBeans called monitor MBeans, which can be instantiated and configured to periodically observe other MBeans. Monitor MBeans emit JMX notifications only if a specific MBean attribute has changed beyond a specific threshold. A monitor MBean can observe the exact value of an attribute in an MBean, or optionally, the difference between two consecutive values of a numeric attribute. The value that a monitor MBean observes is called the derived gauge.

When the value of the derived gauge satisfies a set of conditions, the monitor MBean emits a specific notification type. Monitors can also send notifications when certain error cases are encountered while monitoring an attribute value.

To use monitor MBeans, you configure a monitor MBean and register it with the MBean you want to observe. Then you create a listener class and register the class with the monitor MBean. Because monitor MBeans emit only very specific types of notification, you usually do not use filters when listening for notifications from monitor MBeans.

Figure 2-3 shows a basic system in which a monitor MBean is registered with an MBean. A NotificationListener is registered with the monitor MBean, and it receives notifications when the conditions within the monitor MBean are satisfied.

Figure 2-3 Monitor MBeans

3 Designing Manageable Applications

Several viable JMX design patterns and deployment options can make your application more manageable. The following sections describe Oracle best practices for designing manageable applications. The last section, Additional Design Considerations, provides alternatives to some Oracle recommendations and discusses additional design considerations.

Benefits of Oracle Best Practices

Use Standard MBeans

Registering Custom MBeans in the WebLogic Server Runtime Bean Server

Registering Custom MBeans in the Domain Runtime MBean Server

Use ApplicationLifecycleListener to Register Application MBeans

Unregister Application MBeans When Applications Are Undeployed

Place Management Logic for EJBs and Servlets in a Delegate Class

Use Open MBean Data Types

Emit Notifications Only When Necessary

Additional Design Considerations

Benefits of Oracle Best Practices

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 6.0 API Specification at http://download.oracle.com/javase/6/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 With 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. For more information, 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 With 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 With 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 with 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 3-1.

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

In Figure 3-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. For an example of this technique, see the MedRec example server.

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 6.0 API Specification at http://download.oracle.com/javase/6/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.

For more information, see "Best Practices: Listening Directly Compared to Monitoring" in Developing Custom Management Utilities With 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.

For more information, see "Using the Platform MBean Server" in the Developing Custom Management Utilities With 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 5.0 API Specification at http://download.oracle.com/javaee/5/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 5.0 API Specification at http://download.oracle.com/javaee/5/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 runtime. A security policy is another set of runtime 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.

4 Instrumenting and Registering Custom MBeans

The following sections describe how to instrument and register standard MBeans for application modules:

Overview of the MBean Development Process

Create and Implement a Management Interface

Modify Business Methods to Push Data

Register the MBean

Package Application and MBean Classes

Overview of the MBean Development Process

Figure 4-1 illustrates the MBean development process. The steps in the process, and the results of each are described in Table 4-1. Subsequent sections detail each step in the process.

Figure 4-1 Standard MBean Development Overview

Table 4-1 Model MBean Development Tasks and Results

Step
Description
Result

1. Create and Implement a Management Interface

Create a standard Java interface that describes the properties (management attributes) and operations you want to expose to JMX clients.

Create a Java class that implements the interface. Because management logic should be separate from business logic, the implementation should not be in the same class that contains your business methods.

Source files that describe and implement your management interface.

2. Modify Business Methods to Push Data

If your management attributes contain data about the number of times a business method has been invoked, or if you want management attributes to contain the same value as a business property, modify your business methods to push (update) data into the management implementation class.

For example, if you want to keep track of how frequently your business class writes to the database, modify the business method that is responsible for writing to the database to also increment a counter property in your management implementation class. This design pattern enables you to insert a minimal amount of management code in your business code.

A clean separation between business logic and management logic.

3. Register the MBean

If you want to instantiate your MBeans as part of application deployment, create a WebLogic Server ApplicationLifecycleListener class to register your MBean.

A Java class and added entries in weblogic-application.xml.

4. Package Application and MBean Classes

Package your compiled classes into a single archive.

A JAR, WAR, EAR file or other deployable archive file.

Create and Implement a Management Interface

One of the main advantages to the standard MBeans design pattern is that you define and implement management properties (attributes) as you would any Java property (using getxxx, setxxx, and isxxx methods); similarly, you define and implement management methods (operations) as you would any Java method.

When you register the MBean, the MBean server examines the MBean interface and determines how to represent the data to JMX clients. Then, JMX clients use the MBeanServerConnection.getAttribute() and setAttribute() methods to get and set the values of attributes in your MBean and they use MBeanServerConnection.invoke() to invoke its operations. See MBeanServerConnection in the Java SE 6.0 API Specification at http://download.oracle.com/javase/6/docs/api/javax/management/MBeanServerConnection.html.

To create an interface for your standard MBean:

Declare the interface as public.

Oracle recommends that you name the interface as follows:

Business-objectMBean.java

where Business-object is the object that is being managed.

Oracle's recommended design pattern for standard MBeans enables you to follow whatever naming convention you prefer. In other standard MBean design patterns (patterns in which the MBean's implementation file does not extend javax.management.StandardMBean), the file name must follow this pattern: Impl-fileMBean.java where Impl-file is the name of the MBean's implementation file.

For each read-write attribute that you want to make available in your MBean, define a getter and setter method that follows this naming pattern:

getAttribute-name

setAttribute-name

where Attribute-name is a case-sensitive name that you want to expose to JMX clients.

If your coding conventions prefer that you use an isAttribute-name as the getter method for attributes of type Boolean, you may do so. However, JMX clients use the MBeanServerConnection.getAttribute() method to retrieve an attribute's value regardless of the attribute's data type; there is no MBeanServerConnection.isAttribute() method.

For each read-only attribute that you want to make available, define only an is or a getter method.

For each write-only attribute, define only a setter method.

Define each management operation that you want to expose to JMX clients.

Example 4-1 is an MBean interface that defines a read-only attribute of type int and an operation that JMX clients can use to set the value of the attribute to 0.

Example 4-1 Management Interface

package com.bea.medrec.controller;
public interface RecordSessionEJBMBean {
   public int getTotalRx();
   public void resetTotalRx();
}

To implement the interface:

Create a public class.

Oracle recommends the following pattern as a naming convention for implementation files: MBean-InterfaceImpl.java.

Extend javax.management.StandardMBean to enable this flexibility in the naming requirements.

See StandardMBean in the Java SE 6.0 API Specification at http://download.oracle.com/javase/6/docs/api/javax/management/StandardMBean.html.

Implement the StandardMBean(Object implementation, Class mbeanInterface) constructor.

With Oracle's recommended design pattern in which you separate the management logic into a delegate class, you must provide a public constructor that implements the StandardMBean(Object implementation, Class mbeanInterface) constructor.

Implement the methods that you defined in the management interface.

Follow these guidelines:

If you are using Oracle's recommended design pattern, in which business objects push management data into the management object, provide a method in this implementation class that the business methods use to set the value of the management attribute. In Example 4-2, the incrementTotalRx() method is available to business methods but it is not part of the management interface.

If multiple instances of an EJB, servlet, or other class can set the value of a management attribute, make sure to increment the property atomically and do not make its getter and setter (or increment method) synchronized. While synchronizing guarantees the accuracy of management data, it blocks business threads until the management operation has completed.

Example 4-2 MBean Implementation

package com.bea.medrec.controller;

import javax.management.StandardMBean;
import com.bea.medrec.controller.RecordSessionEJBMBean;
public class RecordSessionEJBMBeanImpl extends StandardMBean
   implements RecordSessionEJBMBean {

   public RecordSessionEJBMBeanImpl() throws
      javax.management.NotCompliantMBeanException {
         super(RecordSessionEJBMBean.class);
   }

   public int TotalRx = 0;
   public int getTotalRx() {
        return TotalRx;
   }
   public void incrementTotalRx() {
      TotalRx++;
   }
   public void resetTotalRx() {
       TotalRx = 0;
   }
}

Modify Business Methods to Push Data

If your management attributes contain data about the number of times a business method has been invoked, or if you want management attributes to contain the same value as a business property, modify your business methods to push (update) data into the management implementation class.

Example 4-3 shows a method in an EJB that increments the integer in the TotalRx property each time the method is invoked.

Example 4-3 EJB Method That Increments the Management Attribute

private Collection addRxs(Collection rXs, RecordLocal recordLocal)
   throws CreateException, Exception {
   ...
   com.bea.medrec.controller.RecordSessionEJBMBeanImpl.incrementTotalRx();
   ...
}

Register the MBean

If you want to instantiate your MBeans as part of application deployment, create an ApplicationLifecycleListener that registers your MBean when the application deploys (see Use ApplicationLifecycleListener to Register Application MBeans):

Create a class that extends weblogic.application.ApplicationLifecycleListener.

In this ApplicationLifecycleListener class, implement the ApplicationLifecycleListener.postStart(ApplicationLifecycleEvent evt) method.

In your implementation of this method:

Construct an object name for your MBean.

Oracle recommends this naming convention:

your.company:Name=Parent-module,Type=MBean-interface-classname

To get the name of the parent module, use ApplicationLifecycleEvent to get an ApplicationContext object. Then use ApplicationContext to get the module's identification.

If you are registering the MBean on the WebLogic Server Runtime MBean Server:

Access the WebLogic Server Runtime MBean Server through JNDI.

If the classes for the JMX client are part of a Java EE module, such as an EJB or Web application, the JNDI name for the Runtime MBeanServer is:

java:comp/env/jmx/runtime

For example:

InitialContext ctx = new InitialContext();
MBeanServer server = (MBeanServer)
     ctx.lookup("java:comp/env/jmx/runtime");

If the classes for the JMX client are not part of a Java EE module, the JNDI name for the Runtime MBean Server is:

java:comp/jmx/runtime

See "Make Local Connections to the Runtime MBean Server" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server.

If you are registering the MBean on the Domain Runtime MBean Server:

Access the Domain Runtime MBean Server through JNDI.

If the classes for the JMX client are part of a Java EE module, such as an EJB or Web application, the JNDI name for the Domain Runtime MBean server is:

java:comp/env/jmx/domainRuntime

For example:

Initial context ctx = new InitialContext();
server = (MBeanServer)ctx.lookup("java:comp/env/jmx/domainRuntime");

If the classes for the JMX client are not part of a Java EE module, the JNDI name for the Domain Runtime MBean Server is:

java:comp/jmx/domainRuntime

Note:

The Domain Runtime MBean Server is present only on the Administration Server. Therefore, since the ctx.lookup() call returns a reference to the local MBean Server, the lookup method can only be called when running on the Administration Server. If called when running on a managed server, a NameNotFound exception will be thrown.

See "Make Local Connections to the Domain Runtime MBean Server" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server

Register your MBean using MBeanServer.registerMBean(Object object, ObjectName name) where:

object is an instance of your MBean implementation class.

name is the JMX object name for your MBean.

When your application deploys, the WebLogic deployment service emits ApplicationLifecycleEvent notifications to all of its registered listeners. When the listener receives a postStart notification, it invokes its postStart method. See "Programming Application Life Cycle Events" in Developing Applications for Oracle WebLogic Server.

In the same class, implement the ApplicationLifecycleListener.preStop(ApplicationLifecycleEvent evt) method.

In your implementation of this method, invoke the

javax.management.MBeanServer.unregister(ObjectName MBean-name) method to unregister your MBean.

Register your class as an ApplicationLifecycleListener by adding the following element to your application's weblogic-application.xml file:

<listener>
   <listener-class>
      fully-qualified-class-name
   </listener-class>
</listener>

For an example of this technique, see the MedRec example server.

Package Application and MBean Classes

Package your MBean classes in the application's APP-INF directory or in a module's JAR, WAR or other type of archive file depending on the access that you want to enable for the MBean. See Additional Design Considerations.

5 Using the WebLogic Server JMX Timer Service

The following sections describe how to use the WebLogic Server JMX timer service:

Overview of the WebLogic Server JMX Timer Service

Creating the Timer Service: Main Steps

Configuring a Timer MBean to Emit Notifications.

Creating Date Objects

Example: Generating a Notification Every Five Minutes After 9 AM

Removing Notifications

Overview of the WebLogic Server JMX Timer Service

If you need your JMX client to carry out a task at a specified time or a regular time interval, you can configure a JMX timer service to emit notifications, and a listener that responds to the notifications with a specified action.

For example, you want a JMX monitor to run between 9am and 9pm each day. You configure the JMX timer service to emit a notification daily at 9am, which triggers a JMX listener to start your monitor. The timer service emits another notification at 9pm, which triggers the listener to stop the monitor MBean.

The JDK includes an implementation of the JMX timer service (see javax.management.timer.Timer in the Java SE 6.0 API Specification at http://download.oracle.com/javase/6/docs/api/javax/management/timer/Timer.html); however, listeners for this timer service run in their own thread in a server's JVM.

WebLogic Server includes an extension of the standard timer service that causes timer listeners to run in a thread that WebLogic Server manages and within the security context of a WebLogic Server user account.

Creating the Timer Service: Main Steps

You construct and manage instances of the timer service for each JMX client. WebLogic Server does not provide a centralized timer service that all JMX clients use. Each time you restart a server instance, each JMX client must re-instantiate any timer service configurations it needs.

To create the WebLogic Server timer service:

Create a JMX listener class in your application.

For general instructions on creating a JMX listener, see "Creating a Notification Listener" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server.

Create a class that does the following:

Configures an instance of weblogic.management.timer.TimerMBean to emit javax.management.timer.TimerNotification notifications at a specific time or at a recurring interval. See TimerNotification in the Java SE 6.0 API Specification at http://download.oracle.com/javase/6/docs/api/javax/management/timer/TimerNotification.html.

For each notification that you configure, include a String in the notification's Type attribute that identifies the event that caused the timer to emit the notification.

See Configuring a Timer MBean to Emit Notifications.

Registers your listener and an optional filter with the timer MBean that you configured.

Starts the timer in the timer MBean that you configured.

For general instructions, see "Configuring a Notification Filter" and "Registering a Notification Listener and Filter" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server.

Unregisters the timer MBean and closes its connection to the MBean server when it finishes using the timer service.

Package and deploy the listener and other JMX classes to WebLogic Server. See "Packaging and Deploying Listeners on WebLogic Server" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server.

Configuring a Timer MBean to Emit Notifications

To configure a Timer MBean instance to emit a notification:

Initialize a connection to the Domain Runtime MBean Server.

See "Make Remote Connections to an MBean Server" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server.

Create an ObjectName for your timer MBean instance.

See javax.management.ObjectName in the Java SE 6.0 API Specification at http://download.oracle.com/javase/6/docs/api/javax/management/ObjectName.html.

Oracle recommends that your object name start with the name of your organization and include key properties that clearly identify the purpose of the timer MBean instance.

For example, "mycompany:Name=myDailyTimer,Type=weblogicTimer"

Create and register the timer MBean.

Use javax.management.MBeanServerConnection.createMBean(String classname ObjectName name) method where:

classname is weblogic.management.timer.Timer

name is the object name that you created for the timer MBean instance.

Note:

The timer MBean that you create runs in the JMX agent on WebLogic Server (it does not run in a client JVM even if you create the timer MBean from a remote JMX client).

Configure the timer MBean to emit a notification.

Invoke the MBean's addNotification operation. Table 5-1 describes each parameter of the addNotification operation. For more information, see weblogic.management.timer.Timer in the WebLogic Server API Reference.

The addNotification operation creates a TimerNotification object and returns a handback object of type Integer, which contains an integer that uniquely identifies the TimerNotification object.

Repeat step 4 for each timer notification that your JMX client needs to receive.

Start the timers in your timer MBean by invoking the timer MBean's start() operation.

When the time that you specify arrives, the timer service emits the TimerNotification object along with a reference to the handback object.

Table 5-1 Parameters of the addNotification Operation

Parameter
Description

java.lang.String type

A string that you use to identify the event that triggers this notification to be broadcast. For example, you can specify midnight for a notification that you configure to be broadcast each day at midnight.

java.lang.String message

Specifies the value of the TimerNotification object's message attribute.

java.lang.Object userData

Specifies the name of an object that contains whatever data you want to send to your listeners. Usually, you specify a reference to the class that registered the notification, which functions as a callback.

java.util.Date startTime

Specifies a Date object that contains the time and day at which the timer emits your notification.

See Creating Date Objects.

long period

(Optional) Specifies the interval in milliseconds between notification occurrences. Repeating notifications are not enabled if this parameter is zero or is not defined (null).

long nbOccurences

(Optional) Specifies the total number of times that the notification will occur. If the value of this parameter is zero or is not defined (null) and if the period is not zero or null, then the notification will repeat indefinitely.

If you specify this parameter, each time the Timer MBean emits the associated notification, it decrements the number of occurrences by one. You can use the timer MBean's getNbOccurrences operation to determine the number of occurrences that remain. When the number of occurrences reaches zero, the timer MBean removes the notification from its list of configured notifications.

Creating Date Objects

The constructor for the java.util.Date object initializes the object to represent the time at which you created the Date object measured to the nearest millisecond. To specify a different time or date:

Create an instance of java.util.Calendar.

Configure the fields in the Calendar object to represent the time or date.

Invoke the Calendar object's getTime() method, which returns a Date object that represents the time in the Calendar object.

For example, the following code configures a Date object that represents midnight:

java.util.Calendar cal = java.util.Calendar.getInstance();
cal.set(java.util.Calendar.HOUR_OF_DAY, 24);
java.util.Date morning = cal.getTime();

See java.util.Calendar in the Java SE 6.0 API Specification.at http://download.oracle.com/javase/6/docs/api/java/util/Calendar.html.

Example: Generating a Notification Every Five Minutes After 9 AM

The code in Example 5-1 creates an instance of weblogic.management.timer.Timer that emits a notification every 5 minutes after 9am.

Note the following about the code:

It creates and registers the timer MBean in the WebLogic Server Runtime MBean Server, under the assumption that the JMX client runs alongside applications that are deployed on multiple server instances. In this case, your JMX client would register a timer MBean in each Runtime MBean Server in the domain.

Even though it creates an instance of the WebLogic Server timer MBean, the class does not import WebLogic Server classes. Only the MBean server needs access to the WebLogic Server Timer class, not the JMX client.

Any generic JMX listener can be used to listen for timer notifications, because all timer notifications extend javax.management.Notification.

Example 5-1 Create, Register, and Configure a Timer MBean

import java.util.Hashtable;
import java.io.IOException;
import java.net.MalformedURLException;

import javax.management.MBeanServerConnection;
import javax.management.ObjectName;
import javax.management.MalformedObjectNameException;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;
import javax.naming.Context;

import javax.management.NotificationFilterSupport;

public class RegisterTimer  {
   private static MBeanServerConnection connection;
   private static JMXConnector connector;
   private static final ObjectName service;

   // Initialize the object name for RuntimeServiceMBean
   // so it can be used throughout the class.
   static {
      try {
         service = new ObjectName(
         "com.bea:Name=RuntimeService,Type=weblogic.management.mbeanservers.ru
          ntime.RuntimeServiceMBean");
      }catch (MalformedObjectNameException e) {
         throw new AssertionError(e.getMessage());
      }
   }

   /*
    * Initialize connection to the Runtime MBean Server.
    * This MBean is the root of the runtime MBean hierarchy, and
    * each server in the domain hosts its own instance.
    */
   public static void initConnection(String hostname, String portString,
      String username, String password) throws IOException,
      MalformedURLException {
      String protocol = "t3";
      Integer portInteger = Integer.valueOf(portString);
      int port = portInteger.intValue();
      String jndiroot = "/jndi/";
      String mserver = "weblogic.management.mbeanservers.runtime";
      JMXServiceURL serviceURL = new JMXServiceURL(protocol, hostname, port,
         jndiroot + mserver);

      Hashtable h = new Hashtable();
      h.put(Context.SECURITY_PRINCIPAL, username);
      h.put(Context.SECURITY_CREDENTIALS, password);
      h.put(JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES,
         "weblogic.management.remote");
      connector = JMXConnectorFactory.connect(serviceURL, h);
      connection = connector.getMBeanServerConnection();
   }

   public static void main(String[] args) throws Exception {
      String hostname = args[0];
      String portString = args[1];
      String username = args[2];
      String password = args[3];

      try {
         /* Invokes a custom method that establishes a connection to the
          * Runtime MBean Server and uses an instance of
          * MBeanServerConnection to represents the connection. The custom
          * method assigns the MBeanServerConnection to a class-wide, static
          * variable named "connection".
         */
         initConnection(hostname, portString, username, password);

         //Creates and registers the timer MBean.
         ObjectName timerON = new
            ObjectName("mycompany:Name=myDailyTimer,Type=weblogicTimer");
         String classname = "weblogic.management.timer.Timer";
         connection.createMBean(classname, timerON);
         System.out.println("===> created timer mbean "+timerON);

         // Configures the timer MBean to emit a morning notification.
         // Assigns the return value of addNotification to a variable so that
         // it will be possible to invoke other operations for this specific
         // notification.
         java.util.Calendar cal = java.util.Calendar.getInstance();
         cal.set(java.util.Calendar.HOUR_OF_DAY, 9);
         java.util.Date morning = cal.getTime();
         String myData = "Timer notification";
         Integer morningTimerID = (Integer) connection.invoke(timerON,
            "addNotification",
            new Object[] { "mycompany.timer.notification.after9am" ,
            "After 9am!", myData, morning, new Long(300000) },
            new String[] {"java.lang.String", "java.lang.String",
            "java.lang.Object", "java.util.Date", "long" });

         //Instantiates your listener class and configures a filter to
         // forward only timer messages.
         MyListener listener = new MyListener();
         NotificationFilterSupport filter = new NotificationFilterSupport();
         filter.enableType("mycompany.timer");

         //Uses the MBean server's addNotificationListener method to
         //register the listener and filter with the timer MBean.
         System.out.println("===> ADD NOTIFICATION LISTENER TO "+ timerON);
         connection.addNotificationListener(timerON, listener, filter, null);
         System.out.println("\n[myListener]: Listener registered ...");

         //Starts the timer.
         connection.invoke(timerON, "start", new Object[] { }, new String[] {});

         //Keeps the remote client active.
         System.out.println("Pausing. Press Return to end...........");
         System.in.read();
      } catch(Exception e) {
         System.out.println("Exception: " + e);
         e.printStackTrace();
      }
   }
}

Removing Notifications

The timer MBean removes notifications from its list when either of the following occurs:

A non-repeating notification is emitted.

A repeating notification exhausts its number of occurrences.

The timer MBean also provides the following operations to remove notifications:

removeAllNotifications(), which removes all notifications that are registered with the timer MBean instance.

removeNotification(java.lang.Integer id), which removes the notification whose handback object contains the integer value that you specify. The addNotification method returns this handback object when you invoke it (see Step 4 in Configuring a Timer MBean to Emit Notifications.

removeNotifications(java.lang.String type), which removes all notifications whose type corresponds to the type that you specify. You define a notification's type value when you create the notification object. See Table 5-1.

For more information, see weblogic.management.timer.Timer in the WebLogic Server API Reference.

6 Accessing Custom MBeans

Besides programmatic JMX access to your custom MBeans, you can use any JMX-compliant management system to access your MBeans. For information, see the Oracle Technology Network Web site, which provides links to books, white papers, and other information on JMX: http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html.

The following sections describe additional ways to access your custom MBeans:

Accessing Custom MBeans from JConsole

Accessing Custom MBeans from WebLogic Scripting Tool

Accessing Custom MBeans from an Administration Console Extension

Accessing Custom MBeans from JConsole

The JDK includes JConsole, a Swing-based JMX client that you can use to browse MBeans. You can browse the MBeans in any WebLogic Server MBean server and in the JVM platform MBean server. Oracle recommends that you use JConsole only in a development environment; it consumes significant amounts of resources. See Using JConsole to Monitor Applications at http://java.sun.com/developer/technicalArticles/J2SE/jconsole.html.

To access custom MBeans from JConsole:

If wljmxclient.jar and wlclient.jar are not in the JConsole classpath:

Enable the IIOP protocol for the WebLogic Server instance that hosts your MBeans.

Configure the default IIOP user to be a WebLogic Server user with Administrator privileges. In this scenario, the login and password you provide in Step 5d or Step 6d is irrelevant, and the default IIOP user will be associated with each request.

See "Enable and Configure IIOP" in Administration Console Online Help.

If wljmxclient.jar and wlclient.jar are in the JConsole classpath, there is no need to enable the default IIOP user. Go to Step 2.

Notes:

wlclient.jar is included in wljmxclient.jar's MANIFEST ClassPath entry, so wlclient.jar and wljmxclient.jar need to be in the same directory, or both jars need to be specified on the classpath.

Ensure that weblogic.jar or wlfullclient.jar is not included in the classpath if wljmxclient.jar is included. Only the thin client wljmxclient.jar/wlclient.jar or the thick client wlfullclient.jar should be used, but not a combination of both.

From a command prompt, make sure that JDK 6 or its equivalent is on the path.

At the command prompt, enter the following command:

jconsole -J-Djava.class.path=$JAVA_HOME/lib/jconsole.jar:$JAVA_HOME/
lib/tools.jar:$WLS_HOME/lib/wljmxclient.jar
-J-Djmx.remote.protocol.provider.pkgs=weblogic.management.remote

Note:

If your configuration is as described in Step 4, you can start JConsole simply by executing the command jconsole. If you start JConsole this way, however, only the user who started the WLS process will be able to connect locally.

If your custom MBeans are registered in the JVM platform MBean server (or if you have configured the WebLogic Server Runtime MBean Server to be the JVM platform MBean server):

In the JConsole window, select Connection > New Connection.

In the New Connection window, select the Local Process tab, select the WebLogic.Server, and click Connect.

If your custom MBeans are registered in the WebLogic Server Runtime MBean Server, and if you have not configured the Runtime MBean Server to be the platform MBean server:

In the JConsole window, select Connection > New Connection.

In the New Connection window, select the Remote Process option.

In the Remote Process JMX URL text box, enter:

service:jmx:rmi:///jndi/iiop://host:port/weblogic.management.mbeanservers.runtime

where host:port is the host name and port of the WebLogic Server instance that hosts your MBeans.

For example:

service:jmx:rmi:///jndi/iiop://localhost:7001/weblogic.management.mbeanservers.runtime

In the User Name and Password fields, enter the user name and password of any user account that is assigned the admin role. This login will be used to authenticate the client and create the Subject that will be associated with each JMX request coming from the client.

Click Connect.

If your custom MBeans are registered in the WebLogic Server Domain Runtime MBean Server:

In the Console window, select Connection > New Connection.

In the New Connection window, select the Remote Process option.

In the Remote Process JMX URL text box, enter:

service:jmx:rmi:///jndi/iiop://host:port/weblogic.management.mbeanservers.domainRuntime

where host:port is the host name and port of the Administration Server.

For example:

service:jmx:rmi///jndi/iiop://localhost:9002/weblogic.management.mbeanservers.domainRuntime

In the User Name and Password fields, enter the user name and password of any user account that is assigned the admin role. This login will be used to authenticate the client and create the Subject that will be associated with each JMX request coming from the client.

Click Connect.

Accessing Custom MBeans from WebLogic Scripting Tool

If you register your MBeans in the Runtime MBean Server or Domain Runtime MBean Server, you can use WebLogic Scripting Tool to access your custom MBeans. See "Accessing Other WebLogic MBeans and Custom MBeans" in Oracle WebLogic Scripting Tool.

Accessing Custom MBeans from an Administration Console Extension

You can extend the WebLogic Server Administration Console by creating Java Server Pages (JSPs) that conform to a specific template. Your JSP can include JMX code that connects to the JVM platform MBean server, the WebLogic Server Runtime MBean Server, or the Domain Runtime MBean Server and looks up your MBeans.

For more information, see Extending the Administration Console for Oracle WebLogic Server.

This figure shows the standard MBean development process.

This figure shows how a notification listener receives a subset of information broadcast from an MBean called Notifications. The information must satisfy a set of filter criteria.

This figure shows a monitor MBean registered with an observed MBean. A notification MBean is registered with the monitor MBean. If a notification satisfies filter criteria set in the monitor MBean, the notification is passed to the notification listener.

This figure shows an MBean server with a delegate class and a standard MBean interface. Session EJBs push management data to the delegate class. JMX clients get management data through the MBean server.

This figure illustrates how a management system uses JMX to access properties in an MBean.

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2010, Oracle and/or its affiliates. All rights reserved.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

Hazardous Applications Notice

This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.

Trademark Notice

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

Third-Party Content, Products, and Services Disclaimer

This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.