HandleDataStore (ACS-2016.6)

java.lang.Object
- com.cosylab.acs.maci.manager.HandleDataStore

All Implemented Interfaces:

java.io.Serializable
```
public class HandleDataStore
extends java.lang.Object
implements java.io.Serializable
```
Data structure for maintaining a collection of elements that can be referred to using handles. Stores data elements in an array-like structure. Individual elements are addressed using handles, which can be though of as indices in the array. It fulfills these requirements:
1. allocation - a new element can be added and is assigned a unique handle. Allocation is an O(1) operation.
2. deallocation - an element can be removed from the registrar. The handle is freed, and can be assigned to another element during allocation at a later time. Deallocation is an O(1) operation.
3. retrieval - a reference to the element can be retrieved for reading and writing. Retrieval is an O(1) operation.
4. enumeration - elements stored can be traversed from first to last. Costs of acquiring first, last, next and previous element of the array are O(1).
This ADT is suitable for enumerating resources that are frequently allocated, retrieved and deallocated without losing large amounts of memory and/or time. This is essentially a doubly-linked list of elements, which are placed in an array. Each element has assigned a handle (the index in the array), and handles of the elements that come previous and next to it. There are actually two chains of elements: the free element chain, which contains all elements that have not yet been allocated, and the allocated element chain. Free element chain is cyclic (passing the end resumes at the beginning), and contains the element with the handle 0. The allocated element chain is not cyclic: it starts with the element that was first allocated, and ends with the one that was last allocated.
Author:

Matej Sekoranja (matej.sekoranja@cosylab.com), Klemen Zagar (klemen.zagar@cosylab.com)

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type Field and Description

static int DEFAULT_MAX_CAPACITY
Default maximum capacity of this ADT.

Fields
Modifier and Type	Field and Description
`static int`	`DEFAULT_MAX_CAPACITY` Default maximum capacity of this ADT.

Constructor Summary

Constructors
Constructor and Description
`HandleDataStore()` Constructs a `HandleDataStore` with zero offset and initial capacity of ten.
`HandleDataStore(int initialCapacity)` Constructs a `HandleDataStore` with zero offset.
`HandleDataStore(int initialCapacity, int maxCapacity)` Constructs a `HandleDataStore`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`ackAllocation(int handle)` Completes allocation of handle, to be used to completely allocate handle after preallocation.
`int`	`allocate()` Allocate an element in this `HandleDataStore`.
`int`	`allocate(int handle)` Allocate an element in this `HandleDataStore`.
`int`	`allocate(int handle, boolean preallocate)` Allocate an element with given handle in this `HandleDataStore`.
`int`	`capacity()` Returns the capacity of this ADT.
`void`	`deallocate(int handle)` Deallocate an element with the given handle.
`void`	`deallocate(int handle, boolean depreallocate)` Deallocate an element with the given handle.
`int`	`first()` Return the handle of the first element in this ADT.
`java.lang.Object`	`get(int handle)` Returns the element with the specified handle.
`boolean`	`isAllocated(int handle)` Determines whether a given handle is allocated.
`boolean`	`isEmpty()` Tests if this list has no elements.
`int`	`last()` Return the handle of the last element in this ADT.
`int`	`next(int handle)` Return the handle of the next element in this ADT.
`int`	`preallocate()` Preallocate an element in this `HandleDataStore`.
`int`	`previous(int handle)` Return the handle of the previous element in this ADT.
`void`	`set(int handle, java.lang.Object data)` Sets the element with the specified handle.
`void`	`setCapacity(int newCapacity)` Sets the capacity of this `HandleDataStore` instance to hold `newCapacity` elements;.
`int`	`size()` Returns the number of elements in this ADT.
`java.lang.String`	`toString()` Returns a single-line rendition of this instance into text.

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

- Field Detail
  - DEFAULT_MAX_CAPACITY
```
public static final int DEFAULT_MAX_CAPACITY
```
    Default maximum capacity of this ADT.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - HandleDataStore
```
public HandleDataStore()
```
    Constructs a HandleDataStore with zero offset and initial capacity of ten.
  - HandleDataStore
```
public HandleDataStore(int initialCapacity)
```
    Constructs a HandleDataStore with zero offset.
    
    Parameters:
    
    initialCapacity - the initial capacity of the list.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the specified initial capacity is negative
  - HandleDataStore
```
public HandleDataStore(int initialCapacity,
                       int maxCapacity)
```
    Constructs a HandleDataStore. Creates a HandleDataStore and allocates enough space to hold initialCapacity elements.
    
    Parameters:
    
    initialCapacity - the initial capacity of the list.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the specified initial capacity is negative
- Method Detail
  - size
```
public int size()
```
    Returns the number of elements in this ADT.
    
    Returns:
    
    the number of elements in this ADT.
  - capacity
```
public int capacity()
```
    Returns the capacity of this ADT. Capacity is the maximum number of elements that this ADT can hold before resizing itself.
    
    Returns:
    
    the capacity of this ADT.
  - isEmpty
