com.atlassian.jira.cluster.distribution.localq

Interface LocalQCacheOpQueue

All Known Implementing Classes:

LocalQCacheOpQueueWithStats, TapeLocalQCacheOpQueue

public interface LocalQCacheOpQueue

Abstracts persistent queue implementation A queue represents a FIFO queue of LocalQCacheOp for a specific node Node. Each node may have from 1 to n queues. Each queue has a single processing (reading) thread so LocalQConfig.NUMBER_OF_QUEUES_PER_NODE i.e. the number of processing threads for each node. LocalQConfig.NUMBER_OF_QUEUES_PER_NODE is the concurrency factor for communicating with a single remote node. Example: if we have a cluster with 3 nodes (node1, node2, node3) on each node there will be LocalQConfig.NUMBER_OF_QUEUES_PER_NODE queues for each of the "other" 2 remote nodes.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	LocalQCacheOpQueue.QueueId Uniquely identifies a queue

Method Summary

Modifier and Type	Method and Description
boolean	add(LocalQCacheOp localQCacheOp) transactional add of LocalQCacheOp to the queue; when operation finished we "guarantee" that the LocalQCacheOp is persisted
void	backupQueue(String prefix) Note: use with caution This method is mainly designed to handle critical state of the queue storage by backing up the current queue persistent store and recreating a new one.
void	close() closes the queue and all resources connected with this queue (like processing thread(s), files); closing a queue is definitive - it will never be open (i.e.
boolean	hasPermission()
LocalQCacheOpQueue.QueueId	id()
boolean	isClosed() Some operations (add(LocalQCacheOp), remove(), peek(), peekOrBlock()) on a closed queue will throw a IllegalStateException.
String	name()
static int	nodeQueueNumber(long threadId) utility method to get the nodeQueueNumber for given thread id
static int	nodeQueueNumberForCurrentThread() utility method to get the nodeQueueNumber for current thread
LocalQCacheOp	peek() Allows to see whats on the head of the queue without removing it
LocalQCacheOp	peekOrBlock() see peek() but will block when the queue is empty;
void	remove() remove LocalQCacheOp from head of the queue
int	size()
Long	usableSpaceInBytes()

Method Detail

close

void close()

closes the queue and all resources connected with this queue (like processing thread(s), files); closing a queue is definitive - it will never be open (i.e. not-closed) again;

isClosed

boolean isClosed()

Some operations (add(LocalQCacheOp), remove(), peek(), peekOrBlock()) on a closed queue will throw a IllegalStateException. This method allows to check if the queue has not been closed.

Returns:

true if queue is closed

name

String name()

Returns:

name of the queue could be useful for the user, like identifying the the queue file path from logs

id

LocalQCacheOpQueue.QueueId id()

Returns:

queue id which uniquely identifies this queue, i.e destination node and nodeQueueNumber, see LocalQCacheOpQueue.QueueId

add

boolean add(LocalQCacheOp localQCacheOp)
     throws IllegalStateException

transactional add of LocalQCacheOp to the queue; when operation finished we "guarantee" that the LocalQCacheOp is persisted

Parameters:

localQCacheOp -

Returns:

true if message was added or false if dropped (like exceeding queue size limit)

Throws:

IllegalStateException - when queue is closed

peek

@Nullable
LocalQCacheOp peek()
                      throws IllegalStateException

Allows to see whats on the head of the queue without removing it

Returns:

localQCacheOp from queue head or null when queue is empty

Throws:

IllegalStateException - when queue is closed

peekOrBlock

@Nullable
LocalQCacheOp peekOrBlock()
                             throws InterruptedException,
                                    IllegalStateException

see peek() but will block when the queue is empty;

Returns:

localQCacheOp from queue head, blocks when the queue is empty, null when queue is closed when in block

Throws:

InterruptedException

IllegalStateException - when queue is closed (when calling this method queue is already closed)

nodeQueueNumberForCurrentThread

static int nodeQueueNumberForCurrentThread()

utility method to get the nodeQueueNumber for current thread

Returns:

nodeQueueNumber for current thread

nodeQueueNumber

static int nodeQueueNumber(long threadId)

utility method to get the nodeQueueNumber for given thread id

Returns:

nodeQueueNumber for given thread id

remove

void remove()
     throws NoSuchElementException,
            IllegalStateException

remove LocalQCacheOp from head of the queue

Throws:

NoSuchElementException - when doing a remove on an empty queue

IllegalStateException - when queue is closed

size

int size()

Returns:

number of elements in this queue

backupQueue

void backupQueue(String prefix)
          throws IOException

Note: use with caution This method is mainly designed to handle critical state of the queue storage by backing up the current queue persistent store and recreating a new one. Renames current queue file name to [prefix]_[queue_file_name] and re-creates queue file with [queue_file_name]. If file with [prefix]_[queue_file_name] already exists it will be deleted. Note that if backupQueue(String) is called between peek() and remove() this can cause remove() to delete a different LocalQCacheOp then expected or may throw NoSuchElementException if the new queue after backupQueue(String) is empty.

Throws:

IOException

usableSpaceInBytes

@Nullable
Long usableSpaceInBytes()

Returns:

number of bytes left on device where this queue is stored or null if unable to get this value

hasPermission

boolean hasPermission()

Returns:

true if has read/write access to queue storage