com.j_spaces.kernel.list

Class ExternallyLockedStoredList<T>

java.lang.Object

com.j_spaces.kernel.list.ExternallyLockedStoredList<T>

All Implemented Interfaces:

IHashEntry<Object,IStoredList<T>>, ICollection<T>, IOrderedList<T>, IStoredList<T>, IObjectsList

public class ExternallyLockedStoredList<T>
extends Object
implements IStoredList<T>, IOrderedList<T>

no Lock version of StoredList locks should be external to this class scanning after establishing a starting position should be left lock free

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	ExternallyLockedStoredList.ObjectInfo<T>
static class	ExternallyLockedStoredList.StoredListIterator<T>

Constructor Summary

Constructors

Constructor and Description
ExternallyLockedStoredList(boolean Support_Random_Scans)

Method Summary

Modifier and Type	Method and Description
IObjectInfo<T>	add(T subject) store an element
IObjectInfo<T>	addUnlocked(T subject) store an element, while the SL is unlocked
boolean	contains(T obj) is this object contained in the SL ?
void	dump(Logger logger, String msg) Dump list content, used for Debug.
IStoredListIterator<T>	establishListOrderedScan(IObjectInfo<T> OrderedScanPivot, boolean ascending) establish a scan position in one direction ascending (twrds head) or descending (towards tail).
ExternallyLockedStoredList.StoredListIterator<T>	establishListScan(boolean random_scan) establish a scan position.
protected ExternallyLockedStoredList.StoredListIterator<T>	establishOrderedPos(ExternallyLockedStoredList.ObjectInfo<T> OrderedScanPivot, boolean ascending, ExternallyLockedStoredList.StoredListIterator<T> res)
protected ExternallyLockedStoredList.StoredListIterator<T>	establishPos(boolean random_scan, ExternallyLockedStoredList.StoredListIterator<T> res)
void	freeSLHolder(IStoredListIterator<T> slh) this method is called by outside scan that want to quit the scan and return the slholder to the factory
int	getHashCode(int id)
IObjectInfo<T>	getHead() get head of SL
Object	getKey(int id)
IObjectInfo<T>	getLargerInOrder(IObjectInfo<T> ref) in an ordered SL, get the element larger than ref
T	getObjectFromHead() get object from head of SL
IObjectInfo<T>	getSmallerInOrder(IObjectInfo<T> ref) in an ordered SL, get the element smaller than ref
IStoredList<T>	getValue(int id)
boolean	invalidate() Sets an indication that this StoredList is invalid.
boolean	isEmpty() Returns true if this list is empty, i.e.
protected boolean	isInvalid()
boolean	isIterator() is the list an iterator or basic list ?
boolean	isMultiObjectCollection() is it an actual multi object container.
boolean	isNativeHashEntry()
IStoredListIterator<T>	next(IStoredListIterator<T> slh) get the next element in scan order
protected IStoredListIterator<T>	nextPos(ExternallyLockedStoredList.StoredListIterator<T> slh)
boolean	optimizeScanForSingleObject() return true if we can save iterator creation and get a single entry
void	remove(IObjectInfo<T> oi) remove an element described by ObjectInfo
boolean	removeByObject(T obj) given an object scan the list, find it and remove it, returns true if found
void	removeUnlocked(IObjectInfo<T> oi) remove an element described by ObjectInfo, while the SL is unlocked
int	size() Returns the amount of elements in the StoredList.
IObjectInfo<T>	storeBeforeCeiling(IObjectInfo<T> theCeiling, T subject) given an ObjectInfo of an existing element, store a new element right "before" this one.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ExternallyLockedStoredList

public ExternallyLockedStoredList(boolean Support_Random_Scans)

Method Detail

size

public int size()

Description copied from interface: ICollection

Returns the amount of elements in the StoredList.

Specified by:

size in interface ICollection<T>

Returns:

size of the StoredList

See Also:

ICollection.isEmpty()

optimizeScanForSingleObject

public boolean optimizeScanForSingleObject()

return true if we can save iterator creation and get a single entry

Specified by:

optimizeScanForSingleObject in interface IStoredList<T>

Returns:

true if we can optimize

isEmpty

public boolean isEmpty()

Description copied from interface: ICollection

Returns true if this list is empty, i.e. has no elements. [Tail] - [Head]

Specified by:

isEmpty in interface ICollection<T>

Returns:

true if list is empty; false otherwise.

getHead

public IObjectInfo<T> getHead()

get head of SL

Specified by:

getHead in interface IStoredList<T>

Returns:

the head of the list

getObjectFromHead

public T getObjectFromHead()

get object from head of SL

Specified by:

getObjectFromHead in interface IStoredList<T>

Returns:

the value of the head of the list

establishPos

protected ExternallyLockedStoredList.StoredListIterator<T> establishPos(boolean random_scan,
                                                                        ExternallyLockedStoredList.StoredListIterator<T> res)

establishOrderedPos

protected ExternallyLockedStoredList.StoredListIterator<T> establishOrderedPos(ExternallyLockedStoredList.ObjectInfo<T> OrderedScanPivot,
                                                                               boolean ascending,
                                                                               ExternallyLockedStoredList.StoredListIterator<T> res)

nextPos

protected IStoredListIterator<T> nextPos(ExternallyLockedStoredList.StoredListIterator<T> slh)

add

public IObjectInfo<T> add(T subject)

store an element

Specified by:

add in interface ICollection<T>

Parameters:

subject - element to store.

Returns:

an information node representing the inserted element; null if StoredList has been invalidated.

addUnlocked

public IObjectInfo<T> addUnlocked(T subject)

store an element, while the SL is unlocked

