XQueue

All Known Implementing Classes:

IndexedXQueue
```
public interface XQueue
```
XQueue is an Interface of First-In-First-Out storage with both tracking and transaction support.

XQueue contains a fixed number of cells with unique ids. Each cell can hold one object. A cell can be in one of four different states: EMPTY, RESERVED, OCCUPIED and TAKEN. Only an empty cell is able to be reserved. Only reserved cells can be occupied. Once a reserved cell is occupied, the object can be taken by an application to process. If an object is taken, the cell is in taken state, meaning the cell is not empty yet. The object may be put back to its original cell or be removed from the cell. Once the object is removed, the cell is empty again and it is available for a new reservation. Once the object is removed from the cell, it can be collected either implicitly or explicitly. If the removed object has not been collected yet, its empty cell is also a collectible. The method of collect() is used to collect an empty cell explicity. The method of reserve() will implicitly collect the cell if it has not been collected yet.

Similarly, each object in an XQueue can be in one of four states, too. Once an object is added to the queue or a cell is occupied by an object, it is new and avaiable to be taken. Once it is taken, the object is in use. Next state will be either done or new due to rollback. Once the object is done, it will be ready for recycle. This state is called ready.

Once the object is put into a cell, the association with the cell will not change until the object is removed from the cell. Therefore, the unique cell IDs can be used to track or operate the objects in the queue. The method reserve() is to have the empty cell ready to be occupied. The method cancel() cancels the reservation on the reserved cell and makes it empty again. The method add() is to have the reserved cell occupied. Before to add, the cell has to be reserved. The method getCellStatus() is used to get the status of a specific cell. The method getNextCell() returns the ID of the next occupied cell and makes the cell taken so that the object can be retrieved via browse() for processing. The method remove() is to remove the in-use object from the cell and makes the cell empty. The method putback() is to put an in-use object back to the cell and to have the cell occupied again. The method takeback() is to take a new object out of the occupied cell and makes the cell empty again. The method browser() gives an instance of Browser for application to browse all the new objects.

capacity -- maximum number of cells in the queue
size -- number of the new and taken objects in the queue
depth -- number of new objects in the queue
collectible -- number of empty cells that have not been collected yet
status -- status of a cell or the object
id -- the id of a cell or the object

The implementation can focus on either the objects or on the cells. If the focus is on the cells, the implementation can assign an unique ID to each of the cells for tracking support. The tracking support allows application to easily track the status of the objects via their cell IDs.

It is up to the implementation to support MT-Safty and XA.

Author:

