com.neeve.toa
Class TopicOrientedApplication

java.lang.Object
  com.neeve.toa.TopicOrientedApplication

All Implemented Interfaces:

MessageInjector, MessageSender

public abstract class TopicOrientedApplication
extends Object
implements MessageSender, MessageInjector

Base class for topic oriented applications.

Restrictions on AEP Usage

The TopicOrientedApplication class reserves usage of several AepEngine features for its own use:

1. Predispatch Message Handler:
   TopicOrientedApplication reserves the sole right to set AepEngine.setPredispatchMessageHandler(IAepPredispatchMessageHandler). Applications may register delegate handlers via addPredispatchMessageHandler(IAepPredispatchMessageHandler).
2. Postdispatch Message Handler:
   TopicOrientedApplication reserves the sole right to set AepEngine.setPostdispatchMessageHandler(IAepPostdispatchMessageHandler). Applications may register delegate handlers via addPostdispatchMessageHandler(IAepPostdispatchMessageHandler).
3. Server Annotations:
   The following annotations are implemented by TopicOrientedApplication and should not be implemented by subclasses:
   • @AppInjectionPoint
TopicOrientedApplication currently implements these injection points, Subclasses may override the following methods instead:
     • onAppLoaderInjected(SrvAppLoader)
     • onEngineDescriptorInjected(AepEngineDescriptor)
     • onEngineInjected(AepEngine)
   • AppInitializer, use onAppFinalized()
   • AppFinalizer, use onAppFinalized()
4. @AppEventHandlerContainersAccessor, @AppStatContainersAccessor and @AppCommandHandlerContainersAccessor
   Talon Server applications return objects containing event handlers and command handlers via methods on the application class annotated with these annotations respectively. TopicOrientedApplication implements the accessors for application event and command handlers, and instead exposes a single collection point for all objects of interest to the server for introspect via a ManagedObjectLocator. The default ManagedObjectLocator

Lifecycle

Apps loaded by a Talon server are initialized using annotations on the application's main class. The sequence for loading a Talon server application is as follows:

1. Instantiate the main class which must have a public 0 argument constructor
2. Inspect the main class for Talon app annotations.
3. Inject SrvAppLoader into a AppInjectionPoint annotated method to let the application first see the server and its SrvConfigAppDescriptor. The SrvAppLoader provides the application with the ability to inspect the identity of the server in which it is being launched.
   Note: because TopicOrientedApplication provides this injection point it is illegal for subclasses to implement an AppInjectionPoint for SrvAppLoader, subclasses can instead override onAppLoaderInjected(SrvAppLoader).
4. Inject the AepEngineDescriptor into an AppInjectionPoint annotated method to let the app customize its AepEngine. The application may augment the AepEngineDescriptor, and to inspect the configuration of the application being launched.
   Note: because TopicOrientedApplication provides this injection point it is illegal for subclasses to implement an AppInjectionPoint for AepEngineDescriptor, subclasses can instead override onEngineDescriptorInjected(AepEngineDescriptor).
5. Call getManagedObjectLocator() and call its ManagedObjectLocator.locateManagedObjects(Set) method to find objects that expose AppCommandHandler or EventHandler annotations.
   Note: TopicOrientedApplication implements AppCommandHandlerContainersAccessor and AppEventHandlerContainersAccessor methods that pass the objects returned from the application's ManagedObjectLocator, so it is illegal for subclasses to use these annotations
6. Call getServiceDefinitionLocator() and invoke its ServiceDefinitionLocator.locateServices(Set). TopicOrientedApplication parses the service models returned by the ServiceDefinitionLocator and based on interest defined by the application's EventHandlers determines which channels to join.
7. Call onConfigured(). At this point the application can call getServiceModels() or getServiceModel(String) to examine the parsed service model.
8. Call to AppStateFactoryAccessor annotated method to retrieve the application's state factory (for use with state replication engines).
9. Construct the AepEngine using the configured AepEngineDescriptor, IAepApplicationStateFactory, and EventHandlers, registering the SrvAppLoader as a IAepWatcher for the engine.
10. Inject AepEngine into a AppInjectionPoint annotated method to provide the application access to its AepEngine.
    Note: because TopicOrientedApplication provides this injection point it is illegal for subclasses to implement an AppInjectionPoint for AepEngine, subclasses can instead override onEngineInjected(AepEngine). In most cases, the application should not use the AepEngine directly and instead use the corresponding facilities provided by TopicOrientedApplication (MessageSender, MessageInjector, EngineClock etc).
11. Insepects Managed Object for User defined stats (annotated with @AppStat. This implies that by the time the call to onEngineInjected(AepEngine) returns, all application defined stats should have been constucted by the application.
12. Call onAppInitialized() to indicate that the applications has been successfully initialized.
    Note because TopicOrientedApplication utilizes the AppInitializer annotation to implement this, applications must not use the AppInitializer annotation.
13. If the application is annotated with an AppMain annotation, spin up Main Thread for the application when the AepEngine becomes Primary and invoke it. For an application that is responsive (i.e. reacts to messages), an application may register additional Aep LifecycleEvent EventHandlers to respond to various application lifecycle events (see link below)
14. When the app is issued a close or unload command, invoke the onAppFinalized() method on the app and join its AppMainn thread if started.
    Note because TopicOrientedApplication utilizes the AppFinalizer annotation to implement this, applications must not use the AppInitializer annotation.

(For an indepth discussion of the underlying AepEngine lifecycle, see X Application Lifecycle)

Clustering

For a TopicOrientedApplication to support clustering, subclasses must be annotated with an AppHAPolicy annotation.

Field Summary

protected static Tracer

_tracer

Constructor Summary

protected

TopicOrientedApplication() Default constructor.

Method Summary

protected void	addAppCommandHandlerContainers(Set<Object> containers) This method may be overridden by subclasses to add additional objects that contain methods with AppCommandHandler annotations.
protected void	addAppStatContainers(Set<Object> containers) This method may be overridden by subclasses to add additional objects that contain methods with AppStat annotations.
protected void	addChannelFilterProviders(Set<Object> containers) This method may be overridden by subclasses to add additional objects that implement ChannelFilterProvider.
protected void	addChannelInitialKeyResolutionTableProviders(Set<Object> containers) This method may be overridden by subclasses to add additional objects that implement ChannelQosProvider.
protected void	addChannelQosProviders(Set<Object> containers) This method may be overridden by subclasses to add additional objects that implement ChannelQosProvider.
protected void	addHandlerContainers(Set<Object> containers) This method may be overridden by subclasses to add additional objects that contain methods with EventHandler annotations.
void	addPostdispatchMessageHandler(IAepPostdispatchMessageHandler handler) Adds a message handler to be invoked after 'normal' message handler dispatch.
void	addPredispatchMessageHandler(IAepPredispatchMessageHandler handler) Adds a message handler to be invoked before 'normal' message handler dispatch.
protected void	addTopicResolverProviders(Set<Object> containers) This method may be overridden by subclasses to add additional objects that implement TopicResolverProvider.
protected String	getChannelFilter(ToaService serviceName, ToaServiceChannel channelName) This method may be overridden by subclasses to associate a channel filter with the application.
protected MessageChannel.Qos	getChannelQos(ToaService service, ToaServiceChannel channel) This method may be overridden by subclasses to specify the MessageChannel.Qos for the provided service channel.
Configurer	getConfigurer() Returns this application's bootstrap configurer.
AepEngine	getEngine() Returns this application's AepEngine.
EngineClock	getEngineClock() Return an interface which may be used to get the AepEngine time.
protected Properties	getInitialChannelKeyResolutionTable(ToaService service, ToaServiceChannel channel) This method may be overridden by subclasses to perform initial key resolution on a channel at the time it is configured which allows all or a portion of a channel's dynamic key parts to be determined statically at configuration time by returning a initial Key Resolution Table (KRT).
protected ManagedObjectLocator	getManagedObjectLocator() Subclasses may override this method to change the strategy for locating an application's managed objects.
MessageInjector	getMessageInjector() Returns the MessageSender implementation which is this class.
MessageSender	getMessageSender() Returns the MessageSender implementation which is this class.
protected ServiceDefinitionLocator	getServiceDefinitionLocator() Subclasses may override this method to change the way service xmls are located.
protected ToaService	getServiceModel(String fullServiceName) Looks up a parsed service model by fully qualified name.
protected Collection<ToaService>	getServiceModels() Returns the application's parsed service definitions.
protected TopicResolver<?>	getTopicResolver(ToaService serviceName, ToaServiceChannel channelName, Class<?> messageType) This method may be overridden by subclasses to return a TopicResolver for messages of the given type sent on the given channel.
void	injectMessage(IRogMessage message) Enqueue a message into an application's AepEngine's event multiplexer.
void	injectMessage(IRogMessage message, boolean nonBlocking) Enqueue a message into an application's AepEngine's event multiplexer.
void	injectMessage(IRogMessage message, boolean nonBlocking, int delay) Enqueue a message into an application's AepEngine's event multiplexer.
protected void	onAppFinalized() This is called after the application's AepEngine has been successfully created and injected into the application.
protected void	onAppInitialized() This is called after the application's AepEngine has been successfully created and injected into the application.
protected void	onAppLoaderInjected(SrvAppLoader loader) Called when the SrvAppLoader is injected into the application.
protected void	onConfigured() Called after configuration of messaging and services has been successfully completed.
protected void	onEngineDescriptorInjected(AepEngineDescriptor engineDescriptor) Called when the AepEngineDescriptor is injected into the application.
protected void	onEngineInjected(AepEngine engine) Called when the AepEngine is injected into the application.
void	sendMessage(IRogMessage message) Sends a message using the message's default channel.
void	sendMessage(IRogMessage message, MessageChannel.RawKeyResolutionTable rawKeyResolutionTable) Sends a message using the provide zero garbage key resolution table.
void	sendMessage(IRogMessage message, Properties keyResolutionTable) Sends a message using the provided key resolution table.
void	sendMessage(IRogMessage message, String topic) Sends a message using the given topic as the channel key.
void	sendMessage(IRogMessage message, XString topic) Sends a message using the given topic as the channel key (zero garbage variant).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_tracer

protected static final Tracer _tracer

Constructor Detail

TopicOrientedApplication

protected TopicOrientedApplication()

Default constructor.

Method Detail

addHandlerContainers

protected void addHandlerContainers(Set<Object> containers)

This method may be overridden by subclasses to add additional objects that contain methods with EventHandler annotations.

This method is called by the DefaultManagedObjectLocator, if an application provides its own ManagedObjectLocator then it is up to that locator as to whether or not this method will be invoked.

This method is called by the application during the configuration phase allowing the application subclass to register event handler containers by adding objects having methods annotated with EventHandler that will serve as the application's message and event handlers.

This class is automatically added as an event handler container, subclasses should not add itself to the set.

Parameters:

containers - Objects with EventHandler methods should be added to this set.

addAppCommandHandlerContainers

protected void addAppCommandHandlerContainers(Set<Object> containers)

This method may be overridden by subclasses to add additional objects that contain methods with AppCommandHandler annotations.

This method is called by the DefaultManagedObjectLocator, if an application provides its own ManagedObjectLocator then it is up to that locator as to whether or not this method will be invoked.

This method is called by the application during the configuration phase allowing the application subclass to register command handler containers by adding objects having methods annotated with AppCommandHandler that will serve as the application's command handlers.

This class is automatically added as an command handler container, subclasses should not add itself to the set.

Parameters:

containers - Objects with AppCommandHandler methods should be added to this set.

addAppStatContainers

protected void addAppStatContainers(Set<Object> containers)

This method may be overridden by subclasses to add additional objects that contain methods with AppStat annotations.

This method is called by the DefaultManagedObjectLocator, if an application provides its own ManagedObjectLocator then it is up to that locator as to whether or not this method will be invoked.

This method is called by the application during the configuration phase allowing the application subclass to register command handler containers by adding objects having methods annotated with AppStat that will serve as the application's command handlers.

This class is automatically added as an command handler container, subclasses should not add itself to the set.

Parameters:

containers - Objects with AppStat should be added to this set.

addChannelFilterProviders

protected void addChannelFilterProviders(Set<Object> containers)

This method may be overridden by subclasses to add additional objects that implement ChannelFilterProvider.

This method is called by the DefaultManagedObjectLocator, if an application provides its own ManagedObjectLocator then it is up to that locator as to whether or not this method will be invoked.

This method is called by the application during the configuration phase allowing the application subclass to register ChannelFilterProviders

The default implementation of this method adds a filter provider that calls getChannelFilter(ToaService, ToaServiceChannel)

Parameters:

containers - Objects implementing ChannelFilterProvider should be added to this set.

addTopicResolverProviders

protected void addTopicResolverProviders(Set<Object> containers)

This method may be overridden by subclasses to add additional objects that implement TopicResolverProvider.

This method is called by the DefaultManagedObjectLocator, if an application provides its own ManagedObjectLocator then it is up to that locator as to whether or not this method will be invoked.

This method is called by the application during the configuration phase allowing the application subclass to register TopicResolverProviders

The default implementation of this method adds 2 TopicResolverProviders:

• A GeneratedTopicResolverProvider which will search the classpath for channel resolvers generated by the ToaCodeGenerator.
• A TopicResolverProvider that calls getChannelFilter(ToaService, ToaServiceChannel), allowing subclasses to return a TopicResolver.

Parameters:

containers - Objects implementing ChannelFilterProvider should be added to this set.

getTopicResolver

protected TopicResolver<?> getTopicResolver(ToaService serviceName,
                                            ToaServiceChannel channelName,
                                            Class<?> messageType)

This method may be overridden by subclasses to return a TopicResolver for messages of the given type sent on the given channel.

This method will not be called unless addTopicResolverProviders(Set) is called on this class. This is done by the DefaultManagedObjectLocator, but may not be called if the application defines its own ManagedObjectLocator.

Parameters:

serviceName - The service name.

channelName - The name of the channel to filter.

messageType - The concrete class of the message.

Returns:

A TopicResolver for the message when it is sent of the given channel.

getChannelFilter

protected String getChannelFilter(ToaService serviceName,
                                  ToaServiceChannel channelName)

This method may be overridden by subclasses to associate a channel filter with the application.

This method will not be called unless addChannelFilterProviders(Set) is called on this class. This is done by the DefaultManagedObjectLocator, but may not be called if the application defines its own ManagedObjectLocator.

Parameters:

serviceName - The service name.

channelName - The name of the channel to filter.

Returns:

A channel filter or null if the channel should not be filtered.

addChannelQosProviders

protected void addChannelQosProviders(Set<Object> containers)

This method may be overridden by subclasses to add additional objects that implement ChannelQosProvider.

This method is called by the DefaultManagedObjectLocator, if an application provides its own ManagedObjectLocator then it is up to that locator as to whether or not this method will be invoked.

This method is called by the application during the configuration phase allowing the application subclass to register ChannelQosProviders

The default implementation of this method adds a ChannelQosProvider that calls getChannelFilter(ToaService, ToaServiceChannel) on this class.

Parameters:

containers - Objects implementing ChannelQosProvider should be added to this set.

getChannelQos

protected MessageChannel.Qos getChannelQos(ToaService service,
                                           ToaServiceChannel channel)

This method may be overridden by subclasses to specify the MessageChannel.Qos for the provided service channel.

The default implementation returns null which in the absense of .

This method will not be called unless addChannelQosProviders(Set) is called on this class. This is done by the DefaultManagedObjectLocator, but may not be called if the application defines its own ManagedObjectLocator.

Parameters:

service - The service

channel - The channel.

Returns:

The quality of service.

addChannelInitialKeyResolutionTableProviders

protected void addChannelInitialKeyResolutionTableProviders(Set<Object> containers)

This method may be overridden by subclasses to add additional objects that implement ChannelQosProvider.

This method is called by the DefaultManagedObjectLocator, if an application provides its own ManagedObjectLocator then it is up to that locator as to whether or not this method will be invoked.

This method is called by the application during the configuration phase allowing the application subclasses to register ChannelInitialKeyResolutionTableProviders

The default implementation of this method adds a ChannelQosProvider that calls getInitialChannelKeyResolutionTable(ToaService, ToaServiceChannel) on this class.

Parameters:

containers - Objects implementing ChannelInitialKeyResolutionTableProvider should be added to this set.

getInitialChannelKeyResolutionTable

protected Properties getInitialChannelKeyResolutionTable(ToaService service,
                                                         ToaServiceChannel channel)

This method may be overridden by subclasses to perform initial key resolution on a channel at the time it is configured which allows all or a portion of a channel's dynamic key parts to be determined statically at configuration time by returning a initial Key Resolution Table (KRT).

This method will not be called unless addChannelQosProviders(Set) is called on this class. This is done by the DefaultManagedObjectLocator, but may not be called if the application defines its own ManagedObjectLocator.

Example:

Given:

• A channel, channel1 with a configured key of: ORDERS/${Region}/${Product}
• An initial KRT returned by this method of: {"Region": "US", "HostName": MyPC}

With the above KRT, the channel would be intialized with a key of ORDERS/US/${Product}. The dynamic 'Region' portion of the key has become static while the 'Product' portion remains dynamic and eligible for substitution with a runtime KRT or from values reflected from a message reflector.

NOTE:
The returned key resolution table is not used for individual send calls, if the channel key still contains dynamic portions then dynamic key resolution can be done on a per send basis using either the message's message reflector or a key resolution table provide as a argument to the send call.

If more than one service share the same channel on the same bus, they will share the same channel key; at this time it is not possible to perform individual channel key resolution on a per service basis. In this sense the initial channel key resolution is global to a channel name. The serviceName is provided here as a hint to assist the application in locating a key resolution table for a channel.

Parameters:

service - The service name.

channel - The channel for which to perform key resolution

Returns:

A key resolution table to substitute some or all of the configured channel key.

getServiceDefinitionLocator

protected ServiceDefinitionLocator getServiceDefinitionLocator()

Subclasses may override this method to change the way service xmls are located.

The default implementation returns a new instance of DefaultServiceDefinitionLocator.

This is called prior to constructing the application's underlying AepEngine at this point the SrvAppLoader will have been injected via onAppLoaderInjected(SrvAppLoader) and the AepEngineDescriptor will have been injected via onEngineDescriptorInjected(AepEngineDescriptor) so they may be used to figure out information about the application's identity.

Returns:

The ServiceDefinitionLocator to use to load the application's services.

See Also:

DefaultServiceDefinitionLocator

getManagedObjectLocator

protected ManagedObjectLocator getManagedObjectLocator()

Subclasses may override this method to change the strategy for locating an application's managed objects.

The default implementation returns a new instance of DefaultManagedObjectLocator.

This is called prior to locating and parsing an application's service model and also prior to construction of the application's underlying AepEngine At this point the SrvAppLoader will have been injected via onAppLoaderInjected(SrvAppLoader) and the AepEngineDescriptor will have been injected via onEngineDescriptorInjected(AepEngineDescriptor) so they may be used to figure out information about the application's identity.

Returns:

The ManagedObjectLocator to use to load the application's services.

See Also:

DefaultManagedObjectLocator

getEngine

public final AepEngine getEngine()

Returns this application's AepEngine. The engine is injected just before the application is initialized, and this method will return null before that occurs.

TopicOrientedApplication subclasses should use the processing facilities provided by this class for most operations, and only utilize the underlying AepEngine for functionality not provided by TOA. In particular, all message sends should go through this application's MessageSender api and message injection should be done through the MessageInjector unless there is a compelling reason to bypass TOA.

Returns:

This application's AepEngine

getEngineClock

public final EngineClock getEngineClock()

Return an interface which may be used to get the AepEngine time.

The default implementation of EngineClock returned simply make a pass through call to the AepEngine.getEngineTime() unless the engine for this application has not yet been set in which case the returned clock will just return System.currentTimeMillis().

Returns:

The EngineClock.

getConfigurer

public final Configurer getConfigurer()

Returns this application's bootstrap configurer.

For applications launched from the talon server Main class this will return the external Configurer for the application. For an embedded Talon server constructed by user code this will return whatever object the application passed to the SrvController.setBootstrapConfigurer(Object).

The talon server injects the Configurer immediately after instantiating the TopicOrientedApplication.

Returns:

This application's bootstrap configurer.

getServiceModels

protected final Collection<ToaService> getServiceModels()

Returns the application's parsed service definitions.

An application's service definitions are parsed just after the application calls addHandlerContainers(Set). The returned collection must not be modified.

Returns:

The collection of parsed service models.

Throws:

IllegalStateException - if services have not yet been parsed.

getServiceModel

protected final ToaService getServiceModel(String fullServiceName)

Looks up a parsed service model by fully qualified name.

An application's service definitions are parsed just after the application calls addHandlerContainers(Set). The returned ToaService must not be modified.

Returns:

The service model or null if no model was parsed.

Throws:

IllegalStateException - if services have not yet been parsed.

getMessageSender

public final MessageSender getMessageSender()

Returns the MessageSender implementation which is this class.

This method is useful for dependency injection frameworks.

Note that the thread safety of the returned implementation is the same as that of using this class directly ... send calls are not thread safe and may only be called from an EventHandler, or in a non concurrent fashion by an unsolicited 'sender' thread if this is a purely producer application.

Returns:

This class.

sendMessage

public final void sendMessage(IRogMessage message)

Description copied from interface: MessageSender

Sends a message using the message's default channel. This method has the same semantics as AepEngine.sendMessage(MessageChannel, IRogMessage), with the message channel resolved based on this application's service definition for the message type and the provided message.

Specified by:

sendMessage in interface MessageSender

Parameters:

message - The message to send.

See Also:

AepEngine.sendMessage(MessageChannel, IRogMessage)

sendMessage

public final void sendMessage(IRogMessage message,
                              String topic)

Description copied from interface: MessageSender

Sends a message using the given topic as the channel key. This method has the same semantics as AepEngine.sendMessage(MessageChannel, IRogMessage, String, Properties), with the message channel resolved based on this application's service definition for the message type, the provided message, the provided topic as the channel key, and no key resolution table.

Specified by:

sendMessage in interface MessageSender

Parameters:

message - The message to send.

See Also:

AepEngine.sendMessage(MessageChannel, IRogMessage)

sendMessage

public final void sendMessage(IRogMessage message,
                              Properties keyResolutionTable)

Description copied from interface: MessageSender

Sends a message using the provided key resolution table. This method has the same semantics as AepEngine.sendMessage(MessageChannel, IRogMessage, Properties), with the message channel resolved based on this application's service definition for the message type, the provided message, key, and the provided message key.

Specified by:

sendMessage in interface MessageSender

Parameters:

message - The message to send.

See Also:

AepEngine.sendMessage(MessageChannel, IRogMessage)

sendMessage

public final void sendMessage(IRogMessage message,
                              XString topic)

Description copied from interface: MessageSender

Sends a message using the given topic as the channel key (zero garbage variant). This method has the same semantics as AepEngine.sendMessage(MessageChannel, IRogMessage, XString, MessageChannel.RawKeyResolutionTable), with the message channel resolved based on this application's service definition for the message type, the provided message, the provided topic as the channel key, and no key resolution table.

Specified by:

sendMessage in interface MessageSender

Parameters:

message - The message to send.

See Also:

AepEngine.sendMessage(MessageChannel, IRogMessage)

sendMessage

public final void sendMessage(IRogMessage message,
                              MessageChannel.RawKeyResolutionTable rawKeyResolutionTable)

Description copied from interface: MessageSender

Sends a message using the provide zero garbage key resolution table. This method has the same semantics as AepEngine.sendMessage(MessageChannel, IRogMessage, MessageChannel.RawKeyResolutionTable), with the message channel resolved based on this application's service definition for the message type, the provided message, and no key resolution table.

Specified by:

sendMessage in interface MessageSender

Parameters:

message - The message to send.

See Also:

AepEngine.sendMessage(MessageChannel, IRogMessage)

getMessageInjector

public final MessageInjector getMessageInjector()

Returns the MessageSender implementation which is this class.

This method is useful for dependency injection frameworks.

Note that the thread safety of the returned implementation is the same as that of using this class directly ... send calls are not thread safe and may only be called from an EventHandler, or in a non concurrent fashion by an unsolicited 'sender' thread if this is a purely producer application.

Returns:

This class.

injectMessage

public final void injectMessage(IRogMessage message)

Description copied from interface: MessageInjector

Enqueue a message into an application's AepEngine's event multiplexer.

This method is the same as MessageInjector.injectMessage(IRogMessage, boolean) with a value of false for nonBlocking.

Specified by:

injectMessage in interface MessageInjector

Parameters:

message - The message to enqueue.

injectMessage

public final void injectMessage(IRogMessage message,
                                boolean nonBlocking)

Description copied from interface: MessageInjector

Enqueue a message into an application's AepEngine's event multiplexer.

This method is the same as MessageInjector.injectMessage(IRogMessage, boolean) with a value of false for nonBlocking and a delay of 0.

Specified by:

injectMessage in interface MessageInjector

Parameters:

message - The message to enqueue.

injectMessage

public final void injectMessage(IRogMessage message,
                                boolean nonBlocking,
                                int delay)

Description copied from interface: MessageInjector

Enqueue a message into an application's AepEngine's event multiplexer.

This method enqueues a message into an engine's event multiplexer event loop and returns to the caller. The message is then dispatched subsequently using the normal message dispatch mechanisms.

Injection from an Event/Message Handler

Injection of messages from an event handler is not currently a safe operation from an HA standpoint and as such it is currently disallowed.

Delayed or Priority Injection

The value of the delay parameter is interpreted as follows:

• A value of 0 causes the message to be added to the end of the underlying engine's event multiplexer queue for immediate dispatch after already enqueued events.
• A positive value is interpreted in milliseconds and will cause the execution of the event to be delay no sooner than the delay period.
• A negative value is treated as a high priority dispatch and are added to the beginning of the engine's event multiplexer queue, a lower delay represents a higher priority dispatch.

Behavior when not in HA Active Role

The message will only be injected on Started engines operating in the Primary role. Calls to inject are ignored on backup instances as the expectation is that the injected message will be replicated from the primary. Calls made while an engine is replaying from a transaction log are similarly ignored as they would interfere with the stream being replayed. An application that injects messages from an external source may call AepEngine.waitForMessagingToStart() to avoid an injected message being discarded while an engine is transitioning to a started, primary role. It is important to note that message injection is thus effectively a BestEffor operation because injections of message that are in the event multiplexer queue at the time of failure will be lost

Message Pooling Considerations

This method transfers ownership of the message to the platform, the method caller must not modify the message subsequent to this call. The platform will call IRogNode.dispose() on the message once it has been dispatched, so an application must call MessageView.acquire() if it will hold on to a (read-only) reference to the message.

Blocking vs. Non Blocking Considerations

Care must be taken when considering whether to use using blocking or non blocking injection. If the injecting thread is injecting to a engine multiplexer that may itself block on a resource held by the thread trying to inject, is can cause a deadlock. Conversely, using non blocking dispatch can result in excessive memory growth, increased latency and fairness issues, so if the injecting thread is drawing events from an external source, blocking dispatch is generally the right choice.

Specified by:

injectMessage in interface MessageInjector

Parameters:

message - The IRogMessage to enqueue.

nonBlocking - Indicates whether the multiplexing should be a non-blocking action or not. If blocking, then the calling thread will block if the main multiplexer queue is full and wait until space is available. If non-blocking, then the method will not wait but rather enque the message in a multiplexer feeder queue and return.

delay - The delay in milliseconds at which the message should be injected.

onEngineDescriptorInjected

protected void onEngineDescriptorInjected(AepEngineDescriptor engineDescriptor)
                                   throws Exception

Called when the AepEngineDescriptor is injected into the application.

This is called prior to creating the engine allowing applications to further customize the AepEngine prior to its construction.

Because TopicOrientedApplication already provides an AppInjectionPoint for AepEngineDescriptor, this method provides subclasses with a means to listen for AepEngineDescriptor injection.

Parameters:

engineDescriptor - the AepEngineDescriptor

Throws:

Exception - An application throwing an exception from this method will cause loading of the application to fail.

onConfigured

protected void onConfigured()
                     throws Exception

Called after configuration of messaging and services has been successfully completed.

At this point the AepEngine is still not available, but ToaServices and the the Configurer are.

Applications may override this method to examine either of these objects.

Throws:

Exception - An application throwing an exception from this method will cause loading of the application to fail.

onEngineInjected

protected void onEngineInjected(AepEngine engine)
                         throws Exception

Called when the AepEngine is injected into the application.

This is called after the AepEngine has been created, but before it is started.

Because TopicOrientedApplication already provides an AppInjectionPoint for AepEngine, this method provides subclasses with a means to listen for AepEngine injection.

Parameters:

engine - the AepEngine

Throws:

Exception - An application throwing an exception from this method will cause loading of the application to fail.

addPredispatchMessageHandler

public final void addPredispatchMessageHandler(IAepPredispatchMessageHandler handler)

Adds a message handler to be invoked before 'normal' message handler dispatch.

TopicOrientedApplication messages are dispatched by the underlying AepEngine to @EventHandler annotated methods exposed by the application. This method, allows an applications to add generic pre dispatch handlers to do pre processing before message dispatch to the 'normal' handlers.

If multiple pre dispatch message handlers are registered and one of them throws an exception, remaining handlers will not be called and the engine will dispatch an AepApplicationExceptionEvent.

Handler addition is not permitted after the call to onEngineInjected(AepEngine) and will thrown an IllegalStateException.

Throws:

IllegalStateException - if this method is called after onEngineInjected(AepEngine).

addPostdispatchMessageHandler

public final void addPostdispatchMessageHandler(IAepPostdispatchMessageHandler handler)

Adds a message handler to be invoked after 'normal' message handler dispatch.

TopicOrientedApplication messages are dispatched by the underlying AepEngine to @EventHandler annotated methods exposed by the application. This method, allows an applications to add generic post dispatch handlers to do post processing after message dispatch to the 'normal' handlers.

If a message handler throws an exception prior to the IAepPostdispatchMessageHandler being invoked, then the IAepPostdispatchMessageHandler will not be invoked, and the engine will instead dispatch an AepApplicationExceptionEvent, so an IAepPostdispatchMessageHandler may want to handle this event as well if it needs to be notified in the event of an unsuccessful dispatch.

Handler addition is not permitted after the call to onEngineInjected(AepEngine) and will thrown an IllegalStateException.

Throws:

IllegalStateException - if this method is called after onEngineInjected(AepEngine).

onAppLoaderInjected

protected void onAppLoaderInjected(SrvAppLoader loader)
                            throws Exception

Called when the SrvAppLoader is injected into the application.

This is called just after application class is constructed providing the means for an application to examine the configuration of the server that is loading it.

Because TopicOrientedApplication already provides an AppInjectionPoint for SrvAppLoader, this method provides subclasses with a means to listen for SrvAppLoader injection.

Parameters:

loader - the SrvAppLoader

Throws:

Exception - An application throwing an exception from this method will cause loading of the application to fail.

onAppInitialized

protected void onAppInitialized()
                         throws Exception

This is called after the application's AepEngine has been successfully created and injected into the application. Subclasses may override this method to do any final initialization prior to the application being started.

Throws:

Exception - An application throwing an exception from this method will cause loading of the application to fail.

onAppFinalized

protected void onAppFinalized()
                       throws Exception

This is called after the application's AepEngine has been successfully created and injected into the application. Subclasses may override this method to do any final initialization prior to the application being started.

Throws:

Exception - An application throwing an exception from this method will cause the app finalization to terminate with an error.