Class COM.odi.util.OSTreeSet

java.lang.Object
   |
   +----COM.odi.util.OSAbstractSet
           |
           +----COM.odi.util.OSTreeSet

public class OSTreeSet

extends OSAbstractSet

implements IPersistent, Cloneable, Set, FastContains, IndexedCollection, Serializable

This class is included in PSE Pro, but not in PSE.

Additional information about OSTreeSet is in the user guide.

The following exceptions might be thrown by many of the methods in this class:

DatabaseNotOpenException If the database containing the object is not open.

NoTransactionInProgressException If there is no transaction in progress.

ObjectNotFoundException If the object was not found, either because the object itself, its segment, or its database was destroyed; or because the OSTreeSet was created in a transaction that was subsequently aborted.

ObjectException Ifthe object was local and was fetched in a previous transaction.

ObjectStoreException If the session implied by an argument to the call or the object the method is called on is not the same as the session associated with the current thread.

UpdateReadOnlyException If there is a readonly transaction in progress or if the database is open for readonly.

See Also:

IPersistent, Set

OSTreeSet(Placement)

Create a new, empty OSTreeSet.

OSTreeSet(Placement, boolean)

Create a new, empty OSTreeSet, and specify whether or not it should be exported.

add(Object)

Ensures that this Collection contains the specified element.

addIndex(Class, String)

Adds an index to a collection.

addIndex(Class, String, boolean, boolean)

Adds an index to a collection.

addIndex(Class, String, boolean, boolean, Placement)

Adds an index to a collection.

addToIndex(Class, String, Object)

Update a mapping for the given value, in the index specified by the given path.

addToIndex(Object)

Update a mapping for the given value, in all indexes on this collection.

clear()

Removes all of the elements from this Collection.

contains(Object)

Returns true if this Collection contains the specified element.

dropIndex(Class, String)

Drop (remove) an index from a collection, if present.

getIndex(Class, String, boolean)

Return an index on a collection that can participate in the execution of the specified kind of query.

getIndexes()

Return a collection of IndexDescriptors, describing the indexes on this collection.

getSuperIndex(Class, String, boolean)

Return an index on a collection that can participate in the execution of the specified kind of query, even if the index is on a supertype or superinterface of the specified elementType.

hasIndex(Class, String, boolean)

Test this collection for the presence of an index that can participate in the execution of the specified kind of query.

isEmpty()

Returns true if this Collection contains no elements.

isSizeMaintained()

Determines if this set maintains its size.

iterator()

Returns an Iterator over the elements in this Collection.

maintainSize(boolean)

Modifies the set to maintain or not maintain information about its size.

remove(Object)

Removes the specified element from this Collection, if it is present.

removeFromIndex(Class, String, Object)

Remove the mapping for the given value, in the index specified by the path argument.

removeFromIndex(Object)

Remove the mapping for the given value, in all indexes on this collection.

size()

Returns the number of elements in this Collection.

sizeEstimate()

For sets that do not maintain their size, returns the size computed by the last call to size().

toArray()

Returns an array containing all of the elements in this Collection.

updateIndex(Class, String, Object, Object, Object)

Update a mapping in the index specified by the given path, by removing the current key/value mapping, and adding a new key/value mapping.

  public OSTreeSet(Placement placement)

Create a new, empty OSTreeSet.

  public OSTreeSet(Placement placement,
                   boolean export)

Create a new, empty OSTreeSet, and specify whether or not it should be exported.

  public int size()

Returns the number of elements in this Collection.

Overrides:

size in class OSAbstractSet

  public int sizeEstimate()

For sets that do not maintain their size, returns the size computed by the last call to size(). For other sets, does the same thing as size().

Returns:

The estimated size.

See Also:

isSizeMaintained, maintainSize

  public boolean isSizeMaintained()

Determines if this set maintains its size.

Returns:

True if the set maintains its size, otherwise false.

See Also:

sizeEstimate, maintainSize

  public void maintainSize(boolean maintainSize)

Modifies the set to maintain or not maintain information about its size. Sets maintain their size by default. For sets that maintain their size, putting or removing entries from the set requires a write lock on the top of the tree, which produces a concurrency hot-spot when using ObjectStore. Sets that do not maintain their size do not have this concurrency problem for putting or removing entries, but need to scan the entire tree to determine the size.

Note that iterators on sets which do not maintain their size do not detect concurrent modifications.

Parameters:

maintainSize - If true, causes the set to maintain its size. If false, causes the set to not maintain its size.

See Also:

sizeEstimate, isSizeMaintained

  public boolean isEmpty()

Returns true if this Collection contains no elements.

Overrides:

isEmpty in class OSAbstractSet

  public boolean contains(Object o)

