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,2003 (C) Exoffice Technologies Inc. All Rights Reserved.
42 *
43 * $Id: EventManager.java,v 1.3 2003/08/17 01:32:22 tanderson Exp $
44 *
45 * Date Author Changes
46 * 07/27/00 jima Created
47 */
48 package org.exolab.jms.events;
49
50 import org.exolab.core.service.Serviceable;
51
52
53 /***
54 * The EventManager manages {@link Event} objects. It has methods to
55 * register and unregister events. It also extends {@link Runnable} interface
56 * which defines the thread responsible for dispatching events.
57 * <p>
58 * An event is defined to occur at sometime in the future, as specified either
59 * by an absolute time through {@link #registerEvent} or as relative time
60 * through {@link #registerEventRelative}. An event must have an associated
61 * event type and may have an attached <code>Serializable</code> object,
62 * which is used when the EventManager makes a callback to the registered
63 * handler when the event fires.
64 * <p>
65 * The register methids will return an event identifier which can subsequently
66 * be used to unregister the event through the {@link #unregisterEvent} event.
67 * This is the only means of unregister an event.
68 * <p>
69 * If the {@link Event} object is incorrectly specified then the
70 * {@link IllegalEventDefinedException} exception is raised.
71 * <p>
72 * When an event fires the EventManager is responsible for ensuring
73 * that the event handler is notified. If the event handler has since been
74 * removed then the EventManager must gracefully abort the delivery and
75 * continue processing the next event.
76 * <p>
77 * Objects of type {@link Event} need to survive subsequent
78 * EventManager restarts, as such they must be persisted, which
79 * implies that the {@link EventHandler} needs to also be persisted. The
80 * ability to store the {@link EventHandler} as a <code>HandleIfc</code> object
81 * which can later be resolved to an object will be required.
82 * <p>
83 * This class is also <code>Serviceable</code>, which implies that it can be
84 * added and controlled by a <code>ServiceManager</code>.
85 *
86 * @version $Revision: 1.3 $ $Date: 2003/08/17 01:32:22 $
87 * @author <a href="mailto:jima@intalio.com">Jim Alateras</a>
88 */
89 public interface EventManager
90 extends Serviceable {
91
92 /***
93 * Register an event to be fired once and only once at the specified
94 * abolsute time. The event object must be Serializable so that it can
95 * be persisted and restored across EventManager restarts.
96 * <p>
97 * If the specified event is ill-defined then the IllegalEventDefined-
98 * Exception exception is thrown.
99 * <p>
100 * Similarly, if the abolsute time has already passed then the exception
101 * IllegalEventDefinedException is raised.
102 * <p>
103 * The method returns an unique event identifier, which can subsequently
104 * be used to deregister the event.
105 *
106 * @param event information about the event
107 * @param abolsute the abolsute time, in ms, that the event
108 * must fire
109 * @return String unique event identifier
110 * @throws IllegalEventDefinedException
111 */
112 String registerEvent(Event event, long absolute)
113 throws IllegalEventDefinedException;
114
115 /***
116 * Register an event to be fired once and only once at a time relative to
117 * now. The event object must be Serializable so that it can be persisted
118 * and restored across EventManager restarts.
119 * <p>
120 * If the specified event is ill-defined then the IllegalEventDefined-
121 * Exception exception is thrown.
122 * <p>
123 * The method returns an unique event identifier, which can subsequently
124 * be used to deregister the event.
125 *
126 * @param event information about the event
127 * @param relative the relative time in ms
128 * (currently no reference to locale).
129 * @return String unique event identifier,
130 * @throws IllegalEventDefinedException
131 */
132 String registerEventRelative(Event event, long relative)
133 throws IllegalEventDefinedException;
134
135 /***
136 * Unregister the event specified by the event identifier. If the event
137 * does not exist then fail silently.
138 *
139 * @param String unique event identifier.
140 */
141 void unregisterEvent(String id);
142 }