com.objy.db.util
Class ooHashMap

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

All Implemented Interfaces:

IooObj, Map, Persistent, PersistentEvents

public final class ooHashMap

extends ooCollection

implements Map

Persistence-capable class for unordered object maps.

API Summary

You may not create your own subclasses of this class.

About Unordered Object Maps

An unordered object map is an unordered collection of key-value pairs; each key and each value is a persistent object. No two elements of the object map may have the same key. As the name implies, each element of an object map is a mapping from its key object to its value object.

Unordered object maps 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 its key.

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

For additional information, see Persistent Collections.

Working With an Unordered Object Map

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

Note: You must make an unordered object map persistent before you call any methods defined by the ooHashMap or ooCollection classes. See the ooObj method descriptions for restrictions on methods inherited from that class.

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

Related Classes

Two additional classes represent persistent collections of key-value pairs:

• ooTreeMap represents a sorted object map. It is implemented using a B-tree data structure.

• ooMap represents an unordered name map, that is, a collection of key-value pairs in which the key is a string and the value is a persistent object. It uses a traditional (non-extendible) hashing mechanism.

API Summary

Functionality

Constructors	ooHashMap() ooHashMap(ooCompare) ooHashMap(int) ooHashMap(ooCompare, int) ooHashMap(int, ooContObj, ooContObj) ooHashMap(ooCompare, int, ooContObj, ooContObj) ooHashMap(ooCompare, int, int, ooContObj, ooContObj)
Adding, Removing, and Changing Elements	put(Object, Object) putAll(Map) ooAddAll(ooCollection) ooRemove(Object) remove(Object)
Getting Elements	get(Object) keyIterator() valueIterator()
Testing	containsKey(Object) containsValue(Object)
Getting Information	maxBucketsPerContainer(int)

Inner classes inherited from class java.util.Map

Map.Entry

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

ooHashMap()
Constructs an empty unordered object map 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.

ooHashMap(int bucketSize)
Constructs an empty unordered object map 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.

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

ooHashMap(ooCompare compare)
Constructs an empty unordered object map 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.

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

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

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

Method Summary

boolean	contains(Object object) Tests whether the specified object is a key of this unordered object map.
boolean	containsKey(Object key) Tests whether this unordered object map contains an element with the specified key.
boolean	containsValue(Object value) Tests whether this unordered object map contains an element with the specified value.
Set	entrySet() Reserved for future use; you should not call this method.
Object	get(Object key) Retrieves the value associated with the specified key in this unordered object map.
ooCollectionIterator	keyIterator() Initializes a collection iterator to find all keys in this unordered object map.
Set	keySet() Reserved for future use; you should not call this method.
void	maxBucketsPerContainer(int max) Sets the maximum number of hash buckets per container for this unordered object map.
boolean	ooAddAll(ooCollection collection) Adds all elements in the specified collection to this unordered object map.
ooCollectionIterator	ooIterator() Initializes a collection iterator to find all keys in this unordered object map.
boolean	ooRemove(Object object) Removes the element of this unordered object map, if any, with the specified key.
Object	put(Object key, Object value) Maps the specified key to the specified value in this unordered object map.
void	putAll(Map map) Adds all elements in the specified map to this unordered object map.
Object	remove(Object object) Removes the element of this unordered object map, if any, with the specified key.
ooCollectionIterator	valueIterator() Initializes a collection iterator to find all values in this unordered object map.
Collection	values() Reserved for future use; you should not call this method.

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

add, clear, comparator, copy, getCollectionPersistor, isEmpty, ooContainsAll, 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.Map

clear, equals, hashCode, isEmpty, size

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

ooHashMap

public ooHashMap()

Constructs an empty unordered object map 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.

ooHashMap

public ooHashMap(int bucketSize)

Constructs an empty unordered object map 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 object map'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.

ooHashMap

public ooHashMap(ooCompare compare)

Constructs an empty unordered object map 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 object map; must be an instance of an application-specific subclass of ooCompare.

ooHashMap

public ooHashMap(ooCompare compare,
                 int bucketSize)

Constructs an empty unordered object map 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 object map; must be an instance of an application-specific subclass of ooCompare.

bucketSize - The size of a hash bucket in the new unordered object map'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.

ooHashMap

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

Constructs an empty unordered object map 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 object map. 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 object map 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 object map; 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 object map; specify null to store each initial hash bucket in its own newly created container.

ooHashMap

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

Constructs an empty unordered object map 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 object map; 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 object map. 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 object map 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 object map; 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 object map; specify null to store each initial hash bucket in its own newly created container.

ooHashMap

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

Constructs an empty unordered object map 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 object map; must be an instance of an application-specific subclass of ooCompare. Specify null to use a default comparator.

bucketSize - The size of a hash bucket in the new unordered object map'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 object map. 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 object map 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 object map; 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 object map; specify null to store each initial hash bucket in its own newly created container.

Method Detail

contains

public boolean contains(Object object)

Tests whether the specified object is a key of this unordered object map.

This method is equivalent to containsKey; the intention of your code will be clearer if you call containsKey instead of this method.

Overrides:

contains in class ooCollection

Parameters:

object - The object to be tested for containment in this unordered object map.

Typically, object is a persistent object, namely the key of interest. If this unordered object map 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 key of interest. See Defining a Comparator Class for Unordered Collections.

Returns:

True if this unordered object map contains an element with the specified key; otherwise, false.

containsKey

public boolean containsKey(Object key)

Tests whether this unordered object map contains an element with the specified key.

You can call this method to check whether this unordered object map maps the specified key to some value.

Specified by:

containsKey in interface Map

Parameters:

