org.apache.hedwig.client.api

Interface Subscriber

public interface Subscriber

Interface to define the client Subscriber API.

Method Summary

Methods

Modifier and Type	Method and Description
void	addSubscriptionListener(SubscriptionListener listener) Register a subscription listener which get notified about subscription event indicating a state of a subscription that subscribed disable resubscribe logic.
void	asyncCloseSubscription(com.google.protobuf.ByteString topic, com.google.protobuf.ByteString subscriberId, Callback<Void> callback, Object context) Closes all of the client side cached data for this subscription without actually sending an unsubscribe request to the server.
void	asyncSubscribe(com.google.protobuf.ByteString topic, com.google.protobuf.ByteString subscriberId, PubSubProtocol.SubscribeRequest.CreateOrAttach mode, Callback<Void> callback, Object context) Deprecated. As of BookKeeper 4.2.0, replaced by asyncSubscribe(com.google.protobuf.ByteString, com.google.protobuf.ByteString, PubSubProtocol.SubscriptionOptions,Callback,Object)
void	asyncSubscribe(com.google.protobuf.ByteString topic, com.google.protobuf.ByteString subscriberId, PubSubProtocol.SubscriptionOptions options, Callback<Void> callback, Object context) Subscribe to the given topic asynchronously for the inputted subscriberId.
void	asyncUnsubscribe(com.google.protobuf.ByteString topic, com.google.protobuf.ByteString subscriberId, Callback<Void> callback, Object context) Unsubscribe from a topic asynchronously that the subscriberId user has previously subscribed to.
void	closeSubscription(com.google.protobuf.ByteString topic, com.google.protobuf.ByteString subscriberId) Closes all of the client side cached data for this subscription without actually sending an unsubscribe request to the server.
void	consume(com.google.protobuf.ByteString topic, com.google.protobuf.ByteString subscriberId, PubSubProtocol.MessageSeqId messageSeqId) Manually send a consume message to the server for the given inputs.
List<com.google.protobuf.ByteString>	getSubscriptionList(com.google.protobuf.ByteString subscriberId) Fills the input List with the subscriptions this subscriberId client is subscribed to.
boolean	hasSubscription(com.google.protobuf.ByteString topic, com.google.protobuf.ByteString subscriberId) Checks if the subscriberId client is currently subscribed to the given topic.
void	removeSubscriptionListener(SubscriptionListener listener) Unregister a subscription listener.
void	startDelivery(com.google.protobuf.ByteString topic, com.google.protobuf.ByteString subscriberId, MessageHandler messageHandler) Begin delivery of messages from the server to us for this topic and subscriberId.
void	startDeliveryWithFilter(com.google.protobuf.ByteString topic, com.google.protobuf.ByteString subscriberId, MessageHandler messageHandler, org.apache.hedwig.filter.ClientMessageFilter messageFilter) Begin delivery of messages from the server to us for this topic and subscriberId.
void	stopDelivery(com.google.protobuf.ByteString topic, com.google.protobuf.ByteString subscriberId) Stop delivery of messages for this topic and subscriberId.
void	subscribe(com.google.protobuf.ByteString topic, com.google.protobuf.ByteString subscriberId, PubSubProtocol.SubscribeRequest.CreateOrAttach mode) Deprecated. As of BookKeeper 4.2.0, replaced by subscribe(com.google.protobuf.ByteString, com.google.protobuf.ByteString, PubSubProtocol.SubscriptionOptions)
void	subscribe(com.google.protobuf.ByteString topic, com.google.protobuf.ByteString subscriberId, PubSubProtocol.SubscriptionOptions options) Subscribe to the given topic for the inputted subscriberId.
void	unsubscribe(com.google.protobuf.ByteString topic, com.google.protobuf.ByteString subscriberId) Unsubscribe from a topic that the subscriberId user has previously subscribed to.

Method Detail

subscribe

@Deprecated
void subscribe(com.google.protobuf.ByteString topic,
                        com.google.protobuf.ByteString subscriberId,
                        PubSubProtocol.SubscribeRequest.CreateOrAttach mode)
               throws PubSubException.CouldNotConnectException,
                      PubSubException.ClientAlreadySubscribedException,
                      PubSubException.ServiceDownException,
                      org.apache.hedwig.client.exceptions.InvalidSubscriberIdException

Deprecated. As of BookKeeper 4.2.0, replaced by subscribe(com.google.protobuf.ByteString, com.google.protobuf.ByteString, PubSubProtocol.SubscriptionOptions)

Subscribe to the given topic for the inputted subscriberId.

Parameters:

topic - Topic name of the subscription

subscriberId - ID of the subscriber

mode - Whether to prohibit, tolerate, or require an existing subscription.

Throws:

PubSubException.CouldNotConnectException - If we are not able to connect to the server host

PubSubException.ClientAlreadySubscribedException - If client is already subscribed to the topic

PubSubException.ServiceDownException - If unable to subscribe to topic

org.apache.hedwig.client.exceptions.InvalidSubscriberIdException - If the subscriberId is not valid. We may want to set aside certain formats of subscriberId's for different purposes. e.g. local vs. hub subscriber

asyncSubscribe

@Deprecated
void asyncSubscribe(com.google.protobuf.ByteString topic,
                             com.google.protobuf.ByteString subscriberId,
                             PubSubProtocol.SubscribeRequest.CreateOrAttach mode,
                             Callback<Void> callback,
                             Object context)

Deprecated. As of BookKeeper 4.2.0, replaced by asyncSubscribe(com.google.protobuf.ByteString, com.google.protobuf.ByteString, PubSubProtocol.SubscriptionOptions,Callback,Object)

Subscribe to the given topic asynchronously for the inputted subscriberId disregarding if the topic has been created yet or not.

Parameters:

topic - Topic name of the subscription

subscriberId - ID of the subscriber

mode - Whether to prohibit, tolerate, or require an existing subscription.

callback - Callback to invoke when the subscribe request to the server has actually gone through. This will have to deal with error conditions on the async subscribe request.

context - Calling context that the Callback needs since this is done asynchronously.

subscribe

void subscribe(com.google.protobuf.ByteString topic,
             com.google.protobuf.ByteString subscriberId,
             PubSubProtocol.SubscriptionOptions options)
               throws PubSubException.CouldNotConnectException,
                      PubSubException.ClientAlreadySubscribedException,
                      PubSubException.ServiceDownException,
                      org.apache.hedwig.client.exceptions.InvalidSubscriberIdException

Subscribe to the given topic for the inputted subscriberId.

Parameters:

topic - Topic name of the subscription

subscriberId - ID of the subscriber

options - Options to pass to the subscription. See asyncSubscribe for details on how to set options.

Throws:

PubSubException.CouldNotConnectException - If we are not able to connect to the server host

PubSubException.ClientAlreadySubscribedException - If client is already subscribed to the topic

PubSubException.ServiceDownException - If unable to subscribe to topic

org.apache.hedwig.client.exceptions.InvalidSubscriberIdException - If the subscriberId is not valid. We may want to set aside certain formats of subscriberId's for different purposes. e.g. local vs. hub subscriber

asyncSubscribe

void asyncSubscribe(com.google.protobuf.ByteString topic,
                  com.google.protobuf.ByteString subscriberId,
                  PubSubProtocol.SubscriptionOptions options,
                  Callback<Void> callback,
                  Object context)

Subscribe to the given topic asynchronously for the inputted subscriberId.

SubscriptionOptions contains parameters for how the hub should make the subscription. The options includes createorattach mode, message bound and message filter.

The createorattach mode defines whether the subscription should create a new subscription, or just attach to a preexisting subscription. If it tries to create the subscription, and the subscription already exists, then an error will occur.

The message bound defines the maximum number of undelivered messages which will be stored for the subscription. This can be used to ensure that unused subscriptions do not grow in an unbounded fashion. By default, the message bound is infinite, i.e. all undelivered messages will be stored for the subscription. Note that if one subscription on a topic has a infinite message bound, the message bound for all other subscriptions on that topic will effectively be infinite as the messages have to be stored for the first subscription in any case.