Returns true if this Collection contains the specified element. More formally, returns true if and only if this Collection contains at least one element e such that o.equals(e).

Parameters:

o - element whose presence in this Collection is to be tested.

Overrides:

contains in class OSAbstractSet

  public Iterator iterator()

Returns an Iterator over the elements in this Collection.

Overrides:

iterator in class OSAbstractSet

  public Object[] toArray()

Returns an array containing all of the elements in this Collection. The returned array will be "safe" in that no references to it are maintained by the Collection. (In other words, this method must allocate a new array even if the Collection is backed by an Array). The caller is thus free to modify the returned array.

This method acts as bridge between array-based and Collection-based APIs.

Overrides:

toArray in class OSAbstractSet

  public boolean add(Object o)

Ensures that this Collection contains the specified element. Returns true if the Collection changed as a result of the call. Returns false if this Collection already contains the specified element.

Parameters:

o - element whose presence in this Collection is to be ensured.

Returns:

true if the Collection changed as a result of the call.

Throws: IllegalArgumentException

if the specified object o is null.

Throws: DuplicateKeyException

if this Collection has an index that does not allow duplicate keys, and the addition of this element would result in a duplicate key.

Overrides:

add in class OSAbstractSet

  public boolean remove(Object o)

Removes the specified element from this Collection, if it is present. More formally, removes an element e such that o.equals(e), if the Collection contains such an element. Returns true if the Collection contained the specified element (or equivalently, if the Collection changed as a result of the call).

Parameters:

o - element to be removed from this Collection, if present.

Returns:

true if the Collection changed as a result of the call.

Overrides:

remove in class OSAbstractSet

  public void clear()

Removes all of the elements from this Collection. The Collection will be empty after this call returns.

Overrides:

clear in class OSAbstractSet

  public void addIndex(Class elementType,
                       String path)

Adds an index to a collection. The index defaults to unordered, and to allow duplicate keys. The index will be stored in the same database and segment as the collection.

Parameters:

elementType - The type to which the given path applies.

path - The name of the member to be indexed.

Throws: DuplicateIndexException

if the collection already has an index using this elementType and path (even if it has different behavior regarding duplicates and support for ordered queries).

Throws: IllegalArgumentException

If the elementType or path is null.

Throws: IndexException

If the given path is does not exist or is not public, or if the keytype of the result of the path evaluation cannot be used as the key in any available index type.

  public void addIndex(Class elementType,
                       String path,
                       boolean ordered,
                       boolean duplicates)

Adds an index to a collection. The index will be stored in the same database and segment as the collection.

Parameters:

elementType - The type to which the given path applies.

path - The name of the member to be indexed.

ordered - True indicates that the index must support ordered queries; false indicates that it need not support ordered queries.

duplicates - True indicates that the index should allow duplicate keys; false indicates that an exception should be thrown if a duplicate key is encountered.

Throws: IllegalArgumentException

If the elementType or path is null.

Throws: IndexException

If the given path does not exist or is not public, or if the keytype of the result of the path evaluation cannot be used as the key in any available index type.

Throws: DuplicateIndexException

if the collection already has an index using this elementType and path (even if it has different behavior regarding duplicates and support for ordered queries).

Throws: DuplicateKeyException

if the index does not allow duplicate keys, and a duplicate key is encountered while building the index.

  public void addIndex(Class elementType,
                       String path,
                       boolean ordered,
                       boolean duplicates,
                       Placement placement)

Adds an index to a collection.

Parameters:

elementType - The type to which the given path applies.

path - The name of the member to be indexed.

ordered - True indicates that the index must support ordered queries; false indicates that it need not support ordered queries.

duplicates - True indicates that the index should allow duplicate keys; false indicates that an exception should be thrown if a duplicate key is encountered. Duplicates occur if a collection contains two elements, both of which have the same value for an indexed member.

Throws: DuplicateIndexException

if the collection already has an index using this elementType and path (even if it has different behavior regarding duplicates and support for ordered queries).

Throws: DuplicateKeyException

if the index does not allow duplicate keys, and a duplicate key is encountered while building the index.

Throws: IllegalArgumentException

If the elementType or path is null.

Throws: IndexException

If the given path does not exist or is not public, or if the keytype of the result of the path evaluation cannot be used as the key in any available index type.

  public boolean dropIndex(Class elementType,
                           String path)

Drop (remove) an index from a collection, if present.

Parameters:

elementType - The type to which the given path applies.

path - The name of the member specifying the index.

Returns:

true if there was a matching index to drop; false if no matching index was present.

Throws: IllegalArgumentException

if the Path or elementType is null.

  public boolean hasIndex(Class elementType,
                          String path,
                          boolean ordered)

Test this collection for the presence of an index that can participate in the execution of the specified kind of query.

Parameters:

