com.objy.db.util
Class ooMap

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

All Implemented Interfaces:

IooObj, Persistent, PersistentEvents

public final class ooMap

extends ooObj

Persistence-capable class for unordered name maps.

API Summary

You may not create your own subclasses of this class.

About Name Maps

A name map is a collection of key-value pairs; each key is a string and each value is a persistent object. No two elements of the name map may have the same key. As the name implies, each element of a name map is a mapping from a name to an object with that name. The word name is used as a synonym for key because an object's key is often a name; however, a key can be any valid Java string that identifies the object. Keys can be strings of any length.

A name map provides an efficient way to assign identifying keys to objects and to look up objects by their keys. Objectivity/DB uses name maps to implement its dictionaries of named roots and scope-named objects. In addition, you can instantiate this class to create your own application-specific dictionary for objects. For more information, see Naming Persistent Objects.

Growth Characteristics

A name map is implemented as a hash table using a traditional hashing mechanism. The hash table can grow dynamically; however, increasing its size requires rehashing the entire hash table.

When you create a name map, you specify:

• The initial number of bins (hash buckets). For optimal performance, the number of bins should always be a prime number.

• The maximum average density, that is, the average number of elements per bin allowed before the hash table must be resized. The hash table is resized whenever:

       totalElements >= numberBins * maximumAverageDensity
   

• The growth factor. This number gives the percentage by which the hash table grows when it is resized. Each time the hash table is resized, the number of bins is increased by the growth factor, then rounded up to the nearest prime number.

Runtime Statistics

Name maps accumulate statistical information about runtime usage. You can print a summary of this information or clear the statistical parameters, resetting them to zero. The statistical parameters record:

• The number of elements added.
• The number of elements deleted.
• The number of times the hash table was rehashed.

Referential Integrity

Each element in a name map pairs a key with an object. By default, a name map maintains referential integrity of its elements. That is, the name map ensures that each object in the name map is a valid persistent object. When an object referenced in a name map is deleted, Objectivity/DB automatically removes the element that references the deleted object.

After you create a name map and before you add any elements, you can call its setIntegrityMaintained method to disable the automatic maintenance of its referential integrity. When you do so, you reduce the overhead in adding and deleting elements; however, you become responsible for ensuring that the name map does not contain any dangling references to deleted objects.

Working With a Name Map

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

Note: You must make a name map persistent before you call any methods defined by the ooMap class; for similar restrictions on inherited methods, see the ooObj method descriptions.

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

If you abort the transaction in which you make a name map persistent, it reverts to the transient state. This behavior is standard for objects of all persistence-capable classes. Note, however, that any growth characteristics that you set when you created the name map will be reset to their default values when the name map is made transient. For this reason, if you create a name map with non-default values for its growth characteristics, you should commit or checkpoint the transaction as soon as possible after you make the new name map persistent.

Related Classes

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

• ooHashMap represents an unordered object map, that is, a collection of key-value pairs in which both the key and the value are persistent objects. It uses an extendible hashing mechanism that allows the hash table to grow without being completely rehashed.

• ooTreeMap represents a sorted object map.

Both object map classes represent scalable collections; unlike name maps, they can increase in size with minimal performance degradations.

For information about the various persistence-capable collection classes, see Persistent Collections.

API Summary

Functionality

Constructors	ooMap() ooMap(long, long, long)
Adding and Removing Elements	add(Object, String) forceAdd(Object, String) remove(String) replace(Object, String)
Finding Objects	lookup(String) lookup(String, int)
Getting Elements	keys() elements()
Getting Information	getMaxAverageDensity() getBinCount() getElementCount() getGrowthFactor() printStatistics()
Testing	isMember(String) isIntegrityMaintained()
Working With Runtime Statistics	clearParameters() printStatistics()
Maintaining the Hash Table	rehash(long) isIntegrityMaintained() setIntegrityMaintained(boolean)

Field Summary

com.objy.pm.ooMapInitialValues

initialValues Reserved for internal use.

Constructor Summary

ooMap()
Constructs a name map.

ooMap(long binCount, long maxAverageDensity, long growthFactor)
Constructs a name map with the specified number of bins, maximum average density, and growth factor.

Method Summary

void	add(Object object, String name) Adds an element with a unique key to this name map.
void	clearParameters() Resets the statistical parameters for this name map to zero.
Object	copy(Object near) Overrides the inherited method; disallows copying for name maps.
Iterator	elements() Initializes an iterator to find all the objects in this name map.
void	forceAdd(Object object, String name) Adds an element to this name map even if its key is not unique.
long	getBinCount() Gets number of bins in this name map's hash table.
long	getElementCount() Gets the number of elements in this name map.
long	getGrowthFactor() Gets the growth factor of this name map's hash table.
long	getMaxAverageDensity() Gets the maximum average density of this name map's hash table.
boolean	isIntegrityMaintained() Tests whether Objectivity/DB automatically maintains the referential integrity of this name map.
boolean	isMember(String name) Tests whether this name map has an element with the specified key.
Iterator	keys() Initializes an iterator to find all the keys of this name map.
Object	lookup(String name) Retrieves the object in this name map with the specified key.
Object	lookup(String name, int lockMode) Retrieves the object in this name map with the specified key, locking the retrieved object as specified.
void	printStatistics() Prints runtime statistics for this name map to the standard output device.
void	rehash(long binCount) Resizes this name map's hash table.
void	remove(String name) Removes the element with the specified key from this name map.
void	replace(Object object, String name) Replaces the element with the specified key in this name map.
void	setIntegrityMaintained(boolean maintain) Enables or disables maintenance of referential integrity for this name map.

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

