co.cask.cdap.messaging

Interface MessagingService

All Known Implementing Classes:

ClientMessagingService, CoreMessagingService, LeaderElectionMessagingService

public interface MessagingService

Main interface to interact with the transactional messaging system.

See Also:

Design documentation

Method Summary

Modifier and Type	Method and Description
void	createTopic(TopicMetadata topicMetadata) Creates a topic with the given metadata.
void	deleteTopic(co.cask.cdap.proto.id.TopicId topicId) Deletes a topic
TopicMetadata	getTopic(co.cask.cdap.proto.id.TopicId topicId) Returns the metadata of the given topic.
List<co.cask.cdap.proto.id.TopicId>	listTopics(co.cask.cdap.proto.id.NamespaceId namespaceId) Returns the list of topics available under the given namespace.
MessageFetcher	prepareFetch(co.cask.cdap.proto.id.TopicId topicId) Prepares to fetch messages from the given topic.
RollbackDetail	publish(StoreRequest request) Publishes a list of messages to the messaging system.
void	rollback(co.cask.cdap.proto.id.TopicId topicId, RollbackDetail rollbackDetail) Rollbacks messages published to the given topic with the given transaction.
void	storePayload(StoreRequest request) Stores a list of messages to the messaging system.
void	updateTopic(TopicMetadata topicMetadata) Updates the metadata of a topic.

Method Detail

createTopic

void createTopic(TopicMetadata topicMetadata)
          throws co.cask.cdap.api.messaging.TopicAlreadyExistsException,
                 IOException

Creates a topic with the given metadata.

Parameters:

topicMetadata - topic to be created

Throws:

co.cask.cdap.api.messaging.TopicAlreadyExistsException - if the topic to be created already exist

IOException - if failed to create the topic

ServiceUnavailableException - if the messaging service is not available

updateTopic

void updateTopic(TopicMetadata topicMetadata)
          throws co.cask.cdap.api.messaging.TopicNotFoundException,
                 IOException

Updates the metadata of a topic.

Parameters:

topicMetadata - the topic metadata to be updated

Throws:

co.cask.cdap.api.messaging.TopicNotFoundException - if the topic doesn't exist

IOException - if failed to update the topic metadata

ServiceUnavailableException - if the messaging service is not available

deleteTopic

void deleteTopic(co.cask.cdap.proto.id.TopicId topicId)
          throws co.cask.cdap.api.messaging.TopicNotFoundException,
                 IOException

Deletes a topic

Parameters:

topicId - the topic to be deleted

Throws:

co.cask.cdap.api.messaging.TopicNotFoundException - if the topic doesn't exist

IOException - if failed to delete the topic

ServiceUnavailableException - if the messaging service is not available

getTopic

TopicMetadata getTopic(co.cask.cdap.proto.id.TopicId topicId)
                throws co.cask.cdap.api.messaging.TopicNotFoundException,
                       IOException

Returns the metadata of the given topic.

Parameters:

topicId - message topic

Returns:

the TopicMetadata of the given topic.

Throws:

co.cask.cdap.api.messaging.TopicNotFoundException - if the topic doesn't exist

IOException - if failed to retrieve topic metadata.

ServiceUnavailableException - if the messaging service is not available

listTopics

List<co.cask.cdap.proto.id.TopicId> listTopics(co.cask.cdap.proto.id.NamespaceId namespaceId)
                                        throws IOException

Returns the list of topics available under the given namespace.

Parameters:

namespaceId - the namespace to list topics under it

Returns:

a List of TopicId.

Throws:

IOException - if failed to retrieve topics.

ServiceUnavailableException - if the messaging service is not available

prepareFetch

MessageFetcher prepareFetch(co.cask.cdap.proto.id.TopicId topicId)
                     throws co.cask.cdap.api.messaging.TopicNotFoundException,
                            IOException

Prepares to fetch messages from the given topic.

Parameters:

topicId - the topic to fetch message from

Returns:

a MessageFetcher for setting up parameters for fetching messages from the messaging system

Throws:

co.cask.cdap.api.messaging.TopicNotFoundException - if the topic doesn't exist

IOException - if failed to fetch messages

ServiceUnavailableException - if the messaging service is not available

publish

@Nullable
RollbackDetail publish(StoreRequest request)
                          throws co.cask.cdap.api.messaging.TopicNotFoundException,
                                 IOException

Publishes a list of messages to the messaging system.

Parameters:

request - the StoreRequest containing messages to be published

Returns:

if the store request is transactional, then returns a RollbackDetail containing information for rollback; otherwise null will be returned.

Throws:

co.cask.cdap.api.messaging.TopicNotFoundException - if the topic doesn't exist

IOException - if failed to publish messages

ServiceUnavailableException - if the messaging service is not available

storePayload

void storePayload(StoreRequest request)
           throws co.cask.cdap.api.messaging.TopicNotFoundException,
                  IOException

Stores a list of messages to the messaging system. It is for long / distributed transactional publishing use case.

Parameters:

request - the StoreRequest containing messages to be stored

Throws:

co.cask.cdap.api.messaging.TopicNotFoundException - if the topic doesn't exist

IOException - if failed to store messages

ServiceUnavailableException - if the messaging service is not available

rollback

void rollback(co.cask.cdap.proto.id.TopicId topicId,
              RollbackDetail rollbackDetail)
       throws co.cask.cdap.api.messaging.TopicNotFoundException,
              IOException

Rollbacks messages published to the given topic with the given transaction.

Parameters:

topicId - the topic where the messages were published under

rollbackDetail - the RollbackDetail as returned by the publish(StoreRequest) call, which contains information needed for the rollback

Throws:

co.cask.cdap.api.messaging.TopicNotFoundException - if the topic doesn't exist

IOException - if failed to rollback changes

ServiceUnavailableException - if the messaging service is not available