Event (jeve 3.0.0 API)

java.lang.Object
- de.skuzzle.jeve.Event<T,L>

Type Parameters:

T - Type of the source of this event.

L - Type of the listener which can handle this event.

Direct Known Subclasses:

DefaultTargetEvent, RegistrationEvent, SequentialEvent
```
public class Event<T,L extends Listener>
extends Object
```
This class is the base of all events that can be fired. It holds the source of the event and provides methods to stop delegation to further listeners if this event has been handled by one listener. Events are meant to be short living objects which are only used once - one Event instance for each call to dispatch . Any different usage might result in undefined behavior, especially when using the isHandled() property. Also, to prevent memory leaks, Event objects should never be stored over longer time.

Events explicitly belong to one kind of Listener implementation which is able to handle it. The class of this listener is passed to the constructor and queried by the EventProvider when collecting a list of targeted listeners for a dispatch action.

Events are used in conjunction with the EventProvider and its dispatch method. The dispatch method serves for notifying all registered listeners with a certain event. The EventProvider will stop notifying further listeners as soon as one listener sets this class' isHandled() to true.

Note on multi-threading

Event objects are not thread safe! Some EventProviders dispatch events asynchronously. If the same event instance is used within different threads, avoid modifying properties of the Event. Those modifications will result in undefined behavior.

Since:

1.0.0

Version:

2.0.0

Author:

Simon Taddiken

Constructor Summary

Constructors
Constructor and Description

Event(T source, Class<L> listenerClass)
Creates a new event with a given source.

Constructors
Constructor and Description
`Event(T source, Class<L> listenerClass)` Creates a new event with a given source.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Class<L>`	`getListenerClass()` Gets the type of the listener which can handle this event.
`protected ListenerStore`	`getListenerStore()` Gets the `ListenerStore` from which the currently notified listener has been retrieved.
`Map<String,Object>`	`getProperties()` Returns the Map that is used to store properties in this event instance.
`T`	`getSource()` Gets the source of this event.
`<E> Optional<E>`	`getValue(String key)` Returns a value that has been stored using `setValue(String, Object)`.
`<E> Optional<E>`	`getValueAs(String key, Class<E> type)` Returns a value that has been stored using `setValue(String, Object)`.
`boolean`	`isHandled()` Gets whether this event was already handled.
`boolean`	`isPrevented()` Whether this event was prevented the last time it has been passed to any dispatch method of an `EventProvider`.
`void`	`setHandled(boolean isHandled)` Sets whether this event was already handled.
`void`	`setListenerStore(ListenerStore store)` Sets the ListenerStore from which the currently dispatching EventProvider retrieves its Listeners.
`void`	`setPrevented(boolean prevented)` Called only by `EventProvider's` dispatch method if this event was prevented from being dispatched.
`void`	`setValue(String key, Object value)` Adds the given key-value mapping to this Event.
`void`	`stopNotifying(L listener)` Removes the provided listener from the `ListenerStore` from which it was supplied to the EventProvider which is currently dispatching this event.

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

- Constructor Detail
  - Event
```
public Event(T source,
             Class<L> listenerClass)
```
    Creates a new event with a given source.
    
    Parameters:
    
    source - The source of this event.
    
    listenerClass - The type of the listener which can handle this event. This value must not be null.
- Method Detail
  - getProperties
```
public Map<String,Object> getProperties()
```
    Returns the Map that is used to store properties in this event instance. All modifications to that map are directly reflected to its Event instance.
    
    Returns:
    
    The property Map of this event.
    
    Since:
    
    3.0.0
  - getValue
```
public <E> Optional<E> getValue(String key)
```
    Returns a value that has been stored using setValue(String, Object). As this method is generic, the value will automatically be casted to the target type of the expression in which this method is called. So this method has to be used with caution in respect to type safety.
    
    Type Parameters:
    
    E - Type of the resulting value.
    
    Parameters:
    
    key - The key of the value to retrieve.
    
    Returns:
    
    The value or an empty optional if the value does not exist.
    
    Since:
    
    3.0.0
    
    See Also:
    
    getValueAs(String, Class)
  - getValueAs
