com.objy.db.util
Class ooTreeSet

java.lang.Object
  |
  +--com.objy.db.app.ooAbstractObj
        |
        +--com.objy.db.app.ooObj
              |
              +--com.objy.db.util.ooCollection
                    |
                    +--com.objy.db.util.ooBTree
                          |
                          +--com.objy.db.util.ooTreeSet

All Implemented Interfaces:

Collection, IooObj, Persistent, PersistentEvents, Set, SortedSet

public final class ooTreeSet

extends ooBTree

implements SortedSet

Persistence-capable class for sorted sets of persistent objects.

API Summary

You may not create your own subclasses of this class.

About Sorted Sets

A sorted set is an ordered collection of persistent objects with no duplicate elements. Like all collections implemented with B-trees, sorted sets are scalable collections, that is, they can increase in size with minimal performance degradation.

The elements of a sorted set are sorted according to the ordering implemented by the set's associated comparator. If a sorted set has a default comparator, its elements are sorted by their OIDs.

For additional information, see Persistent Collections.

Working With a Sorted Set

A sorted set is transient when it is created. You can make the sorted set persistent in any of the ways that you make any basic object persistent (see Making an Object Persistent). You can store and retrieve the sorted set just like any other persistent object. For example, you can store a sorted set in a persistent field of a persistent object.

Note: You must make a sorted set persistent before you call any methods defined by the ooTreeSet, ooBTree, or ooCollection classes. See the ooObj method descriptions for restrictions on methods inherited from that class.

Like any persistent object, a sorted set belongs to the session that is in a transaction when the sorted set is made persistent or retrieved. Objectivity/DB does not allow a sorted set to interact with objects that belong to different sessions; see Object Isolation.

Related Classes

Two additional classes represent persistent collections of persistent objects:

• ooHashSet represents an unordered collection of persistent objects with no duplicate elements. It uses an extendible hashing mechanism.

• ooTreeList represents a collection of persistent objects that are maintained in the order specified when they are added to the collection. A list can contain duplicate elements. Like this class, ooTreeList is implemented using a B-tree data structure.

API Summary

Functionality

Constructors	ooTreeSet() ooTreeSet(ooContObj, ooContObj) ooTreeSet(int) ooTreeSet(int, ooContObj, ooContObj) ooTreeSet(ooCompare) ooTreeSet(ooCompare, ooContObj, ooContObj) ooTreeSet(ooCompare, int) ooTreeSet(ooCompare, int, ooContObj, ooContObj)
Adding and Removing Elements	addAll(Collection) remove(Object) ooRemove(Object) removeAll(Collection) retainAll(Collection)
Getting Elements	iterator() get(Object)
Getting Indexes	indexOf(Object, int)
Testing	containsAll(Collection)

Field Summary

ooContObj	_adminContainer Reserved for internal use.
ooContObj	_arrayContainer Reserved for internal use.
int	_maxUsedSizePerNode Reserved for internal use.

Fields inherited from class com.objy.db.util.ooCollection

_comparator

Constructor Summary

ooTreeSet()
Constructs an empty sorted set with a default comparator and the default node size.

ooTreeSet(int maxNodeSize)
Constructs an empty sorted set with a default comparator and the specified node size.

ooTreeSet(int maxNodeSize, ooContObj adminContainer, ooContObj arrayContainer)
Constructs an empty sorted set with a default comparator, the specified node size, and the specified containers for internal objects.

ooTreeSet(ooCompare compare)
Constructs an empty sorted set with the specified comparator and the default node size.

ooTreeSet(ooCompare compare, int maxNodeSize)
Constructs an empty sorted set with the specified comparator and node size.

ooTreeSet(ooCompare compare, int maxNodeSize, ooContObj adminContainer, ooContObj arrayContainer)
Constructs an empty sorted set with the specified comparator, node size, and containers for internal objects.

ooTreeSet(ooCompare compare, ooContObj adminContainer, ooContObj arrayContainer)
Constructs an empty sorted set with the specified comparator, the default node size, and the specified containers for internal objects.

ooTreeSet(ooContObj adminContainer, ooContObj arrayContainer)
Constructs an empty sorted set with a default comparator, the default node size, and the specified containers for internal objects.

Method Summary

