com.softwareag.eda.nerv.subscription

Interface Subscription

All Known Subinterfaces:

EndpointSubscription, EventTypeSubscription

All Known Implementing Classes:

AbstractSubscription, DefaultEndpointSubscription, DefaultEventTypeSubscription

public interface Subscription

Provides a mechanism for configuring EDA subscriptions. EDA consumers can use this interface to tweak the way they receive events from NERV. Most of the methods implement the Builder pattern so users can chain invocations and quickly configure the subscription behavior they need. For example if you want to filter duplicate events out and then re-order the rest by time stamp you have to do the following: Subscription.suppressDuplicateEvents().orderEvents();

It's very important to understand that the order of builder invocations matters. For example Subscription.filterEvents().suppressDuplicateEvents(); is different than Subscription.suppressDuplicateEvents().filterEvents();

In the first case events are filtered and just after that duplicates are suppressed which may be faster than first suppressing the duplicates and just after than filter the ones you're not interested in. So think about what exactly you want your subscription to do and in which order before making it.

Method Summary

Methods

Modifier and Type	Method and Description
Subscription	addPreprocessor(org.apache.camel.Processor preprocessor) Adds a preprocessor to the subscription route.
Subscription	filterEvents(java.lang.String simpleFilter) Filters events out on the EDA client side so consumers don't have to do this themselves.
Subscription	filterEvents(java.lang.String header, java.lang.String value) Filters events out on the EDA client side so consumers don't have to do this themselves.
Subscription	filterEventsOnServerSide(java.lang.String serverSideFilter) Filters events out on the Event Bus (server side filtering).
java.util.List<Configuration>	getConfigurations() Returns an unmodifiable ordered list containing the different configurations used by this subscription.
java.util.List<org.apache.camel.Processor>	getPreprocessors() Returns an unmodifiable ordered list of all the preprocessors added by EDA clients to this subscription.
org.apache.camel.Processor	getProcessor() Provides a reference to the last processor of the processing chain which will receive the events once all other operations have been completed.
Subscription	orderEvents() Enables reordering of events by the time-stamp in $Event$Start header for consumers using this subscription.
Subscription	orderEvents(OrderEventsConfiguration config) Configures this subscription to reorder events as specified by custom configuration.
Subscription	suppressDuplicateEvents()
Subscription	suppressDuplicateEvents(DuplicateEventsConfiguration config)
Subscription	useDurableSubscription(java.lang.String clientId, java.lang.String subscriptionName) Creates a durable subscription which receive messages while the subscriber is not active. For more detailed information please see Session.createDurableSubscriber(javax.jms.Topic, String) and Connection.setClientID(String)
Subscription	useThreadPool(int poolSize) Configures the subscription to use a thread pool with the specified size.
Subscription	useThreadPool(ThreadPoolConfiguration config) Configures the subscription to use a thread pool with the specified configuration.

Method Detail

getConfigurations

java.util.List<Configuration> getConfigurations()

Returns an unmodifiable ordered list containing the different configurations used by this subscription. The list increases with every change EDA clients make to this object. For example if you suppress duplicate events using Subscription.suppressDuplicateEvents() a new configuration will be added to the list.

Returns:

An ordered list containing the different configurations used by this subscription.

getPreprocessors

java.util.List<org.apache.camel.Processor> getPreprocessors()

Returns an unmodifiable ordered list of all the preprocessors added by EDA clients to this subscription.

Returns:

An ordered list of all the preprocessors of this subscription.

See Also:

#addPreprocessor(Processor)} - Used for adding preprocessors.

getProcessor

org.apache.camel.Processor getProcessor()

Provides a reference to the last processor of the processing chain which will receive the events once all other operations have been completed. It is usually an instance of a class provided by EDA consumers that does the actual work.

Returns:

A reference to the last route processor.

See Also:

#getPreprocessors()} - Returns a list of all previously added preprocessors.

addPreprocessor

Subscription addPreprocessor(org.apache.camel.Processor preprocessor)

Adds a preprocessor to the subscription route. Usually this is an object that does some preliminary processing of all incoming events before they reach the EDA client. For example users can add a transformer which converts events from the old EDA format to the new one and vice versa.

Parameters:

preprocessor - - The preprocessor that has to be added to the subscription route.

Returns:

A reference to this object. Can be used by clients for rapidly building subscription configurations.

useDurableSubscription

Subscription useDurableSubscription(java.lang.String clientId,
                                  java.lang.String subscriptionName)

