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