Objectivity for Java Reference

com.objy.db.util
Class ooCollection

java.lang.Object
  |
  +--com.objy.db.app.ooAbstractObj
        |
        +--com.objy.db.app.ooObj
              |
              +--com.objy.db.util.ooCollection
All Implemented Interfaces:
IooObj, Persistent, PersistentEvents
Direct Known Subclasses:
ooBTree, ooHashMap, ooHashSet

public abstract class ooCollection
extends ooObj

Abstract superclass for persistence-capable classes that represent scalable collections containing persistent objects.

API Summary

A collection is an aggregate that can contain a variable number of elements. A scalable collection can increase in size with minimal performance degradation.

Concrete classes derived from this class represent more specific kinds of scalable collections of persistent objects and collections of key-value pairs: lists of persistent objects, unordered sets of persistent objects, sorted sets of persistent objects, unordered object maps, and sorted object maps. (An object map is a collection of key-value pairs in which both the key and the value are persistent objects.)

Because this class is abstract, you never instantiate it; instead, you work with instances of its concrete derived classes. You should not create your own subclasses of this class.

Related Classes

An instance of any class derived from ooCollection except ooTreeList has an associated comparator, an instance of a concrete subclass of ooCompare.

Objectivity for Java includes one additional persistence-capable collection class that is not derived from ooCollection. ooMap represents a collection of key-value pairs in which the key is a string and the value is a persistent object. For information about the difference among the various persistence-capable collection classes, see Persistent Collections. For information about retrieving persistent objects from the various kinds of persistent collections, see Retrieving Elements of a Persistent Collection.

API Summary

Functionality
Adding and Removing Elements add(Object)
ooAddAll(ooCollection)
ooRemove(Object)
ooRemoveAll(ooCollection)
ooRetainAll(ooCollection)
removeAllDeleted()
clear()
Getting Elements ooIterator()
keyIterator()
toArray()
toArray(Object[])
Getting Information size()
comparator()
Testing isEmpty()
contains(Object)
ooContainsAll(ooCollection)
Viewing in an MROW Transaction refresh(int)


Field Summary
 ooCompare _comparator
          Reserved for internal use.
 
Method Summary
 boolean add(Object object)
          Adds the specified object to this collection.
 void clear()
          Sets this collection to an empty collection, removing any elements it contains.
 Comparator comparator()
          Gets the comparator for this collection.
 boolean contains(Object object)
          Tests whether this collection contains the specified object.
 Object copy(Object near)
          Overrides the inherited method; disallows copying for collections.
protected  com.objy.pm.ooScalableCollectionsPersistor getCollectionPersistor()
          Reserved for internal use; you should not call this method.
 boolean isEmpty()
          Tests whether this collection is empty.
 ooCollectionIterator keyIterator()
          Initializes a collection iterator to find the keys or elements of this collection.
 boolean ooAddAll(ooCollection collection)
          Adds all elements (or keys) in the specified collection to this collection.
 boolean ooContainsAll(ooCollection collection)
          Tests whether this collection contains all elements (or keys) in the specified collection.
 ooCollectionIterator ooIterator()
          Initializes a collection iterator to find the elements of this collection.
abstract  boolean ooRemove(Object object)
          Removes the first occurrence of the specified object from this collection.
 boolean ooRemoveAll(ooCollection collection)
          Removes all elements (or keys) of the specified collection from this collection.
 boolean ooRetainAll(ooCollection collection)
          Retains all elements of this collection that are also in the specified collection, deleting all other elements.
 void refresh(int mode)
          Refreshes each container used internally by this collection, except for the container in which the collection itself is stored.
 void removeAllDeleted()
          Removes from this collection all persistent objects that have been deleted from the federated database.
 int size()
          Gets the size of this collection.
 Object[] toArray()
          Creates an array containing all the elements (or keys) in this collection.
 Object[] toArray(Object[] a)
          Returns an array that contains all elements in this collection and whose runtime type is that of the specified array.
 
Methods inherited from class com.objy.db.app.ooObj
activate, clearModified, cluster, deactivate, delete, deleteNoProp, deleteReference, dropCachedReference, fetch, fetch, getContainer, getOid, getPersistor, getSession, isDead, isFetchRequired, isModified, isPersistent, isValid, lock, lockNoProp, lookupObj, lookupObj, lookupObjName, markFetchRequired, markModified, move, nameObj, persistor, preWrite, scopedBy, scopedObjects, setPersistor, unnameObj, updateIndexes, write
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