Creates a durable subscription which receive messages while the subscriber is not active.
For more detailed information please see Session.createDurableSubscriber(javax.jms.Topic, String) and Connection.setClientID(String)

Parameters:

clientId - an unique client ID which can only be used by a single JMS connection instance.

subscriptionName - durable subscriber name for specifying durable topic subscriptions.

Returns:

A reference to this object. Can be used by clients for rapidly building subscription configurations.

suppressDuplicateEvents

Subscription suppressDuplicateEvents()

suppressDuplicateEvents

Subscription suppressDuplicateEvents(DuplicateEventsConfiguration config)

filterEvents

Subscription filterEvents(java.lang.String header,
                        java.lang.String value)

Filters events out on the EDA client side so consumers don't have to do this themselves. It's not as performant as filtering the events on the server side but nevertheless provides convenient functionality to clients. This method uses Camel's Simple Language and is equivalent to filterEvents("${header.<name>} == '<value>'"). For example the following code filterEvents("$Event$Kind", "Event") is equivalent to filterEvents("${header.$Event$Kind} == 'Event'"). The later one uses Camel's Simple Language directly. Both will only allow events of kind "Event" to pass through, all "Heartbeat" events will be filtered out.

Parameters:

header - - The name of the header you want your filter to be based on.

value - - The value of the header you want your filter to be based on.

Returns:

A reference to this object. Can be used by clients for rapidly building subscription configurations.

See Also:

#filterEvents(String)} - Provides more powerful client side filter capabilities based on Camel's Simple language., #filterEventsOnServerSide(String)} - Filters events out on the server side using a JMS message selector.

filterEvents

Subscription filterEvents(java.lang.String simpleFilter)

Filters events out on the EDA client side so consumers don't have to do this themselves. It's not as performant as filtering the events on the server side but nevertheless provides convenient functionality to clients. This method uses Camel's Simple Language. For more information check Apache Camel online documentation. Example: filterEvents("${header.$Event$Kind} == 'Event'"). This code will only allow events of kind "Event" to pass through, all "Heartbeat" events will be filtered out.

Parameters:

simpleFilter - - A Camel simple language filter. For more information check Apache Camel online documentation.

Returns:

A reference to this object. Can be used by clients for rapidly building subscription configurations.

See Also:

#filterEventsOnServerSide(String)} - Filters events out on the server side using a JMS message selector., Camel's Simple Language

filterEventsOnServerSide

Subscription filterEventsOnServerSide(java.lang.String serverSideFilter)

Filters events out on the Event Bus (server side filtering). This is much more performant than filtering the events on the client side but currently only the JMS protocol is supported, i.e. this would only work if the underlying transport protocol is JMS. The method accepts a valid JMS message selector filter which is based on SQL 92. For more information on the syntax of this filter please check Java's online documentation on JMS message selectors. Example: filterEventsOnServerSide("$Event$Kind == 'Event'"). This code will only allow events of kind "Event" to pass through, all "Heartbeat" events will be filtered out, all events will be filtered on the JMS provider side.

Parameters:

serverSideFilter - - A JMS message selector filter.

Returns:

A reference to this object. Can be used by clients for rapidly building subscription configurations.

See Also:

JMS Message, The JMS API Programming Model

orderEvents

Subscription orderEvents()

Enables reordering of events by the time-stamp in $Event$Start header for consumers using this subscription.

Returns:

- A subscription configured for reordering of events by date.

See Also:

OrderEventsConfiguration, Resequencer EIP

orderEvents

Subscription orderEvents(OrderEventsConfiguration config)

Configures this subscription to reorder events as specified by custom configuration. For available configuration parameters see OrderEventsConfiguration.

Parameters:

config - - A set of parameters used for reordering. For example, a header name by which the events are compared.

Returns:

- A a subscription configured for reordering of events with custom parameters.

useThreadPool

Subscription useThreadPool(int poolSize)

Configures the subscription to use a thread pool with the specified size.

Parameters:

poolSize - The size of the pool. In this case it's also equal to the maximum pool size.

Returns:

A reference to this object. Can be used by clients for rapidly building subscription configurations. The returned subscription is configured to use thread pools.

useThreadPool

Subscription useThreadPool(ThreadPoolConfiguration config)

Configures the subscription to use a thread pool with the specified configuration.

Parameters:

config - - The configuration which should be used for configuring the thread pool parameters such as default size, maximum pool size, and thread name template to be used.