com.hp.util.dcord

Interface PublishSubscribeService

public interface PublishSubscribeService

Publish–subscribe messaging service where senders of messages, called publishers, do not program the messages to be sent directly to specific receivers, called subscribers. Instead, published messages are characterized into classes, without knowledge of what, if any, subscribers there may be. Similarly, subscribers express interest in one or more classes, and only receive messages that are of interest, without knowledge of what, if any, publishers there are.

Distribution mechanism for publishing messages that are delivered to multiple subscribers which is also known as publish/subscribe messaging model. Publish and subscriptions are cluster-wide. When a member subscribes for an event type, it is actually registering for messages published by any member in the cluster, including the new members joined after you added the listener. Messages are ordered, meaning, listeners(subscribers) will process the messages in the order they are actually published. If cluster member M publishes messages m1, m2, m3...mn of type T, then all of the subscribers of type T will receive and process m1, m2, m3...mn in order. The user shouldn't keep the thread busy and preferably dispatch it via an Executor.

NOTE: Subscribers will start receiving messages from the point they subscribe and message delivery is not guaranteed (events can get lost because of network issues).

Author:

Mark Mozolewski, Vamsi Devaki, Nachiket Abhyankar, Carlos Villareal, Fabiel Zuniga

Method Summary

Methods

Modifier and Type	Method and Description
void	disableGlobalOrdering(Class<?> messageType) Disables global ordering for the given message type.
void	enableGlobalOrdering(Class<?> messageType) Enables global ordering for the given messages type.
<M> void	publish(M message) Publishes a message.
<M> void	publish(M message, Class<? super M> messageType) Publishes a message as the type messageType.
<M> void	subscribe(Subscriber<M> subscriber, Class<M> messageType) Subscribes a listener for the given message type.
void	unsubscribe(Subscriber<?> subscriber) Un-subscribes a listener from the given message type.

Method Detail

subscribe

<M> void subscribe(Subscriber<M> subscriber,
                 Class<M> messageType)

Subscribes a listener for the given message type.

Parameters:

subscriber - subscriber

messageType - message type

unsubscribe

void unsubscribe(Subscriber<?> subscriber)

Un-subscribes a listener from the given message type.

Parameters:

subscriber - subscriber

publish

<M> void publish(M message)

Publishes a message.

This method is equivalent to publish(Object, Class) where message.getClass() is used as the message type.

Parameters:

message - message

publish

<M> void publish(M message,
               Class<? super M> messageType)

Publishes a message as the type messageType.

This method is useful when the message type extends or implements a class that is also a valid message to publish.

Example using interfaces:

 
 public interface Message {
     ...
 }
 
 public class ConcreteMessage implements Message {
     ...
 }
 
 public class MessageSubscriber implements Subscriber<Message> {
     ...
 }
 
 publishSubscribeService.register(new MessageSubscriber(), Message.class);
 publishSubscribeService.publish(new ConcreteMessage(), Message.class);
 
 

Example using inheritance:

 
 public class MessageA {
     ...
 }
 
 public class MessageB extends MessageA {
     ...
 }
 
 public class MessageASubscriber implements Subscriber<MessageA> {
     ...
 }
 
 public class MessageBSubscriber implements Subscriber<MessageB> {
     ...
 }
 
 publishSubscribeService.register(new MessageASubscriber(), MessageA.class);
 publishSubscribeService.register(new MessageBSubscriber(), MessageB.class);
 
 Message messageA = new MessageA(...);
 publishSubscribeService.publish(messageA);
 
 Message messageB = new MessageB(...);
 publishSubscribeService.publish(messageB); // MessageASubscriber won't receive this message        
 publishSubscribeService.publish(messageB, MessageA.class); // MessageBSubscriber won't receive this message
 
 

Parameters:

message - message

messageType - message type

enableGlobalOrdering

void enableGlobalOrdering(Class<?> messageType)

Enables global ordering for the given messages type. By default global ordering is disabled, thus just call this method if enabling is desired.

With global ordering enabled, all receivers will receive all messages from all sources with the same order. If global order is disabled two different receivers could receive messages from source A and B in different orders (Note that messages from A will be ordered and messages from B will be ordered). Example:

 Let A and B be message publishers (Sources).
 Let R and W be message subscribers (Receivers).
 Assume A sends messages a1 a2 a3 in that order.
 Assume B sends messages b1 b2 b3 in that order.
 With or without global ordering the following holds:
 - a1 arrives before a2
 - a2 arrives before a3
 - b1 arrives before b2
 - b2 arrives before b3
 With global ordering
 - Let a1 b1 a2 a3 b2 b3 be the sequence of messages received by R
 - Then W receives messages in the same order
 Without global ordering
 - Let a1 b1 a2 a3 b2 b3 be the sequence of messages received by R
 - Then W may (or may not) receives messages in the same order.
 

Global ordering degradates performance.

Parameters:

messageType - messages type to enable global ordering for

disableGlobalOrdering

void disableGlobalOrdering(Class<?> messageType)

Disables global ordering for the given message type. See enableGlobalOrdering(Class) for details.

Parameters:

messageType - messages type to enable global ordering for