org.projectodd.stilts.stomplet
Interface Stomplet

All Known Subinterfaces:

AcknowledgeableStomplet

All Known Implementing Classes:

AbstractStomplet, DefaultStomplet, SimpleQueueStomplet, SimpleSubscribableStomplet, SimpleTopicStomplet

public interface Stomplet

Defines methods that all Stomplets must implement.

A Stomplet is a small Java class that performs two functions related to asynchronous message processing:

Handle requests from clients to subscribe and unsubscribe from matching destinations

Receive messages sent to the destination from clients, and handle dispatching outbound messages to subscribers.

A single Stomplet may be configured to services multiple destinations based upon routing rules.

Author:

Bob McWhirter

See Also:

http://stilts.projectodd.org/stomplet/

Method Summary

void	destroy() Clean up any resources allocated by the stomplet before removing it from the container.
void	initialize(StompletConfig config) Initialize the Stomplet in its container environment
void	onMessage(StompMessage message) Handle a message sent to a destination matched by this stomplet.
void	onSubscribe(Subscriber subscriber) Handle a subscription request.
void	onUnsubscribe(Subscriber subscriber) Handle the cancellation of a subscription.

Method Detail

initialize

void initialize(StompletConfig config)
                throws StompException

Initialize the Stomplet in its container environment

Parameters:

config - The configuration for the stomplet.

Throws:

StompException - If an error occurs during initialization.

destroy

void destroy()
             throws StompException

Clean up any resources allocated by the stomplet before removing it from the container.

Throws:

StompException - If an error occurs during destruction.

onMessage

void onMessage(StompMessage message)
               throws StompException

Handle a message sent to a destination matched by this stomplet.

In the event the stomplet is servicing multiple destinations, the stomplet may need to inspect the StompMessage for details as to how to handle the incoming message.

If named-segments are present in the applicable routing rule, each named segment is added to the message's header values, prefixed with stomplet..

For instance, the following routing rule:

 ROUTE /queues/:queue_name com.mycorp.MyStomplet
 

Would result in all inbound messages with matching destinations to have a header named stomplet.queue_name added to it, with the value being the matching portion of the destination.

Parameters:

message - The inbound message.

Throws:

StompException - If an error occurs while processing the message.

onSubscribe

void onSubscribe(Subscriber subscriber)
                 throws StompException

Handle a subscription request.

For subscription requests matching destinations mapped to this stomplet, the onSubscribe(Subscriber) method will be invoked with a Subscriber object. If the stomplet chooses to allow the subscription, it may route further messages to the Subscriber to satisfy the subscription.

If it chooses to deny the subscription request (for any reason), throwing a StompException is appropriate.

Parameters:

subscriber - The live subscriber making the request.

Throws:

StompException - If an error occurs processing the subscription request.

onUnsubscribe

void onUnsubscribe(Subscriber subscriber)
                   throws StompException

Handle the cancellation of a subscription.

When a client explicitly cancels a subscription, or disconnects, the stomplet is notified through onUnsubscribe(Subscriber), having the same Subscriber instance passed to it.

Parameters:

subscriber - The subscriber cancelling the subscription.

Throws:

StompException - If an error occurs processing the subscription cancellation request.