Interface COM.odi.coll.Collection

public interface Collection

extends IPersistent

Use the NewCollection methods to create ObjectStore collections. These methods create Java peer objects that represent persistent C++ collections; you cannot create transient collections.

Transient collections are considered read-only. Any attempt to modify a transient collection throws ModifyTransientCollectionException. Also, queries are only supported on persistent collections.

Any attempt to store a transient primary object into a collection causes the object to first be migrated to the collection's segment, as an unexported object. Any attempt to store a primary unexported persistent object whose segment is not the same as the collection's segment throws ObjectNotExportedException.

Unlike java.lang.Vector, a search for an object in a collection uses == for comparison, rather than Object.equals(). For example, Collection.remove(Object o) removes the object o itself, and not any other object that equals o.

In the coll package, the same exceptions might be thrown in almost all of the methods. These exceptions are described here instead of repeating the information for each method.

For all methods:

COM.odi.NoTransactionInProgressException If there is no transaction in progress.

For static methods:

COM.odi.ObjectStoreException If the current thread is not associated with a session and there is no global session.

For instance methods:

COM.odi.ObjectStoreException If the session implied by an argument to the call or the object the method is called on has been terminated or if the current thread is associated with a session other than the session implied by the argument to the call or the object the method is called on.

For methods that modify persistent objects:

COM.odi.UpdateReadOnlyException If there is a read-only transaction in progress or if the database is open for read-only.

See Also:

Array, Bag, Dictionary_int, Dictionary_String, List, Set

ALLOW_NULLS

This flag controls whether or not null is allowed as an element of the collection.

MAINTAIN_CURSORS

This must be specified for the collection to have safe cursors.

PICK_FROM_EMPTY_RETURNS_NULL

This flag controls what happens when a pick() method is invoked on an empty collection.

SIGNAL_DUPLICATES

This flag controls the behavior when an operation attempts to insert a duplicate element into a collection that does not permit duplicates.

addIndex(Path)

Adds an index to a collection.

addIndex(Path, int)

Adds an index to a collection, specifying options.

addIndex(Path, int, Placement)

Adds an index to a collection, specifying options and placement.

cardinality()

Returns the number of elements in the collection.

cardinalityEstimate()

If the collection does not maintain cardinality, returns the collection's "estimated cardinality".

cardinalityIsMaintained()

Indicates whether or not the collection maintains a variable that holds the cardinality.

changeBehavior(int, boolean)

Changes the behavior of this class to be as described by the collection behavior flags provided.

clear()

Removes all elements from the collection; this makes the collection empty.

contains(Object)

Indicates whether or not the specified object is in the collection.

count(Object)

Indicates the number of elements in the collection that are the specified object.

differenceWith(Collection)

Subtracts the contents of c from this collection.

dropIndex(Path)

Drop (remove) an index from a collection.

elements()

Creates an enumeration of the elements in this collection.

empty()

Returns true if the collection is empty (has no elements).

equals(Collection)

Indicates whether or not the specified collection is the same as this collection.

exists(BoundQuery)

Queries a collection to determine if any elements in the collection satisfy the query expression.

exists(String, String)

Queries a collection to determine if any elements in the collection satisfy the query expression.

getBehavior()

Obtains the behavior flags for this collection.

hasIndex(Path, int)

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

insert(Object)

Inserts an element into the collection.

intersectionWith(Collection)

Makes this collection be the intersection of this collection and the specified collection.

newCursor(int)

Creates a new cursor, associated with this collection, with the specified flags.

only()

Returns the one and only element of the collection.

pick()

Returns any one element of the collection.

properSubset(Collection)

Indicates whether or not c is a proper subset of this collection.

query(BoundQuery)

Queries a collection and returns a newly-created transient collection that contains all elements found and does not contain duplicates.

query(BoundQuery, boolean)

Queries a collection and returns a newly-created transient collection that contains all elements found and might contain duplicates.

query(String, String)

Queries a collection and returns a newly-created transient collection that contains all elements found and does not contain duplicates.

query(String, String, boolean)

Queries a collection and returns a newly-created transient collection that contains all elements found and might contain duplicates.

queryPick(BoundQuery)

Queries a collection and returns one element that satisfies the query string.

