Package dev.getelements.elements.sdk.annotation

Annotation Interface ElementEventConsumer

@Target(METHOD) @Retention(RUNTIME) @Repeatable(ElementEventConsumers.class) public @interface ElementEventConsumer
Annotates a method capable of receiving an instance of Event. When an event is published, the runtime will invoke this method with the event data. If the method's parameters match the types of Event.getEventArguments(), the method will receive the unpacked arguments directly.

Direct Event Consumption

For classes annotated with ElementServiceExport, event consumer methods are automatically discovered and invoked when matching events are published. The service locator will find the service instance and dispatch the event to it. 

 @ElementServiceExport
 public class MyService {
     @ElementEventConsumer("my.event")
     public void onMyEvent(String arg1, int arg2) {
         // Called when "my.event" is published with matching arguments
     }
 }

Routed Event Consumption

For implementation classes that are not directly exposed as services, use the via() field to route events through an exported service interface. This allows internal implementation classes to receive events without needing to be part of the public API. 

 // Public service interface
 @ElementPublic
 public interface MyService {
     // Service methods
 }

 // Private implementation that receives events
 public class MyServiceImpl implements MyService {
     @ElementEventConsumer(
         value = "my.event",
         via = @ElementServiceReference(MyService.class)
     )
     public void onMyEvent(String arg1, int arg2) {
         // Called when "my.event" is published
         // The service locator finds this instance via MyService interface
     }
 }
When using via(), the service locator will:
  1. Look up the service instance using the specified service interface
  2. Cast the instance to the declaring class of the annotated method
  3. Invoke the method on that instance
This is useful when you want to keep implementation details private while still participating in the event system.
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    ElementEventConsumer.None
    Placeholder type used as the default value for via() to indicate that no service routing should be used.

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    value
    The name of the Event.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    ElementServiceReference
    via
    Specifies a service interface through which this event consumer should be invoked.

  • Element Details

    • value

      String value
      The name of the Event.
      Returns:
      the name of the event

    • via

      ElementServiceReference via
      Specifies a service interface through which this event consumer should be invoked. When specified, the ServiceLocator will look up the service instance using the provided service reference, then invoke this method on that instance.

      This allows implementation classes that are not directly exported to receive events by routing through their public service interface. The implementation class must still be annotated with ElementServiceExport and implement the interface specified in this field.

      If not specified (defaults to ElementEventConsumer.None), the event consumer is invoked directly on the service instance, which requires the declaring class to be annotated with ElementServiceExport.

      Example:

      
 @ElementServiceExport
 public class MyServiceImpl implements MyPublicService {
     @ElementEventConsumer(
         value = "my.event",
         via = @ElementServiceReference(MyPublicService.class)
     )
     public void onEvent(String arg) {
         // Invoked via lookup of MyPublicService
     }
 }
      Returns:
      the service reference to use for event routing, or @ElementServiceReference(None.class) to use direct invocation
      Since:
      3.7
      See Also:
      Default:
      @dev.getelements.elements.sdk.annotation.ElementServiceReference(dev.getelements.elements.sdk.annotation.ElementEventConsumer.None.class)