The message filter defines a ServerMessageFilter run in hub server to filter messages delivered to the subscription. The server message filter should be placed in the classpath of hub server before using it.

All these subscription options would be stored as SubscriptionPreferences in metadata manager. The next time subscriber attached with difference options, the new options would overwrite the old options. Usage is as follows:

 // create a new subscription with a message bound of 5
 SubscriptionOptions options = SubscriptionOptions.newBuilder()
     .setCreateOrAttach(CreateOrAttach.CREATE).setMessageBound(5).build();
 client.getSubscriber().asyncSubscribe(ByteString.copyFromUtf8("myTopic"),
                                       ByteString.copyFromUtf8("mySubscription"),
                                       options,
                                       myCallback,
                                       myContext);
 
 

Parameters:

topic - Topic name of the subscription

subscriberId - ID of the subscriber

options - Options to pass to the subscription.

callback - Callback to invoke when the subscribe request to the server has actually gone through. This will have to deal with error conditions on the async subscribe request.

context - Calling context that the Callback needs since this is done asynchronously.

unsubscribe

void unsubscribe(com.google.protobuf.ByteString topic,
               com.google.protobuf.ByteString subscriberId)
                 throws PubSubException.CouldNotConnectException,
                        PubSubException.ClientNotSubscribedException,
                        PubSubException.ServiceDownException,
                        org.apache.hedwig.client.exceptions.InvalidSubscriberIdException

Unsubscribe from a topic that the subscriberId user has previously subscribed to.

Parameters:

topic - Topic name of the subscription

subscriberId - ID of the subscriber

Throws:

PubSubException.CouldNotConnectException - If we are not able to connect to the server host

PubSubException.ClientNotSubscribedException - If the client is not currently subscribed to the topic

PubSubException.ServiceDownException - If the server was down and unable to complete the request

org.apache.hedwig.client.exceptions.InvalidSubscriberIdException - If the subscriberId is not valid. We may want to set aside certain formats of subscriberId's for different purposes. e.g. local vs. hub subscriber

asyncUnsubscribe

void asyncUnsubscribe(com.google.protobuf.ByteString topic,
                    com.google.protobuf.ByteString subscriberId,
                    Callback<Void> callback,
                    Object context)

Unsubscribe from a topic asynchronously that the subscriberId user has previously subscribed to.

Parameters:

topic - Topic name of the subscription

subscriberId - ID of the subscriber

callback - Callback to invoke when the unsubscribe request to the server has actually gone through. This will have to deal with error conditions on the async unsubscribe request.

context - Calling context that the Callback needs since this is done asynchronously.

consume

void consume(com.google.protobuf.ByteString topic,
           com.google.protobuf.ByteString subscriberId,
           PubSubProtocol.MessageSeqId messageSeqId)
             throws PubSubException.ClientNotSubscribedException

Manually send a consume message to the server for the given inputs.

Parameters:

topic - Topic name of the subscription

subscriberId - ID of the subscriber

messageSeqId - Message Sequence ID for the latest message that the client app has successfully consumed. All messages up to that point will also be considered as consumed.

Throws:

PubSubException.ClientNotSubscribedException - If the client is not currently subscribed to the topic based on the client's local state.

hasSubscription

boolean hasSubscription(com.google.protobuf.ByteString topic,
                      com.google.protobuf.ByteString subscriberId)
                        throws PubSubException.CouldNotConnectException,
                               PubSubException.ServiceDownException

Checks if the subscriberId client is currently subscribed to the given topic.

Parameters:

topic - Topic name of the subscription.

subscriberId - ID of the subscriber

Returns:

Boolean indicating if the client has a subscription or not.

Throws:

PubSubException.CouldNotConnectException - If we are not able to connect to the server host

PubSubException.ServiceDownException - If there is an error checking the server if the client has a subscription

getSubscriptionList

List<com.google.protobuf.ByteString> getSubscriptionList(com.google.protobuf.ByteString subscriberId)
                                                         throws PubSubException.CouldNotConnectException,
                                                                PubSubException.ServiceDownException

