com.netflix.astyanax.recipes.queue.MessageQueue Maven / Gradle / Ivy
/**
* Copyright 2013 Netflix, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.netflix.astyanax.recipes.queue;
import java.util.Collection;
import java.util.List;
import java.util.Map;
/**
* Base interface for a distributed message queue.
*
* Common use pattern
*
* MessageQueue queue = ...;
* List messages = queue.readMessages(10);
* for (Message message : messages) {
* try {
* // Do something with this message
* }
* finally {
* queue.ackMessage(message);
* }
* }
*
* @author elandau
*
*/
public interface MessageQueue {
/**
* Return the number of messages in the queue. This is an estimate.
* This is an expensive operation and should be used sparingly.
* @return Number of messages, including messages currently being processed
*/
long getMessageCount() throws MessageQueueException;
/**
* Clear all messages in the queue
* @throws MessageQueueException
*/
void clearMessages() throws MessageQueueException;
/**
* Create the underlying storage
* @throws MessageQueueExcewption
*/
void createStorage() throws MessageQueueException;
/**
* Destroy the storage associated with this column family
* @throws MessageQueueException
*/
void dropStorage() throws MessageQueueException;
/**
* Create any metadata in the storage necessary for the queue
* @throws MessageQueueException
*/
void createQueue() throws MessageQueueException;
/**
* Deletes all the rows for this queue. This will not
* delete any 'key' columns'
*
* @throws MessageQueueException
*/
void deleteQueue() throws MessageQueueException;
/**
* Read a specific message from the queue. The message isn't modified or removed from the queue.
*
* @param messageId Message id returned from MessageProducer.sendMessage
* @return
* @throws MessageQueueException
*/
Message peekMessage(String messageId) throws MessageQueueException;
/**
* Peek into messages from the queue. The queue state is not altered by this operation.
* @param itemsToPeek
* @return
* @throws MessageQueueException
*/
List peekMessages(int itemsToPeek) throws MessageQueueException;
/**
* Read a specific message from the queue. The message isn't modified or removed from the queue.
* This operation will require a lookup of key to messageId
*
* @param message Message id returned from MessageProducer.sendMessage
* @return
* @throws MessageQueueException
*/
Message peekMessageByKey(String key) throws MessageQueueException;
/**
* Return list of pending associated with the key.
*
* @param key
* @return
* @throws MessageQueueException
*/
List peekMessagesByKey(String key) throws MessageQueueException;
/**
* Read history for the specified key
* @param key
* @return
* @throws MessageQueueException
*/
List getKeyHistory(String key, Long startTime, Long endTime, int count) throws MessageQueueException;
/**
* Delete a specific message from the queue.
* @param message
* @throws MessageQueueException
*/
void deleteMessage(String messageId) throws MessageQueueException;
/**
* Delete a message using the specified key. This operation will require a lookup of key to messageId
* prior to deleting the message
* @param key
* @return true if any items were deleted
* @throws MessageQueueException
*/
boolean deleteMessageByKey(String key) throws MessageQueueException;
/**
* Delete a set of messages
* @param messageIds
* @throws MessageQueueException
*/
void deleteMessages(Collection messageIds) throws MessageQueueException;
/**
* Get the counts for each shard in the queue. This is an estimate.
* This is an expensive operation and should be used sparingly.
* @return
* @throws MessageQueueException
*/
Map getShardCounts() throws MessageQueueException;
/**
* Return a map of shards and their stats for THIS instance of the queue.
* These counts are only for the lifetime of this instance and are only incremented
* by operations performed by this instance. For actual shard sizes
* call getShardCounts();
* @return
*/
Map getShardStats();
/**
* Create a consumer of the message queue. The consumer will have it's own context
*
* @return
* @throws MessageQueueException
*/
MessageConsumer createConsumer();
/**
* Create a producer of messages for this queue.
* @return
* @throws MessageQueueException
*/
MessageProducer createProducer();
/**
* Return the queue's unique name
* @return
*/
String getName();
}