Specified by:

addUnlocked in interface IStoredList<T>

Parameters:

subject - element to store.

Returns:

an information node representing the inserted element; null if StoredList has been invalidated.

storeBeforeCeiling

public IObjectInfo<T> storeBeforeCeiling(IObjectInfo<T> theCeiling,
                                         T subject)

given an ObjectInfo of an existing element, store a new element right "before" this one. Method used in OrderedIndex object when the MasterList reflects the order of elements- head is the largest, tail the smallest

Specified by:

storeBeforeCeiling in interface IOrderedList<T>

Parameters:

theCeiling - a ceiling to the new element (towards the head); when null, the ceiling will be the Head.

subject - a new element, to be inserted before the ceiling (towards the tail)

Returns:

an information node representing the inserted element.

Note: not relevant for random scans

getLargerInOrder

public IObjectInfo<T> getLargerInOrder(IObjectInfo<T> ref)

in an ordered SL, get the element larger than ref

Specified by:

getLargerInOrder in interface IOrderedList<T>

Parameters:

ref - a reference to an OI (element in the )

Returns:

the next largest element to ref (towards head)

getSmallerInOrder

public IObjectInfo<T> getSmallerInOrder(IObjectInfo<T> ref)

in an ordered SL, get the element smaller than ref

Specified by:

getSmallerInOrder in interface IOrderedList<T>

Parameters:

ref - a reference to an OI (element in the )

Returns:

the next smallest to ref (towards tail)

remove

public void remove(IObjectInfo<T> oi)

remove an element described by ObjectInfo

Specified by:

remove in interface IStoredList<T>

Parameters:

oi - an existing element between Tail and Head

removeUnlocked

public void removeUnlocked(IObjectInfo<T> oi)

remove an element described by ObjectInfo, while the SL is unlocked

Specified by:

removeUnlocked in interface IStoredList<T>

Parameters:

oi - an existing element between Tail and Head

removeByObject

public boolean removeByObject(T obj)

given an object scan the list, find it and remove it, returns true if found

Specified by:

removeByObject in interface ICollection<T>

Parameters:

obj - element to remove

Returns:

true if object was removed; false otherwise (if element wasn't found)

contains

public boolean contains(T obj)

is this object contained in the SL ?

Specified by:

contains in interface ICollection<T>

Parameters:

obj - the element to search for

Returns:

true if element exists in the StoredList; false otherwise.

invalidate

public boolean invalidate()

Sets an indication that this StoredList is invalid. if isEmpty() returns true, the indication is set; otherwise the indication remains false. Called by PersistentGC when scanning for empty StoredList that can be garbage collected.

Specified by:

invalidate in interface IStoredList<T>

Returns:

true if StoredList was set to invalid; false otherwise.

isInvalid

protected boolean isInvalid()

Returns:

true if the list is invalid

dump

public void dump(Logger logger,
                 String msg)

Description copied from interface: IStoredList

Dump list content, used for Debug.

Specified by:

dump in interface IStoredList<T>

Parameters:

logger - logger to use

msg - message to add in log

establishListScan

public ExternallyLockedStoredList.StoredListIterator<T> establishListScan(boolean random_scan)

establish a scan position. if random scanning supported we select a random position

Specified by:

establishListScan in interface ICollection<T>

Parameters:

random_scan - true enable random scan; false start from head.

Returns:

a Holder for this scan. This Resource should be released if scan ended prematurely.

establishListOrderedScan

public IStoredListIterator<T> establishListOrderedScan(IObjectInfo<T> OrderedScanPivot,
                                                       boolean ascending)

establish a scan position in one direction ascending (twrds head) or descending (towards tail). if random scanning supported starting at a predefined pos this API is used by the OrderedIndex masterList to establish an index scan

Specified by:

establishListOrderedScan in interface IOrderedList<T>

Parameters:

OrderedScanPivot - a pivot from which to start this scan. if null, pivot is Head (if ascending is true); Tail otherwise

ascending - if true scan from pivot towards head; if false scan from pivot towards tail.

Returns:

returns a Holder of this scan. This Resource should be released if scan ended prematurely.

next

public IStoredListIterator<T> next(IStoredListIterator<T> slh)

get the next element in scan order

Specified by:

next in interface ICollection<T>

Parameters:

slh - Holder representing a pivot position.

Returns:

the next pivot position in this scan; null if reached end of scan.

freeSLHolder

public void freeSLHolder(IStoredListIterator<T> slh)

this method is called by outside scan that want to quit the scan and return the slholder to the factory

Specified by:

freeSLHolder in interface IStoredList<T>

Parameters:

slh - Holder resource to return to pool; can be null.

isMultiObjectCollection

public boolean isMultiObjectCollection()

Description copied from interface: ICollection

is it an actual multi object container.

Specified by:

isMultiObjectCollection in interface ICollection<T>

Returns:

true if its an actual list; false otherwise

isIterator

public boolean isIterator()

Description copied from interface: IObjectsList

is the list an iterator or basic list ?

Specified by:

isIterator in interface IObjectsList

getHashCode

public int getHashCode(int id)

Specified by:

getHashCode in interface IHashEntry<Object,IStoredList<T>>

getKey

public Object getKey(int id)

Specified by:

getKey in interface IHashEntry<Object,IStoredList<T>>

getValue

public IStoredList<T> getValue(int id)

Specified by:

getValue in interface IHashEntry<Object,IStoredList<T>>

isNativeHashEntry

public boolean isNativeHashEntry()

Specified by:

isNativeHashEntry in interface IHashEntry<Object,IStoredList<T>>

Returns:

true if this is a native hashmap entry