initialValues

public com.objy.pm.ooMapInitialValues initialValues

Reserved for internal use.

Constructor Detail

ooMap

public ooMap()

Constructs a name map.

The new name map's hash table has 11 bins, a maximum average density of 5 elements per bin, and a growth factor of 100%.

ooMap

public ooMap(long binCount,
             long maxAverageDensity,
             long growthFactor)

Constructs a name map with the specified number of bins, maximum average density, and growth factor.

Note: If you create a name map with non-default values for number of bins, maximum average density, or growth factor, you should commit or checkpoint the transaction as soon as you make the name map persistent. If the transaction is aborted, the name map will revert to the transient state and its growth characteristics will be reset to the default values (11 bins, 5 elements per bin, and a 100% growth factor).

Parameters:

binCount - The initial number of bins in the new name map's hash table. For optimal performance, the number of bins should be a prime number.

maxAverageDensity - The maximum average density allowed before the new name map's hash table must be resized.

percentGrowth - The growth factor for the new name map's hash table, expressed as a percentage (for example, use 80 for a growth factor of 80%).

Method Detail

add

public void add(Object object,
                String name)

Adds an element with a unique key to this name map. Before you call this method, you can call isMember to test whether name is already a key.

Parameters:

object - The object to be added with the specified key, or null to make name the key for a null object reference. If an object is specified, it must be an instance of a persistence-capable class; if the object is transient, this method makes it persistent.

name - The key for the new element.

Throws:

ObjyRuntimeException - If this name map already contains an element with the key name.

ObjectNotPersistentException - If this name map is transient.

See Also:

forceAdd(java.lang.Object, java.lang.String), remove(java.lang.String), replace(java.lang.Object, java.lang.String)

forceAdd

public void forceAdd(Object object,
                     String name)

Adds an element to this name map even if its key is not unique.

This method is more efficient than add, because it doesn't check that name is a unique key. If this name map already contains an element with that key, the key will be ambiguous. In that case, it is undefined which object will be returned if you call lookup with name as the key.

Note: You should call this method only if you are sure that this name map doesn't contain an element with the specified key.

Parameters:

object - The object to be added with the specified key, or null to make name the key for a null object reference. If an object is specified, it must be an instance of a persistence-capable class; if the object is transient, this method makes it persistent.

name - The key for the new element.

Throws:

ObjectNotPersistentException - If this name map is transient.

See Also:

replace(java.lang.Object, java.lang.String)

replace

public void replace(Object object,
                    String name)

Replaces the element with the specified key in this name map.

If this name map contains an element with the key name, this method replaces that element's object with object. Otherwise, a runtime exception is thrown.

Parameters:

object - The new object for the element with the specified key, or null to make name the key for a null object reference. If an object is specified, it must be an instance of a persistence-capable class; if the object is transient, this method makes it persistent.

name - The key of the element to be replaced.

Throws:

ObjectNotPersistentException - If this name map is transient.

See Also:

remove(java.lang.String)

remove

public void remove(String name)

Removes the element with the specified key from this name map.

If forceAdd was used to add more than one element with the key name, this method deletes only the first such element it finds and gives no indication that there are other elements with the same key.

Parameters:

name - The key of the element to be removed. This method throws an exception if this name map does not contain an element with the key name. Before you call this method, you can call isMember to test whether name is a key.

Throws:

ObjectNotPersistentException - If this name map is transient.

See Also:

add(java.lang.Object, java.lang.String), replace(java.lang.Object, java.lang.String)

rehash

public void rehash(long binCount)

Resizes this name map's hash table.

Objectivity/DB automatically increases the size of the hash table as necessary. The only time you should need to call this method is when the number of bins is very large and the total number of elements is relatively small. This situation can occur when many elements are deleted after the hash table has grown to its peak size.

Parameters:

binCount - The new number of bins for the hash table. If this parameter is 0, the default number of bins (11) is used. For optimal performance, the number of bins should be a prime number.

Throws:

ObjectNotPersistentException - If this name map is transient.

clearParameters

public void clearParameters()

Resets the statistical parameters for this name map to zero.

Throws:

ObjectNotPersistentException - If this name map is transient.

See Also:

printStatistics()

copy

public Object copy(Object near)

Overrides the inherited method; disallows copying for name maps.

