Overview

To reduce boilerplate code, the AepEngine and XVM provide a basic set of annotations. EventHandler annotations are the primary means by which an AepEngine communicates events to an application. XVM annotations allow the XVM to inject the objects it creates into the application, and for the application to expose hooks for monitoring and lifecycle-related operations that the XVM manages. 
 

AEP Annotations

EventHandler

The EventHandler annotation is used to annotate a method that serves as an AEPEngine event handler.

Developers should annotate methods that serve as AEP event handlers with this annotation. Upon creation, the AEP engine searches the event handler container objects supplied to the engine constructor or to an XVM via the AppEventHandlerAccessor annotation for methods that are annotated with this annotation. If the annotated method accepts an SMA message as its (only) argument, it is treated as a message handler; i.e. inbound messages are dispatched to the annotated method. Otherwise, if the method accepts an event object as its (only) argument, then the method is treated as the handler for the same event type as the method argument. All other methods annotated with this annotated annotation are flagged as erroneous annotations and ignored. 

Message Handlers

The most common usage of the EventHandler annotation is to mark a method as a handler for a Message. 

...

Work done in a message event handler is transactional and atomic: changes to state, delivery of outbound messages, and acknowledgement of the received message are an atomic unit of work. 

Lifecycle

...

Events

The AepEngine will also communicate events about the engine lifecycle to the application if it has annotated event handlers for the event type. Lifecycle events all implement the com.neeve.event.lifecycle.ILifecycleEvent. The engine will forward such events to the application with the exception of the events which occur before the application has registered event handlers. 

Applications should not modify state or send outbound messages as a result of handling an a lifecycle event because they are typically dispatched outside of a transactional context. 

See Talon Application Lifecycle for more details on the application lifecycle and events emitted. 

Below is an example of an a lifecycle event handler: 

/**
 * Notification that the engine is stopping. 
 */
@EventHandler
public void onMessage(AepEngineStoppedEvent event) {
  // Insert some cleanup code here?
}

Alert

...

Events

The AepEngine also communicates alerts to the application if it has annotated event handlers for the event type. Alert events all implement the com.neeve.event.alert.IAlertEvent. The engine will forward such events to the application with the exception of those which occur before the application has registered event handlers. 

Applications should not modify state or send outbound messages as a result of handling an alert event because they are typically dispatched outside of a transactional context. 

...

/**
 * Indicates that a message handler threw an exception.
 */
@EventHandler
public void onMessage(AepApplicationExceptionEvent event) {
  // Dump some diagnostic information
}

XVM Annotations

The Talon XVM manages the creation and lifecycle of the Talon Applications that it contains. For each application it loads, it discovers event handlers and injects AEP objects of interest into the loaded application. This process is described in detail in the Talon Application Lifecycle's Load Phase. Below is A subset of some of the most commonly used annotations are discussed below. 

AppHAPolicy

Because the choice of HA Policy for an application is a design choice, it isn't a configurable option. The AppHAPolicy should be declared on your application's main class: 

import com.neeve.server.app.annotations.*;
 
@AppHaPolicy(StateReplication)
public class MyApp {
     ...
}

App Injection Points

Several objects created by the Talon XVM during application startup can be injected into your application's main class during startup.  Below is an example of a Talon XVM event handler that injects a the message sender :for your application. 

import com.neeve.server.app.annotations.*;
 
@AppHaPolicy(StateReplication)
public class MyApp {


  private AepMessageSender messageSender;

  public MyApp () {}
 
  /**
   * Injects the message sender used by the application to send 
   * messages through talon
   */
  @AppInjectionPoint
  final public void setMessageSender(final AepMessageSender messageSender) {
     this.messageSender = messageSender;
  }
}

See the Talon Application Lifecycle for more details on the types of objects that are injected during Talon load. An application may use the @AppInjectionPoint on multiple methods, but may only use it once per type of object being injected. 

Note that an XVM is not meant to server as a dependency injection framework (other then the few Talon specific objects that it injects). Rather, an XVM allows applications to use a DI framework of its choice. A common usage pattern is to use the Talon XVM as an the application's entry point and to load the application's specific objects via the DI framework early on in the Talon XVM's lifecycle. 

import com.neeve.server.app.annotations.*;
import com.neeve.server.app.*;
import org.springframework.beans.factory.BeanFactory;
import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;


@AppHaPolicy(StateReplication)
public class MyApp {

  private InventoryManager inventoryManager;
  private CustomerManager customerManager;

  private AepMessageSender messageSender;

  public MyApp () {}
 
  @AppInjectionPoint
  public void setLoader(final SrvAppLoader loader) {
     ApplicationContext context = new ClassPathXmlApplicationContext(
                "META-INF/" + loader.getAppName() + ".xml");
     inventoryManager = (InventoryManager) context.getBean("inventoryManager");
     customerManager = (CustomerManager ) context.getBean("customerManager");
  }
}

Exposing Additional Event Handlers

Most applications won't define all of their event handlers on the application main class. To let the runtime know about additional objects in your application that expose event handlers, your main class can use the AppEventHandlerContainersAccessor annotation to provide additional handlers:

import com.neeve.server.app.annotations.*;

@AppHaPolicy(StateReplication)
public class MyApp {
 
  private final InventoryManager inventoryManager;
  private final CustomerManager customerManager;

  public MyApp () {
    inventoryManager = new InventoryManager(this);
    customerManager= new CustomerManager (this);
  }

  @AppEventHandlerContainersAccessor 
  public void getEventHandlers (Set<Object> handlers) {
      handlers.add(inventoryManager);
      handlers.add(customerManager);
  }
}

The AppEventHandlerContainersAccessor method must have a signature that accepts a java.util.Set as its only argument and should appear only once in an application. The provided set is an ordered Set, so if multiple handlers declare EventHandlers for the same type, Talon will dispatch events to them in the order they are added to the set.