Fills the input List with the subscriptions this subscriberId client is subscribed to.

Parameters:

subscriberId - ID of the subscriber

Returns:

List filled with subscription name (topic) strings.

Throws:

PubSubException.CouldNotConnectException - If we are not able to connect to the server host

PubSubException.ServiceDownException - If there is an error retrieving the list of topics

startDelivery

void startDelivery(com.google.protobuf.ByteString topic,
                 com.google.protobuf.ByteString subscriberId,
                 MessageHandler messageHandler)
                   throws PubSubException.ClientNotSubscribedException,
                          org.apache.hedwig.client.exceptions.AlreadyStartDeliveryException

Begin delivery of messages from the server to us for this topic and subscriberId.

Parameters:

topic - Topic name of the subscription

subscriberId - ID of the subscriber

messageHandler - Message Handler that will consume the subscribed messages

Throws:

PubSubException.ClientNotSubscribedException - If the client is not currently subscribed to the topic

org.apache.hedwig.client.exceptions.AlreadyStartDeliveryException - If someone started delivery a message handler before stopping existed one.

startDeliveryWithFilter

void startDeliveryWithFilter(com.google.protobuf.ByteString topic,
                           com.google.protobuf.ByteString subscriberId,
                           MessageHandler messageHandler,
                           org.apache.hedwig.filter.ClientMessageFilter messageFilter)
                             throws PubSubException.ClientNotSubscribedException,
                                    org.apache.hedwig.client.exceptions.AlreadyStartDeliveryException

Begin delivery of messages from the server to us for this topic and subscriberId. Only the messages passed messageFilter could be delivered to messageHandler.

Parameters:

topic - Topic name of the subscription

subscriberId - ID of the subscriber

messageHandler - Message Handler that will consume the subscribed messages

Throws:

PubSubException.ClientNotSubscribedException - If the client is not currently subscribed to the topic

org.apache.hedwig.client.exceptions.AlreadyStartDeliveryException - If someone started delivery a message handler before stopping existed one.

NullPointerException - If either messageHandler or messageFilter is null.

stopDelivery

void stopDelivery(com.google.protobuf.ByteString topic,
                com.google.protobuf.ByteString subscriberId)
                  throws PubSubException.ClientNotSubscribedException

Stop delivery of messages for this topic and subscriberId.

Parameters:

topic - Topic name of the subscription

subscriberId - ID of the subscriber

Throws:

PubSubException.ClientNotSubscribedException - If the client is not currently subscribed to the topic

closeSubscription

void closeSubscription(com.google.protobuf.ByteString topic,
                     com.google.protobuf.ByteString subscriberId)
                       throws PubSubException.ServiceDownException

Closes all of the client side cached data for this subscription without actually sending an unsubscribe request to the server. This will close the subscribe channel synchronously (if it exists) for the topic.

Parameters:

topic - Topic name of the subscription

subscriberId - ID of the subscriber

Throws:

PubSubException.ServiceDownException - If the subscribe channel was not able to be closed successfully

asyncCloseSubscription

void asyncCloseSubscription(com.google.protobuf.ByteString topic,
                          com.google.protobuf.ByteString subscriberId,
                          Callback<Void> callback,
                          Object context)

Closes all of the client side cached data for this subscription without actually sending an unsubscribe request to the server. This will close the subscribe channel asynchronously (if it exists) for the topic.

Parameters:

topic - Topic name of the subscription

subscriberId - ID of the subscriber

callback - Callback to invoke when the subscribe channel has been closed.

context - Calling context that the Callback needs since this is done asynchronously.

addSubscriptionListener

void addSubscriptionListener(SubscriptionListener listener)

Register a subscription listener which get notified about subscription event indicating a state of a subscription that subscribed disable resubscribe logic.

Parameters:

listener - Subscription Listener

removeSubscriptionListener

void removeSubscriptionListener(SubscriptionListener listener)

Unregister a subscription listener.

Parameters:

listener - Subscription Listener