EventBroker


1   /*
2    * Copyright (C) 2003  Christian Cryder [christianc@granitepeaks.com]
3    *
4    * This library is free software; you can redistribute it and/or
5    * modify it under the terms of the GNU Lesser General Public
6    * License as published by the Free Software Foundation; either
7    * version 2.1 of the License, or (at your option) any later version.
8    *
9    * This library is distributed in the hope that it will be useful,
10   * but WITHOUT ANY WARRANTY; without even the implied warranty of
11   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12   * Lesser General Public License for more details.
13   *
14   * You should have received a copy of the GNU Lesser General Public
15   * License along with this library; if not, write to the Free Software
16   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
17   *
18   * $Id: EventBroker.java,v 1.7 2004/02/01 05:16:28 christianc Exp $
19   */
20  package org.enhydra.barracuda.core.event;
21  
22  import java.io.*;
23  import java.util.*;
24  
25  /**
26   * This interface defines the methods needed to implement an EventBroker
27   */
28  public interface EventBroker {
29  
30      /**
31       * Return the event extension handled by this event broker
32       *
33       * @return the event extension associated with this broker
34       */
35      public String   getEventExtension();
36  
37      /**
38       * register a listener id, so that events addressed to a 
39       * specific listener can be delivered
40       *
41       * @param factory the listener factory to be added
42       */    
43      public void addEventListener(ListenerFactory factory);
44  
45      /**
46       * add an event listener for a particular class of an event.
47       * If the class referenced is not an instance of BaseEvent,
48       * a ClassNotEventException will be thrown. Note that this 
49       * method also registers the listener in the idMap as well.
50       *
51       * @param factory the listener factory to be added
52       * @param event the specific class of event for which the factory is listening
53       * @throws InvalidClassException if the event class does not implement BaseEvent
54       */    
55      public void addEventListener(ListenerFactory factory, Class   event) throws InvalidClassException;
56  
57      /**
58       * remove a listener from general availability
59       *
60       * @param factory the listener factory to be removed
61       */
62      public void removeEventListener(ListenerFactory factory);
63  
64      /**
65       * remove an event listener for specific types of events
66       * If the class referenced is not an instance of BaseEvent,
67       * a InvalidClassException will be thrown. Note that this 
68       * method effectively deregisters the listener from the 
69       * idMap as well.
70       *
71       * @param factory the listener factory to be removed
72       * @param event the specific class of event for which the factory is listening
73       * @throws InvalidClassException if the event class does not implement BaseEvent
74       */
75      public void removeEventListener(ListenerFactory factory, Class   event) throws InvalidClassException;
76  
77      /**
78       * remove all references to an event listener, both for id and
79       * for any event classes it has registered an interest in.
80       *
81       * @param factory the listener factory to be removed
82       */
83      public void purgeEventListener(ListenerFactory factory);
84  
85      /**
86       * Manually register aliases for a given event (the aliases
87       * will be determined automatically based on the class name
88       * and the event ID)
89       *
90       * @param event the specific class of event we'd like to alias
91       * @throws InvalidClassException if the event class does not implement BaseEvent
92       */
93      public void addEventAlias(Class   event) throws InvalidClassException;
94   
95      /**
96       * Manually add an alias for a given event. Note that
97       * the alias parameter will be converted into all possible 
98       * aliases based on '.' delimiters.
99       *
100      * @param event the specific class of event we'd like to alias
101      * @param alias the alias for this event
102      * @throws InvalidClassException if the event class does not implement BaseEvent
103      */
104     public void addEventAlias(Class   event, String   alias) throws InvalidClassException;
105 
106     /**
107      * Get a specific listener based on listener ID
108      *
109      * @param id the listener id we're looking for
110      * @return the ListenerFactory that matches that id
111      */
112     public ListenerFactory getEventListener(Object   id);
113 
114     /**
115      * Get a List of listeners for a type of event. Returns a copy 
116      * of the broker's internal list, so you can do what you want 
117      * with it. If the class referenced is not an instance of BaseEvent,
118      * a InvalidClassException will be thrown. 
119      *
120      * @param event the event class we are looking for
121      * @return a List of listeners that are interested in this class of event
122      * @throws InvalidClassException if the event class does not implement BaseEvent
123      */
124     public List getEventListeners(Class   event) throws InvalidClassException;
125 
126     /**
127      * Given a partial event class name, return the fully qualified class
128      * name if it's possible to determine. If it is unknown, throw and
129      * InvalidClassException. This method is primarily used by the 
130      * ApplicationGateway to support event aliasing.
131      *
132      * @param eventStr the event name alias
133      * @return the fully qualified event class name
134      * @throws InvalidClassException if the eventStr cannot be unambiguously 
135      *      matched to a class name
136      */
137     public String   matchEventClass(String   eventStr) throws InvalidClassException;
138 
139     /**
140      * Given a partial id name, return the fully qualified listener
141      * ID if it's possible to determine. If it is unknown, throw and
142      * InvalidClassException. This method is primarily used by the 
143      * ApplicationGateway to support id aliasing.
144      *
145      * @param idStr the id name alias
146      * @return the fully qualified listener id name
147      * @throws InvalidClassException if the idStr cannot be unambiguously 
148      *      matched to a listener id name
149      */
150     public String   matchListenerID(String   idStr) throws InvalidClassException;
151 
152 
153     /**
154      * <p>Dispatch a queue of events. Generally, the queue will only
155      * contain one event, however, if you ever need to dispatch
156      * multiple events at once, the broker can handle it. All the real 
157      * dispatching work is carried out by the underlying event
158      * dispatcher.
159      *
160      * <p>The event queue you pass in should contain several pieces of 
161      * state information:
162      *
163      * <ul>
164      *    <li>DefaultEventDispatcher.DEFAULT_RESPONSE_EVENT (BaseEvent)</li>
165      *    <li>DefaultBaseEventListener.HTTP_SERVLET_REQUEST (HttpServletRequest) - if dispatching from a servlet</li>
166      *    <li>DefaultBaseEventListener.HTTP_SERVLET_RESPONSE (HttpServletResponse) - if dispatching from a servlet</li>
167      * </ul>
168      *
169      * @param context the event context containing event, queue, and, sometimes, http information
170      * @throws EventException
171      */
172     public void dispatchEvent(EventContext context) throws EventException;
173 
174     /** @link dependency */
175     /*#EventDispatcher lnkEventDispatcher;*/
176 }
177
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags