AbstractEventProvider (jeve 3.0.0 API)

java.lang.Object
- de.skuzzle.jeve.providers.AbstractEventProvider<S>

Type Parameters:

S - The type of the ListenerStore this provider uses.

All Implemented Interfaces:

EventProvider<S>

Direct Known Subclasses:

AsynchronousEventProvider, AWTEventProvider, ParallelEventProvider, SequentialEventProvider, UnrollingEventProvider
```
public abstract class AbstractEventProvider<S extends ListenerStore>
extends Object
implements EventProvider<S>
```
Implementation of basic EventProvider methods. All implementations are thread-safe.
Note about thread safe interface: All publicly accessible methods are thread safe, internal and protected helper methods are not thread safe.

Since:

1.0.0

Author:

Simon Taddiken

Field Summary

Fields
Modifier and Type	Field and Description
`protected ExceptionCallback`	`defaultHandler` The default `ExceptionCallback` which prints some information about the occurred error to logger.
`protected ExceptionCallback`	`exceptionHandler` Callback to handle event handler exceptions.

Constructor Summary

Constructors
Constructor and Description

AbstractEventProvider(S store)
Creates a new AbstractEventProvider.

Constructors
Constructor and Description
`AbstractEventProvider(S store)` Creates a new `AbstractEventProvider`.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected <L extends Listener,E extends Event<?,?>> void`	`checkDispatchArgs(E event, Object bc, ExceptionCallback ec)` Helper method which serves for throwing `IllegalArgumentException` if any of the passed arguments is null.
`void`	`close()` Closes this EventProvider and its `ListenerStore` (thus, removes all registered Listeners from the store).
`protected <L extends Listener,E extends Event<?,L>> EventInvocation`	`createInvocation(L listener, E event, BiConsumer<L,E> bc, ExceptionCallback ec)` Creates a new `EventInvocation` object for dispatching the given event to the given listener.
`void`	`dispatch(DefaultDispatchable event)` Dispatches the given event by calling its `DefaultDispatchable.defaultDispatch(EventProvider, ExceptionCallback)` method, passing `this` as first argument and the currently set ExceptionCallback as second argument.
`<L extends Listener,E extends Event<?,L>> void`	`dispatch(E event, BiConsumer<L,E> bc)` Notifies all listeners of a certain kind about an occurred event.
`<L extends Listener,E extends Event<?,L>> void`	`dispatch(E event, BiConsumer<L,E> bc, ExceptionCallback ec)` Notifies all listeners of a certain kind about an occurred event with explicit error handling.
`protected abstract boolean`	`isImplementationSequential()` Whether this EventProvider implementation is sequential.
`boolean`	`isSequential()` Returns whether this EventProvider is sequential, which means it strictly notifies listeners in the order in which they were registered for a certain event.
`S`	`listeners()` Retrieves the `ListenerStore` which supplies `Listeners` to this EventProvider.
`protected <L extends Listener,E extends Event<?,L>> void`	`notifyListeners(E event, BiConsumer<L,E> bc, ExceptionCallback ec)` Notifies all listeners registered for the provided class with the provided event.
`protected <L extends Listener,E extends Event<?,L>> void`	`notifySingle(L listener, E event, BiConsumer<L,E> bc, ExceptionCallback ec)` Notifies a single listener and internally handles exceptions using the `ExceptionCallback`.
`void`	`setExceptionCallback(ExceptionCallback callBack)` Sets the default `ExceptionCallback` which will be notified about exceptions when dispatching events without explicitly specifying an ExceptionCallback.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface de.skuzzle.jeve.EventProvider
canDispatch, configure, createDefault, dispatch, dispatch, dispatch

- Field Detail
  - exceptionHandler
```
protected ExceptionCallback exceptionHandler
```
    Callback to handle event handler exceptions.
  - defaultHandler
```
protected final ExceptionCallback defaultHandler
```
    The default ExceptionCallback which prints some information about the occurred error to logger. The exact format is not specified.
- Constructor Detail
  - AbstractEventProvider
```
public AbstractEventProvider(S store)
```
    Creates a new AbstractEventProvider.
    
    Parameters:
    
    store - Responsible for storing and retrieving listeners of this provider.
- Method Detail
  - listeners
```
public S listeners()
```
    Description copied from interface: EventProvider
    
    Retrieves the ListenerStore which supplies Listeners to this EventProvider.
    
    Specified by:
    
    listeners in interface EventProvider<S extends ListenerStore>
    
    Returns:
    
    The listener store.
  - dispatch
```
public <L extends Listener,E extends Event<?,L>> void dispatch(E event,
                                                               BiConsumer<L,E> bc)