queryPick(String, String)

Queries a collection and returns one element that satisfies the query string.

remove(Object)

Removes an element from the collection.

retrieve(Cursor)

Returns the object in the collection that the cursor is positioned at.

set(Collection)

Sets the contents of this collection to be the same as the contents of c.

subset(Collection)

Indicates whether or not the specified collection is a subset of this collection.

unionWith(Collection)

Adds the contents of the c collection to this collection.

updateCardinality()

If the collection does not maintain cardinality, computes the current cardinality and stores it in the "estimated cardinality" variable.

  public final static int MAINTAIN_CURSORS

This must be specified for the collection to have safe cursors. You might use safe cursors when you want to update a collection while you are iterating through it. A safe cursor ensures that the iteration visits elements added since the cursor was bound to the collection and does not visit elements removed since the cursor was bound to the collection. Also, you can reposition a safe cursor if it becomes invalid.

  public final static int SIGNAL_DUPLICATES

This flag controls the behavior when an operation attempts to insert a duplicate element into a collection that does not permit duplicates. If the flag is not specified, the default, then the insertion does nothing. If the flag is specified, ObjectStore throws DuplicateEntryException. For collections that permit duplicates, the flag has no effect.

  public final static int ALLOW_NULLS

This flag controls whether or not null is allowed as an element of the collection. By default, sets, bags, and lists do not allow null elements, while arrays do allow null elements. If this flag is specified, the collection allows null elements.

  public final static int PICK_FROM_EMPTY_RETURNS_NULL

This flag controls what happens when a pick() method is invoked on an empty collection. If this flag is specified, the pick() method returns null. If this flag is not specified, NoSuchElementException is thrown.

  public abstract void clear()

Removes all elements from the collection; this makes the collection empty.

  public abstract void insert(Object o)

Inserts an element into the collection. If the object is not already persistent, ObjectStore tries to migrate it into the segment that contains the collection. If the collection is ordered, ObjectStore inserts the element at the end of the collection.

Parameters:

o - The element to insert.

Throws: CollectionException

If this collection is a dictionary or if the object being inserted is a Java peer object that identifies a transient C++ object.

Throws: DuplicateEntryException

If the collection does not allow duplicates and the object being inserted is already in the collection.

Throws: IllegalArgumentException

If the object is null and ALLOW_NULLS is not specified for the collection.

Throws: ModifyTransientCollectionException

If the collection is transient.

Throws: ObjectNotExportedException

If the collection and the object being inserted are in different segments and the object is not exported.

Throws: ObjectNotPersistenceCapableException

If the object is not persistence-capable.

  public abstract boolean remove(Object o)

Removes an element from the collection. The element must be exactly the specified object, and not any object equal to it, unlike java.util.Vector. If there are many elements in the collection that are the same object as the specified argument, remove any one of them. If this is a dictionary, remove any one of them regardless of the associated key.

Returns:

True if the object was found and removed. False if the object was not found in the collection.

Throws: ModifyTransientCollectionException

If the collection is transient.

  public abstract Object retrieve(Cursor c)

Returns the object in the collection that the cursor is positioned at. This method does not modify the collection.

Returns:

The object pointed to by the cursor.

Throws: InvalidCursorException

If the cursor is invalid.

Throws: NullCursorException

If the cursor is null.

  public abstract Object pick()

Returns any one element of the collection. This method does not modify the collection. If the collection is empty, this method either returns null or throws NoSuchElementException. The behavior depends on whether or not PICK_FROM_EMPTY_RETURNS_NULL is set.

Returns:

An element of the collection.

Throws: NoSuchElementException

If the collection is empty and PICK_FROM_EMPTY_RETURNS_NULL behavior is off.

  public abstract Object only()

Returns the one and only element of the collection. This method does not modify the collection. If the collection is empty, this method either returns null or throws NoSuchElementException. The behavior depends on whether or not PICK_FROM_EMPTY_RETURNS_NULL is set.

Returns:

The element of the collection.

Throws: NoSuchElementException

If the collection is empty and PICK_FROM_EMPTY_RETURNS_NULL behavior is off.

Throws: NotSingletonException

If the collection has more than one element.

  public abstract boolean contains(Object o)

