co.cask.coopr.common.queue

Interface TrackingQueue

public interface TrackingQueue

Queue that tracks consuming of the elements and may re-add elements that were attempted to be consumed. E.g. when consumer fails to ack finish of processing of the element. TODO: consider making generic, current implementation works only with Strings

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	TrackingQueue.ConsumingStatus Defines Tracking Queue Consuming Status.
static class	TrackingQueue.PossessionState Defines PossessionState.

Method Summary

Methods

Modifier and Type	Method and Description
com.google.common.util.concurrent.ListenableFuture<String>	add(Element element) Adds element to the queue.
Iterator<QueuedElement>	getBeingConsumed() Get all QueuedElement that are being consumed.
Iterator<QueuedElement>	getQueued() Get all QueuedElement in the queue that are not being consumed.
TrackingQueue.PossessionState	recordProgress(String consumerId, String elementId, TrackingQueue.ConsumingStatus status, String result) Records progress of consuming the element.
boolean	remove(String elementId) Removes element from the queue by element id.
boolean	removeAll() Removes all elements from the queue.
int	size() Get the size of the queue (both queued and being consumed).
Element	take(String consumerId) Take next available element from the queue act on it.
boolean	toHighestPriority(String elementId) Promotes element to the top of the queue.

Method Detail

add

com.google.common.util.concurrent.ListenableFuture<String> add(Element element)

Adds element to the queue.

Parameters:

element - to add

Returns:

future of the consuming result. It will be set when consuming is successfully reported to be completed

take

Element take(String consumerId)

Take next available element from the queue act on it.

After element is taken it is no longer available for others to take unless it is not placed back to queue. Element can be placed back in the following cases:

• By invoking add(Element) method. In this case element will be considered a new element never seen before. Element will not be removed from list of "in-progress" elements list automatically.
• By reporting TrackingQueue.ConsumingStatus.FAILED status via recordProgress(String, String, ConsumingStatus, String). Element will be rescheduled automatically and removed from the "in-progress" list.
• Element can be rescheduled automatically based on the implementation logic of subclasses.

Parameters:

consumerId - element consumer

Returns:

next available element, or null if no element is available

recordProgress

TrackingQueue.PossessionState recordProgress(String consumerId,
                                           String elementId,
                                           TrackingQueue.ConsumingStatus status,
                                           String result)

Records progress of consuming the element. If element no longer belongs to this consumer this will be noted in returned possession state as TrackingQueue.PossessionState.NOT_POSSESSES. This may happen e.g. if TrackingQueue implementation decided that this consumer is dead and put it back to queue.

If TrackingQueue.ConsumingStatus.FAILED status is reported, element will be placed back to queue automatically

If TrackingQueue.ConsumingStatus.FINISHED_SUCCESSFULLY status is reported the queue no longer tracks the element consuming status.

Parameters:

consumerId - consumer that is processing the element and reporting the progress

elementId - element to report progress on

status - status of the consuming.

result - current value of the result of consuming.

Returns:

true if this consumer still possesses the element and can continue processing it.

remove

boolean remove(String elementId)

Removes element from the queue by element id. If element was being consumed,

Parameters:

elementId - id of the element to remove

Returns:

true if removed successfully or element was not present in the queue, false otherwise

removeAll

boolean removeAll()

Removes all elements from the queue. See remove(String) for more details.

Returns:

true if all removed successfully, false otherwise

toHighestPriority

boolean toHighestPriority(String elementId)

Promotes element to the top of the queue.

Parameters:

elementId - id of the element to promote

Returns:

true if promoted successfully

getQueued

Iterator<QueuedElement> getQueued()

Get all QueuedElement in the queue that are not being consumed.

Returns:

an iterator over the queued (but not being consumed) elements in this queue. The iterator returns elements ordered in the way they are offered to be consumed starting with the top of the queue.

getBeingConsumed

Iterator<QueuedElement> getBeingConsumed()

Get all QueuedElement that are being consumed.

Returns:

an iterator over the queue elements that are being consumed.

size

int size()

Get the size of the queue (both queued and being consumed).

Returns:

size of queue (both queued and being consumed).