This method always throws an exception. If you want to copy this name map, you should create a new name map and add the elements of this name map to the new name map.

Overrides:

copy in class ooObj

Parameters:

near - Ignore

Returns:

Ignore

isMember

public boolean isMember(String name)

Tests whether this name map has an element with the specified key.

Parameters:

name - The key to be tested.

Returns:

True if this name map has an element with the key name; otherwise, false.

Throws:

ObjectNotPersistentException - If this name map is transient.

lookup

public Object lookup(String name)

Retrieves the object in this name map with the specified key.

Parameters:

name - The key to be looked up. This method throws an ObjyRuntimeException if this name map does not contain an element with the key name. Before you call this method, you can call isMember to test whether name is a key.

Returns:

The object in this name map with the specified key.

Throws:

ObjectNotPersistentException - If this name map is transient.

lookup

public Object lookup(String name,
                     int lockMode)

Retrieves the object in this name map with the specified key, locking the retrieved object as specified.

Parameters:

name - The key to be looked up. This method throws an ObjyRuntimeException if this name map does not contain an element with the key name. Before you call this method, you can call isMember to test whether name is a key.

lockMode - The type of lock to obtain for the retrieved object; one of the following constants defined in the oo interface:

READ

Obtain a read lock.

WRITE

Obtain a write lock.

Returns:

The object in this name map with the specified key; the returned object is locked as specified by lockMode.

Throws:

ObjectNotPersistentException - If this name map is transient.

getMaxAverageDensity

public long getMaxAverageDensity()

Gets the maximum average density of this name map's hash table.

Returns:

The maximum average density allowed before this name map must be resized.

Throws:

ObjectNotPersistentException - If this name map is transient.

getBinCount

public long getBinCount()

Gets number of bins in this name map's hash table.

Returns:

The number of bins currently in this name map's hash table.

Throws:

ObjectNotPersistentException - If this name map is transient.

getElementCount

public long getElementCount()

Gets the number of elements in this name map.

Returns:

The number of elements currently in this name map.

Throws:

ObjectNotPersistentException - If this name map is transient.

getGrowthFactor

public long getGrowthFactor()

Gets the growth factor of this name map's hash table.

Returns:

The growth factor, expressed as a percentage (for example, a return value of 100 indicates a growth factor of 100%).

Throws:

ObjectNotPersistentException - If this name map is transient.

isIntegrityMaintained

public boolean isIntegrityMaintained()

Tests whether Objectivity/DB automatically maintains the referential integrity of this name map.

By default, Objectivity/DB maintains the referential integrity of name maps. You can disable the automatic maintenance of referential integrity for a particular name map by calling its setIntegrityMaintained method.

Returns:

True if Objectivity/DB maintains the referential integrity of this name map; otherwise, false.

com.objy.db.ObjectNotPersistentException If this name map is transient.

setIntegrityMaintained

public void setIntegrityMaintained(boolean maintain)

Enables or disables maintenance of referential integrity for this name map.

By default, Objectivity/DB maintains the referential integrity of name maps. You may disable referential integrity to reduce the overhead of adding and deleting elements. However, if you disable referential integrity, you are responsible for deleting elements from the name map when the corresponding objects are deleted from the database.

If you call this method, you must call it before any elements are added to this name map.

Warning: Do not disable referential integrity unless you are fully aware of the consequences.

Parameters:

maintain - True to maintain referential integrity and false to disable maintenance of referential integrity.

Throws:

ObjectNotPersistentException - If this name map is transient.

See Also:

isIntegrityMaintained()

keys

public Iterator keys()

Initializes an iterator to find all the keys of this name map.

Returns:

An iterator that finds all the keys of this name map.

Throws:

ObjectNotPersistentException - If this name map is transient.

See Also:

elements()

elements

public Iterator elements()

Initializes an iterator to find all the objects in this name map.

Returns:

An iterator that finds all the persistent objects in this name map.

Throws:

ObjectNotPersistentException - If this name map is transient.

See Also:

keys()

printStatistics

public void printStatistics()

Prints runtime statistics for this name map to the standard output device.

This method prints the runtime statistics accumulated since this name map was created or since its clearParameters method was last called. It also prints this name map's growth characteristics and indicates whether Objectivity/DB automatically maintains the referential integrity of this name map.

The output identifies this name map by its OID, and gives the current date and time. This method produces output similar to:

     *********************************************
     Run statistics of ooMap #2-3-4-10  (Wed Mar 04 14:56:30 1998)

     ** Number of elements added            =>  10
     ** Number of elements removed          =>  0
     ** Number of rehashes                  =>  0
     ** Current state:
             Number of bins                 =>  11
             Number of elements             =>  10
             Maximum average density        =>  5
             Percent growth                 =>  100
             Average length per bin         =>  0.909091
             Maximum length                 =>  3
             Standard deviation of length   =>  0.899954
             Maintain referential integrity =>  Yes
     ***********************************************
 

Throws:

ObjectNotPersistentException - If this name map is transient.