Interface COM.odi.util.IndexedCollection

public interface IndexedCollection

extends Collection

Additional information about indexes is in the user guide.

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

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.

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.

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.

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 abstract void addIndex(Class elementType,
                                String path)

Adds an index to a collection. The index defaults to unordered, and to allow duplicate keys. PSE Pro stores the index 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: 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 implementaton.

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).

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

Adds an index to a collection. PSE Pro stores the index 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. Duplicates occur if a collection contains two elements, both of which have the same value for an indexed member.

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 implementaton.

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 abstract 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.

placement - The database or segment in which the index should be allocated.

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 implementaton.

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 abstract 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 elementType or Path is null.

  public abstract 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 abstract 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 abstract 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 abstract 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 abstract 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.

Use this overloading when you do not know what indexes might exist, or you modified a lot of different fields and you want to update all indexes. Use the longer overloading when you know which index you want to update.

A call to removeFromIndex() followed by a call to addToIndex() has the same result as a single call to updateIndex(). The difference is that removeFromIndex() and addToIndex() inspect the value to determine the key. That is, they apply the index's path expression to obtain the key from the value. With updateIndex(), you pass in the old key and the new key. PSE Pro does not need to inspect the value to determine its key.

Parameters:

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

Throws: NoSuchElementException

the the value is not an element of this collection.

  public abstract 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. Use this overloading when you know which index you want to update. Use the shorter overloading when you do not know what indexes might exist, or you modified a lot of different fields and you want to update all indexes.

A call to removeFromIndex() followed by a call to addToIndex() has the same result as a single call to updateIndex(). The difference is that removeFromIndex() and addToIndex() inspect the value to determine the key. That is, they apply the index's path expression to obtain the key from the value. With updateIndex(), you pass in the old key and the new key. PSE Pro does not need to inspect the value to determine its key.

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 abstract 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. Use this overloading when you do not know what indexes might exist, or you modified a lot of different fields and you want to update all indexes. Use the longer overloading when you know which index you want to update.

A call to removeFromIndex() followed by a call to addToIndex() has the same result as a single call to updateIndex(). The difference is that removeFromIndex() and addToIndex() inspect the value to determine the key. That is, they apply the index's path expression to obtain the key from the value. With updateIndex(), you pass in the old key and the new key. PSE Pro does not need to inspect the value to determine its key.

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.

Throws: IndexException

If the path does not exist or is not public.

  public abstract 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.

Use this overloading when you know which index you want to update. Use the shorter overloading when you do not know what indexes might exist, or you modified a lot of different fields and you want to update all indexes.

A call to removeFromIndex() followed by a call to addToIndex() has the same result as a single call to updateIndex(). The difference is that removeFromIndex() and addToIndex() inspect the value to determine the key. That is, they apply the index's path expression to obtain the key from the value. With updateIndex(), you pass in the old key and the new key. PSE Pro does not need to inspect the value to determine its key.

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

the 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 abstract 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. A call to removeFromIndex() followed by a call to addToIndex() has the same result as a single call to updateIndex(). The difference is that removeFromIndex() and addToIndex() inspect the value to determine the key. That is, they apply the index's path expression to obtain the key from the value. With updateIndex(), you pass in the old key and the new key. PSE Pro does not need to inspect the value to determine its key.

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

If 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.