rcf.core.util.position
Interface Position<T>

Type Parameters:

T - The type of the elements which are stored at positions in the backing abstract data structure.

All Superinterfaces:

ImmutablePosition<T>, ImmutableSingletonInterface<T>, SingletonInterface<T>

All Known Subinterfaces:

Iterator<T>

All Known Implementing Classes:

Pair.Iterator, Singleton.Iterator, Triple.Iterator

@Revision(value="$Revision: 1.6 $",
          date="$Date: 2006/12/16 17:53:21 $",
          tag="$Name:  $")
public interface Position<T>
extends ImmutablePosition<T>, SingletonInterface<T>

A combination of the ImmutablePosition and SingletonInterface interfaces which adds support for the modification of the element at this position through SingletonInterface.set(Object) and it's removal from the backing abstract data structure with remove().

Positions, in general, may support concurrent modifications to the backing abstract data structure, but are not required to. In the event that a position does not support concurrent modification, it should throw ConcurrentModificationException rather than fail at some later time, in a non-deterministic way. This is the basis of the fail-fast behavior of the rcf.core.util.collection.iterator package.

Some implementations will throw ConcurrentModificationException in response to any modification other than those through a single position object. Others will only throw an exception for structural modifications which did not go through the position object. Still others will support concurrent modifications without exceptions. Because these exceptions are optional they should be used for debugging only, and cannot be relied on for correctness.

In order to avoid using exceptions to decide normal control flow, the methods isRemoved(), isValid() and ImmutablePosition.isSentinel() are provided. See the method documentation for more details.

TODO: Javadoc review, Seal/Finalize

Version:

$Revision: 1.6 $

Author:

Greg Gibeling

Method Summary

boolean	isRemoved() Determine if this position has been removed from the backing abstract data structure.
boolean	isValid() Determine if there has been a concurrent modification to the backing abstract data structure.
T	remove() Remove this position, and the element associated with it from the backing abstract data structure, and return the element.
T	set(T a) Set the content element of this position, and possibly change this position's relationship to other positions in the backing abstract data structure.

Methods inherited from interface rcf.core.util.position.ImmutablePosition

equals, isCompatible, isSentinel

Methods inherited from interface rcf.core.util.groups.ImmutableSingletonInterface

get

Methods inherited from interface rcf.core.util.groups.ImmutableSingletonInterface

get

Method Detail

isRemoved

boolean isRemoved()

Determine if this position has been removed from the backing abstract data structure.

Returns:

true if this position has been removed from the backing abstract data structure.

Throws:

ConcurrentModificationException - The abstract data structure has been modified through another object.

isValid

boolean isValid()

Determine if there has been a concurrent modification to the backing abstract data structure. This method must return false in all cases where any method may throw a ConcurrentModificationException.

Returns:

true indicates that this position is still valid (though it may have been removed, see isRemoved()) in the backing abstract data structure. This also indicates that no method on this object will throw a ConcurrentModificationException at the time of this call.

remove

T remove()

Remove this position, and the element associated with it from the backing abstract data structure, and return the element.

Returns:

The element at this position.

Throws:

IllegalStateException - This position and it's associated element have already been removed.

SentinelPositionException - This is a sentinel position, and therefor cannot be removed.

See Also:

ImmutableSingletonInterface.get()

set

T set(T a)

Set the content element of this position, and possibly change this position's relationship to other positions in the backing abstract data structure. This may interrupt the normal flow of any iterations in progress.

Specified by:

set in interface SingletonInterface<T>

Parameters:

a - The new content element of this position.

Returns:

The old content element of this position.