Events

What is an Event?

An event is anything which can happen at an uncertain point in time and which implies that dependent actions should be executed. In jeve, events are represented by the class Event<T>. An event always has an unique source, which type is denoted by the event's generic parameter . jeve then presents mechanics to send this event to a set of Listeners interested in a certain event type.

How to Use Events

Normally, in order to use events, you create a new sublclass of Event which suits your needs and carries all the information you need. For example, an UserEvent could carry an User object:

import de.skuzzle.jeve.Event;

public class UserEvent extends Event<UserManager> {
    // It's recommended to always use immutable fields
    private final User user;

    public UserEvent(UserManager source, User user) {
        // pass the source of this event to the super class
        super(source);
    }

    public User getUser() {
        return this.user;
    }
}

As said before, each event not only knows its source, but also the source's type. In our example, UserEvents are raised by the class UserManager. Therefore, each UserEvent instance gets a reference to the UserManager passed in the constructor.

Event Lifecycle

Events are meant to be short living objects. The intended lifecycle is:

1. Perform any actions which result in rasing an event.
2. Create a specialized Event instance for this action.
3. Pass the Event instance to the dispatch method of an EventProvider to notify all interested listeners.
4. Don't care about the Event object anymore.

This implies that you should not store an Event instance for longer than needed as it could prevent attached objects from being garbage collected.

Special Properties

Currently, all events hold one special property, which denotes whether they have already been handled. After instantiating an event this property yields false. When being passed to a Listener, the handling method of the listener may set the event to be handled. In this case, no further Listeners will be notified about that event and the dispatching process stops.

Thread-safety note: For obvious reasons, when using a ParallelEventProvider or any other non-sequential EventProvider implementation, this mechanism only works in a non-deterministic way because the listeners are notified in an undifined order. The same holds for non-immutable events which are modified in any way by listeners during the dispatching process. Whether an EventProvider is sequential can be figured out in its documentation and at runtime using EventProvider#isSequential()