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