```
public <E> Optional<E> getValueAs(String key,
                                  Class<E> type)
```
    Returns a value that has been stored using setValue(String, Object). The value will be casted to the given type.
    
    Type Parameters:
    
    E - Type of the resulting value.
    
    Parameters:
    
    key - The key of the value to retrieve.
    
    type - The type that the value will be casted to.
    
    Returns:
    
    The value or an empty optional if the value does not exist.
    
    See Also:
    
    getValue(String)
  - setValue
```
public void setValue(String key,
                     Object value)
```
    Adds the given key-value mapping to this Event. The value can be queried using getValue(String).
    Note: Storing properties on events is generally discouraged in favor of creating explicit attributes with getters. However, there might arise situations in which you must attach further properties to an event without being able to modify its original source code. In these situations, storing properties with a String key might be useful.
    
    Parameters:
    
    key - The key under which the value is stored.
    
    value - The value to store.
    
    Since:
    
    3.0.0
    
    See Also:
    
    getValue(String), getProperties()
  - getSource
```
public T getSource()
```
    Gets the source of this event.
    
    Returns:
    
    The source of this event.
  - isPrevented
```
public boolean isPrevented()
```
    Whether this event was prevented the last time it has been passed to any dispatch method of an EventProvider.
    
    Returns:
    
    Whether this event has been prevented.
  - setPrevented
```
public void setPrevented(boolean prevented)
```
    Called only by EventProvider's dispatch method if this event was prevented from being dispatched.
    
    Parameters:
    
    prevented - Whether the event was prevented.
  - getListenerClass
```
public Class<L> getListenerClass()
```
    Gets the type of the listener which can handle this event.
    
    Returns:
    
    The listener's type.
  - stopNotifying
```
public void stopNotifying(L listener)
```
    Removes the provided listener from the ListenerStore from which it was supplied to the EventProvider which is currently dispatching this event. Hence this method can only be called from within a listening method while the event is being dispatched. Calling this method on an Event instance which is not currently dispatched will raise an exception.
```
 
 public class OneTimeUserListener extends UserListener {
     @Override
     public void userAdded(UserEvent e) {
         // logic goes here
         // ...

         // this listener should not be notified any more about this kind of
         // event.
         e.stopNotifying(this);
     }
 }
 
 
```
    Removing the listener will have no effect on the current dispatch action. Even if you remove a different listener than this, it will be notified anyway during this run, because the EventProvider collects the Listeners before starting to dispatch the event.
    Parameters:
    
    listener - The listener to remove from the currently dispatching EventProvider
    
    Since:
    
    2.0.0
  - getListenerStore
```
protected ListenerStore getListenerStore()
```
    Gets the ListenerStore from which the currently notified listener has been retrieved. If this Event is not currently dispatched, an exception will be thrown.
    
    Returns:
    
    The ListenerStore
  - setListenerStore
```
public void setListenerStore(ListenerStore store)
```
    Sets the ListenerStore from which the currently dispatching EventProvider retrieves its Listeners. The method will only set the store once. A second call to this method on the same event instance has no effect. This is to allow wrapping EventProviders so that the store set by the outermost provider is not overridden by an inner (wrapped) provider.
    
    Parameters:
    
    store - The listener store.
    
    Since:
    
    2.0.0
  - isHandled
```
public boolean isHandled()
```
    Gets whether this event was already handled. If this returns true, no further listeners will be notified about this event.
    
    Returns:
    
    Whether this event was handled.
  - setHandled
```
public void setHandled(boolean isHandled)
```
    Sets whether this event was already handled. If an event has been marked as "handled", no further listeners will be notified about it.
    Note that setting an event to be handled might have unintended side effects when using an EventProvider which is not sequential.
    
    Parameters:
    
    isHandled - Whether this event was handled.

Class Event<T,L extends Listener>

Note on multi-threading

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Event

Method Detail

getProperties

getValue

getValueAs

setValue

getSource

isPrevented

setPrevented

getListenerClass

stopNotifying

getListenerStore

setListenerStore

isHandled

setHandled