_comparator

public transient ooCompare _comparator
Reserved for internal use.
Method Detail

add

public boolean add(Object object)
Adds the specified object to this collection.

Parameters:
object - The element to be added; must be an instance of a persistence-capable class. If object is transient, this method makes it persistent.

Returns:
True if an element was added; otherwise, false.

See Also:
ooAddAll(com.objy.db.util.ooCollection), ooRemove(java.lang.Object)

ooAddAll

public boolean ooAddAll(ooCollection collection)
Adds all elements (or keys) in the specified collection to this collection.

Parameters:
collection - The collection whose elements are to be added to this collection. If the elements of collection are key-value pairs and the elements of this collection are persistent objects, only the keys of collection are added to this collection.

Returns:
True if any elements were added; otherwise, false.

See Also:
add(java.lang.Object), ooRemoveAll(com.objy.db.util.ooCollection)

clear

public void clear()
Sets this collection to an empty collection, removing any elements it contains.

See Also:
ooRemove(java.lang.Object), ooRemoveAll(com.objy.db.util.ooCollection), ooRetainAll(com.objy.db.util.ooCollection)

comparator

public Comparator comparator()
Gets the comparator for this collection.

Returns:
The comparator for this collection, or null if this collection has a default comparator.

contains

public boolean contains(Object object)
Tests whether this collection contains the specified object.

Parameters:
object - The object to be tested for containment in this collection.

Typically, object is a persistent object, namely the element (or key) of interest. If this collection has an application-defined comparator that can identify a persistent object based on class-specific data, object can instead be a transient object that identifies the element (or key) of interest. See Application-Defined Comparator Classes.

Returns:
True if this collection contains the specified element; otherwise, false.

See Also:
ooContainsAll(com.objy.db.util.ooCollection)

ooContainsAll

public boolean ooContainsAll(ooCollection collection)
Tests whether this collection contains all elements (or keys) in the specified collection.

The meaning of this method depends on whether the elements of the collections being compared are persistent objects or key-value pairs.

Elements of This Collection Elements of collection Tests Whether
persistent objects persistent objects This collection contains all elements of collection
persistent objects key-value pairs This collection contains all keys of collection
key-value pairs persistent objects All elements of collection are keys of this collection
key-value pairs key-value pairs All keys of collection are also keys of this collection

Parameters:
collection - The collection whose elements (or keys) are to be tested for containment in this collection.

Returns:
True if this collection contains an element (or key) equal to each element (or key) of collection; otherwise, false.

See Also:
contains(java.lang.Object)

copy

public Object copy(Object near)
Overrides the inherited method; disallows copying for collections.

This method always throws an exception. If you want to copy this collection, you should create a new collection and add the elements of this collection to the new collection by calling the new collection's ooAddAll method.

Overrides:
copy in class ooObj
Parameters:
near - Ignore
Returns:
Ignore

keyIterator

public ooCollectionIterator keyIterator()
Initializes a collection iterator to find the keys or elements of this collection.

Returns:
A collection iterator for finding the keys or elements of this collection.

If the elements of this collection are key-value pairs, the returned iterator finds the keys of this collection; if the elements are persistent objects, the iterator finds this collection's elements.

If this collection is ordered, the returned iterator finds the keys or elements as ordered in the collection; if the collection is unordered, the iterator finds the keys or elements in an undefined order.


isEmpty

public boolean isEmpty()
Tests whether this collection is empty.

Returns:
True if this collection has no elements; otherwise, false.

ooIterator

public ooCollectionIterator ooIterator()
Initializes a collection iterator to find the elements of this collection.

Returns:
A collection iterator for finding the elements of this collection. If this collection is ordered, the iterator finds the elements as ordered in the collection; if this collection is unordered, the iterator finds the elements in an undefined order.

ooRemove

public abstract boolean ooRemove(Object object)
Removes the first occurrence of the specified object from this collection.

If the elements of this collection are persistent objects, this method removes the first element (if any) that is equal to object. If the elements are key-value pairs, this method removes the element (if any) whose key is object.

