Treasury Events API

This page is incomplete and invalid as of Treasury v2.0.0.

---

⚠️ This page has not been updated for Treasury v2 ⚠️

Whilst we're working on updating all the documentation to the new API, please contact us if you have any questions.

---

Description

The way of calling and listening to Treasury's Events (at the time of writing, Treasury Economy API's events and Treasury Service API's events) is Treasury's Events API. It needed to be created because we aim the whole Treasury API to be completely platform independent. It is inspired by Velocity's Events API but it has been radically changed in order to simplify the implementation and the usage.

NOTE: The Treasury Events API is not limited only to Treasury's APIs events. You are able to use it too if you want.

Fundamental systems

Treasury's Events API has a few things in order to function properly.

EventBus

The EventBus is the most fundamental thing you have on the library. This is how you call events, this is how you register listeners (or as we'd like to call stuff in Treasury - subscribers). The coolest thing about our events is that you can make literally every object an event. What do I mean by that is that you don't need to extend any voodoo magic classes. You just create your object and call it and you're good to go.

Completion

The Completion is something like java's CompletableFuture, but it's only resulted to exceptions. It is used to block event execution until a asynchronous task finishes. The only 2 methods as a event subscriber you shall be interested in are the Completion#complete and Completion#completeExceptionally . Continue reading to have more understanding about it all :) .

EventSubscriber

The EventSubscriber is one of the ways to register a event subscription. This is a fundamental class, without it the system won't function. In order for you to use it, you have to implement it. It is recommended that you use this if you need to block the event execution. There are other solutions if you don't need to block the event execution, so you might want to continue reading :) .

SimpleEventSubscriber

The SimpleEventSubscriber is the smaller brother of the EventSubscriber. Just as the EventSubscriber, you have to implement this class. This is the subscriber you need if you don't need to block event execution.

EventSubscriberBuilder

The EventSubscriberBuilder is the last, but not least of the 3 ways of creating a subscriber. In our opinion this is the most friendliest way of creating a event subscriber. You can obtain instance of it through EventBus#subscriptionFor

EventPriority

The EventPriority is the way of binding a subscription a priority. Lower the priority means that the subscription will be called with one of the first subscriptions. High priority means that the subscription is of "high importance" and should have one of the final says in the event handling.

FireCompletion

The FireCompletion is a simplified resulted Completion, returned by EventBus#fire. See examples below to understand better.

Cancellable

The Cancellable is just like the Cancellable in other platforms - Bukkit, BungeeCord for example.

Examples

Builder pattern

With the need of blocking event execution

 EventBus eventBus = EventBus.INSTANCE;
 eventBus.subscribe(
   eventBus.subscriptionFor(AnEvent.class)
     .withPriority(EventPriority.HIGH)
     .whenCalled(event -> {
       Completion completion = new Completion();
       doAsync(() -> {
         // do something
         // then you run either completion.complete() or completion.completeWithException(error)
         // if you don't call it the event won't proceed, potentially blocking the transaction so please don't forget to do this before doing a release or sth of your plugin
         completion.complete();
       });
       return completion;
     });
     .completeSubscription()
 );

Without the need of blocking event execution

 EventBus eventBus = EventBus.INSTANCE;
 eventBus.subscribe(
   eventBus.subscriptionFor(AnEvent.class)
     .withPriority(EventPriority.HIGH)
     .whenCalled(event -> {
       // do stuff
     });
     .completeSubscription()
 );

Implementing subscribers

With the need of blocking event execution

 public class MyEventListener extends EventSubscriber<MyEvent> {

   public MyEventListener() {
     super(MyEvent.class, EventPriority.NORMAL);
   }

   @Override
   public Completion onEvent(MyEvent event) {
     Completion completion = new Completion();
     doAsync(() -> {
       // do something
       // then you run either completion.complete() or completion.completeWithException(error)
       // if you don't call it the event won't proceed, potentially blocking the transaction so please don't forget to do this before doing a release or sth of your plugin
       completion.complete();
     });
     return completion;
   }
 }

 // then you register
 EventBus.INSTANCE.subscribe(new MyEventListener());

Without the need of blocking event execution

 public class MyEventListener extends SimpleEventSubscriber<MyEvent> {

   public MyEventListener() {
     super(MyEvent.class, EventPriority.NORMAL);
   }

   @Override
   public void subscribe(MyEvent event) {
     // do stuff
   }
 }

 // then you register
 EventBus.INSTANCE.subscribe(new MyEventListener());

Calling events

// create your event
public class MyEvent {
  // whatever you want
}

// calling the event
EventBus eventBus = EventBus.INSTANCE;

// if you want to ignore whenever the event got completed: 
eventBus.fire(new MyEvent());

// if you want to do stuff the moment event got called
// this blocks the thread it is called onto
eventBus.fire(new MyEvent()).whenCompleteBlocking((event, errors) -> {
  if (!errors.isEmpty()) {
    // do stuff with errors
    return;
  }
  
  // do stuff with the event
});

// if you want to do stuff the moment event got called
// this is asynchronous and does not block the thread it is called onto
eventBus.fire(new MyEvent()).whenCompleteAsync((event, errors) -> {
  if (!errors.isEmpty()) {
    // do stuff with errors
    return;
  }
  
  // do stuff with the event
});