elementType - The type to which the given path applies.

path - The name of the member specifying the index.

ordered - True indicates that this method should return true only if there is an ordered index on this collection; false indicates that this method should return true if there is any index on this collection with this path (ordered or unordered).

Returns:

true if this collection has an index on the specified path, meeting the ordering requirements specified by the ordered parameter; false if no matching index is available.

Throws: IllegalArgumentException

if the path or elementType is null.

  public IndexMap getIndex(Class elementType,
                           String path,
                           boolean ordered)

Return an index on a collection that can participate in the execution of the specified kind of query. If no such index exists, null is returned.

Parameters:

elementType - The type to which the given path applies.

path - The name of the member specifying the index.

ordered - True indicates that the returned index must support ordered lookup. False indicates that the returned index need not support ordered lookup.

Returns:

The index on the specified path, meeting the ordering requirements specified by the ordered parameter, if such an index is available; null if no matching index is available.

Throws: IllegalArgumentException

if the path or elementType is null.

  public IndexMap getSuperIndex(Class elementType,
                                String path,
                                boolean ordered)

Return an index on a collection that can participate in the execution of the specified kind of query, even if the index is on a supertype or superinterface of the specified elementType. If no such index exists, null is returned.

Parameters:

elementType - The type to which the given path applies.

path - The name of the member specifying the index.

ordered - True indicates that the returned index must support ordered lookup. False indicates that the returned index need not support ordered lookup.

Returns:

The index on the specified path, meeting the ordering requirements specified by the ordered parameter, if such an index is available; null if no matching index is available.

Throws: IllegalArgumentException

if the path or elementType is null.

  public IndexDescriptorSet getIndexes()

Return a collection of IndexDescriptors, describing the indexes on this collection. This is normally called to get a set of index descriptors that can be passed to Query.optimize().

Returns:

A collection of IndexDescriptors, describing the indexes on this collection. If this collection does not have any indexes, null is returned.

  public void removeFromIndex(Object value)

Remove the mapping for the given value, in all indexes on this collection. This is typically called to accomplish index update when one or more possibly indexed fields are about to be modified. Note that a call to addToIndex() should also be made, after any field modification.

Parameters:

value - The value to be removed from any index mappings.

Throws: NoSuchElementException

the the value is not an element of this collection.

  public void removeFromIndex(Class elementType,
                              String path,
                              Object value)

Remove the mapping for the given value, in the index specified by the path argument. This is typically called to accomplish index update when one or more possibly indexed fields are about to be modified. Note that a call to addToIndex() should also be made, after any field modification.

Parameters:

elementType - The type to which the given path applies.

path - The name of the member specifying the index.

value - The value to be removed from this index.

Throws: NoSuchElementException

the the value is not an element of this collection.

Throws: IllegalArgumentException

If the elementType, the path or the value is null.

Throws: IndexException

If the path does not exist or is not public.

  public void addToIndex(Object value)

Update a mapping for the given value, in all indexes on this collection. This is typically called to accomplish index update after one or more possibly indexed fields have been modified. Note that a call to removeFromIndex() should also be made, before any field modification.

Parameters:

value - The value to be updated in any index mappings.

Throws: NoSuchElementException

the the value is not an element of this collection.

Throws: DuplicateKeyException

if any index does not allow duplicate keys, and a value with the same key is already present in this collection.

  public void addToIndex(Class elementType,
                         String path,
                         Object value)

Update a mapping for the given value, in the index specified by the given path. This is typically called to accomplish index update after one or more possibly indexed fields have been modified. Note that a call to removeFromIndex() should also be made, before any field modification.

Parameters:

elementType - The type to which the given path applies.

path - The name of the member specifying the index.

value - The value to be updated in any index mappings.

Throws: NoSuchElementException

If the value is not an element of this collection.

Throws: DuplicateKeyException

If the index does not allow duplicate keys, and a value with the same key is already present in this collection.

Throws: IndexException

If the path does not exist or is not public.

Throws: IllegalArgumentException

If the elementType or the path is null.

  public void updateIndex(Class elementType,
                          String path,
                          Object oldKey,
                          Object newKey,
                          Object value)

Update a mapping in the index specified by the given path, by removing the current key/value mapping, and adding a new key/value mapping.

Parameters:

elementType - The type to which the given path applies.

path - The name of the member specifying the index.

oldKey - The previous key, to be removed.

newKey - The new key, to be added.

value - The value to be updated.

Throws: NoSuchElementException

the the value is not an element of this collection, or if oldKey does not currently map to the value.

Throws: DuplicateKeyException

if the index does not allow duplicate keys, and newKey already present as a key in this collection.

Throws: IllegalArgumentException

if the elementType or the path is null.

Throws: IndexException

If the path does not exist or is not public.