key - The key to be tested for containment in this unordered object map.

Typically, key is a persistent object, namely the key of interest. If this unordered object map has an application-defined comparator that can identify a persistent object based on class-specific data, key can instead be a transient object that identifies the key of interest. See Defining a Comparator Class for Unordered Collections.

Returns:

True if this unordered object map contains an element with the specified key; otherwise, false.

See Also:

containsValue(java.lang.Object)

containsValue

public boolean containsValue(Object value)

Tests whether this unordered object map contains an element with the specified value.

You can call this method to check whether this unordered object map maps at least one key to the specified value.

Specified by:

containsValue in interface Map

Parameters:

value - The value to be tested for containment in this unordered object map.

Returns:

True if this unordered object map contains an element whose value is value; otherwise, false.

See Also:

containsKey(java.lang.Object)

entrySet

public Set entrySet()

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

Specified by:

entrySet in interface Map

get

public Object get(Object key)

Retrieves the value associated with the specified key in this unordered object map.

Specified by:

get in interface Map

Parameters:

key - The key to be looked up.

Typically, key is a persistent object, namely the key of interest. If this unordered object map has an application-defined comparator that can identify a persistent object based on class-specific data, key can instead be a transient object that identifies the key of interest. See Defining a Comparator Class for Unordered Collections.

Returns:

The value in the element with the specified key, or null if this unordered object map contains no mapping for that key.

A return value of null does not necessarily indicate that no element has the specified key. It is possible that this unordered object map explicitly maps the specified key to null. The containsKey method may be used to distinguish these two cases.

See Also:

put(java.lang.Object, java.lang.Object)

keyIterator

public ooCollectionIterator keyIterator()

Initializes a collection iterator to find all keys in this unordered object map.

Overrides:

keyIterator in class ooCollection

Returns:

A collection iterator that finds all the persistent objects used as keys in this unordered object map. The iterator finds the keys in an undefined order; however, it iterates through the key-value pairs of this unordered object map in the same order as does an iterator returned by valueIterator.

See Also:

valueIterator()

keySet

public Set keySet()

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

Specified by:

keySet in interface Map

maxBucketsPerContainer

public void maxBucketsPerContainer(int max)

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

Parameters:

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

ooAddAll

public boolean ooAddAll(ooCollection collection)

Adds all elements in the specified collection to this unordered object map.

If collection is an object map, its elements are added to this unordered object map. If this unordered object map currently has an element with the same key as an element of collection, the existing element is replaced by the element of collection.

If collection is a collection of persistent objects, each of its elements is added as a key to this unordered object map; the associated values are null. If this unordered object map currently has an element whose key is an element of collection, the value of the existing element is replaced by null.

Overrides:

ooAddAll in class ooCollection

Parameters:

collection - The collection whose elements are to be added to this unordered object map.

Returns:

True if any elements were added; otherwise, false.

ooIterator

public ooCollectionIterator ooIterator()

Initializes a collection iterator to find all keys in this unordered object map.

This method is equivalent to keyIterator; the intention of your code will be clearer if you call keyIterator instead of this method.

Overrides:

ooIterator in class ooCollection

Returns:

A collection iterator that finds all the persistent objects used as keys in this unordered object map. The iterator finds the keys in an undefined order; however, it iterates through the key-value pairs of this unordered object map in the same order as does an iterator returned by valueIterator.

See Also:

valueIterator()

ooRemove

public boolean ooRemove(Object object)

Removes the element of this unordered object map, if any, with the specified key.

Overrides:

ooRemove in class ooCollection

Parameters:

object - The key of the element to be removed.

Returns:

True if an element was removed; otherwise, false.

See Also:

remove(java.lang.Object)

put

public Object put(Object key,
                  Object value)

Maps the specified key to the specified value in this unordered object map.

If this unordered object map already contains an element with the specified key, this method replaces the value in that element. Otherwise, this method adds a new element with the specified key and value.

Specified by:

put in interface Map

Parameters:

key - The key; must be an instance of a persistence-capable class. If key is transient, this method makes it persistent.

value - The value; must be an instance of a persistence-capable class or null. If value is a transient object, this method makes it persistent.

Returns:

The value previously associated with key in this unordered object map, or null if there was no mapping for key.

Note that a null return might indicate that this unordered object map previously mapped key to null.

See Also:

get(java.lang.Object), putAll(java.util.Map)

putAll

public void putAll(Map map)

Adds all elements in the specified map to this unordered object map.

If this unordered object map currently has an element with the same key as an element of map, the existing element is replaced by the element of map.

Specified by:

putAll in interface Map

Parameters:

map - The map whose elements are to be added to this unordered object map. Every key and every value in map must be an instance of a persistence-capable class. If any key or value is transient, this method makes it persistent.

See Also:

put(java.lang.Object, java.lang.Object), ooAddAll(com.objy.db.util.ooCollection)

remove

public Object remove(Object object)

Removes the element of this unordered object map, if any, with the specified key.

Specified by:

remove in interface Map

Parameters:

object - The key of the element to be removed.

Returns:

The value in the element that was removed, or null if there was no mapping for object. A null return can also indicate that this unordered object map previously mapped the key object to null.

See Also:

ooRemove(java.lang.Object)

valueIterator

public ooCollectionIterator valueIterator()

Initializes a collection iterator to find all values in this unordered object map.

Returns:

A collection iterator that finds all the persistent objects used as values in elements of this object map. The iterator finds the values in an undefined order; however, it iterates through the key-value pairs of this unordered object map in the same order as does an iterator returned by keyIterator.

See Also:

keyIterator()

values

public Collection values()

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

Specified by:

values in interface Map