Vincent Massol wrote:
Here's my latest proposal:
/** * Components wanting to receive Observation {@link Event events} must implement this interface. * * @version $Id: EventListener.java 10164 2008-06-09 12:44:53Z sdumitriu $ */ public interface EventListener { /** * @return the listener's name. It's a free form text identifying this listener instance in a unique manner. * This name is used for some operations in {@link ObservationManager}. */ String getName();
/** * @return the list of events this listener is configured to receive. This listener will be automatically * registered with this list of events against the {@link ObservationManager}.
Thi is not clear enough, replace with: When an event occurs, for each matching event in this list,
For each matching event * the {@link #onEvent(Event, Object, Object)} method will be called. */ List<Event> getEvents();
/** * The {@link org.xwiki.observation.ObservationManager} calls this methods when an event matches
one of
the events for * which this listener is registered (see {@link #getEvents()}. * * @param event the event triggered. Can be used to differentiate different events if your Object supports several * events for example. * @param source the event source i.e. the object for which the event was triggered. For example this would be the * document Object if the event is a document update event. * @param data some additional and optional data passed that can be acted on. */ void onEvent(Event event, Object source, Object data); }
And:
/** * The main orchestrator for event notification. To receive events create a component implementing the * {@link EventListener} interface. Your component will be automatically registered when this Observation * Manager component is loaded. To send events to all registered listeners, call one of the * {@link #notify} methods. * * @version $Id: ObservationManager.java 20537 2009-05-26 20:41:25Z vmassol $ */ @ComponentRole public interface ObservationManager { /** * Manually add a listener. Components implementing the {@link EventListener} interfaces are only loaded * when the Observation Manager component is created. Thus if you need to add a new listener while the * system is running you'll need to call this method. *
Remove this @param
* @param event the event to register the listener against; acts as a template that filters out only specific events * the listener is interested in * @param eventListener the listener to register */ void addListener(EventListener eventListener);
/** * Remove a listener from the list of registered listeners. The removed listener will no longer receive events. * * @param listenerName the name of the listener to remove (must match {@link EventListener#getName()} */ void removeListener(String listenerName);
/** * Adds an Event to an already registered listener. * * @param listenerName the name of the listener to which the event must be added * (must match {@link EventListener#getName()} * @param event the event to add to the matching listener */ void addEvent(String listenerName, Event event);
/** * Removes an Event to an already registered listener. * * @param listenerName the name of the listener to which the event must be removed * (must match {@link EventListener#getName()} * @param event the event to remove to the matching listener */ void removeEvent(String listenerName, Event event);
/** * Remove a listener from a specific event. * * @param event the event to remove the listener from. * @param eventListener the listener to remove. */ void removeListener(Event event, EventListener eventListener);
/** * Call the registered listeners matching the passed Event. * The definition of <em>source</em> and <em>data</em> is purely up to the communicating classes. * * @param event the event to pass to the registered listeners * @param source the source of the event (or <code>null</code>) * @param data the additional data related to the event (or <code>null</code>) */ void notify(Event event, Object source, Object data);
/** * Convenience front-end where the additional data parameter is <code>null</code>. * * @param event the event to pass to the registered listeners * @param source the source of the event (or <code>null</code>) * @see #notify(org.xwiki.observation.event.Event, Object, Object) */ void notify(Event event, Object source); }
This allows adding events after the listener is registered thus allowing Sergiu's use case in the Localization module.
OK, looks good. -- Sergiu Dumitriu http://purl.org/net/sergiu/