KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > exolab > jms > events > EventManager


1 /**
2  * Redistribution and use of this software and associated documentation
3  * ("Software"), with or without modification, are permitted provided
4  * that the following conditions are met:
5  *
6  * 1. Redistributions of source code must retain copyright
7  * statements and notices. Redistributions must also contain a
8  * copy of this document.
9  *
10  * 2. Redistributions in binary form must reproduce the
11  * above copyright notice, this list of conditions and the
12  * following disclaimer in the documentation and/or other
13  * materials provided with the distribution.
14  *
15  * 3. The name "Exolab" must not be used to endorse or promote
16  * products derived from this Software without prior written
17  * permission of Exoffice Technologies. For written permission,
18  * please contact info@exolab.org.
19  *
20  * 4. Products derived from this Software may not be called "Exolab"
21  * nor may "Exolab" appear in their names without prior written
22  * permission of Exoffice Technologies. Exolab is a registered
23  * trademark of Exoffice Technologies.
24  *
25  * 5. Due credit should be given to the Exolab Project
26  * (http://www.exolab.org/).
27  *
28  * THIS SOFTWARE IS PROVIDED BY EXOFFICE TECHNOLOGIES AND CONTRIBUTORS
29  * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
30  * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
31  * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
32  * EXOFFICE TECHNOLOGIES OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
33  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
34  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
35  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
36  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
37  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
38  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
39  * OF THE POSSIBILITY OF SUCH DAMAGE.
40  *
41  * Copyright 2000-2004 (C) Exoffice Technologies Inc. All Rights Reserved.
42  *
43  * $Id: EventManager.java,v 1.1 2004/11/26 01:50:41 tanderson Exp $
44  */
45 package org.exolab.jms.events;
46
47 import org.exolab.jms.service.Serviceable;
48
49
50 /**
51  * The EventManager manages {@link Event} objects. It has methods to
52  * register and unregister events. It also extends {@link Runnable} interface
53  * which defines the thread responsible for dispatching events.
54  * <p>
55  * An event is defined to occur at sometime in the future, as specified either
56  * by an absolute time through {@link #registerEvent} or as relative time
57  * through {@link #registerEventRelative}. An event must have an associated
58  * event type and may have an attached <code>Serializable</code> object,
59  * which is used when the EventManager makes a callback to the registered
60  * handler when the event fires.
61  * <p>
62  * The register methids will return an event identifier which can subsequently
63  * be used to unregister the event through the {@link #unregisterEvent} event.
64  * This is the only means of unregister an event.
65  * <p>
66  * If the {@link Event} object is incorrectly specified then the
67  * {@link IllegalEventDefinedException} exception is raised.
68  * <p>
69  * When an event fires the EventManager is responsible for ensuring
70  * that the event handler is notified. If the event handler has since been
71  * removed then the EventManager must gracefully abort the delivery and
72  * continue processing the next event.
73  * <p>
74  * This class is also <code>Serviceable</code>, which implies that it can be
75  * added and controlled by a <code>ServiceManager</code>.
76  *
77  * @version $Revision: 1.1 $ $Date: 2004/11/26 01:50:41 $
78  * @author <a HREF="mailto:jima@intalio.com">Jim Alateras</a>
79  */
80 public interface EventManager
81     extends Serviceable {
82
83     /**
84      * Register an event to be fired once and only once at the specified
85      * abolsute time. The event object must be Serializable so that it can
86      * be persisted and restored across EventManager restarts.
87      * <p>
88      * If the specified event is ill-defined then the IllegalEventDefined-
89      * Exception exception is thrown.
90      * <p>
91      * Similarly, if the abolsute time has already passed then the exception
92      * IllegalEventDefinedException is raised.
93      * <p>
94      * The method returns an unique event identifier, which can subsequently
95      * be used to deregister the event.
96      *
97      * @param event information about the event
98      * @param abolsute the abolsute time, in ms, that the event
99      * must fire
100      * @return String unique event identifier
101      * @throws IllegalEventDefinedException
102      */
103     String JavaDoc registerEvent(Event event, long absolute)
104         throws IllegalEventDefinedException;
105
106     /**
107      * Register an event to be fired once and only once at a time relative to
108      * now. The event object must be Serializable so that it can be persisted
109      * and restored across EventManager restarts.
110      * <p>
111      * If the specified event is ill-defined then the IllegalEventDefined-
112      * Exception exception is thrown.
113      * <p>
114      * The method returns an unique event identifier, which can subsequently
115      * be used to deregister the event.
116      *
117      * @param event information about the event
118      * @param relative the relative time in ms
119      * (currently no reference to locale).
120      * @return String unique event identifier,
121      * @throws IllegalEventDefinedException
122      */
123     String JavaDoc registerEventRelative(Event event, long relative)
124         throws IllegalEventDefinedException;
125
126     /**
127      * Unregister the event specified by the event identifier. If the event
128      * does not exist then fail silently.
129      *
130      * @param String unique event identifier.
131      */
132     void unregisterEvent(String JavaDoc id);
133 }
134
Popular Tags