001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.management.timer;
023:
024: import java.util.Date;
025: import java.util.Vector;
026:
027: import javax.management.InstanceNotFoundException;
028:
029: /**
030: * The timer service MBean interface. <p>
031: *
032: * @author <a href="mailto:Adrian.Brock@HappeningTimes.com">Adrian Brock</a>
033: * @version $Revision: 57200 $
034: */
035:
036: public interface TimerMBean {
037: // Constants -----------------------------------------------------
038:
039: // Static --------------------------------------------------------
040:
041: // Public --------------------------------------------------------
042:
043: /**
044: * Starts the timer. If there are any notifications before the current time
045: * these notifications are processed. The notification only takes place
046: * when send past notiications is true.
047: */
048: public void start();
049:
050: /**
051: * Stops the timer.
052: */
053: public void stop();
054:
055: /**
056: * Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date, period and number of occurences.
057: * <p/>
058: * If the timer notification to be inserted has a date that is before the current date, the method behaves as if the specified date were the current date.
059: * For once-off notifications, the notification is delivered immediately.
060: * For periodic notifications, the first notification is delivered immediately and the subsequent ones are spaced as specified by the period parameter.
061: * <p/>
062: * Note that once the timer notification has been added into the list of notifications, its associated date, period and number of occurences cannot be updated.
063: * <p/>
064: * In the case of a periodic notification, the value of parameter fixedRate is used to specify the execution scheme, as specified in Timer.
065: *
066: * @param type The timer notification type.
067: * @param message The timer notification detailed message.
068: * @param userData The timer notification user data object.
069: * @param date The date when the notification occurs.
070: * @param period The period of the timer notification (in milliseconds).
071: * @param nbOccurences The total number the timer notification will be emitted.
072: * @param fixedRate If true and if the notification is periodic, the notification is scheduled with a fixed-rate execution scheme. If false and if the notification is periodic, the notification is scheduled with a fixed-delay execution scheme. Ignored if the notification is not periodic.
073: * @return The identifier of the new created timer notification.
074: * @throws IllegalArgumentException The period or the number of occurences is negative
075: */
076: public Integer addNotification(String type, String message,
077: Object userData, Date date, long period, long nbOccurences,
078: boolean fixedRate) throws IllegalArgumentException;
079:
080: /**
081: * Creates a new timer notification for a specific date/time, with an
082: * optional repeat period and a maximum number of occurences.<p>
083: * <p/>
084: * If the date and time is before the the current date and time the period
085: * is repeatedly added until a date after the current date and time is
086: * found. If the number of occurences is exceeded before the
087: * current date and time is reached, an IllegalArgumentException is raised.
088: *
089: * @param type the notification type.
090: * @param message the notification's message string.
091: * @param userData the notification's user data.
092: * @param date the date/time the notification will occur.
093: * @param period the repeat period in milli-seconds. Passing zero means
094: * no repeat.
095: * @param occurences the maximum number of repeats. When the period is not
096: * zero and this parameter is zero, it will repeat indefinitely.
097: * @return the notification id for this notification.
098: * @throws IllegalArgumentException when the date is before the current
099: * date, the period is negative or the number of repeats is
100: * negative.
101: */
102: public Integer addNotification(String type, String message,
103: Object userData, Date date, long period, long occurences)
104: throws IllegalArgumentException;
105:
106: /**
107: * Creates a new timer notification for a specific date/time, with an
108: * optional repeat period.
109: * When the repeat period is not zero, the notification repeats forever.<p>
110: * <p/>
111: * If the date and time is before the the current date and time the period
112: * is repeatedly added until a date after the current date and time is
113: * found.
114: *
115: * @param type the notification type.
116: * @param message the notification's message string.
117: * @param userData the notification's user data.
118: * @param date the date/time the notification will occur.
119: * @param period the repeat period in milli-seconds. Passing zero means
120: * no repeat.
121: * @return the notification id for this notification.
122: * @throws IllegalArgumentException when the date is before the current
123: * date or the period is negative.
124: */
125: public Integer addNotification(String type, String message,
126: Object userData, Date date, long period)
127: throws IllegalArgumentException;
128:
129: /**
130: * Creates a new timer notification for a specific date/time.
131: * The notification is performed once.
132: *
133: * @param type the notification type.
134: * @param message the notification's message string.
135: * @param userData the notification's user data.
136: * @param date the date/time the notification will occur.
137: * @return the notification id for this notification.
138: * @throws IllegalArgumentException when the date is before the current
139: * date.
140: */
141: public Integer addNotification(String type, String message,
142: Object userData, Date date) throws IllegalArgumentException;
143:
144: /**
145: * Removes a notification from the timer MBean with the specified
146: * notification id.
147: *
148: * @param id the notification id.
149: * @throws InstanceNotFoundException when there are no notification
150: * registered with the id passed.
151: */
152: public void removeNotification(Integer id)
153: throws InstanceNotFoundException;
154:
155: /**
156: * Removes all notifications from the timer MBean of the specified
157: * notification type.
158: *
159: * @param type the notification type.
160: * @throws InstanceNotFoundException when there are no notifications of
161: * the type passed.
162: */
163: public void removeNotifications(String type)
164: throws InstanceNotFoundException;
165:
166: /**
167: * Removes all notifications from the timer MBean.
168: */
169: public void removeAllNotifications();
170:
171: /**
172: * Retrieves the number of registered timer notifications.
173: *
174: * @return the number of notifications.
175: */
176: public int getNbNotifications();
177:
178: /**
179: * Retrieves all timer notifications ids.
180: *
181: * @return a vector of Integers containing the ids. The list is empty
182: * when there are no timer notifications.
183: */
184: public Vector getAllNotificationIDs();
185:
186: /**
187: * Retrieves all timer notifications ids of the passed notification type.
188: *
189: * @param type the notification type.
190: * @return a vector of Integers containing the ids. The list is empty
191: * when there are no timer notifications of the passed type.
192: */
193: public Vector getNotificationIDs(String type);
194:
195: /**
196: * Retrieves the notification type for a passed notification id.
197: *
198: * @param id the notification id.
199: * @return the notification type or null when the notification id is
200: * not registered.
201: */
202: public String getNotificationType(Integer id);
203:
204: /**
205: * Retrieves the notification message for a passed notification id.
206: *
207: * @param id the notification id.
208: * @return the notification message or null when the notification id is
209: * not registered.
210: */
211: public String getNotificationMessage(Integer id);
212:
213: /**
214: * Retrieves the notification user data for a passed notification id.
215: *
216: * @param id the notification id.
217: * @return the notification user data or null when the notification id is
218: * not registered.
219: */
220: public Object getNotificationUserData(Integer id);
221:
222: /**
223: * Retrieves a copy of the notification date for a passed notification id.
224: *
225: * @param id the notification id.
226: * @return a copy of the notification date or null when the notification id
227: * is not registered.
228: */
229: public Date getDate(Integer id);
230:
231: /**
232: * Retrieves a copy of the notification period for a passed notification id.
233: *
234: * @param id the notification id.
235: * @return a copy of the notification period or null when the notification
236: * id is not registered.
237: */
238: public Long getPeriod(Integer id);
239:
240: /**
241: * Retrieves a copy of the maximum notification occurences for a passed
242: * notification id.
243: *
244: * @param id the notification id.
245: * @return a copy of the maximum notification occurences or null when the
246: * notification id is not registered.
247: */
248: public Long getNbOccurences(Integer id);
249:
250: /**
251: * Gets a copy of the flag indicating whether a peridic notification is executed at fixed-delay or at fixed-rate.
252: *
253: * @param id The timer notification identifier.
254: * @return A copy of the flag indicating whether a peridic notification is executed at fixed-delay or at fixed-rate.
255: */
256: public Boolean getFixedRate(Integer id);
257:
258: /**
259: * Retrieves the flag indicating whether past notifications are sent.
260: *
261: * @return true when past notifications are sent, false otherwise.
262: */
263: public boolean getSendPastNotifications();
264:
265: /**
266: * Sets the flag indicating whether past notifications are sent.
267: *
268: * @param value the new value of the flag. true when past notifications
269: * are sent, false otherwise.
270: */
271: public void setSendPastNotifications(boolean value);
272:
273: /**
274: * Test whether the timer MBean is active.
275: *
276: * @return true when timer is active, false otherwise.
277: */
278: public boolean isActive();
279:
280: /**
281: * Test whether the timer MBean has any registered notifications.
282: *
283: * @return true when timer has no registered notifications, false otherwise.
284: */
285: public boolean isEmpty();
286:
287: }
|