Programming WebLogic Management Services with JMX
WebLogic Server includes a timer service that you can configure to emit notifications at specific dates and times or at a constant interval. To listen and respond to these timer notifications, you create a JMX notification listener and register it with the timer service.
The WebLogic timer service extends the standard JMX timer service, enabling it to run within a Weblogic Server execute thread and within the security context of a WebLogic Server user account. (Execute threads enable you to fine-tune your application's use of server resources and optimize performance. For more information, refer to "Using Execute Queues to Control Thread Usage" in WebLogic Server Performance and Tuning.)
The following sections describe how to use the WebLogic timer service:
WebLogic Server does not provide a centralized timer service that can be accessed by all resources that are deployed on a specific server instance. Instead, each application constructs and manages instances of the timer service as it requires. Each time you restart a server instance, each application must re-instantiate any timer service configurations it needs.
To configure the WebLogic timer service to emit notifications and to create a listener that receives those notifications, create a class that does the following:
Timer
.addNotification
API to configure the Timer
MBean to emit a notification object at a specific time or at a recurring interval. The class can invoke the addNotification
API multiple times to configure the Timer
MBean to emit notification objects at different times and time intervals.
Timer
MBean. Your class can register multiple listeners and filters with the Timer
MBean instance.
For information about creating and registering listeners, refer to Listening for Notifications from WebLogic Server MBeans: Main Steps.
When your listener receives notifications, it can invoke TimerNotification
methods to retrieve data from the notification.
An application can include multiple classes that construct and configure a Timer
MBean. Each class uses its own instance of the Timer
MBean and listens for notifications only from the Timer
MBean that it instantiated.
To configure a Timer
MBean instance to emit notifications, you invoke the MBean's addNotification
method. The method includes parameters that configure the frequency of notifications and specify a handback object.
When you invoke the addNotification
method, the timer service creates a TimerNotification
object and returns an identifier for the new object. You can use this identifier to retrieve information about the TimerNotification
object from the timer or to remove the object from the timer's list of notifications. When the time that you specify arrives, the timer service emits the TimerNotification
object along with a reference to the handback object.
The method signature for addNotification
is as follows:
addNotification (java.lang.String type, java.lang.String message,
java.lang.Object userData,java.util.Date startTime,
long period, long nbOccurences)
Table 7-1 describes each parameter of the addNotification
API. For more information, refer to the WebLogic Server Javadoc for weblogic.management.timer.Timer
.
A string that you use to identify the event that triggers this notification to be broadcast. For example, you can specify |
|
Specifies the value of the |
|
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. |
|
Specifies a For more information, refer to the next section, Specifying Time Intervals. |
|
(Optional) Specifies the interval in milliseconds between notification occurrences. Repeating notifications are not enabled if this parameter is zero or is not defined ( For more information, refer to the next section, Specifying Time Intervals. |
|
(Optional) Specifies the total number of times that the notification will occur. If the value of this parameter is zero or is not defined ( If you specify this parameter, each time the |
To facilitate specifying dates, the Timer
MBean includes the following integer constants:
ONE_SECOND
, which resolves to the number of milliseconds in one second.ONE_MINUTE
, which resolves to the number of milliseconds in one minute.ONE_HOUR
, which resolves to the number of milliseconds in one hour.ONE_DAY
, which resolves to the number of milliseconds in one day.ONE_WEEK
, which resolves to the number of milliseconds in one week.For example, the following code configures the timer service to emit a TimerNotification
object once a day at midnight:
java.util.Date midnight =
java.util.Calendar.getInstance.set(HOUR_OF_DAY=24:00:00).getTime();
addNotification (eachMidnight, "the time is midnight",
this,midnight,Timer.ONE_DAY);
If the time and date that you specify is earlier than the current time and date, the addNotification
method attempts to update this entry as follows:
period
parameter, the method increments the date
value by the period
value until the date is later than the current date. For example, if you specified ONE_DAY
for the period
value, the addNotification
increments the date
value one day until it is later than the current date.nbOccurrences
parameter, the method updates the notification date as explained above. Each time it increments the date
value, it decreases the specified number of occurrences by one. If the number of occurrences reaches 0
and the notification date remains earlier than the current date, the method throws IllegalArgumentException
.period
parameter, the notification date cannot be updated and the method throws IllegalArgumentException
.
The code in Listing 7-1 is a servlet listener that configures the timer service to emit notifications every minute. It takes the following actions:
NotificationListener
class so it can listen for notifications from the Timer
MBean that the class instantiates.The Date object configures the timer to start emitting this notification 5 seconds after it is added to the Timer
MBean's notification list. The PERIOD
value causes the notification to be emitted every minute.
The class attaches itself as the user-defined userData
object.
Each time the Timer
MBean emits a notification, it will emit a TimerNotification
object that contains this object, and whose Message
attribute contains the string a recurring call, and whose Type
attribute contains the string oneMinuteTimer
.
When you redeploy or undeploy the servlet, it invokes it the Timer.stop
method for the Timer
MBean instance that is represented by the timer
variable.
import java.util.Date;
import javax.management.Notification;
import javax.management.NotificationListener;
import javax.management.InstanceNotFoundException;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
import weblogic.management.timer.Timer;
// Implementing NotificationListener
public final class LifecycleListener implements ServletContextListener,
NotificationListener {
private static final long PERIOD = Timer.ONE_MINUTE;
private Timer timer;
private Integer notificationId;
public void contextInitialized(ServletContextEvent event) {
System.out.println(">>> contextInitialized called.");
// Instantiating the Timer MBean
timer = new Timer();
// Registering this class as a listener
timer.addNotificationListener(this, null, "some handback object");
// Adding the notification to the Timer and assigning the
// ID that the Timer returns to a variable
Date timerTriggerAt = new Date((new Date()).getTime() + 5000L);
notificationId = timer.addNotification("oneMinuteTimer",
"a recurring call", this,
timerTriggerAt, PERIOD);
timer.start();
System.out.println(">>> timer started.");
}
public void contextDestroyed(ServletContextEvent event) {
System.out.println(">>> contextDestroyed called.");
try {
timer.stop();
timer.removeNotification(notificationId);
System.out.println(">>> timer stopped.");
} catch (InstanceNotFoundException e) {
e.printStackTrace();
}
}
/* callback method */
public void handleNotification(Notification notif, Object handback) {
System.out.println(">>> "+(new Date())+
" timer handleNotification="+notif+
", handback="+handback);
}
}
The deployment descriptor for the servlet listener must use the <listener>
and <listener-class>
statements to declare the class in the example above. See Listing 7-2.
Listing 7-2 Deployment Descriptor for Servlet Listener
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application
2.3//EN" "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">
<web-app>
<listener>
<listener-class>
examples.jmxtimer.LifecycleListener
</listener-class>
</listener>
</web-app>
The Timer
MBean removes notifications from its list when either of the following occurs:
The Timer
MBean also provides the following APIs to remove notifications:
removeAllNotifications()
, which remove all notifications that are registered with the Timer
MBean instance.removeNotification(java.lang.Integer id)
, which removes the notification whose ID matches the ID you specify. The addNotification
method returns this ID when you invoke it. You can also use Timer
APIs to retrieve IDs. removeNotifications(java.lang.String type)
, which removes all notifications whose type corresponds to the type that you specify.To use these remove notification APIs for a given Timer
MBean instance, add them to the class that you use to instantiate the Timer
MBean. Wrap each API within a method, similar to the timer.start()
and timer.stop()
invocations in Listing 7-1. For example, if you assigned the Timer
MBean instance to a variable named timer
, add the following method to your class:
public void removeMyNotification (java.lang.Integer id) {
timer.removeNotification(id);
}
For more information, refer to the WebLogic Server Javadoc for weblogic.management.timer.Timer
.