yannanlu@yahoo.com

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CELL_EMPTY`
`static int`	`CELL_OCCUPIED`
`static int`	`CELL_OUTBOUND`
`static int`	`CELL_RESERVED`
`static int`	`CELL_TAKEN`
`static int`	`EXTERNAL_XA`
`static int`	`KEEP_RUNNING`
`static int`	`PAUSE`
`static int`	`STANDBY`
`static int`	`XQ_ERROR`

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`int`	`add(java.lang.Object obj, int index)` adds a new object to the cell with the id and returns the depth of the queue upon success or -1 to indicate failure.
`int`	`add(java.lang.Object obj, int index, XQCallbackWrapper callback)` adds a new object and the callback wrapper to the cell with the id and returns the depth of the queue upon success or -1 to indicate failure.
`boolean`	`available()` returns true if any new objects in the queue or false otherwise
`java.lang.Object`	`browse(int id)` returns the object in the cell with the id or null if the id is out of bound or the cell at the id is empty.
`Browser`	`browser()` returns an instance of Browser for browsing ids of all occupied cells
`int`	`cancel(int id)` cancels the reservation on the cell with the id and returns the watermark upon success or -1 otherwise.
`void`	`clear()` clear all cells and reset all marks
`int`	`collect(long milliSec)` collects the next collectible cell and returns its id
`int`	`collect(long milliSec, int id)` collects the empty cell at the id and marks it as non-collectible.
`int`	`collect(long milliSec, int begin, int len)` collects the first collectible cell out of len cells starting from begin and returns its id
`int`	`collectible()` returns the number of collectible objects in the queue
`int`	`depth()` returns the number of new objects in the queue
`int`	`getCapacity()` returns the capacity of the queue
`int`	`getCellStatus(int id)` returns the status of the cell with the id
`long`	`getCount()` returns the number of objects taken out of the queue since the reset at its timestamp
`int`	`getGlobalMask()` returns the global mask of the queue
`long`	`getMTime()` returns the timestamp of the reset on the queue
`java.lang.String`	`getName()` returns the name of the queue
`int`	`getNextCell(long milliSec)` returns the id of the next occupied cell or -1 if there is none of the occupied cells available.
`int`	`getNextCell(long milliSec, int id)` verifies the occupency on the cell with the id and returns the id if it is occupied or -1 otherwise.
`int`	`getNextCell(long milliSec, int begin, int len)` returns the id of the first available occupied cell in the range of len cells starting from begin or -1 if there is none of the occupied cells available.
`boolean`	`isCollectible()` returns true if the queue supports collectible() and collect()
`boolean`	`isFull()` returns true if the queue is full or false otherwise
`int`	`locate(int[] ids, int begin, int len)` locates all unreserved empty cells among the given ids in the list ranging from the id of begin thru the id of begin+len-1 and returns the number of ids found or -1 to indicate errors.
`int`	`putback(int id)` puts the in-use object back to the cell with the id and returns the depth of the queue upon success or -1 otherwise.
`int`	`remove(int id)` removes the in-use object from the cell with the id and returns the size of the queue upon success or -1 otherwise.
`int`	`reserve(long milliSec)` reserves an empty cell and returns its id upon success or -1 otherwise.
`int`	`reserve(long milliSec, int id)` reserves the empty cell with the id and returns the id upon success or -1 otherwise.
`int`	`reserve(long milliSec, int begin, int len)` reserves an empty cell in the range of len cells starting from begin and returns the id of the cell upon success or -1 otherwise.
`long`	`reset()` resets the counter to 0, updates the timestamp and returns the total number of objects taken out of the queue since the previous reset
`void`	`setGlobalMask(int mask)` sets the global mask of the queue
`int`	`size()` returns the number of objects in the queue, new and taken
`java.lang.Object`	`takeback(int index)` takes back the new object in the cell with the id and sets the cell EMPTY again.

- Field Detail
  - XQ_ERROR
```
static final int XQ_ERROR
```
    See Also:
    
    Constant Field Values
  - KEEP_RUNNING
```
static final int KEEP_RUNNING
```
    See Also:
    
    Constant Field Values
  - PAUSE
```
static final int PAUSE
```
    See Also:
    
    Constant Field Values
  - STANDBY
```
static final int STANDBY
```
    See Also:
    
    Constant Field Values
  - EXTERNAL_XA
```
static final int EXTERNAL_XA
```
    See Also:
    
    Constant Field Values
  - CELL_OUTBOUND
```
static final int CELL_OUTBOUND
```
    See Also:
    
    Constant Field Values
  - CELL_EMPTY
```
static final int CELL_EMPTY
```
    See Also:
    
    Constant Field Values
  - CELL_RESERVED
```
static final int CELL_RESERVED
```
    See Also:
    
    Constant Field Values
  - CELL_OCCUPIED
```
static final int CELL_OCCUPIED
```
    See Also:
    
    Constant Field Values
  - CELL_TAKEN
```
static final int CELL_TAKEN
```
    See Also:
    
    Constant Field Values
- Method Detail
  - size
```
int size()
```
    returns the number of objects in the queue, new and taken
  - depth
```
int depth()
```
    returns the number of new objects in the queue
  - collectible
```
int collectible()
```
    returns the number of collectible objects in the queue
  - getCount
```
long getCount()
```
    returns the number of objects taken out of the queue since the reset at its timestamp
  - getMTime
```
long getMTime()
```
    returns the timestamp of the reset on the queue
  - reset
```
long reset()
```
    resets the counter to 0, updates the timestamp and returns the total number of objects taken out of the queue since the previous reset
  - getName
```
java.lang.String getName()
```
    returns the name of the queue
  - getCapacity
```
int getCapacity()
```
    returns the capacity of the queue
  - getGlobalMask
```
int getGlobalMask()
```
    returns the global mask of the queue
  - setGlobalMask
```
void setGlobalMask(int mask)
```
    sets the global mask of the queue
  - available
```
boolean available()
```
    returns true if any new objects in the queue or false otherwise
  - isFull
```
boolean isFull()
```
    returns true if the queue is full or false otherwise
  - isCollectible
```
boolean isCollectible()
```
    returns true if the queue supports collectible() and collect()
  - getCellStatus
```
int getCellStatus(int id)
```
    returns the status of the cell with the id
  - collect
```
int collect(long milliSec,
            int id)
```
    collects the empty cell at the id and marks it as non-collectible. It returns the id or -1 if the cell is not a collectible.
  - collect
```
int collect(long milliSec,
            int begin,
            int len)
