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.ejb;
023:
024: import java.io.Serializable;
025: import java.util.Collection;
026: import java.util.Date;
027:
028: /**
029: * The TimerService interface provides enterprise bean components with access to the
030: * container-provided Timer Service. The EJB Timer Service allows entity beans, stateless
031: * session beans, and message-driven beans to be registered for timer callback events at
032: * a specified time, after a specified elapsed time, or after a specified interval.
033: **/
034: public interface TimerService {
035:
036: /**
037: * Create a single-action timer that expires after a specified duration.
038: *
039: * @param duration The number of milliseconds that must elapse before the timer expires.
040: * @param info Application information to be delivered along with the timer expiration
041: * notification. This can be null.
042: *
043: * @return The newly created Timer.
044: *
045: * @throws IllegalArgumentException If duration is negative
046: * @throws IllegalStateException If this method is invoked while the instance is in
047: * a state that does not allow access to this method.
048: * @throws EJBException If this method could not complete due to a system-level failure.
049: **/
050: public Timer createTimer(long duration, Serializable info)
051: throws IllegalArgumentException, IllegalStateException,
052: EJBException;
053:
054: /**
055: * Create an interval timer whose first expiration occurs after a specified duration,
056: * and whose subsequent expirations occur after a specified interval.
057: *
058: * @param initialDuration The number of milliseconds that must elapse before the first
059: * timer expiration notification.
060: * @param intervalDuration The number of milliseconds that must elapse between timer
061: * expiration notifications. Expiration notifications are
062: * scheduled relative to the time of the first expiration. If
063: * expiration is delayed(e.g. due to the interleaving of other
064: * method calls on the bean) two or more expiration notifications
065: * may occur in close succession to "catch up".
066: * @param info Application information to be delivered along with the timer expiration
067: * notification. This can be null.
068: *
069: * @return The newly created Timer.
070: *
071: * @throws IllegalArgumentException If initialDuration is negative, or intervalDuration
072: * is negative.
073: * @throws IllegalStateException If this method is invoked while the instance is in
074: * a state that does not allow access to this method.
075: * @throws EJBException If this method could not complete due to a system-level failure.
076: **/
077: public Timer createTimer(long initialDuration,
078: long intervalDuration, Serializable info)
079: throws IllegalArgumentException, IllegalStateException,
080: EJBException;
081:
082: /**
083: * Create a single-action timer that expires at a given point in time.
084: *
085: * @param expiration The point in time at which the timer must expire.
086: * @param info Application information to be delivered along with the timer expiration
087: * notification. This can be null.
088: *
089: * @return The newly created Timer.
090: *
091: * @throws IllegalArgumentException If expiration is null, or expiration.getTime() is negative.
092: * @throws IllegalStateException If this method is invoked while the instance is in
093: * a state that does not allow access to this method.
094: * @throws EJBException If this method could not complete due to a system-level failure.
095: **/
096: public Timer createTimer(Date expiration, Serializable info)
097: throws IllegalArgumentException, IllegalStateException,
098: EJBException;
099:
100: /**
101: * Create an interval timer whose first expiration occurs at a given point in time and
102: * whose subsequent expirations occur after a specified interval.
103: *
104: * @param initialExpiration The point in time at which the first timer expiration must occur.
105: * @param intervalDuration The number of milliseconds that must elapse between timer
106: * expiration notifications. Expiration notifications are
107: * scheduled relative to the time of the first expiration. If
108: * expiration is delayed(e.g. due to the interleaving of other
109: * method calls on the bean) two or more expiration notifications
110: * may occur in close succession to "catch up".
111: * @param info Application information to be delivered along with the timer expiration
112: * notification. This can be null.
113: *
114: * @return The newly created Timer.
115: *
116: * @throws IllegalArgumentException If initialExpiration is null, or initialExpiration.getTime()
117: * is negative, or intervalDuration is negative.
118: * @throws IllegalStateException If this method is invoked while the instance is in
119: * a state that does not allow access to this method.
120: * @throws EJBException If this method could not complete due to a system-level failure.
121: **/
122: public Timer createTimer(Date initialExpiration,
123: long intervalDuration, Serializable info)
124: throws IllegalArgumentException, IllegalStateException,
125: EJBException;
126:
127: /**
128: * Get all the active timers associated with this bean.
129: *
130: * @return A collection of javax.ejb.Timer objects.
131: * @throws IllegalStateException If this method is invoked while the instance is in
132: * a state that does not allow access to this method.
133: * @throws EJBException If this method could not complete due to a system-level failure.
134: **/
135: public Collection getTimers() throws IllegalStateException,
136: EJBException;
137: }
|