```
    Description copied from interface: EventProvider
    Notifies all listeners of a certain kind about an occurred event. If this provider is not ready for dispatching as determined by EventProvider.canDispatch(), this method returns immediately without doing anything. This method will stop notifying further listeners if the passed event has been marked 'handled' using Event.setHandled(boolean).
    Consider an UserListener interface:
```
 public interface UserListener extends Listener {
     public void userAdded(UserEvent e);

     public void userDeleted(UserEvent e);
 }
 
```
    Notifying all registered UserListeners about an added user is as easy as calling
```
 eventProvider.dispatchEvent(event, UserListener::userAdded)
 
```
    This method uses the global ExceptionCallback provided to EventProvider.setExceptionCallback(ExceptionCallback) or an default instance if none has been explicitly set.
    
    Note on concurrency: This method operates on a copy of the list of targeted listeners. This allows you to add/remove listeners from within a listening method.
    
    Please note that neither parameter to this method must be null.
    Specified by:
    
    dispatch in interface EventProvider<S extends ListenerStore>
    
    Type Parameters:
    
    L - Type of the listeners which will be notified.
    
    E - Type of the event which will be passed to a listener.
    
    Parameters:
    
    event - The occurred event which shall be passed to each listener.
    
    bc - Function to delegate the event to the specific callback method of the listener.
  - dispatch
```
public <L extends Listener,E extends Event<?,L>> void dispatch(E event,
                                                               BiConsumer<L,E> bc,
                                                               ExceptionCallback ec)
```
    Description copied from interface: EventProvider
    Notifies all listeners of a certain kind about an occurred event with explicit error handling. If this provider is not ready for dispatching as determined by EventProvider.canDispatch(), this method returns immediately without doing anything. This method will stop notifying further listeners if the passed event has been marked 'handled' using Event.setHandled(boolean).
    Consider an UserListener interface:
```
 public interface UserListener extends Listener {
     public void userAdded(UserEvent e);

     public void userDeleted(UserEvent e);
 }
 
```
    Notifying all registered UserListeners about an added user is as easy as calling
```
 final ExceptionCallback callBack = new EceptionCallback() { ... };
 eventProvider.dispatchEvent(event, UserListener::userAdded, callBack);
 
```
    The ExceptionCallback gets notified when any of the listeners throws an unexpected exception. If the exception handler itself throws an exception, it will be ignored. The callback provided to this method takes precedence over the global callback provided by EventProvider.setExceptionCallback(ExceptionCallback).
    
    Note on concurrency: This method operates on a copy of the list of targeted listeners. This allows you to add/remove listeners from within a listening method.
    
    Please note that neither parameter to this method must be null.
    Specified by:
    
    dispatch in interface EventProvider<S extends ListenerStore>
    
    Type Parameters:
    
    L - Type of the listeners which will be notified.
    
    E - Type of the event which will be passed to a listener.
    
    Parameters:
    
    event - The occurred event which shall be passed to each listener.
    
    bc - Function to delegate the event to the specific callback method of the listener.
    
    ec - Callback to be notified when any of the listeners throws an exception.
  - dispatch
```
public void dispatch(DefaultDispatchable event)
```
    Description copied from interface: EventProvider
    
    Dispatches the given event by calling its DefaultDispatchable.defaultDispatch(EventProvider, ExceptionCallback) method, passing this as first argument and the currently set ExceptionCallback as second argument. The defaultDispatch method will in return call EventProvider.dispatch(Event, BiConsumer, ExceptionCallback) on this provider.
    
    Specified by:
    
    dispatch in interface EventProvider<S extends ListenerStore>
    
    Parameters:
    
    event - The event to dispatch using its default dispatch method.
    
    See Also:
    
    DefaultDispatchable
  - checkDispatchArgs
```
protected <L extends Listener,E extends Event<?,?>> void checkDispatchArgs(E event,
                                                                           Object bc,
                                                                           ExceptionCallback ec)