```
    collects the first collectible cell out of len cells starting from begin and returns its id
  - collect
```
int collect(long milliSec)
```
    collects the next collectible cell and returns its id
  - reserve
```
int reserve(long milliSec)
```
    reserves an empty cell and returns its id upon success or -1 otherwise. In case of success, it sets the cell to RESERVED so that the cell is available to be occupied.
  - reserve
```
int reserve(long milliSec,
            int id)
```
    reserves the empty cell with the id and returns the id upon success or -1 otherwise. The operation is not supposed to change the order of other empty cells.
  - reserve
```
int reserve(long milliSec,
            int begin,
            int len)
```
    reserves an empty cell in the range of len cells starting from begin and returns the id of the cell upon success or -1 otherwise. The operation is not supposed to change the order of other empty cells.
  - cancel
```
int cancel(int id)
```
    cancels the reservation on the cell with the id and returns the watermark upon success or -1 otherwise. In case of success, it sets the cell to EMPTY so that it is available for reservation again. The operation is not supposed to change the order of other reserved cells.
  - add
```
int add(java.lang.Object obj,
        int index)
```
    adds a new object to the cell with the id and returns the depth of the queue upon success or -1 to indicate failure. In case of success, it sets the cell to OCCUPIED so that it is available to be taken. The operation is not supposed to change the order of other reserved cells.
  - add
```
int add(java.lang.Object obj,
        int index,
        XQCallbackWrapper callback)
```
    adds a new object and the callback wrapper to the cell with the id and returns the depth of the queue upon success or -1 to indicate failure. In case of success, it sets the cell to OCCUPIED so that it is available to be taken. The operation is not supposed to change the order of other reserved cells. The callback wrapper will be invoked when the object is dequeued.
  - takeback
```
java.lang.Object takeback(int index)
```
    takes back the new object in the cell with the id and sets the cell EMPTY again. It returns the object upon success or null otherwise. The operation is not supposed to change the order of other occupied cells.
  - getNextCell
```
int getNextCell(long milliSec)
```
    returns the id of the next occupied cell or -1 if there is none of the occupied cells available. In case of success, it sets the cell to TAKEN to indicate the object is in-use.
  - getNextCell
```
int getNextCell(long milliSec,
                int begin,
                int len)
```
    returns the id of the first available occupied cell in the range of len cells starting from begin or -1 if there is none of the occupied cells available. In case of success, it sets the cell to TAKEN to indicate the object is in-use. The operation is not supposed to change the order of other occupied cells.
  - getNextCell
```
int getNextCell(long milliSec,
                int id)
```
    verifies the occupency on the cell with the id and returns the id if it is occupied or -1 otherwise. In case of verified, it sets the cell to TAKEN to indicate the object is in-use. The operation is not supposed to change the order of other occupied cells.
  - browse
```
java.lang.Object browse(int id)
```
    returns the object in the cell with the id or null if the id is out of bound or the cell at the id is empty. There is no change on the status of the cell or object. The application should always get the id before calling this method. Otherwise, the object may be owned by others.
  - putback
```
int putback(int id)
```
    puts the in-use object back to the cell with the id and returns the depth of the queue upon success or -1 otherwise. In case of success, it sets the cell OCCUPIED again so that the object is available to be taken. The operation is not supposed to change the order of other taken cells.
  - remove
```
int remove(int id)
```
    removes the in-use object from the cell with the id and returns the size of the queue upon success or -1 otherwise. In case of success, it sets the cell to EMPTY so that it is available to be collected or reserved. The operation is not supposed to change the order of other taken cells.
  - locate
```
int locate(int[] ids,
           int begin,
           int len)
```
    locates all unreserved empty cells among the given ids in the list ranging from the id of begin thru the id of begin+len-1 and returns the number of ids found or -1 to indicate errors. All the found ids are stored in the list starting from begin and in the same order of the queue.
  - clear
```
void clear()
```
    clear all cells and reset all marks
  - browser
```
Browser browser()
```
    returns an instance of Browser for browsing ids of all occupied cells

Interface XQueue

Field Summary

Method Summary

Field Detail

XQ_ERROR

KEEP_RUNNING

PAUSE

STANDBY

EXTERNAL_XA

CELL_OUTBOUND

CELL_EMPTY

CELL_RESERVED

CELL_OCCUPIED

CELL_TAKEN

Method Detail

size

depth

collectible

getCount

getMTime

reset

getName

getCapacity

getGlobalMask

setGlobalMask

available

isFull

isCollectible

getCellStatus

collect

collect

collect

reserve

reserve

reserve

cancel

add

add

takeback

getNextCell

getNextCell

getNextCell

browse

putback

remove

locate

clear

browser