001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036: package javax.ejb;
037:
038: import java.io.Serializable;
039: import java.util.Date;
040: import java.util.Collection;
041:
042: /**
043: * The TimerService interface provides enterprise bean components
044: * with access to the container-provided Timer Service. The EJB
045: * Timer Service allows entity beans, stateless session beans,
046: * and message-driven beans to be registered for timer callback
047: * events at a specified time, after a specified elapsed time, or
048: * after a specified interval.
049: *
050: */
051: public interface TimerService {
052:
053: /**
054: * Create a single-action timer that expires after a specified duration.
055: *
056: * @param duration The number of milliseconds that must elapse before
057: * the timer expires.
058: *
059: * @param info Application information to be delivered along
060: * with the timer expiration notification. This can be null.
061: *
062: * @return The newly created Timer.
063: *
064: * @exception java.lang.IllegalArgumentException If duration is negative
065: *
066: * @exception java.lang.IllegalStateException If this method is
067: * invoked while the instance is in a state that does not allow access
068: * to this method.
069: *
070: * @exception javax.ejb.EJBException If this method fails due to a
071: * system-level failure.
072: *
073: */
074: public Timer createTimer(long duration, Serializable info)
075: throws java.lang.IllegalArgumentException,
076: java.lang.IllegalStateException, javax.ejb.EJBException;
077:
078: /**
079: * Create an interval timer whose first expiration occurs after a specified
080: * duration, and whose subsequent expirations occur after a specified
081: * interval.
082: *
083: * @param initialDuration The number of milliseconds that must elapse
084: * before the first timer expiration notification.
085: *
086: * @param intervalDuration The number of milliseconds that must elapse
087: * between timer expiration notifications. Expiration notifications are
088: * scheduled relative to the time of the first expiration. If expiration
089: * is delayed(e.g. due to the interleaving of other method calls on the
090: * bean) two or more expiration notifications may occur in close
091: * succession to "catch up".
092: *
093: * @param info Application information to be delivered along
094: * with the timer expiration. This can be null.
095: *
096: * @return The newly created Timer.
097: *
098: * @exception java.lang.IllegalArgumentException If initialDuration is
099: * negative, or intervalDuration is negative.
100: *
101: * @exception java.lang.IllegalStateException If this method is
102: * invoked while the instance is in a state that does not allow access
103: * to this method.
104: *
105: * @exception javax.ejb.EJBException If this method could not complete
106: * due to a system-level failure.
107: *
108: */
109: public Timer createTimer(long initialDuration,
110: long intervalDuration, Serializable info)
111: throws java.lang.IllegalArgumentException,
112: java.lang.IllegalStateException, javax.ejb.EJBException;
113:
114: /**
115: * Create a single-action timer that expires at a given point in time.
116: *
117: * @param expiration The point in time at which the timer must expire.
118: *
119: * @param info Application information to be delivered along
120: * with the timer expiration notification. This can be null.
121: *
122: * @return The newly created Timer.
123: *
124: * @exception java.lang.IllegalArgumentException If expiration is null, or
125: * expiration.getTime() is negative.
126: *
127: * @exception java.lang.IllegalStateException If this method is
128: * invoked while the instance is in a state that does not allow access
129: * to this method.
130: *
131: * @exception javax.ejb.EJBException If this method could not complete
132: * due to a system-level failure.
133: *
134: */
135: public Timer createTimer(Date expiration, Serializable info)
136: throws java.lang.IllegalArgumentException,
137: java.lang.IllegalStateException, javax.ejb.EJBException;
138:
139: /**
140: * Create an interval timer whose first expiration occurs at a given
141: * point in time and whose subsequent expirations occur after a specified
142: * interval.
143: *
144: * @param initialExpiration The point in time at which the first timer
145: * expiration must occur.
146: *
147: * @param intervalDuration The number of milliseconds that must elapse
148: * between timer expiration notifications. Expiration notifications are
149: * scheduled relative to the time of the first expiration. If expiration
150: * is delayed(e.g. due to the interleaving of other method calls on the
151: * bean) two or more expiration notifications may occur in close
152: * succession to "catch up".
153: *
154: * @param info Application information to be delivered along
155: * with the timer expiration. This can be null.
156: *
157: * @return The newly created Timer.
158: *
159: * @exception java.lang.IllegalArgumentException If initialExpiration is
160: * null, or initialExpiration.getTime() is negative, or intervalDuration
161: * is negative.
162: *
163: * @exception java.lang.IllegalStateException If this method is
164: * invoked while the instance is in a state that does not allow access
165: * to this method.
166: *
167: * @exception javax.ejb.EJBException If this method could not complete
168: * due to a system-level failure.
169: *
170: */
171: public Timer createTimer(Date initialExpiration,
172: long intervalDuration, Serializable info)
173: throws java.lang.IllegalArgumentException,
174: java.lang.IllegalStateException, javax.ejb.EJBException;
175:
176: /**
177: * Get all the active timers associated with this bean.
178: *
179: * @return A collection of javax.ejb.Timer objects.
180: *
181: * @exception java.lang.IllegalStateException If this method is
182: * invoked while the instance is in a state that does not allow access
183: * to this method.
184: *
185: * @exception javax.ejb.EJBException If this method could not complete
186: * due to a system-level failure.
187: *
188: */
189: public Collection getTimers()
190: throws java.lang.IllegalStateException,
191: javax.ejb.EJBException;
192:
193: }
|