Indicates whether or not the specified object is in the collection.

Returns:

true if the collection contains the specified object. false if it does not.

  public abstract int count(Object o)

Indicates the number of elements in the collection that are the specified object. This counts only this exact object; it does not count other objects that are equal to it.

Returns:

The number of times the specified object appears in the collection.

  public abstract int cardinality()

Returns the number of elements in the collection.

  public abstract boolean empty()

Returns true if the collection is empty (has no elements).

  public abstract boolean cardinalityIsMaintained()

Indicates whether or not the collection maintains a variable that holds the cardinality. In some of the underlying representations of collections, the cardinality (number of objects in the collection) is not maintained. This means that it is not stored in a variable, and must be dynamically computed, at some computational expense. These representations maintain a state variable called the "estimated cardinality", which is a snapshot of the actual cardinality at some time in the past.

Returns:

True if this collection maintains cardinality.

  public abstract int updateCardinality()

If the collection does not maintain cardinality, computes the current cardinality and stores it in the "estimated cardinality" variable.

Returns:

The cardinality of the collection.

  public abstract int cardinalityEstimate()

If the collection does not maintain cardinality, returns the collection's "estimated cardinality". Otherwise, returns the collection's cardinality.

  public abstract void set(Collection c)

Sets the contents of this collection to be the same as the contents of c. This makes the collection empty, and then inserts each of the elements of c into the collection. This operation is not allowed for dictionaries, but the dictionary classes provide their own overloading to allow a dictionary to be set from another dictionary of the same type.

Parameters:

c - The collection whose elements you want to place in the collection.

Throws: CollectionException

If this collection is a dictionary.

Throws: ModifyTransientCollectionException

If the collection is transient.

Throws: ObjectNotExportedException

If there are objects in the collection argument that are not exported and are stored in a different segment from this collection.

  public abstract void unionWith(Collection c)

Adds the contents of the c collection to this collection. In other words, this method makes this collection be the union of this collection and c. For each element in c, if the element is not already a member of this collection, this method inserts the element into this collection.

If this collection is a bag (bags allow duplicates), this method adds each element in c to the bag. For example, suppose element e appears twice in the bag and once in c. The result is that there are three instances of e in the bag. This operation is not allowed on dictionaries.

Parameters:

c - The collection whose elements you want to add to this collection.

Throws: CollectionException

If this collection is a dictionary.

Throws: ModifyTransientCollectionException

If the collection is transient.

Throws: ObjectNotExportedException

If there are objects in the collection argument that are not exported and are stored in a different segment from this collection.

  public abstract void intersectionWith(Collection c)

Makes this collection be the intersection of this collection and the specified collection. For each element in c, if the element is not a member of this collection, this method removes the element from this collection. The result is a collection in which each element is also an element in c. This operation is not allowed on dictionaries.

Parameters:

c - The collection whose elements are the only elements that can be in this collection.

Throws: CollectionException

If this collection is a dictionary.

Throws: ModifyTransientCollectionException

If the collection is transient.

  public abstract void differenceWith(Collection c)

Subtracts the contents of c from this collection. The result is a collection that does not include any elements that are included in c. For each element in c, if the element is a member of this collection, this method removes the element from this collection. This operation is not allowed on dictionaries.

Parameters:

c - The collection whose elements cannot be in this collection.

Throws: CollectionException

If this collection is a dictionary.

Throws: ModifyTransientCollectionException

If the collection is transient.

  public abstract boolean equals(Collection c)

Indicates whether or not the specified collection is the same as this collection. Two collections are equal if they have the same number of elements, and the same elements. If duplicates are allowed, the number of each duplicate element must be the same in each collection. For dictionaries, this operation pays no attention to keys.

It is possible to cast both collections to Object and then use the Object.equals() method. This alternative and the equals() method have the same effect. This method is simply more convenient.

Returns:

true if the collections are equal. false if they are not equal.

  public abstract boolean subset(Collection c)

Indicates whether or not the specified collection is a subset of this collection. Collections can have duplicates, so the meaning of subset is extended as follows. c is a subset of this when for all e in c, the count of e in c is less than or equal to the count of e in this. For dictionaries, this operation pays no attention to keys.

Parameters:

c - The collection for which you want to determine if its elements are a subset of this collection.

Returns:

true if c is a subset of this collection.

  public abstract boolean properSubset(Collection c)

Indicates whether or not c is a proper subset of this collection. A proper subset is a collection that is a subset of this collection but is not equal to this collection. For dictionaries, this operation pays no attention to keys.

Parameters:

c - The collection for which you want to determine if its elements are a proper subset of this collection.

Returns:

true if c is a proper subset of this collection.

  public abstract int getBehavior()

Obtains the behavior flags for this collection. Only the flags defined symbolically in this interface should be considered meaningful.

Throws: CollectionException

If this collection is a dictionary.

  public abstract void changeBehavior(int behavior,
                                      boolean verify)

Changes the behavior of this class to be as described by the collection behavior flags provided.

Your application should always call getBehavior() to obtain the current behavior. It should then call changeBehavior() and modify the flags of interest in the result from getBehavior(). This avoids inadvertently changing any flags.

Parameters:

behavior - An integer specifying zero or more behavior flags.

verify - If true, and the collection is being changed from allowing nulls to not allowing nulls, then examine the collection to see whether there are any nulls, and if there are any, throw IllegalArgumentException. In this case, the behavior is not changed.

Throws: CollectionException

If this collection is a dictionary.

Throws: IllegalArgumentException

If there are any nulls in the collection and the behavior of the collection is being changed to not allowing nulls.

Throws: ModifyTransientCollectionException

If the collection is transient.

  public abstract Collection query(String elementType,
                                   String query)

Queries a collection and returns a newly-created transient collection that contains all elements found and does not contain duplicates. When you are finished with the resulting collection, you should call ObjectStore.destroy() on it to free the C++ transient storage.

If the query finds an element more than once, it inserts the element into the result collection only once.

Parameters:

elementType - A fully-qualified Java class name. Every element of this collection must be an instance of (in the sense of instanceOf) the named class. The instance variables used in the query string can be public, protected, or private instance variables of the class.

query - The query string.

Returns:

A transient collection that contains the elements found.

  public abstract Collection query(String elementType,
                                   String query,
                                   boolean duplicates)

Queries a collection and returns a newly-created transient collection that contains all elements found and might contain duplicates. When you are finished with the resulting collection, you should call ObjectStore.destroy() on it to free the C++ transient storage.

If the query finds an element more than once, it uses the value of the duplicates parameter to determine whether or not to insert duplicates.

Parameters:

elementType - A fully-qualified Java class name. Every element of this collection must be an instance of (in the sense of instanceOf) the named class. The instance variables used in the query string can be public, protected, or private instance variables of the class.

query - The query string.

duplicates - What to do if some element is found more than once by the query. If this is false, only insert the element into the result collection once. If this is true, insert each occurrence of the element into the result collection.

Returns:

A transient collection that contains the elements found.

  public abstract Object queryPick(String elementType,
                                   String query)

Queries a collection and returns one element that satisfies the query string. If any elements are found, picks one arbitrarily and returns it. Otherwise, returns null.

Parameters:

elementType - A fully-qualified Java class name. Every element of this collection must be an instance of (in the sense of instanceOf) the named class. The instance variables used in the query string can be public, protected, or private instance variables of the class.

query - The query string.

  public abstract boolean exists(String elementType,
                                 String query)

Queries a collection to determine if any elements in the collection satisfy the query expression. Returns true if any elements are found. Otherwise, returns false.

Parameters:

elementType - A fully-qualified Java class name. Every element of this collection must be an instance of (in the sense of instanceOf) the named class. The instance variables used in the query string can be public, protected, or private instance variables of the class.

query - The query string.

  public abstract Collection query(BoundQuery boundQuery)

Queries a collection and returns a newly-created transient collection that contains all elements found and does not contain duplicates. When you are finished with the resulting collection, you should call ObjectStore.destroy() on it to free the C++ transient storage.

If the query finds an element more than once, it inserts the element into the result collection only once.

Parameters:

boundQuery - A BoundQuery with all of its free variables bound.

Returns:

A transient collection that contains the elements found.

Throws: BoundQueryException

