001: /* JFox, the OpenSource J2EE Application Server
002: *
003: * Copyright (C) 2002 huihoo.org
004: * Distributable under GNU LGPL license
005: * See the GNU Lesser General Public License for more details.
006: */
007:
008: package javax.management.timer;
009:
010: import java.util.Date;
011: import java.util.Vector;
012: import javax.management.InstanceNotFoundException;
013:
014: /**
015: * Exposes the management interface of the timer MBean.
016: *
017: * @author <a href="mailto:young_yy@hotmail.org">Young Yang</a>
018: */
019:
020: public interface TimerMBean {
021: /**
022: * Starts the timer.
023: * <P>
024: * If there is one or more timer notifications before the time in the list of notifications, the notification
025: * is sent according to the <CODE>sendPastNotifications</CODE> flag and then, updated
026: * according to its period and remaining number of occurences.
027: * If the timer notification date remains earlier than the current date, this notification is just removed
028: * from the list of notifications.
029: */
030: public void start();
031:
032: /**
033: * Stops the timer.
034: */
035: public void stop();
036:
037: /**
038: * Creates a new timer notification with the specified <CODE>type</CODE>, <CODE>message</CODE>
039: * and <CODE>userData</CODE> and inserts it into the list of notifications with a given date,
040: * period and number of occurences.
041: * <P>
042: * If the timer notification to be inserted has a date that is before the current date,
043: * the method behaves as if the specified date were the current date. <BR>
044: * For once-off notifications, the notification is delivered immediately. <BR>
045: * For periodic notifications, the first notification is delivered immediately and the
046: * subsequent ones are spaced as specified by the period parameter.
047: * <P>
048: * Note that once the timer notification has been added into the list of notifications,
049: * its associated date, period and number of occurences cannot be updated.
050: * <P>
051: * In the case of a periodic notification, the value of parameter <i>fixedRate</i> is used to
052: * specify the execution scheme, as specified in {@link java.util.Timer}.
053: *
054: * @param type The timer notification type.
055: * @param message The timer notification detailed message.
056: * @param userData The timer notification user data object.
057: * @param date The date when the notification occurs.
058: * @param period The period of the timer notification (in milliseconds).
059: * @param nbOccurences The total number the timer notification will be emitted.
060: * @param fixedRate If <code>true</code> and if the notification is periodic, the notification
061: * is scheduled with a <i>fixed-rate</i> execution scheme. If
062: * <code>false</code> and if the notification is periodic, the notification
063: * is scheduled with a <i>fixed-delay</i> execution scheme. Ignored if the
064: * notification is not periodic.
065: *
066: * @return The identifier of the new created timer notification.
067: *
068: * @exception java.lang.IllegalArgumentException The period or the number of occurences is negative
069: *
070: * @see #addNotification(String, String, Object, Date, long, long)
071: */
072: // NPCTE fix for bugId 4464388, esc 0, MR, to be added after modification of jmx spec
073: // public synchronized Integer addNotification(String type, String message, Serializable userData,
074: // Date date, long period, long nbOccurences)
075: // end of NPCTE fix for bugId 4464388
076: public Integer addNotification(String type, String message,
077: Object userData, Date date, long period, long nbOccurences,
078: boolean fixedRate)
079: throws java.lang.IllegalArgumentException;
080:
081: /**
082: * Creates a new timer notification with the specified <CODE>type</CODE>, <CODE>message</CODE>
083: * and <CODE>userData</CODE> and inserts it into the list of notifications with a given date,
084: * period and number of occurences.
085: * <P>
086: * If the timer notification to be inserted has a date that is before the current date,
087: * the method behaves as if the specified date were the current date. <BR>
088: * For once-off notifications, the notification is delivered immediately. <BR>
089: * For periodic notifications, the first notification is delivered immediately and the
090: * subsequent ones are spaced as specified by the period parameter.
091: * <P>
092: * Note that once the timer notification has been added into the list of notifications,
093: * its associated date, period and number of occurences cannot be updated.
094: * <P>
095: * In the case of a periodic notification, uses a <i>fixed-delay</i> execution scheme, as specified in
096: * {@link java.util.Timer}. In order to use a <i>fixed-rate</i> execution scheme, use
097: * {@link #addNotification(String, String, Object, Date, long, long, boolean)} instead.
098: *
099: * @param type The timer notification type.
100: * @param message The timer notification detailed message.
101: * @param userData The timer notification user data object.
102: * @param date The date when the notification occurs.
103: * @param period The period of the timer notification (in milliseconds).
104: * @param nbOccurences The total number the timer notification will be emitted.
105: *
106: * @return The identifier of the new created timer notification.
107: *
108: * @exception java.lang.IllegalArgumentException The period or the number of occurences is negative
109: *
110: * @see #addNotification(String, String, Object, Date, long, long, boolean)
111: */
112: // NPCTE fix for bugId 4464388, esc 0, MR , to be added after modification of jmx spec
113: // public synchronized Integer addNotification(String type, String message, Serializable userData,
114: // Date date, long period)
115: // end of NPCTE fix for bugId 4464388 */
116: public Integer addNotification(String type, String message,
117: Object userData, Date date, long period, long nbOccurences)
118: throws java.lang.IllegalArgumentException;
119:
120: /**
121: * Creates a new timer notification with the specified <CODE>type</CODE>, <CODE>message</CODE>
122: * and <CODE>userData</CODE> and inserts it into the list of notifications with a given date
123: * and period and a null number of occurences.
124: * <P>
125: * The timer notification will repeat continuously using the timer period using a <i>fixed-delay</i>
126: * execution scheme, as specified in {@link java.util.Timer}. In order to use a <i>fixed-rate</i>
127: * execution scheme, use {@link #addNotification(String, String, Object, Date, long, long,
128: * boolean)} instead.
129: * <P>
130: * If the timer notification to be inserted has a date that is before the current date,
131: * the method behaves as if the specified date were the current date. The
132: * first notification is delivered immediately and the subsequent ones are
133: * spaced as specified by the period parameter.
134: *
135: * @param type The timer notification type.
136: * @param message The timer notification detailed message.
137: * @param userData The timer notification user data object.
138: * @param date The date when the notification occurs.
139: * @param period The period of the timer notification (in milliseconds).
140: *
141: * @return The identifier of the new created timer notification.
142: *
143: * @exception java.lang.IllegalArgumentException The period is negative or
144: * the date notification is before the current date.
145: */
146: // NPCTE fix for bugId 4464388, esc 0, MR , to be added after modification of jmx spec
147: // public synchronized Integer addNotification(String type, String message, Serializable userData,
148: // Date date, long period)
149: // end of NPCTE fix for bugId 4464388 */
150: public Integer addNotification(String type, String message,
151: Object userData, Date date, long period)
152: throws java.lang.IllegalArgumentException;
153:
154: /**
155: * Creates a new timer notification with the specified <CODE>type</CODE>, <CODE>message</CODE>
156: * and <CODE>userData</CODE> and inserts it into the list of notifications with a given date
157: * and a null period and number of occurences.
158: * <P>
159: * The timer notification will be handled once at the specified date.
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 and the
163: * notification is delivered immediately.
164: *
165: * @param type The timer notification type.
166: * @param message The timer notification detailed message.
167: * @param userData The timer notification user data object.
168: * @param date The date when the notification occurs.
169: *
170: * @return The identifier of the new created timer notification.
171: *
172: * @exception java.lang.IllegalArgumentException The date notification is before the current date.
173: */
174: // NPCTE fix for bugId 4464388, esc 0, MR, to be added after modification of jmx spec
175: // public synchronized Integer addNotification(String type, String message, Serializable userData, Date date)
176: // throws java.lang.IllegalArgumentException {
177: // end of NPCTE fix for bugId 4464388
178: public Integer addNotification(String type, String message,
179: Object userData, Date date)
180: throws java.lang.IllegalArgumentException;
181:
182: /**
183: * Removes the timer notification corresponding to the specified identifier from the list of notifications.
184: *
185: * @param id The timer notification identifier.
186: *
187: * @exception InstanceNotFoundException The specified identifier does not correspond to any timer notification
188: * in the list of notifications of this timer MBean.
189: */
190: public void removeNotification(Integer id)
191: throws InstanceNotFoundException;
192:
193: /**
194: * Removes all the timer notifications corresponding to the specified type from the list of notifications.
195: *
196: * @param type The timer notification type.
197: *
198: * @exception InstanceNotFoundException The specified type does not correspond to any timer notification
199: * in the list of notifications of this timer MBean.
200: */
201: public void removeNotifications(String type)
202: throws InstanceNotFoundException;
203:
204: /**
205: * Removes all the timer notifications from the list of notifications
206: * and resets the counter used to update the timer notification identifiers.
207: */
208: public void removeAllNotifications();
209:
210: // GETTERS AND SETTERS
211: //--------------------
212:
213: /**
214: * Gets the number of timer notifications registered into the list of notifications.
215: *
216: * @return The number of timer notifications.
217: */
218: public int getNbNotifications();
219:
220: /**
221: * Gets all timer notification identifiers registered into the list of notifications.
222: *
223: * @return A vector of <CODE>Integer</CODE> objects containing all the timer notification identifiers.
224: * <BR>The vector is empty if there is no timer notification registered for this timer MBean.
225: */
226: public Vector getAllNotificationIDs();
227:
228: /**
229: * Gets all the identifiers of timer notifications corresponding to the specified type.
230: *
231: * @param type The timer notification type.
232: *
233: * @return A vector of <CODE>Integer</CODE> objects containing all the identifiers of
234: * timer notifications with the specified <CODE>type</CODE>.
235: * <BR>The vector is empty if there is no timer notifications registered for this timer MBean
236: * with the specified <CODE>type</CODE>.
237: */
238: public Vector getNotificationIDs(String type);
239:
240: /**
241: * Gets the timer notification type corresponding to the specified identifier.
242: *
243: * @param id The timer notification identifier.
244: *
245: * @return The timer notification type or null if the identifier is not mapped to any
246: * timer notification registered for this timer MBean.
247: */
248: public String getNotificationType(Integer id);
249:
250: /**
251: * Gets the timer notification detailed message corresponding to the specified identifier.
252: *
253: * @param id The timer notification identifier.
254: *
255: * @return The timer notification detailed message or null if the identifier is not mapped to any
256: * timer notification registered for this timer MBean.
257: */
258: public String getNotificationMessage(Integer id);
259:
260: /**
261: * Gets the timer notification user data object corresponding to the specified identifier.
262: *
263: * @param id The timer notification identifier.
264: *
265: * @return The timer notification user data object or null if the identifier is not mapped to any
266: * timer notification registered for this timer MBean.
267: */
268: // NPCTE fix for bugId 4464388, esc 0 , MR , 03 sept 2001 , to be added after modification of jmx spec
269: //public Serializable getNotificationUserData(Integer id);
270: // end of NPCTE fix for bugId 4464388
271: public Object getNotificationUserData(Integer id);
272:
273: /**
274: * Gets a copy of the date associated to a timer notification.
275: *
276: * @param id The timer notification identifier.
277: *
278: * @return A copy of the date or null if the identifier is not mapped to any
279: * timer notification registered for this timer MBean.
280: */
281: public Date getDate(Integer id);
282:
283: /**
284: * Gets a copy of the period (in milliseconds) associated to a timer notification.
285: *
286: * @param id The timer notification identifier.
287: *
288: * @return A copy of the period or null if the identifier is not mapped to any
289: * timer notification registered for this timer MBean.
290: */
291: public Long getPeriod(Integer id);
292:
293: /**
294: * Gets a copy of the remaining number of occurences associated to a timer notification.
295: *
296: * @param id The timer notification identifier.
297: *
298: * @return A copy of the remaining number of occurences or null if the identifier is not mapped to any
299: * timer notification registered for this timer MBean.
300: */
301: public Long getNbOccurences(Integer id);
302:
303: /**
304: * Gets a copy of the flag indicating whether a peridic notification is
305: * executed at <i>fixed-delay</i> or at <i>fixed-rate</i>.
306: *
307: * @param id The timer notification identifier.
308: *
309: * @return A copy of the flag indicating whether a peridic notification is
310: * executed at <i>fixed-delay</i> or at <i>fixed-rate</i>.
311: */
312: public Boolean getFixedRate(Integer id);
313:
314: /**
315: * Gets the flag indicating whether or not the timer sends past notifications.
316: *
317: * @return The past notifications sending on/off flag value.
318: *
319: * @see #setSendPastNotifications
320: */
321: public boolean getSendPastNotifications();
322:
323: /**
324: * Sets the flag indicating whether the timer sends past notifications or not.
325: *
326: * @param value The past notifications sending on/off flag value.
327: *
328: * @see #getSendPastNotifications
329: */
330: public void setSendPastNotifications(boolean value);
331:
332: /**
333: * Tests whether the timer MBean is active.
334: * A timer MBean is marked active when the {@link #start doStart} method is called.
335: * It becomes inactive when the {@link #stop doStop} method is called.
336: *
337: * @return <CODE>true</CODE> if the timer MBean is active, <CODE>false</CODE> otherwise.
338: */
339: public boolean isActive();
340:
341: /**
342: * Tests whether the list of timer notifications is empty.
343: *
344: * @return <CODE>true</CODE> if the list of timer notifications is empty, <CODE>false</CODE> otherwise.
345: */
346: public boolean isEmpty();
347:
348: }
|