```
    Helper method which serves for throwing IllegalArgumentException if any of the passed arguments is null.
    
    Type Parameters:
    
    L - Type of the listeners which will be notified.
    
    E - Type of the event which will be passed to a listener.
    
    Parameters:
    
    event - The event.
    
    bc - The method to call on the listener
    
    ec - The ExceptionCallback
    
    Throws:
    
    IllegalArgumentException - If any argument is null.
  - setExceptionCallback
```
public void setExceptionCallback(ExceptionCallback callBack)
```
    Description copied from interface: EventProvider
    
    Sets the default ExceptionCallback which will be notified about exceptions when dispatching events without explicitly specifying an ExceptionCallback. The ExceptionCallback which is installed by default simply prints the stack traces to the error console.
    You can reset the ExceptionCallback to the default handler by providing null as parameter.
    
    Specified by:
    
    setExceptionCallback in interface EventProvider<S extends ListenerStore>
    
    Parameters:
    
    callBack - The ExceptionCallback for handling event handler exceptions, or null to use the default behavior.
  - notifyListeners
```
protected <L extends Listener,E extends Event<?,L>> void notifyListeners(E event,
                                                                         BiConsumer<L,E> bc,
                                                                         ExceptionCallback ec)
```
    Notifies all listeners registered for the provided class with the provided event. This method is failure tolerant and will continue notifying listeners even if one of them threw an exception. Exceptions are passed to the provided ExceptionCallback.
    This method does not check whether this provider is ready for dispatching and might thus throw an exception when trying to dispatch an event while the provider is not ready.
    
    Type Parameters:
    
    L - Type of the listeners which will be notified.
    
    E - Type of the event which will be passed to a listener.
    
    Parameters:
    
    event - The event to pass to each listener.
    
    bc - The method of the listener to call.
    
    ec - The callback which gets notified about exceptions.
    
    Throws:
    
    AbortionException - If the ExceptionCallback threw an AbortionException
  - notifySingle
```
protected <L extends Listener,E extends Event<?,L>> void notifySingle(L listener,
                                                                      E event,
                                                                      BiConsumer<L,E> bc,
                                                                      ExceptionCallback ec)
```
    Notifies a single listener and internally handles exceptions using the ExceptionCallback.
    
    Type Parameters:
    
    L - Type of the listeners which will be notified.
    
    E - Type of the event which will be passed to a listener.
    
    Parameters:
    
    listener - The single listener to notify.
    
    event - The event to pass to the listener.
    
    bc - The method of the listener to call.
    
    ec - The callback which gets notified about exceptions.
    
    Throws:
    
    AbortionException - If the ExceptionCallback or the listener threw an AbortionException.
    
    Since:
    
    1.1.0
  - createInvocation
```
protected <L extends Listener,E extends Event<?,L>> EventInvocation createInvocation(L listener,
                                                                                     E event,
                                                                                     BiConsumer<L,E> bc,
                                                                                     ExceptionCallback ec)
```
    Creates a new EventInvocation object for dispatching the given event to the given listener.
    
    Type Parameters:
    
    L - Type of the listeners which will be notified.
    
    E - Type of the event which will be passed to a listener.
    
    Parameters:
    
    listener - The listener to notify.
    
    event - The event to pass to the listener
    
    bc - The method of the listener to call.
    
    ec - The callback which gets notified about exceptions.
    
    Returns:
    
    The EventInvocation instance.
    
    Since:
    
    3.0.0
  - isSequential
```
public final boolean isSequential()
```
    Description copied from interface: EventProvider
    
    Returns whether this EventProvider is sequential, which means it strictly notifies listeners in the order in which they were registered for a certain event.
    Note: Implementors must obey the result of the isSequential property of the currently used ListenerStore. If the store is not sequential, this provider won't be either.
    
    Specified by:
    
    isSequential in interface EventProvider<S extends ListenerStore>
    
    Returns:
    
    Whether this instance is sequential.
  - isImplementationSequential
```
protected abstract boolean isImplementationSequential()
```
    Whether this EventProvider implementation is sequential. The isSequential() method considers the result of this method and the result of the current ListenerStore's isSequential method for determining whether dispatch events of this provider are sequential.
    
    Returns:
    
    Whether this EventProvider implementation is sequential.
  - close
```
public void close()
```
    Description copied from interface: EventProvider
    
    Closes this EventProvider and its ListenerStore (thus, removes all registered Listeners from the store). Depending on the actual implementation, the EventProvider might not be able to dispatch further events after closing. On some implementations closing might have no additional effect.
    
    Specified by:
    
    close in interface EventProvider<S extends ListenerStore>
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class AbstractEventProvider<S extends ListenerStore>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface de.skuzzle.jeve.EventProvider

Field Detail

exceptionHandler

defaultHandler

Constructor Detail

AbstractEventProvider

Method Detail

listeners

dispatch

dispatch

dispatch

checkDispatchArgs

setExceptionCallback

notifyListeners

notifySingle

createInvocation

isSequential

isImplementationSequential

close

toString