boolean	addAll(Collection collection) Adds all elements in the specified collection to this sorted set.
boolean	containsAll(Collection collection) Tests whether this sorted set contains all elements in the specified collection.
Object	get(Object lookupValue) Gets the element of this sorted set that is equal to the specified lookup data, as determined by the comparator for this sorted set.
SortedSet	headSet(Object toElement) Reserved for future use; you should not call this method.
int	indexOf(Object object, int index) Searches forward in this sorted set, starting at the specified index, for the first element that is equal to the specified object.
Iterator	iterator() Initializes a collection iterator to find the elements of this sorted set.
boolean	ooRemove(Object object) Removes the specified object from this sorted set.
boolean	remove(Object object) Removes the specified object from this sorted set.
boolean	removeAll(Collection collection) Removes all elements of the specified collection from this sorted set.
boolean	retainAll(Collection collection) Retains all elements of this sorted set that are also in the specified collection, deleting all other elements.
SortedSet	subSet(Object fromElement, Object toElement) Reserved for future use; you should not call this method.
SortedSet	tailSet(Object fromElement) Reserved for future use; you should not call this method.

Methods inherited from class com.objy.db.util.ooBTree

compact, contains, first, get, getCollectionPersistor, indexOf, last, lastIndexOf, lastIndexOf, maxNodesPerContainer, maxVArraysPerContainer

Methods inherited from class com.objy.db.util.ooCollection

add, clear, comparator, copy, isEmpty, keyIterator, ooAddAll, ooContainsAll, ooIterator, ooRemoveAll, ooRetainAll, refresh, removeAllDeleted, size, toArray, toArray

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

Methods inherited from interface java.util.SortedSet

comparator, first, last

Methods inherited from interface java.util.Set

add, clear, contains, equals, hashCode, isEmpty, size, toArray, toArray

Field Detail

_maxUsedSizePerNode

public transient int _maxUsedSizePerNode

Reserved for internal use.

_adminContainer

public transient ooContObj _adminContainer

Reserved for internal use.

_arrayContainer

public transient ooContObj _arrayContainer

Reserved for internal use.

Constructor Detail

ooTreeSet

public ooTreeSet()

Constructs an empty sorted set with a default comparator and the default node size.

ooTreeSet

public ooTreeSet(ooContObj adminContainer,
                 ooContObj arrayContainer)

Constructs an empty sorted set with a default comparator, the default node size, and the specified containers for internal objects.

Parameters:

adminContainer - The container in which to store the tree administrator for the new sorted set. See Tree Administrator.

arrayContainer - The initial array container for the new sorted set. See Array Containers.

ooTreeSet

public ooTreeSet(ooCompare compare)

Constructs an empty sorted set with the specified comparator and the default node size.

Parameters:

compare - The comparator for the new sorted set; must be an instance of an application-specific subclass of ooCompare.

ooTreeSet

public ooTreeSet(ooCompare compare,
                 ooContObj adminContainer,
                 ooContObj arrayContainer)

Constructs an empty sorted set with the specified comparator, the default node size, and the specified containers for internal objects.

Parameters:

compare - The comparator for the new sorted set; must be an instance of an application-specific subclass of ooCompare.

adminContainer - The container in which to store the tree administrator for the new sorted set. See Tree Administrator.

arrayContainer - The initial array container for the new sorted set. See Array Containers.

ooTreeSet

public ooTreeSet(int maxNodeSize)

Constructs an empty sorted set with a default comparator and the specified node size.

Parameters:

maxNodeSize - The node size for the new sorted set's B-tree. See Node Size.

ooTreeSet

public ooTreeSet(int maxNodeSize,
                 ooContObj adminContainer,
                 ooContObj arrayContainer)

Constructs an empty sorted set with a default comparator, the specified node size, and the specified containers for internal objects.

Parameters:

maxNodeSize - The node size for the new sorted set's B-tree. See Node Size.

adminContainer - The container in which to store the tree administrator for the new sorted set. See Tree Administrator.

arrayContainer - The initial array container for the new sorted set. See Array Containers.

ooTreeSet

public ooTreeSet(ooCompare compare,
                 int maxNodeSize)

Constructs an empty sorted set with the specified comparator and node size.

Parameters:

compare - The comparator for the new sorted set; must be an instance of an application-specific subclass of ooCompare.

maxNodeSize - The node size for the new sorted set's B-tree. See Node Size.

ooTreeSet

public ooTreeSet(ooCompare compare,
                 int maxNodeSize,
                 ooContObj adminContainer,
                 ooContObj arrayContainer)

Constructs an empty sorted set with the specified comparator, node size, and containers for internal objects.

Parameters:

compare - The comparator for the new sorted set; must be an instance of an application-specific subclass of ooCompare.

maxNodeSize - The node size for the new sorted set's B-tree. See Node Size.

adminContainer - The container in which to store the tree administrator for the new sorted set. See Tree Administrator.

