org.garret.perst
Interface SortedCollection

All Superinterfaces:

java.io.Externalizable, IPersistent, IResource, ITable, java.io.Serializable

public interface SortedCollection

extends IPersistent, IResource, ITable

Interface of sorted collection. Sorted collections keeps in members in order specified by comparator. Members in the collections can be located using key or range of keys. The SortedCollection is efficient container of objects for in-memory databases. For databases which size is significatly larger than size of page pool, operation with SortedList can cause trashing and so very bad performance. Unlike other index structures SortedCollection doesn't store values of keys and so search in the collection requires fetching of its members.

Method Summary

boolean	add(IPersistent obj) Add new member to collection
void	clear() Remove all objects from the collection
boolean	contains(IPersistent obj) Check if collections contains member equals to specified object More formally, returns true if and only if this collection contains at least one element e such that (obj==null ?
boolean	containsObject(IPersistent obj) Check if collections contains specified object instance
IPersistent	get(java.lang.Object key) Get member with specified key.
IPersistent[]	get(java.lang.Object from, boolean fromInclusive, java.lang.Object till, boolean tillInclusive) Get members which key value belongs to the specified range.
IPersistent[]	get(java.lang.Object from, java.lang.Object till) Get members which key value belongs to the specified range.
PersistentComparator	getComparator() Get comparator used in this collection
java.util.Iterator	iterator() Get iterator for traversing all collection members.
java.util.Iterator	iterator(java.lang.Object from, boolean fromInclusive, java.lang.Object till, boolean tillInclusive) Get iterator for traversing collection members with key belonging to the specified range.
java.util.Iterator	iterator(java.lang.Object from, java.lang.Object till) Get iterator for traversing collection members with key belonging to the specified range.
void	remove(IPersistent obj) Remove member from collection
int	size() Get number of objects in the collection
IPersistent[]	toPersistentArray() Get all objects in the index as array ordered by index key.
IPersistent[]	toPersistentArray(IPersistent[] arr) Get all objects in the index as array ordered by index key.

Methods inherited from interface org.garret.perst.IPersistent

assignOid, deallocate, getOid, getStorage, invalidate, isDeleted, isModified, isPersistent, isRaw, load, loadAndModify, makePersistent, modify, onLoad, onStore, recursiveLoading, store

Methods inherited from interface java.io.Externalizable

readExternal, writeExternal

Methods inherited from interface org.garret.perst.IResource

exclusiveLock, exclusiveLock, reset, sharedLock, sharedLock, unlock

Methods inherited from interface org.garret.perst.ITable

select

Method Detail

add

public boolean add(IPersistent obj)

Add new member to collection

Parameters:

obj - new member

Returns:

true if object is successfully added in the index, false if collection was declared as unique and there is already member with such value of the key in the collection.

clear

public void clear()

Remove all objects from the collection

contains

public boolean contains(IPersistent obj)

Check if collections contains member equals to specified object More formally, returns true if and only if this collection contains at least one element e such that (obj==null ? e==null : obj.equals(e)).

Parameters:

obj - object to be searched in the collection

Returns:

true if collection contains object equals to the specified

containsObject

public boolean containsObject(IPersistent obj)

Check if collections contains specified object instance

Parameters:

obj - object to be searched in the collection

Returns:

true if specified member belongs to the collection

get

public IPersistent get(java.lang.Object key)

Get member with specified key.

Parameters:

key - specified key. It should match with type of the index and should be inclusive.

Returns:

object with this value of the key or null if key not found

Throws:

StorageError(StorageError.KEY_NOT_UNIQUE) - exception if there are more than one objects in the collection with specified value of the key.

get

public IPersistent[] get(java.lang.Object from,
                         boolean fromInclusive,
                         java.lang.Object till,
                         boolean tillInclusive)

Get members which key value belongs to the specified range. Either from boundary, either till boundary either both of them can be null. In last case the method returns all objects from the collection.

Parameters:

from - inclusive low boundary. If null then low boundary is not specified.

fromInclusive - specifies whether from boundary is inclusive or exclusive

till - inclusive high boundary. If null then high boundary is not specified.

tillInclusive - specifies whether till boundary is inclusive or exclusive

Returns:

array of objects which keys belongs to the specified interval, ordered by key value

get

public IPersistent[] get(java.lang.Object from,
                         java.lang.Object till)

Get members which key value belongs to the specified range. Either from boundary, either till boundary either both of them can be null. In last case the method returns all objects from the collection.

Parameters:

from - inclusive low boundary. If null then low boundary is not specified.

till - inclusive high boundary. If null then high boundary is not specified.

Returns:

array of objects which keys belongs to the specified interval, ordered by key value

getComparator

public PersistentComparator getComparator()

Get comparator used in this collection

Returns:

collection comparator

iterator

public java.util.Iterator iterator()

Get iterator for traversing all collection members. This iterator fetches all selected objects in memory. It supports remove() method and all modifications of collection during iteration has no influence on iterator.

Specified by:

iterator in interface ITable

Returns:

collection iterator.

iterator

public java.util.Iterator iterator(java.lang.Object from,
                                   boolean fromInclusive,
                                   java.lang.Object till,
                                   boolean tillInclusive)

Get iterator for traversing collection members with key belonging to the specified range. This iterator fetches all selected objects in memory. It supports remove() method and all modifications of collecction during iteration has no influence on iterator.

Parameters:

from - inclusive low boundary. If null then low boundary is not specified.

fromInclusive - specifies whether from boundary is inclusive or exclusive

till - inclusive high boundary. If null then high boundary is not specified.

tillInclusive - specifies whether till boundary is inclusive or exclusive

Returns:

selection iterator

iterator

public java.util.Iterator iterator(java.lang.Object from,
                                   java.lang.Object till)

Get iterator for traversing collection members with key belonging to the specified range. This iterator fetches all selected objects in memory. It supports remove() method and all modifications of collection during iteration has no influence on iterator.

Parameters:

from - inclusive low boundary. If null then low boundary is not specified.

till - inclusive high boundary. If null then high boundary is not specified.

Returns:

selection iterator

remove

public void remove(IPersistent obj)

Remove member from collection

Parameters:

obj - member to be removed

Throws:

StorageError(StorageError.KEY_NOT_FOUND) - exception if there is no such key in the collection

size

public int size()

Get number of objects in the collection

Specified by:

size in interface ITable

Returns:

number of objects in the collection

toPersistentArray

public IPersistent[] toPersistentArray()

Get all objects in the index as array ordered by index key.

Returns:

array of objects in the index ordered by key value

toPersistentArray

public IPersistent[] toPersistentArray(IPersistent[] arr)

Get all objects in the index as array ordered by index key. The runtime type of the returned array is that of the specified array. If the index fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this index.

If this index fits in the specified array with room to spare (i.e., the array has more elements than this index), the element in the array immediately following the end of the index is set to null. This is useful in determining the length of this index only if the caller knows that this index does not contain any null elements.)

Returns:

array of objects in the index ordered by key value