Parameters:
object - The object to be removed.

Returns:
True if an element was removed; otherwise, false.

See Also:
clear(), ooRemoveAll(com.objy.db.util.ooCollection), ooRetainAll(com.objy.db.util.ooCollection)

ooRemoveAll

public boolean ooRemoveAll(ooCollection collection)
Removes all elements (or keys) of the specified collection from this collection.

Which elements are removed depends on whether the elements of the two collections are persistent objects or key-value pairs.

Elements of This Collection Elements of collection Removes From This Collection
persistent objects persistent objects All elements that are also elements of collection
persistent objects key-value pairs All elements that are keys of collection
key-value pairs persistent objects All elements whose keys are elements of collection
key-value pairs key-value pairs All elements whose keys are also keys of collection

Parameters:
collection - The collection whose elements are to be removed from this collection.

Returns:
True if any elements were removed; otherwise, false.

See Also:
clear(), ooRemove(java.lang.Object), ooRetainAll(com.objy.db.util.ooCollection)

refresh

public void refresh(int mode)
Refreshes each container used internally by this collection, except for the container in which the collection itself is stored.

You typically call this method when you need to refresh your view of a collection that you are reading in an MROW transaction. This method calls refresh on each container that is used internally by the collection--that is, on the administrator, node, and array containers maintained by an ordered scalable collection, or the administrator and hash-bucket containers maintained by an unordered scalable collection. This method does not refresh the container in which the collection itself is stored, nor does it necessarily refresh the containers that store the collection’s elements.

Parameters:
mode - The type of lock to obtain for each refreshed container; one of the following constants defined in the oo interface:
READ
Obtain a read lock.
WRITE
Obtain a write lock.

removeAllDeleted

public void removeAllDeleted()
Removes from this collection all persistent objects that have been deleted from the federated database.

If the elements of this collection are persistent objects, this method removes any element that has been deleted. If the elements are key-value pairs, this method removes any element in which either the key or the value has been deleted.

You can call this method to restore this collection's referential integrity.


ooRetainAll

public boolean ooRetainAll(ooCollection collection)
Retains all elements of this collection that are also in the specified collection, deleting all other elements.

Which elements are removed depends on whether the elements of the two collections are persistent objects or key-value pairs.

Elements of This Collection Elements of collection Removes From This Collection
persistent objects persistent objects All elements that are not also elements of collection
persistent objects key-value pairs All elements that are not keys of collection
key-value pairs persistent objects All elements whose keys are not elements of collection
key-value pairs key-value pairs All elements whose keys are not also keys of collection

Parameters:
collection - The collection whose elements (or keys) are to be retained in this collection.

Returns:
True if any elements were removed; otherwise, false.

See Also:
clear(), ooRemove(java.lang.Object), ooRemoveAll(com.objy.db.util.ooCollection)

size

public int size()
Gets the size of this collection.

Returns:
The number of elements in this collection.

toArray

public Object[] toArray()
Creates an array containing all the elements (or keys) in this collection.

Returns:
A new array containing all of the elements (or keys) in this collection. If this is an ordered collection, the returned array contains the elements in their order in this collection.

toArray

public Object[] toArray(Object[] a)
Returns an array that contains all elements in this collection and whose runtime type is that of the specified array.

If the specified array is large enough to hold all elements of this collection, this method replaces the elements of that array with the elements (or keys) of this collection and returns the updated array. If the array has more elements than this collection, the element in the array immediately following the end of the collection is set to null. If this collection is not a list, the caller can use the null element to determine the length of this collection. Because lists can contain null elements, however, the caller cannot be sure that the first null element of the array indicates the end of the list whose elements were stored in the array.

If the specified array is smaller than this collection, this method allocates a new array with the runtime type of the specified array and the size of this collection. It then sets the elements of the new array to the elements (or keys) of this collection and returns the new array.

Parameters:
a - The array giving the runtime type of the returned array.

Returns:
An array containing the elements of this collection. If this is an ordered collection, the returned array contains the elements in their order in this collection.

getCollectionPersistor

protected com.objy.pm.ooScalableCollectionsPersistor getCollectionPersistor()
Reserved for internal use; you should not call this method.


Objectivity for Java Reference

Copyright © 2000 Objectivity, Inc. All rights reserved.