001: /**
002: * The XMOJO Project 5
003: * Copyright © 2003 XMOJO.org. All rights reserved.
004:
005: * NO WARRANTY
006:
007: * BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
008: * THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
009: * OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
010: * PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
011: * OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
012: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
013: * TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE
014: * LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
015: * REPAIR OR CORRECTION.
016:
017: * IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
018: * ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
019: * THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
020: * GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
021: * USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF
022: * DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
023: * PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE),
024: * EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
025: * SUCH DAMAGES.
026: **/package javax.management.timer;
027:
028: import java.util.Date;
029: import java.util.Vector;
030:
031: import javax.management.InstanceNotFoundException;
032:
033: /**
034: * This interface exposes the management interface of the timer MBean.
035: */
036: public abstract interface TimerMBean {
037: /**
038: * This method starts the timer.
039: * <P>
040: * If there is one or more timer notifications before the time in the
041: * list of notifications, the notification is sent according to the
042: * <CODE>sendPastNotifications</CODE> flag and then, updated according
043: * to its period and remaining number of occurences. If the timer
044: * notification date remains earlier than the current date, this
045: * notification is just removed from the list of notifications.
046: */
047: public void start();
048:
049: /**
050: * This method stops the timer.
051: */
052: public void stop();
053:
054: /**
055: * This method creates a new timer notification with the specified
056: * <CODE>type</CODE>, <CODE>message</CODE> and <CODE>userData</CODE>
057: * and inserts it into the list of notifications with a given date and
058: * a null period and number of occurences.
059: * <P>
060: * The timer notification will be handled once at the specified date.
061: *
062: * @param type The timer notification type.
063: *
064: * @param message The timer notification detailed message.
065: *
066: * @param userData The timer notification user data object.
067: *
068: * @param date The date when the notification occurs.
069: *
070: * @return An instance of java.lang.Integer which is the identifier of
071: * the new created timer notification.
072: *
073: * @exception java.lang.IllegalArgumentException The date notification
074: * is before the current date.
075: */
076: public Integer addNotification(String type, String message,
077: Object userData, Date date) throws IllegalArgumentException;
078:
079: /**
080: * This method creates a new timer notification with the specified
081: * <CODE>type</CODE>, <CODE>message</CODE> and <CODE>userData</CODE>
082: * and inserts it into the list of notifications with a given date
083: * and period and a null number of occurences.
084: * <P>
085: * The timer notification will repeat continuously using the timer period.
086: *
087: * @param type The timer notification type.
088: *
089: * @param message The timer notification detailed message.
090: *
091: * @param userData The timer notification user data object.
092: *
093: * @param date The date when the notification occurs.
094: *
095: * @param period The period of the timer notification (in milliseconds).
096: *
097: * @return An instance of java.lang.Integer which is the identifier of
098: * the new created timer notification.
099: *
100: * @exception java.lang.IllegalArgumentException - The period is negative
101: * or the date notification is before the current date.
102: */
103: public Integer addNotification(String type, String message,
104: Object userData, Date date, long period)
105: throws IllegalArgumentException;
106:
107: /**
108: * This method creates a new timer notification with the specified
109: * <CODE>type</CODE>, <CODE>message</CODE> and <CODE>userData</CODE>
110: * and inserts it into the list of notifications with a given date,
111: * period and number of occurences.
112: * <P>
113: * If the timer notification to be inserted has a date that is before
114: * the current date, the method attempts to update the notification
115: * using the defined period. If the defined period is null, the method
116: * generates an exception.
117: * <P>
118: * If the timer notification has a non null period, the date of the
119: * notification is updated by adding the period until the notification
120: * date is later than the current date. The timer notification is then
121: * inserted into the list of notifications.
122: * <P>
123: * If the specified number of occurences is non null, the previous
124: * mechanism is employed. The number of times that the period is added
125: * is limited by the specified number of occurences. If the notification
126: * date remains earlier than the current date, an exception is generated.
127: * <P>
128: * Note that once the timer notification has been added into the list
129: * of notifications, its associated date, period and number of occurences
130: * cannot be updated.
131: *
132: * @param type The timer notification type.
133: *
134: * @param message The timer notification detailed message.
135: *
136: * @param userData The timer notification user data object.
137: *
138: * @param date The date when the notification occurs.
139: *
140: * @param period The period of the timer notification (in milliseconds).
141: *
142: * @param nbOccurences The total number the timer notification will be emitted.
143: *
144: * @return An instance of java.lang.Integer which is the identifier of
145: * the new created timer notification.
146: *
147: * @exception java.lang.IllegalArgumentException - The period or the
148: * number of occurences is negative or the date notification
149: * is before the current date.
150: */
151: public Integer addNotification(String type, String message,
152: Object userData, Date date, long period, long nbOccurences)
153: throws IllegalArgumentException;
154:
155: /**
156: * This method gets all timer notification identifiers registered into
157: * the list of notifications.
158: *
159: * @return A vector of <CODE>Integer</CODE> objects containing all the
160: * timer notification identifiers. <BR>The vector is empty if
161: * there is no timer notification registered for this timer MBean.
162: */
163: public Vector getAllNotificationIDs();
164:
165: /**
166: * This method gets a copy of the date associated to a timer notification.
167: *
168: * @param id - The timer notification identifier.
169: *
170: * @return A copy of the date or null if the identifier is not mapped to
171: * any timer notification registered for this timer MBean.
172: */
173: public Date getDate(Integer id);
174:
175: /**
176: * This method gets the number of timer notifications registered into
177: * the list of notifications.
178: *
179: * @return The number of timer notifications.
180: */
181: public int getNbNotifications();
182:
183: /**
184: * This method gets a copy of the remaining number of occurences
185: * associated to a timer notification.
186: *
187: * @param id - The timer notification identifier.
188: *
189: * @return A copy of the remaining number of occurences or null if
190: * the identifier is not mapped to any timer notification
191: * registered for this timer MBean.
192: */
193: public Long getNbOccurences(Integer id);
194:
195: /**
196: * This method gets all the identifiers of timer notifications
197: * corresponding to the specified type.
198: *
199: * @param type - The timer notification type.
200: *
201: * @return A vector of <CODE>Integer</CODE> objects containing all the
202: * identifiers of timer notifications with the specified
203: * <CODE>type</CODE>. <BR>The vector is empty if there is no
204: * timer notifications registered for this timer MBean
205: * with the specified <CODE>type</CODE>.
206: */
207: public Vector getNotificationIDs(String type);
208:
209: /**
210: * This method gets the timer notification detailed message corresponding
211: * to the specified identifier.
212: *
213: * @param id - The timer notification identifier.
214: *
215: * @return The timer notification detailed message or null if the
216: * identifier is not mapped to any timer notification
217: * registered for this timer MBean.
218: */
219: public String getNotificationMessage(Integer id);
220:
221: /**
222: * This method gets the timer notification type corresponding to the
223: * specified identifier.
224: *
225: * @param id - The timer notification identifier.
226: *
227: * @return The timer notification type or null if the identifier is not
228: * mapped to any timer notification registered for this timer MBean.
229: */
230: public String getNotificationType(Integer id);
231:
232: /**
233: * This method gets the timer notification user data object corresponding
234: * to the specified identifier.
235: *
236: * @param id - The timer notification identifier.
237: *
238: * @return The timer notification user data object or null if the
239: * identifier is not mapped to any timer notification
240: * registered for this timer MBean.
241: */
242: public Object getNotificationUserData(Integer id);
243:
244: /**
245: * This method gets a copy of the period (in milliseconds) associated
246: * to a timer notification.
247: *
248: * @param id - The timer notification identifier.
249: *
250: * @return A copy of the period or null if the identifier is not mapped
251: * to any timer notification registered for this timer MBean.
252: */
253: public Long getPeriod(Integer id);
254:
255: /**
256: * This method gets the flag indicating whether or not the timer
257: * sends past notifications.
258: *
259: * @return The past notifications sending on/off flag value.
260: */
261: public boolean getSendPastNotifications();
262:
263: /**
264: * This method tests whether the timer MBean is active. A timer MBean is
265: * marked active when the start method is called. It becomes inactive
266: * when the stop method is called.
267: *
268: * @return true if the timer MBean is active, false otherwise.
269: */
270: public boolean isActive();
271:
272: /**
273: * This method tests whether the list of timer notifications is empty.
274: *
275: * @return true if the list of timer notifications is empty, false otherwise.
276: */
277: public boolean isEmpty();
278:
279: /**
280: * This method removes all the timer notifications from the list of
281: * notifications and resets the counter used to update the timer
282: * notification identifiers.
283: */
284: public void removeAllNotifications();
285:
286: /**
287: * This method Removes the timer notification corresponding to the
288: * specified identifier from the list of notifications.
289: *
290: * @param id - The timer notification identifier.
291: *
292: * @exception InstanceNotFoundException - The specified identifier does
293: * not correspond to any timer notification in the list
294: * of notifications of this timer MBean.
295: */
296: public void removeNotification(Integer id)
297: throws InstanceNotFoundException;
298:
299: /**
300: * Removes all the timer notifications corresponding to the specified type
301: * from the list of notifications.
302: *
303: * @param type - The timer notification type.
304: *
305: * @exception InstanceNotFoundException - The specified type does not
306: * correspond to any timer notification in the list of
307: * notifications of this timer MBean.
308: */
309: public void removeNotifications(String type)
310: throws InstanceNotFoundException;
311:
312: /**
313: * This method Sets the flag indicating whether the timer sends past
314: * notifications or not.
315: *
316: * @param value - The past notifications sending on/off flag value.
317: */
318: public void setSendPastNotifications(boolean value);
319: }
|