com.objy.db.util
Class ooHashSet

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

All Implemented Interfaces:

Collection, IooObj, Persistent, PersistentEvents, Set

public final class ooHashSet

extends ooCollection

implements Set

Persistence-capable class for unordered sets of persistent objects.

API Summary

You may not create your own subclasses of this class.

About Unordered Sets

An unordered set is an unordered collection of persistent objects with no duplicate elements. Unordered sets are scalable collections, that is, they can increase in size with minimal performance degradation. They are implemented using an extendible hashing mechanism so that elements can be added, deleted, and retrieved efficiently. The hash value for each element is computed from the element itself.

The hash values for elements of an unordered set are computed by the set's associated comparator. If an unordered set has a default comparator, the hash values are computed from the OIDs of the elements.

For additional information, see Persistent Collections.

Working With an Unordered Set

An unordered set is transient when it is created. You can make the 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 set just like any other persistent object. For example, you can store a set in a persistent field of a persistent object.

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

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

Related Classes

Two additional classes represent persistent collections of persistent objects:

• ooTreeSet represents a sorted collection of persistent objects with no duplicate elements.

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

Both sorted sets and lists are implemented using a B-tree data structure.

API Summary

Functionality

Constructors	ooHashSet() ooHashSet(ooCompare) ooHashSet(int) ooHashSet(ooCompare, int) ooHashSet(int, ooContObj, ooContObj) ooHashSet(ooCompare, int, ooContObj, ooContObj) ooHashSet(ooCompare, int, int, ooContObj, ooContObj)
Adding and Removing Elements	addAll(Collection) remove(Object) ooRemove(Object) removeAll(Collection) retainAll(Collection)
Getting Elements	iterator() get(Object)
Testing	containsAll(Collection)
Setting Properties	maxBucketsPerContainer(int)

Field Summary

ooContObj	_adminContainer Reserved for internal use.
ooContObj	_bucketContainer Reserved for internal use.
int	_bucketSize Reserved for internal use.
int	_initialBuckets Reserved for internal use.

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

_comparator

Constructor Summary

ooHashSet()
Constructs an empty unordered set with a default comparator, the default hash-bucket size, one initial hash bucket, a newly created administrator container, and a newly created hash-bucket container.

ooHashSet(int bucketSize)
Constructs an empty unordered set with the specified hash-bucket size, a default comparator, one initial hash bucket, a newly created administrator container, and a newly created hash-bucket container.

ooHashSet(int initialBuckets, ooContObj adminContainer, ooContObj bucketContainer)
Constructs an empty unordered set with a default comparator, the default hash-bucket size, and the specified number of initial hash buckets, administrator container, and hash-bucket container.

ooHashSet(ooCompare compare)
Constructs an empty unordered set with the specified comparator, the default hash-bucket size, one initial hash bucket, a newly created administrator container, and a newly created hash-bucket container.

ooHashSet(ooCompare compare, int bucketSize)
Constructs an empty unordered set with the specified comparator and hash-bucket size, one initial hash bucket, a newly created administrator container, and a newly created hash-bucket container.

ooHashSet(ooCompare compare, int bucketSize, int initialBuckets, ooContObj adminContainer, ooContObj bucketContainer)
Constructs an empty unordered set with the specified comparator, hash-bucket size, number of initial hash buckets, administrator container, and hash-bucket container.

ooHashSet(ooCompare compare, int initialBuckets, ooContObj adminContainer, ooContObj bucketContainer)
Constructs an empty unordered set with the default hash-bucket size and the specified comparator, number of initial hash buckets, administrator container, and hash-bucket container.

Method Summary

boolean	addAll(Collection collection) Adds all elements in the specified collection to this unordered set.
boolean	containsAll(Collection collection) Tests whether this unordered set contains all elements in the specified collection.
Object	get(Object lookupValue) Gets the element of this unordered set that is equal to the specified lookup data, as determined by the comparator for this unordered set.
Iterator	iterator() Initializes a collection iterator to find the elements of this unordered set.
void	maxBucketsPerContainer(int max) Sets the maximum number of hash buckets per container for this unordered set.
boolean	ooRemove(Object object) Removes the specified object from this unordered set.
boolean	remove(Object object) Removes the specified object from this unordered set.
boolean	removeAll(Collection collection) Removes all elements of the specified collection from this unordered set.
boolean	retainAll(Collection collection) Retains all elements of this unordered set that are also in the specified collection, deleting all other elements.

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

add, clear, comparator, contains, copy, getCollectionPersistor, 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.Set

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

Field Detail

_bucketSize

public transient int _bucketSize

Reserved for internal use.

_adminContainer

public transient ooContObj _adminContainer

Reserved for internal use.

_initialBuckets

public transient int _initialBuckets

Reserved for internal use.

_bucketContainer

public transient ooContObj _bucketContainer

Reserved for internal use.

Constructor Detail

ooHashSet

public ooHashSet()

Constructs an empty unordered set with a default comparator, the default hash-bucket size, one initial hash bucket, a newly created administrator container, and a newly created hash-bucket container.

ooHashSet

public ooHashSet(int bucketSize)

Constructs an empty unordered set with the specified hash-bucket size, a default comparator, one initial hash bucket, a newly created administrator container, and a newly created hash-bucket container.

Parameters:

bucketSize - The size of a hash bucket in the new unordered set's hash table. The size of a hash bucket is the number of elements that can be hashed into each bucket. For optimal performance, the bucket size should be a prime number. If you specify a bucket size that is not a prime number, the next higher prime number is computed and used as the actual bucket size.

ooHashSet

public ooHashSet(ooCompare compare)

