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