TimerMBean


1   /*
2    * @(#)TimerMBean.java  4.25 04/02/10
3    * 
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.management.timer; 
9   
10  
11  
12  // java imports
13  //
14  import java.util.Date  ;
15  import java.util.Enumeration  ;
16  import java.util.Vector  ;
17  // NPCTE fix for bugId 4464388, esc 0,  MR , to be added after modification of jmx spec
18  //import java.io.Serializable;
19  // end of NPCTE fix for bugId 4464388 
20  
21  // jmx imports
22  //
23  import javax.management.InstanceNotFoundException  ;
24  
25  /**
26   * Exposes the management interface of the timer MBean.
27   *
28   * @version     4.25     02/10/04
29   * @author      Sun Microsystems, Inc
30   *
31   * @since 1.5
32   */
33  public interface TimerMBean { 
34  
35      /**
36       * Starts the timer.
37       * <P>
38       * If there is one or more timer notifications before the time in the list of notifications, the notification
39       * is sent according to the <CODE>sendPastNotifications</CODE> flag and then, updated
40       * according to its period and remaining number of occurrences.
41       * If the timer notification date remains earlier than the current date, this notification is just removed 
42       * from the list of notifications.
43       */
44      public void start();
45      
46      /**
47       * Stops the timer.
48       */
49      public void stop();
50              
51      /**
52       * Creates a new timer notification with the specified <CODE>type</CODE>, <CODE>message</CODE> 
53       * and <CODE>userData</CODE> and inserts it into the list of notifications with a given date, 
54       * period and number of occurrences.
55       * <P>
56       * If the timer notification to be inserted has a date that is before the current date,
57       * the method behaves as if the specified date were the current date. <BR>
58       * For once-off notifications, the notification is delivered immediately. <BR>
59       * For periodic notifications, the first notification is delivered immediately and the
60       * subsequent ones are spaced as specified by the period parameter. 
61       * <P>
62       * Note that once the timer notification has been added into the list of notifications,
63       * its associated date, period and number of occurrences cannot be updated.
64       * <P>
65       * In the case of a periodic notification, the value of parameter <i>fixedRate</i> is used to
66       * specify the execution scheme, as specified in {@link java.util.Timer}.
67       *
68       * @param type The timer notification type.
69       * @param message The timer notification detailed message.
70       * @param userData The timer notification user data object.
71       * @param date The date when the notification occurs.
72       * @param period The period of the timer notification (in milliseconds).
73       * @param nbOccurences The total number the timer notification will be emitted.
74       * @param fixedRate If <code>true</code> and if the notification is periodic, the notification
75       *                  is scheduled with a <i>fixed-rate</i> execution scheme. If
76       *                  <code>false</code> and if the notification is periodic, the notification
77       *                  is scheduled with a <i>fixed-delay</i> execution scheme. Ignored if the
78       *                  notification is not periodic.
79       *
80       * @return The identifier of the new created timer notification.
81       *
82       * @exception java.lang.IllegalArgumentException The period or the number of occurrences is negative
83       *
84       * @see #addNotification(String, String, Object, Date, long, long)
85       */
86  // NPCTE fix for bugId 4464388, esc 0,  MR, to be added after modification of jmx spec
87  //  public synchronized Integer addNotification(String type, String message, Serializable userData, 
88  //                                                Date date, long period, long nbOccurences) 
89  // end of NPCTE fix for bugId 4464388
90  
91      public Integer   addNotification(String   type, String   message, Object   userData,
92                                     Date   date, long period, long nbOccurences, boolean fixedRate)
93          throws java.lang.IllegalArgumentException  ;
94  
95      /**
96       * Creates a new timer notification with the specified <CODE>type</CODE>, <CODE>message</CODE> 
97       * and <CODE>userData</CODE> and inserts it into the list of notifications with a given date, 
98       * period and number of occurrences.
99       * <P>
100      * If the timer notification to be inserted has a date that is before the current date,
101      * the method behaves as if the specified date were the current date. <BR>
102      * For once-off notifications, the notification is delivered immediately. <BR>
103      * For periodic notifications, the first notification is delivered immediately and the
104      * subsequent ones are spaced as specified by the period parameter. 
105      * <P>
106      * Note that once the timer notification has been added into the list of notifications,
107      * its associated date, period and number of occurrences cannot be updated.
108      * <P>
109      * In the case of a periodic notification, uses a <i>fixed-delay</i> execution scheme, as specified in
110      * {@link java.util.Timer}. In order to use a <i>fixed-rate</i> execution scheme, use 
111      * {@link #addNotification(String, String, Object, Date, long, long, boolean)} instead.
112      *
113      * @param type The timer notification type.
114      * @param message The timer notification detailed message.
115      * @param userData The timer notification user data object.
116      * @param date The date when the notification occurs.
117      * @param period The period of the timer notification (in milliseconds).
118      * @param nbOccurences The total number the timer notification will be emitted.
119      *
120      * @return The identifier of the new created timer notification.
121      *
122      * @exception java.lang.IllegalArgumentException The period or the number of occurrences is negative
123      *
124      * @see #addNotification(String, String, Object, Date, long, long, boolean)
125      */
126 // NPCTE fix for bugId 4464388, esc 0,  MR , to be added after modification of jmx spec 
127 //  public synchronized Integer addNotification(String type, String message, Serializable userData, 
128 //                                              Date date, long period) 
129 // end of NPCTE fix for bugId 4464388 */ 
130 
131     public Integer   addNotification(String   type, String   message, Object   userData,
132                                    Date   date, long period, long nbOccurences) 
133         throws java.lang.IllegalArgumentException  ;
134         
135     /**
136      * Creates a new timer notification with the specified <CODE>type</CODE>, <CODE>message</CODE> 
137      * and <CODE>userData</CODE> and inserts it into the list of notifications with a given date
138      * and period and a null number of occurrences.
139      * <P>
140      * The timer notification will repeat continuously using the timer period using a <i>fixed-delay</i>
141      * execution scheme, as specified in {@link java.util.Timer}. In order to use a <i>fixed-rate</i>
142      * execution scheme, use {@link #addNotification(String, String, Object, Date, long, long,
143      * boolean)} instead. 
144      * <P>
145      * If the timer notification to be inserted has a date that is before the current date,
146      * the method behaves as if the specified date were the current date. The
147      * first notification is delivered immediately and the subsequent ones are
148      * spaced as specified by the period parameter.
149      * 
150      * @param type The timer notification type.
151      * @param message The timer notification detailed message.
152      * @param userData The timer notification user data object.
153      * @param date The date when the notification occurs.
154      * @param period The period of the timer notification (in milliseconds).
155      *
156      * @return The identifier of the new created timer notification.
157      *
158      * @exception java.lang.IllegalArgumentException The period is negative or
159      * the date notification is before the current date.
160      */
161 // NPCTE fix for bugId 4464388, esc 0,  MR , to be added after modification of jmx spec 
162 //  public synchronized Integer addNotification(String type, String message, Serializable userData, 
163 //                                              Date date, long period) 
164 // end of NPCTE fix for bugId 4464388 */ 
165 
166     public Integer   addNotification(String   type, String   message, Object   userData,
167                                    Date   date, long period)
168         throws java.lang.IllegalArgumentException  ;
169   
170     /**
171      * Creates a new timer notification with the specified <CODE>type</CODE>, <CODE>message</CODE> 
172      * and <CODE>userData</CODE> and inserts it into the list of notifications with a given date
173      * and a null period and number of occurrences.
174      * <P>
175      * The timer notification will be handled once at the specified date.
176      * <P>
177      * If the timer notification to be inserted has a date that is before the current date,
178      * the method behaves as if the specified date were the current date and the
179      * notification is delivered immediately.
180      * 
181      * @param type The timer notification type.
182      * @param message The timer notification detailed message.
183      * @param userData The timer notification user data object.
184      * @param date The date when the notification occurs.
185      *
186      * @return The identifier of the new created timer notification.
187      *
188      * @exception java.lang.IllegalArgumentException The date notification is before the current date.
189      */
190 // NPCTE fix for bugId 4464388, esc 0,  MR, to be added after modification of jmx spec
191 //  public synchronized Integer addNotification(String type, String message, Serializable userData, Date date) 
192 //      throws java.lang.IllegalArgumentException {
193 // end of NPCTE fix for bugId 4464388
194  
195     public Integer   addNotification(String   type, String   message, Object   userData, Date   date)
196         throws java.lang.IllegalArgumentException  ;
197 
198     /**
199      * Removes the timer notification corresponding to the specified identifier from the list of notifications.
200      * 
201      * @param id The timer notification identifier.
202      *
203      * @exception InstanceNotFoundException The specified identifier does not correspond to any timer notification
204      * in the list of notifications of this timer MBean.
205      */
206     public void removeNotification(Integer   id) throws InstanceNotFoundException  ;
207       
208     /**
209      * Removes all the timer notifications corresponding to the specified type from the list of notifications.
210      * 
211      * @param type The timer notification type.
212      *
213      * @exception InstanceNotFoundException The specified type does not correspond to any timer notification
214      * in the list of notifications of this timer MBean.
215      */
216     public void removeNotifications(String   type) throws InstanceNotFoundException  ;
217     
218     /**
219      * Removes all the timer notifications from the list of notifications
220      * and resets the counter used to update the timer notification identifiers.
221      */
222     public void removeAllNotifications();
223     
224     // GETTERS AND SETTERS
225     //--------------------    
226         
227     /**
228      * Gets the number of timer notifications registered into the list of notifications.
229      *
230      * @return The number of timer notifications.
231      */
232     public int getNbNotifications();
233     
234     /**
235      * Gets all timer notification identifiers registered into the list of notifications.
236      *
237      * @return A vector of <CODE>Integer</CODE> objects containing all the timer notification identifiers.
238      * <BR>The vector is empty if there is no timer notification registered for this timer MBean.
239      */
240     public Vector   getAllNotificationIDs();
241     
242     /**
243      * Gets all the identifiers of timer notifications corresponding to the specified type.
244      *
245      * @param type The timer notification type.
246      *
247      * @return A vector of <CODE>Integer</CODE> objects containing all the identifiers of 
248      * timer notifications with the specified <CODE>type</CODE>.
249      * <BR>The vector is empty if there is no timer notifications registered for this timer MBean 
250      * with the specified <CODE>type</CODE>.
251      */
252     public Vector   getNotificationIDs(String   type);
253     
254     /**
255      * Gets the timer notification type corresponding to the specified identifier.
256      *
257      * @param id The timer notification identifier.
258      *
259      * @return The timer notification type or null if the identifier is not mapped to any 
260      * timer notification registered for this timer MBean.
261      */
262     public String   getNotificationType(Integer   id);
263     
264     /**
265      * Gets the timer notification detailed message corresponding to the specified identifier.
266      *
267      * @param id The timer notification identifier.
268      *
269      * @return The timer notification detailed message or null if the identifier is not mapped to any 
270      * timer notification registered for this timer MBean.
271      */
272     public String   getNotificationMessage(Integer   id);
273     
274     /**
275      * Gets the timer notification user data object corresponding to the specified identifier.
276      *
277      * @param id The timer notification identifier.
278      *
279      * @return The timer notification user data object or null if the identifier is not mapped to any 
280      * timer notification registered for this timer MBean.
281      */
282     // NPCTE fix for bugId 4464388, esc 0 , MR , 03 sept 2001 , to be added after modification of jmx spec
283     //public Serializable getNotificationUserData(Integer id);
284     // end of NPCTE fix for bugId 4464388
285     public Object   getNotificationUserData(Integer   id);    
286     /**
287      * Gets a copy of the date associated to a timer notification.
288      *
289      * @param id The timer notification identifier.
290      *
291      * @return A copy of the date or null if the identifier is not mapped to any 
292      * timer notification registered for this timer MBean.
293      */
294     public Date   getDate(Integer   id);
295     
296     /**
297      * Gets a copy of the period (in milliseconds) associated to a timer notification.
298      *
299      * @param id The timer notification identifier.
300      *
301      * @return A copy of the period or null if the identifier is not mapped to any 
302      * timer notification registered for this timer MBean.
303      */
304     public Long   getPeriod(Integer   id);
305     
306     /**
307      * Gets a copy of the remaining number of occurrences associated to a timer notification.
308      *
309      * @param id The timer notification identifier.
310      *
311      * @return A copy of the remaining number of occurrences or null if the identifier is not mapped to any 
312      * timer notification registered for this timer MBean.
313      */
314     public Long   getNbOccurences(Integer   id);
315     
316     /**
317      * Gets a copy of the flag indicating whether a periodic notification is
318      * executed at <i>fixed-delay</i> or at <i>fixed-rate</i>.
319      *
320      * @param id The timer notification identifier.
321      *
322      * @return A copy of the flag indicating whether a periodic notification is
323      *         executed at <i>fixed-delay</i> or at <i>fixed-rate</i>.
324      */
325     public Boolean   getFixedRate(Integer   id);
326     
327     /**
328      * Gets the flag indicating whether or not the timer sends past notifications.
329      *
330      * @return The past notifications sending on/off flag value.
331      *
332      * @see #setSendPastNotifications
333      */
334     public boolean getSendPastNotifications();
335     
336     /**
337      * Sets the flag indicating whether the timer sends past notifications or not.
338      *
339      * @param value The past notifications sending on/off flag value.
340      *
341      * @see #getSendPastNotifications
342      */
343     public void setSendPastNotifications(boolean value);
344     
345     /**
346      * Tests whether the timer MBean is active.
347      * A timer MBean is marked active when the {@link #start start} method is called.
348      * It becomes inactive when the {@link #stop stop} method is called.
349      *
350      * @return <CODE>true</CODE> if the timer MBean is active, <CODE>false</CODE> otherwise.
351      */
352     public boolean isActive();
353 
354     /**
355      * Tests whether the list of timer notifications is empty.
356      *
357      * @return <CODE>true</CODE> if the list of timer notifications is empty, <CODE>false</CODE> otherwise.
358      */
359     public boolean isEmpty();
360 }
361
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags