com.neeve.toa
Interface MessageInjector

All Known Implementing Classes:

TopicOrientedApplication

public interface MessageInjector

Defines the interface for injecting messages into a Topic Oriented Applications.

Injection of a message into a TopicOrientedApplication directly enqueues the message for processing by the underlying AepEngine's event multiplexer similar to how a message received from a message bus would be injected into the engine.

Threading

See Also:

AepEngine.multiplexMessage(IRogMessage), AepEngine.multiplexMessage(IRogMessage, boolean), AepEngine, TopicOrientedApplication

Threading:

This method is safe for concurrent access by multiple threads.

Method Summary

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.

Method Detail

injectMessage

void injectMessage(IRogMessage message)

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

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

Parameters:

message - The message to enqueue.

injectMessage

void injectMessage(IRogMessage message,
                   boolean nonBlocking)

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

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

Parameters:

message - The message to enqueue.

injectMessage

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

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.

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.

Threading:

This method is safe for concurrent access by multiple threads.