001: /**
002: * EasyBeans
003: * Copyright (C) 2006 Bull S.A.S.
004: * Contact: easybeans@objectweb.org
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation; either
009: * version 2.1 of the License, or any later version.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: *
016: * You should have received a copy of the GNU Lesser General Public
017: * License along with this library; if not, write to the Free Software
018: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
019: * USA
020: *
021: * --------------------------------------------------------------------------
022: * $Id: TimerService.java 1311 2007-02-13 17:33:45Z benoitf $
023: * --------------------------------------------------------------------------
024: */package javax.ejb;
025:
026: import java.io.Serializable;
027: import java.util.Collection;
028: import java.util.Date;
029:
030: /**
031: * The TimerService interface provides enterprise bean components with access to
032: * the container-provided Timer Service. The EJB Timer Service allows entity
033: * beans, stateless session beans, and message-driven beans to be registered for
034: * timer callback events at a specified time, after a specified elapsed time, or
035: * after a specified interval.
036: * @see <a href="http://www.jcp.org/en/jsr/detail?id=220">EJB 3.0 specification</a>
037: * @author Florent Benoit
038: */
039: public interface TimerService {
040:
041: /**
042: * Create a single-action timer that expires after a specified duration.
043: * @param duration The number of milliseconds that must elapse before the
044: * timer expires.
045: * @param info Application information to be delivered along with the timer
046: * expiration notification. This can be null.
047: * @return The newly created Timer.
048: * @throws IllegalArgumentException If duration is negative
049: * @throws IllegalStateException If this method is invoked while the
050: * instance is in a state that does not allow access to this method.
051: * @throws EJBException If this method fails due to a system-level failure.
052: */
053: Timer createTimer(final long duration, final Serializable info)
054: throws IllegalArgumentException, IllegalStateException,
055: EJBException;
056:
057: /**
058: * Create an interval timer whose first expiration occurs after a specified
059: * duration, and whose subsequent expirations occur after a specified
060: * interval.
061: * @param initialDuration The number of milliseconds that must elapse before
062: * the first timer expiration notification.
063: * @param intervalDuration The number of milliseconds that must elapse
064: * between timer expiration notifications. Expiration notifications
065: * are scheduled relative to the time of the first expiration. If
066: * expiration is delayed(e.g. due to the interleaving of other method
067: * calls on the bean) two or more expiration notifications may occur
068: * in close succession to "catch up".
069: * @param info Application information to be delivered along with the timer
070: * expiration. This can be null.
071: * @return The newly created Timer.
072: * @throws IllegalArgumentException If initialDuration is negative, or
073: * intervalDuration is negative.
074: * @throws IllegalStateException If this method is invoked while the
075: * instance is in a state that does not allow access to this method.
076: * @throws EJBException If this method could not complete due to a
077: * system-level failure.
078: */
079: Timer createTimer(final long initialDuration,
080: final long intervalDuration, final Serializable info)
081: throws IllegalArgumentException, IllegalStateException,
082: EJBException;
083:
084: /**
085: * Create a single-action timer that expires at a given point in time.
086: * @param expiration The point in time at which the timer must expire.
087: * @param info Application information to be delivered along with the timer
088: * expiration notification. This can be null.
089: * @return The newly created Timer.
090: * @throws IllegalArgumentException If expiration is null, or
091: * expiration.getTime() is negative.
092: * @throws IllegalStateException If this method is invoked while the
093: * instance is in a state that does not allow access to this method.
094: * @throws EJBException If this method could not complete due to a
095: * system-level failure.
096: */
097: Timer createTimer(final Date expiration, final Serializable info)
098: throws IllegalArgumentException, IllegalStateException,
099: EJBException;
100:
101: /**
102: * Create an interval timer whose first expiration occurs at a given point
103: * in time and whose subsequent expirations occur after a specified
104: * interval.
105: * @param initialExpiration The point in time at which the first timer
106: * expiration must occur.
107: * @param intervalDuration The number of milliseconds that must elapse
108: * between timer expiration notifications. Expiration notifications
109: * are scheduled relative to the time of the first expiration. If
110: * expiration is delayed(e.g. due to the interleaving of other method
111: * calls on the bean) two or more expiration notifications may occur
112: * in close succession to "catch up".
113: * @param info Application information to be delivered along with the timer
114: * expiration. This can be null.
115: * @return The newly created Timer.
116: * @throws IllegalArgumentException If initialExpiration is null, or
117: * initialExpiration.getTime() is negative, or intervalDuration is
118: * negative.
119: * @throws IllegalStateException If this method is invoked while the
120: * instance is in a state that does not allow access to this method.
121: * @throws EJBException If this method could not complete due to a
122: * system-level failure.
123: */
124: Timer createTimer(Date initialExpiration, long intervalDuration,
125: Serializable info) throws IllegalArgumentException,
126: IllegalStateException, EJBException;
127:
128: /**
129: * Get all the active timers associated with this bean.
130: * @return A collection of javax.ejb.Timer objects.
131: * @throws IllegalStateException If this method is invoked while the
132: * instance is in a state that does not allow access to this method.
133: * @throws EJBException If this method could not complete due to a
134: * system-level failure.
135: */
136: Collection getTimers() throws IllegalStateException, EJBException;
137:
138: }
|