arrayContainer - The initial array container for the new sorted set. See Array Containers.

Method Detail

addAll

public boolean addAll(Collection collection)

Adds all elements in the specified collection to this sorted set.

Specified by:

addAll in interface Set

Parameters:

collection - The collection whose elements are to be added to this sorted set. Every element of collection must be an instance of a persistence-capable class. If any element is transient, this method makes it persistent.

Returns:

True if any elements were added; otherwise, false.

This method returns false if this sorted set already contains all the elements of collection.

containsAll

public boolean containsAll(Collection collection)

Tests whether this sorted set contains all elements in the specified collection.

Specified by:

containsAll in interface Set

Parameters:

collection - The collection whose elements are to be tested for containment in this sorted set.

Returns:

True if this sorted set contains elements equal to each element of collection; otherwise, false.

get

public Object get(Object lookupValue)

Gets the element of this sorted set that is equal to the specified lookup data, as determined by the comparator for this sorted set.

Note: This sorted set must have an application-defined comparator that can identify an element based on class-specific data. See Defining a Comparator Class for Sorted Collections.

Parameters:

lookupValue - The object that identifies the desired element.

Returns:

The element found equal to lookupValue, or null if this sorted set does not contain such an element.

headSet

public SortedSet headSet(Object toElement)

Reserved for future use; you should not call this method.

Specified by:

headSet in interface SortedSet

indexOf

public int indexOf(Object object,
                   int index)

Searches forward in this sorted set, starting at the specified index, for the first element that is equal to the specified object. This method compares each element with object. Search stops when a matching element is found; if more than one element matches, this method finds the one closest to the beginning (but at or after the starting index).

Overrides:

indexOf in class ooBTree

Parameters:

object - The object whose index is to be found.

Typically, object is the persistent object to be found. If this sorted set has an application-defined comparator that can identify an element based on class-specific data, object can instead be a transient object that identifies the element to be found. See Defining a Comparator Class for Sorted Collections.

index - The zero-based index at which search should start.

Returns:

The index of the first element in this sorted set at or after the index index, that is equal to object. If no such element is found, this method returns -1.

iterator

public Iterator iterator()

Initializes a collection iterator to find the elements of this sorted set.

Specified by:

iterator in interface Set

Returns:

A collection iterator for finding the elements of this sorted set. The iterator finds the elements in their sorted order.

If you want to call any methods that are specific to Objectivity for Java collection iterators, you should cast the returned iterator to ooCollectionIterator.

ooRemove

public boolean ooRemove(Object object)

Removes the specified object from this sorted set.

This method is equivalent to remove.

Overrides:

ooRemove in class ooCollection

Parameters:

object - The object to be removed.

Typically, object is the persistent object to be removed from this sorted set. If this sorted set has an application-defined comparator that can identify an element based on class-specific data, object can instead be a transient object that identifies the element to be removed. See Defining a Comparator Class for Sorted Collections.

Returns:

True if an element was removed; otherwise, false.

remove

public boolean remove(Object object)

Removes the specified object from this sorted set.

Specified by:

remove in interface Set

Parameters:

object - The object to be removed.

Typically, object is the persistent object to be removed from this sorted set. If this sorted set has an application-defined comparator that can identify an element based on class-specific data, object can instead be a transient object that identifies the element to be removed. See Defining a Comparator Class for Sorted Collections.

Returns:

True if an element was removed; otherwise, false.

See Also:

removeAll(java.util.Collection), retainAll(java.util.Collection)

removeAll

public boolean removeAll(Collection collection)

Removes all elements of the specified collection from this sorted set.

Specified by:

removeAll in interface Set

Parameters:

collection - The collection whose elements are to be removed from this sorted set.

Returns:

True if any elements were removed; otherwise, false.

See Also:

remove(java.lang.Object), retainAll(java.util.Collection)

retainAll

public boolean retainAll(Collection collection)

Retains all elements of this sorted set that are also in the specified collection, deleting all other elements.

Specified by:

retainAll in interface Set

Parameters:

collection - The collection whose elements are to be retained in this sorted set.

Returns:

True if any elements were removed; otherwise, false.

See Also:

remove(java.lang.Object), removeAll(java.util.Collection)

subSet

public SortedSet subSet(Object fromElement,
                        Object toElement)

Reserved for future use; you should not call this method.

Specified by:

subSet in interface SortedSet

tailSet

public SortedSet tailSet(Object fromElement)

Reserved for future use; you should not call this method.

Specified by:

tailSet in interface SortedSet