Events

Interfacing with the Terra API is primarily done through events.

The Event Manager

The base for working with events in Terra is the EventManager. The Event Manager contains methods to:

• Call events (#callEvent)

• Register event handlers (#registerHandler)

• Access event handlers (#getHandler)

Accessing the Event Manager

The Event Manager is accessed through the Platform instance:

platform.getEventManager();

Note

To access the Platform instance in your addon, use Dependency Injection.

Note

You’ll generally want to register event listeners in your addon’s entry point(s).

Event Handlers

Event handlers provide API to register event listeners. Terra provides a single event handler by default, the FunctionalEventHandler. Addons are able to register custom event handlers if they wish to use different APIs to register events, for example, annotated methods.

Accessing an Event Handler

To access an event handler, simply pass its Class instance into EventManager#getHandler(Class).

Here’s an example for accessing the default FunctionalEventHandler:

platform.getEventManager()
        .getHandler(FunctionalEventHandler.class);

The Functional Event Handler

The Functional Event Handler is the default Event Handler provided by Terra. Most addons will want to use this event handler. This handler provides a functional-style API for registering events using Java’s lambda expressions.

Registering a Listener

When registering an event listener with the Functional Event Handler, invoke the FunctionalEventHandler#register(BaseAddon, Class) method. This will return an instance of EventContext which you can use to build your listener.

Adding an Action to the Listener

To add actions to your event listener, append EventContext#then(Consumer) calls. these operations will execute consecutively, with the consumer accepting the event instance.

Example

platform.getEventManager()                        // Get the event manager.
        .getHandler(FunctionalEventHandler.class) // Get the functional event handler.
        .register(addon, SomeEvent.class)         // Register a listener for SomeEvent, to our addon.
        .then(someEventInstance -> {              // Perform an action when the event is fired.
            logger.info("Handling Some Event!");
            logger.info("Event says: {}", someEventInstance.getSomething());
        });

This example registers a listener for SomeEvent. When the event is called, the result of the event instance’s #getSomething() is logged.