If there are missing, extraneous, or duplicate bindings.

  public abstract Collection query(BoundQuery boundQuery,
                                   boolean duplicates)

Queries a collection and returns a newly-created transient collection that contains all elements found and might contain duplicates. When you are finished with the resulting collection, you should call ObjectStore.destroy() on it to free the C++ transient storage.

If the query finds an element more than once, it uses the value of the duplicates parameter to determine whether or not to insert duplicates.

Parameters:

boundQuery - A BoundQuery with all of its free variables bound.

duplicates - What to do if some element is found more than once by the query. If this is false, only insert the element into the result collection once. If this is true, insert each occurrence of the element into the result collection.

Returns:

A transient collection that contains the elements found.

Throws: BoundQueryException

If there are missing, extraneous, or duplicate bindings.

  public abstract Object queryPick(BoundQuery boundQuery)

Queries a collection and returns one element that satisfies the query string. If any elements are found, picks one arbitrarily and returns it. Otherwise, returns null.

Parameters:

boundQuery - A BoundQuery with all of its free variables bound.

Returns:

The specified element of the collection.

Throws: BoundQueryException

If there are missing, extraneous, or duplicate bindings.

  public abstract boolean exists(BoundQuery boundQuery)

Queries a collection to determine if any elements in the collection satisfy the query expression. Returns true if any elements are found. Otherwise, returns false.

Parameters:

boundQuery - A BoundQuery with all of its free variables bound.

Returns:

True if the any element is found, otherwise false.

Throws: BoundQueryException

If there are missing, extraneous, or duplicate bindings.

  public abstract void addIndex(Path path)

Adds an index to a collection. ObjectStore stores the index in the same segment as the collection to which the index is being added.

Parameters:

path - The index path. You must have previously created this transient object with the COM.odi.Path.create() method.

  public abstract void addIndex(Path path,
                                int options)

Adds an index to a collection, specifying options. ObjectStore stores the index in the same segment as the collection to which the index is being added.

Parameters:

path - The index path. You must have previously created this transient object with the COM.odi.Path.create() method.

options - The option bits, OR'ed together. The basic option values are provided in the Path class.

  public abstract void addIndex(Path path,
                                int options,
                                Placement placement)

Adds an index to a collection, specifying options and placement.

Parameters:

path - The index path. You must have previously created this transient object with the COM.odi.Path.create() method.

options - The option bits, OR'ed together. The basic option values are provided in the Path class.

placement - Where the index itself should be stored.

  public abstract void dropIndex(Path path)

Drop (remove) an index from a collection.

  public abstract boolean hasIndex(Path path,
                                   int options)

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

Parameters:

path - The path specifying the index to ask about.

options - This should be either Path.ORDERED or Path.UNORDERED. Path.ORDERED means that hasIndex should return true only if the index exists and can participate in ordered (inequality) queries. Path.UNORDERED means that hasIndex should return true only if the index exists and can participate in ordered (equality) queries. Note that ORDERED indexes can participate in UNORDERED queries.

  public abstract Enumeration elements()

Creates an enumeration of the elements in this collection. If the collection is modified while the enumeration is in progress, the behavior of enumeration is unspecified.

  public abstract Cursor newCursor(int flags)

Creates a new cursor, associated with this collection, with the specified flags. The meaningful flags are drawn from the values specified for the Cursor.SAFE, Cursor.ORDER_BY_ADDRESS, and Cursor.UPDATE_INSENSITIVE constants, OR'ed together. The cursor is always transient; persistent cursors are not supported.

When you create a safe cursor, ObjectStore modifies the database. Consequently, the database that contains the collection must be open for update, an update transaction must be in progress, and you must have permission to modify the database.

All cursors need to be destroyed when an application is done with them. This releases the transient C++ objects associated with the cursor. Not destroying a cursor causes a memory leak in the C++ heap. If it is a safe cursor, you must destroy it before you commit the transaction or ObjectStore throws CollectionException.

You cannot specify ORDER_BY_ADDRESS for a dictionary.

Parameters:

flags - The flag bits describing this cursor's properties.

Throws: UpdateReadOnlyException

If you try to create a safe cursor and the database is not open for update, or the transaction is not an update transaction.

See Also:

Cursor