```
public boolean isEmpty()
```
    Tests if this list has no elements.
    
    Returns:
    
    true if this list has no elements, false otherwise.
  - get
```
public java.lang.Object get(int handle)
```
    Returns the element with the specified handle. NOTE: handle is not checked, if it is valid.
    
    Parameters:
    
    handle - handle of the element
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if handle is out of bounds.
  - set
```
public void set(int handle,
                java.lang.Object data)
```
    Sets the element with the specified handle. NOTE: handle is not checked, if it is valid.
    
    Parameters:
    
    handle - handle of the element
    
    data - data to be set
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if handle is out of bounds.
  - setCapacity
```
public void setCapacity(int newCapacity)
```
    Sets the capacity of this HandleDataStore instance to hold newCapacity elements;.
    
    Parameters:
    
    newCapacity - the desired capacity.
  - first
```
public int first()
```
    Return the handle of the first element in this ADT.
    
    Returns:
    
    the handle of the element that was the first one to get allocated and has not yet been deallocated. Useful for determining the starting point when enumerating the entire ADT.
    
    See Also:
    
    next(int), previous(int), last
  - last
```
public int last()
```
    Return the handle of the last element in this ADT.
    
    Returns:
    
    the handle of the element that was the last one to get allocated and has not yet been deallocated. Useful for determining the starting point when enumerating the entire ADT.
    
    See Also:
    
    next(int), previous(int), first
  - next
```
public int next(int handle)
```
    Return the handle of the next element in this ADT.
    
    Parameters:
    
    handle - handle of the element whose sucessor's handle we wish to acquire.
    
    Returns:
    
    the handle of the element that follows the one whose handle is handle. If handle is the last element, 0 is returned.
  - previous
```
public int previous(int handle)
```
    Return the handle of the previous element in this ADT.
    
    Parameters:
    
    handle - handle of the element whose predecessor's handle we wish to acquire.
    
    Returns:
    
    the handle of the element that precedes the one whose handle is handle. If handle is the first element, 0 is returned.
  - isAllocated
```
public boolean isAllocated(int handle)
```
    Determines whether a given handle is allocated.
    
    Parameters:
    
    handle - the handle in question.
    
    Returns:
    
    true if an element with handle handle already exists in this ADT, false otherwise.
  - allocate
```
public int allocate()
```
    Allocate an element in this HandleDataStore.
    
    Returns:
    
    newly allocated handle if allocation was successful, otherwise 0
    
    See Also:
    
    deallocate(int)
  - allocate
```
public int allocate(int handle)
```
    Allocate an element in this HandleDataStore.
    
    Parameters:
    
    handle - hanlde be allocated
    
    Returns:
    
    newly allocated handle if allocation was successful, otherwise 0
    
    See Also:
    
    deallocate(int)
  - preallocate
```
public int preallocate()
```
    Preallocate an element in this HandleDataStore.
    
    Returns:
    
    newly allocated handle if allocation was successful, otherwise 0
    
    See Also:
    
    allocate(), deallocate(int)
  - allocate
```
public int allocate(int handle,
                    boolean preallocate)
```
    Allocate an element with given handle in this HandleDataStore. Assures that this ADT is capable of holding yet another element and returns a handle to it.
    
    Parameters:
    
    handle - handle to be allocated
    
    preallocate - if true element is not really allocated (only reserved, listing through the ADT will skip preallocated elements), to completely allocate preallocated elements use ackAllocation(handle) or canceled by deallocate(handle, true) method.
    
    Returns:
    
    newly allocated handle if allocation was successful, otherwise 0
    
    See Also:
    
    deallocate(int)
  - ackAllocation
```
public void ackAllocation(int handle)
```
    Completes allocation of handle, to be used to completely allocate handle after preallocation.
    
    Parameters:
    
    handle - handle to be completely allocated
  - deallocate
```
public void deallocate(int handle)
```
    Deallocate an element with the given handle. The element and its corresponding handle can be reused at a later call to allocate.
    
    Parameters:
    
    handle - the handle of the element to deallocate.
    
    See Also:
    
    allocate()
  - deallocate
```
public void deallocate(int handle,
                       boolean depreallocate)
```
    Deallocate an element with the given handle. The element and its corresponding handle can be reused at a later call to allocate.
    
    Parameters:
    
    handle - the handle of the element to deallocate.
    
    depreallocate - has to be true, if handle was only preallocated
    
    See Also:
    
    allocate()
  - toString
```
public java.lang.String toString()
```
    Returns a single-line rendition of this instance into text.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    internal state of this instance

Class HandleDataStore

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_MAX_CAPACITY

Constructor Detail

HandleDataStore

HandleDataStore

HandleDataStore

Method Detail

size

capacity

isEmpty

get

set

setCapacity

first

last

next

previous

isAllocated

allocate

allocate

preallocate

allocate

ackAllocation

deallocate

deallocate

toString