Constructs an empty unordered set with the specified comparator, the default hash-bucket size, one initial hash bucket, a newly created administrator container, and a newly created hash-bucket container.

Parameters:

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

ooHashSet

public ooHashSet(ooCompare compare,
                 int bucketSize)

Constructs an empty unordered set with the specified comparator and hash-bucket size, one initial hash bucket, a newly created administrator container, and a newly created hash-bucket container.

Parameters:

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

bucketSize - The size of a hash bucket in the new unordered set's hash table. The size of a hash bucket is the number of elements that can be hashed into each bucket. For optimal performance, the bucket size should be a prime number. If you specify a bucket size that is not a prime number, the next higher prime number is computed and used as the actual bucket size.

ooHashSet

public ooHashSet(int initialBuckets,
                 ooContObj adminContainer,
                 ooContObj bucketContainer)

Constructs an empty unordered set with a default comparator, the default hash-bucket size, and the specified number of initial hash buckets, administrator container, and hash-bucket container.

Parameters:

initialBuckets - The minimum number of initial hash buckets to create for the new unordered set. The actual number of hash buckets created is the smallest power of 2 that is greater than initialBuckets. For example, if initialBuckets is 10, the number of initial hash buckets is 2**4, or 16.

Preallocating multiple hash buckets increases the speed of adding and finding elements. If each hash bucket is stored in a separate container, preallocating hash buckets also reduces the chance of lock conflicts. However, an unordered set with a large number of initial hash buckets requires more disk space, more memory for the directory, and more time to create.

adminContainer - The container in which to store the hash administrator for the new unordered set; specify null to store the hash administrator in a newly created container.

bucketContainer - The container in which to store the initial hash buckets for the new unordered set; specify null to store each initial hash bucket in its own newly created container.

ooHashSet

public ooHashSet(ooCompare compare,
                 int initialBuckets,
                 ooContObj adminContainer,
                 ooContObj bucketContainer)

Constructs an empty unordered set with the default hash-bucket size and the specified comparator, number of initial hash buckets, administrator container, and hash-bucket container.

Parameters:

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

initialBuckets - The minimum number of initial hash buckets to create for the new unordered set. The actual number of hash buckets created is the smallest power of 2 that is greater than initialBuckets. For example, if initialBuckets is 10, the number of initial hash buckets is 2**4, or 16.

Preallocating multiple hash buckets increases the speed of adding and finding elements. If each hash bucket is stored in a separate container, preallocating hash buckets also reduces the chance of lock conflicts. However, an unordered set with a large number of initial hash buckets requires more disk space, more memory for the directory, and more time to create.

adminContainer - The container in which to store the hash administrator for the new unordered set; specify null to store the hash administrator in a newly created container.

bucketContainer - The container in which to store the initial hash buckets for the new unordered set; specify null to store each initial hash bucket in its own newly created container.

ooHashSet

public ooHashSet(ooCompare compare,
                 int bucketSize,
                 int initialBuckets,
                 ooContObj adminContainer,
                 ooContObj bucketContainer)

Constructs an empty unordered set with the specified comparator, hash-bucket size, number of initial hash buckets, administrator container, and hash-bucket container.

Parameters:

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

bucketSize - The size of a hash bucket in the new unordered set's hash table. The size of a hash bucket is the number of elements that can be hashed into each bucket. For optimal performance, the bucket size should be a prime number. If you specify a bucket size that is not a prime number, the next higher prime number is computed and used as the actual bucket size.

initialBuckets - The minimum number of initial hash buckets to create for the new unordered set. The actual number of hash buckets created is the smallest power of 2 that is greater than initialBuckets. For example, if initialBuckets is 10, the number of initial hash buckets is 2**4, or 16.

Preallocating multiple hash buckets increases the speed of adding and finding elements. If each hash bucket is stored in a separate container, preallocating hash buckets also reduces the chance of lock conflicts. However, an unordered set with a large number of initial hash buckets requires more disk space, more memory for the directory, and more time to create.

adminContainer - The container in which to store the hash administrator for the new unordered set; specify null to store the hash administrator in a newly created container.

bucketContainer - The container in which to store the initial hash buckets for the new unordered set; specify null to store each initial hash bucket in its own newly created container.

Method Detail

addAll

public boolean addAll(Collection collection)

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

Specified by:

addAll in interface Set

Parameters:

collection - The collection whose elements are to be added to this unordered 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 unordered set already contains all the elements of collection.

containsAll

public boolean containsAll(Collection collection)

Tests whether this unordered 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 unordered set.

Returns:

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

get

public Object get(Object lookupValue)

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

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

Parameters:

lookupValue - The object that identifies the desired element.

Returns:

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

iterator

public Iterator iterator()

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

Specified by:

iterator in interface Set

Returns:

A collection iterator for finding the elements of this unordered set. The iterator finds the elements in an undefined 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.

maxBucketsPerContainer

public void maxBucketsPerContainer(int max)

Sets the maximum number of hash buckets per container for this unordered set.

Parameters:

max - The maximum number of hash buckets for this unordered set that can be stored in a single container.

ooRemove

public boolean ooRemove(Object object)

Removes the specified object from this unordered set.

This method is equivalent to remove.

Overrides:

ooRemove in class ooCollection

Parameters:

object - The object to be removed.

Returns:

True if an element was removed; otherwise, false.

remove

public boolean remove(Object object)

Removes the specified object from this unordered set.

Specified by:

remove in interface Set

Parameters:

object - The object to be removed.

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 unordered set.

Specified by:

removeAll in interface Set

Parameters:

collection - The collection whose elements are to be removed from this unordered 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 unordered 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 unordered set.

Returns:

True if any elements were removed; otherwise, false.

See Also:

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