You are looking at documentation for an older release. Not what you want? See the current release documentation.
Listeners must be subclasses of org.exoplatform.services.listener.Listener.
To register a listener, you need to call the addListener() method.
/**
* This method is used to register a {@link Listener} to the events of the same
* name. It is similar to addListener(listener.getName(), listener)
*
* @param listener the listener to notify any time an even of the same name is
* triggered
*/
public void addListener(Listener listener)
/**
* This method is used to register a new {@link Listener}. Any time an
* event of the given event name has been triggered, the {@link Listener} will be
* notified.
* This method will:
* <ol>
* <li>Check if it exists a list of listeners that have been registered for the
* given event name, create a new list if no list exists</li>
* <li>Add the listener to the list</li>
* </ol>
* @param eventName The name of the event to listen to
* @param listener The Listener to notify any time the event with the given
* name is triggered
*/
public void addListener(String eventName, Listener listener)
By convention, we use the listener name as the name of the event to listen to.
To trigger an event, an application can call one of the broadcast() methods of ListenerService.
/**
* This method is used to broadcast an event. This method should: 1. Check if
* there is a list of listener that listen to the event name. 2. If there is a
* list of listener, create the event object with the given name , source and
* data 3. For each listener in the listener list, invoke the method
* onEvent(Event)
*
* @param <S> The type of the source that broadcast the event
* @param <D> The type of the data that the source object is working on
* @param name The name of the event
* @param source The source object instance
* @param data The data object instance
* @throws Exception
*/
public <S, D> void broadcast(String name, S source, D data) throws Exception {
...
}
/**
* This method is used when a developer want to implement his own event object
* and broadcast the event. The method should: 1. Check if there is a list of
* listener that listen to the event name. 2. If there is a list of the
* listener, For each listener in the listener list, invoke the method
* onEvent(Event)
*
* @param <T> The type of the event object, the type of the event object has
* to be extended from the Event type
* @param event The event instance
* @throws Exception
*/
public <T extends Event> void broadcast(T event) throws Exception {
...
}
The boadcast() methods retrieve the name of the event and find the registered listeners with the same name and call the method onEvent() on each listener found.
Each listener is a class that extends org.exoplatform.services.listener.Listener, and this superclass itself extends org.exoplatform.container.component.BaseComponentPlugin, as you can see below:
public abstract class Listener<S, D> extends BaseComponentPlugin {
/**
* This method should be invoked when an event with the same name is
* broadcasted
*/
public abstract void onEvent(Event<S, D> event) throws Exception;
}
As you can see we use generics to limit the source of the event to the type 'S' and the data of the event to the type 'D', so we expect that listeners implement the method onEvent() with the corresponding types
Each listener is also a ComponentPlugin with a name and a description, in other words, the name of the listener will be the name given in the configuration file, for more details see the next section.
public interface ComponentPlugin {
public String getName();
public void setName(String name);
public String getDescription();
public void setDescription(String description);
}
Some events may take a lot of time and you do not need to
process them immediately, in that case, you can
make your listener asynchronous. To do so, just mark
your Listener implementation with the annotation
@Asynchronous.
@Asynchronous
public class AsynchListenerWithException<S,D> extends Listener<S,D>
{
@Override
public void onEvent(Event<S,D> event) throws Exception
{
// some expensive operation
}
}
Now, our AsynchListener will be executed in separate thread thanks
to an ExecutorService.
By default, the pool size of the
ExecutorService is 1, you can change it by
configuration as next:
<component>
<key>org.exoplatform.services.listener.ListenerService</key>
<type>org.exoplatform.services.listener.ListenerService</type>
<init-params>
<value-param>
<name>asynchPoolSize</name>
<value>5</value>
</value-param>
</init-params>
</component>