Developing Manageable Applications with JMX

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

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

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 J2SE 5.0 API Specification); 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:

  1. Create a JMX listener class in your application.
  2. For general instructions on creating a JMX listener, see Creating a Notification Listener in Developing Custom Management Utilities in JMX.

  3. Create a class that does the following:
    1. 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 J2SE 5.0 API Specification.
    2. 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.

    3. Registers your listener and an optional filter with the timer MBean that you configured.
    4. Starts the timer in the timer MBean that you configured.
    5. For general instructions, see Configuring a Notification Filter and Registering a Notification Listener and Filter in Developing Custom Management Utilities in JMX.

    6. Unregisters the timer MBean and closes its connection to the MBean server when it finishes using the timer service.
  4. 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 in JMX.

 


Configuring a Timer MBean to Emit Notifications

To configure a Timer MBean instance to emit a notification:

  1. Initialize a connection to the Domain Runtime MBean Server.
  2. See Connect to an MBean Server in Developing Custom Management Utilities in JMX.

  3. Create an ObjectName for your timer MBean instance.
  4. See javax.management.ObjectName in the J2SE 5.0 API Specification.

    BEA 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"

  5. Create and register the timer MBean.
  6. 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).
  7. Configure the timer MBean to emit a notification.
  8. 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.

  9. Repeat step 4 for each timer notification that your JMX client needs to receive.
  10. 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.
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:

  1. Create an instance of java.util.Calendar.
  2. Configure the fields in the Calendar object to represent the time or date.
  3. 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 J2SE 5.0 API Specification.

 


Example: Generating a Notification Every Five Minutes After 9 AM

The code in Listing 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:

 


Removing Notifications

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

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

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


  Back to Top       Previous  Next