com.netflix.eventbus.spi.Subscribe Maven / Gradle / Ivy
package com.netflix.eventbus.spi;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Consumers for {@link EventBus} must annotate their consumer methods with this annotation.
* A consumer is asynchronous, however it can choose to batch events consumed at a time using a batching strategy.
* A consumer can indicate if it favors synchronous event consumption, provided, it is allowed in the current
* environment, by setting the property {@link SyncSubscribersGatekeeper#ALLOW_SYNC_SUBSCRIBERS} to true.
* A consumer is always assumed to be thread-safe.
* Any method annotated with this must have one and only one argument which is the event object that it is supposed to
* handle.
*
* @author Nitesh Kant ([email protected])
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Subscribe {
public static final String NO_NAME = "none";
/**
* Batching strategy for event batches.
*/
enum BatchingStrategy {
/**
* The events will be batched based on the time elapsed between the addition of the first entry and now.
* The time is always in milliseconds and is defined by the property {@link com.netflix.eventbus.spi.Subscribe#batchAge}
**/
Age,
/**
* The events will be dispatched if the number of events in the batch exceeds the threshold as defined by
* {@link com.netflix.eventbus.spi.Subscribe#batchSize} or the age as defined by
* {@link Subscribe#batchAge}.
*/
SizeOrAge,
/**
* No batching, the events will be dispatched one at a time.
*/
None
}
/**
* A name for this subscriber, this is only required if you want to have a dynamic configuration via
* {@link SubscriberConfigProvider} AND each subscriber method in the class has a different configuration.
*
* @return A name, unique in a single subscriber class. This name does not need to be unique amongst all
* subscriber classes.
*/
String name() default NO_NAME;
/**
* Returns the batching strategy for this subscriber. If a subscriber chooses a batching strategy other than
* {@link BatchingStrategy#None}, the argument to the subscriber method must be an {@link Iterable}.
* Event batches does not support removal.
*
* @return The batching strategy for this subscriber.
*/
BatchingStrategy batchingStrategy() default BatchingStrategy.None;
/**
* The threshold for the age of the batch in milliseconds since the first entry was added. Only considered if the
* batching strategy is {@link BatchingStrategy#Age} or {@link BatchingStrategy#SizeOrAge}
*
* @return The age of the batch in milliseconds.
*/
int batchAge() default 0;
/**
* The threshold for the size of the batch. Only considered if the batching strategy is {@link BatchingStrategy#SizeOrAge}
*
* @return The threshold for the size of the batch.
*/
int batchSize() default 1;
/**
* The queue size for the consumer. In case, the consumer receives batches of events, this will be the number of
* batches and not individual events.
*
* @return The queue size for the consumer.
*/
int queueSize() default -1;
/**
* A backdoor in the eventbus to allow synchronous events consumption. This mode is controlled by the property
* {@link SyncSubscribersGatekeeper#ALLOW_SYNC_SUBSCRIBERS}, which when set to true, allows registration of synchronous consumers.
* Setting this property to true, does NOT guarantee synchronous event consumption. It is only available when
* the property {@link SyncSubscribersGatekeeper#ALLOW_SYNC_SUBSCRIBERS} is set to true at the time of event publishing.
* If the property is set to false the events will be sent to the consumer asynchronously.
*
* @return true if this subscriber favors synchronous consumption of events. false by
* default.
*/
boolean syncIfAllowed() default false;
}