QList

java.lang.Object
- org.qbroker.common.QList

```
public class QList
extends java.lang.Object
```
QList combines a List and Queue as a FIFO storage for storing objects with associated unigue IDs. It also has a Browser for quick browsing on all the new objects or all occupied cells.

All cells in the QList line up in a circular array. The cells in the same status always stay together in a group. Therefore the circle is divided into four segments of arcs. There are four marks separating those four arcs, ie, the four different groups of cells. Head divides taken cells and occupied cells. Tail separates occupied cells and reserved cells. Lead divides taken cells and empty cells. Mark separates reserved cells and empty cells.

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
watermark -- size + number of reserved cells
collectible -- number of empty cells that have not been collected yet
type -- type of a cell or status of the object
id -- the id of a cell or the object

This is not MT-Safe. It should only used by its owner.

Author:

yannanlu@yahoo.com

Constructor Summary

Constructors
Constructor and Description

QList(java.lang.String name, int capacity)
initialzes a queue with capacity of cells

Constructors
Constructor and Description
`QList(java.lang.String name, int capacity)` initialzes a queue with capacity of cells

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`add(java.lang.Object obj, int id)` adds a new object to the cell with the id and returns the depth of the queue upon success or -1 to indicate failure.
`java.lang.Object`	`browse(int id)` returns the object in the cell with the id or null if id is out of bound.
`Browser`	`browser()` returns an instance of Browser for ids of 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()` collects the next collectible cell so that it is ready to be reserved
`int`	`collect(int id)` collects the id-th cell so that it is ready to be reserved.
`int`	`collectible()` returns the number of collectible objects in the queue
`int`	`depth()` returns the number of new objects in the queue
`protected void`	`finalize()`
`int`	`getCapacity()`
`java.lang.String`	`getName()`
`int`	`getNextID()` returns the id of the next occupied cell or -1 if there is none of the occupied cells available.
`int`	`getNextID(int id)` verifies the occupency on the cell with the id and returns the id if it is occupied or -1 otherwise.
`int`	`getType(int id)` returns the type of the cell with the id if it is not out of bound or -1 otherwise
`boolean`	`isFull()`
`int`	`putback(int id)` puts an in-use object back to the cell with the id and returns the depth of the queue upon success or -1 otherwise.
`int`	`queryIDs(int[] ids, int type)` loads the ids of the type of cells in the natual order to the given array
`java.lang.Object`	`remove(int id)` removes the in-use object from the cell with the id and returns the original object upon success or null otherwise.
`int`	`reserve()` reserves the empty cell with the id and returns the id upon success or -1 otherwise.
`int`	`reserve(int id)` 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.
`int`	`rotate(int id)` rotates the object with the id to the end of the list and returns 1 for success, 0 for failure or -1 for out of bound.
`int`	`size()` returns the number of objects in the queue, new and in-use
`int`	`swap(int id, int jd)` swaps the positions between the two occupied cells referenced by their ids and returns 1 for success, 0 for failure or -1 for out of bound.
`java.lang.Object`	`takeback(int id)` takes back the new object in the cell with the id and sets the cell EMPTY again.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - QList
```
public QList(java.lang.String name,
             int capacity)
```
    initialzes a queue with capacity of cells
- Method Detail
  - getName
```
public java.lang.String getName()
```
  - size
```
public int size()
```
    returns the number of objects in the queue, new and in-use
  - depth
```
public int depth()
```
    returns the number of new objects in the queue
  - collectible
```
public int collectible()
```
    returns the number of collectible objects in the queue
  - getCapacity
```
public int getCapacity()
```
  - isFull
```
public boolean isFull()
```
  - getType
```
public int getType(int id)
```
    returns the type of the cell with the id if it is not out of bound or -1 otherwise
  - collect
```
public int collect()
```
    collects the next collectible cell so that it is ready to be reserved
  - collect
```
public int collect(int id)
```
    collects the id-th cell so that it is ready to be reserved.
  - reserve
```
public int reserve()
```
    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
```
public int reserve(int id)
```
    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
```
public 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
```
public int add(java.lang.Object obj,
               int id)
```
    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.
  - takeback
```
public java.lang.Object takeback(int id)
```
    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.
  - getNextID
```
public int getNextID()
```
    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.
  - getNextID
```
public int getNextID(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
```
public java.lang.Object browse(int id)
```
    returns the object in the cell with the id or null if id is out of bound.
  - putback
```
public int putback(int id)
```
    puts an 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
```
public java.lang.Object remove(int id)
```
    removes the in-use object from the cell with the id and returns the original object upon success or null 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 taken cells.
  - swap
```
public int swap(int id,
                int jd)
```
    swaps the positions between the two occupied cells referenced by their ids and returns 1 for success, 0 for failure or -1 for out of bound.
  - rotate
```
public int rotate(int id)
```
    rotates the object with the id to the end of the list and returns 1 for success, 0 for failure or -1 for out of bound.
  - queryIDs
```
public int queryIDs(int[] ids,
                    int type)
```
    loads the ids of the type of cells in the natual order to the given array
  - browser
```
public Browser browser()
```
    returns an instance of Browser for ids of occupied cells
  - clear
```
public void clear()
```
    clear all cells and reset all marks
  - finalize
```
protected void finalize()
```
    Overrides:
    
    finalize in class java.lang.Object

Class QList

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

QList

Method Detail

getName

size

depth

collectible

getCapacity

isFull

getType

collect

collect

reserve

reserve

cancel

add

takeback

getNextID

getNextID

browse

putback

remove

swap

rotate

queryIDs

browser

clear

finalize