com.objy.db.util
Class ooTreeMap

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

All Implemented Interfaces:

IooObj, Map, Persistent, PersistentEvents, SortedMap

public final class ooTreeMap

extends ooBTree

implements SortedMap

Persistence-capable class for sorted object maps.

API Summary

You may not create your own subclasses of this class.

About Sorted Object Maps

A sorted object map is an ordered 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.

Like all collections implemented with B-trees, sorted object maps are scalable collections, that is, they can increase in size with minimal performance degradation.

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

For additional information, see Persistent Collections.

Working With a Sorted Object Map

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

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

Like any persistent object, a sorted object map belongs to the session that is in a transaction when the sorted object map is made persistent or retrieved. Objectivity/DB does not allow a sorted 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.

• ooHashMap represents an unordered object map. It uses an extendible hashing mechanism.

• 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	ooTreeMap() ooTreeMap(ooContObj, ooContObj) ooTreeMap(int) ooTreeMap(int, ooContObj, ooContObj) ooTreeMap(ooCompare) ooTreeMap(ooCompare, ooContObj, ooContObj) ooTreeMap(ooCompare, int) ooTreeMap(ooCompare, int, ooContObj, ooContObj)
Adding, Removing, and Changing Elements	put(Object, Object) putAll(Map) ooAddAll(ooCollection) ooRemove(Object) remove(Object)
Getting Elements	get(Object) firstKey() lastKey() keyIterator() valueIterator()
Getting Indexes	indexOf(Object, int)
Testing	containsKey(Object) containsValue(Object)

Inner classes inherited from class java.util.Map

Map.Entry

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

ooTreeMap()
Constructs an empty sorted object map with a default comparator and the default node size.

ooTreeMap(int maxNodeSize)
Constructs an empty sorted object map with a default comparator and the specified node size.

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

ooTreeMap(ooCompare compare)
Constructs an empty sorted object map with the specified comparator and the default node size.

ooTreeMap(ooCompare compare, int maxNodeSize)
Constructs an empty sorted object map with the specified comparator and node size.

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

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

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

Method Summary

boolean	add(Object object) Overrides the inherited method; disallows adding an element to this sorted object map.
boolean	contains(Object object) Tests whether the specified object is a key of this sorted object map.
boolean	containsKey(Object key) Tests whether this sorted object map contains an element with the specified key.
boolean	containsValue(Object value) Tests whether this sorted object map contains an element with the specified value.
Set	entrySet() Reserved for future use; you should not call this method.
Object	firstKey() Gets the first key in this sorted object map.
Object	get(Object key) Retrieves the value associated with the specified key in this sorted object map.
SortedMap	headMap(Object toKey) Reserved for future use; you should not call this method.
int	indexOf(Object object, int index) Searches forward in this sorted object map, starting at the specified index, for the first key that is equal to the specified object.
ooCollectionIterator	keyIterator() Initializes a collection iterator to find all keys in this sorted object map.
Set	keySet() Reserved for future use; you should not call this method.
Object	lastKey() Gets the last key in this sorted object map.
boolean	ooAddAll(ooCollection collection) Adds all elements in the specified collection to this sorted object map.
boolean	ooRemove(Object object) Removes the element of this sorted object map, if any, with the specified key.
Object	put(Object key, Object value) Maps the specified key to the specified value in this sorted object map.
void	putAll(Map map) Adds all elements in the specified map to this sorted object map.
Object	remove(Object object) Removes the element of this sorted object map, if any, with the specified key.
SortedMap	subMap(Object fromKey, Object toKey) Reserved for future use; you should not call this method.
SortedMap	tailMap(Object fromKey) Reserved for future use; you should not call this method.
ooCollectionIterator	valueIterator() Initializes a collection iterator to find all values in this sorted object map.
Collection	values() Reserved for future use; you should not call this method.

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

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

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

clear, comparator, copy, isEmpty, 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.SortedMap

comparator

Methods inherited from interface java.util.Map

clear, equals, hashCode, isEmpty, size

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

ooTreeMap

public ooTreeMap()

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

ooTreeMap

public ooTreeMap(ooContObj adminContainer,
                 ooContObj arrayContainer)

Constructs an empty sorted object map 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 object map. See Tree Administrator.

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

ooTreeMap

public ooTreeMap(ooCompare compare)

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

Parameters:

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

ooTreeMap

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

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

Parameters:

compare - The comparator for the new sorted object map; 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 object map. See Tree Administrator.

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

ooTreeMap

public ooTreeMap(int maxNodeSize)

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

Parameters:

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

ooTreeMap

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

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

Parameters:

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

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

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

ooTreeMap

public ooTreeMap(ooCompare compare,
                 int maxNodeSize)

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

Parameters:

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

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

ooTreeMap

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

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

Parameters:

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

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

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

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

Method Detail

add

public boolean add(Object object)

Overrides the inherited method; disallows adding an element to this sorted object map.

This method always throws an exception. You should use put instead of this method.

Overrides:

add in class ooCollection

Parameters:

object - Ignore

Returns:

Ignore

contains

public boolean contains(Object object)

Tests whether the specified object is a key of this sorted 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 ooBTree

Parameters:

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

Typically, object is a persistent object, namely the key of interest. If this sorted 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 Sorted Collections.

Returns:

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

containsKey

public boolean containsKey(Object key)

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

You can call this method to check whether this sorted 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 sorted object map.

Typically, key is a persistent object, namely the key of interest. If this sorted 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 Sorted Collections.

Returns:

True if this sorted 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 sorted object map contains an element with the specified value.

You can call this method to check whether this sorted 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 sorted object map.

Returns:

True if this sorted 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

firstKey

public Object firstKey()

Gets the first key in this sorted object map.

Specified by:

firstKey in interface SortedMap

Returns:

The key of the first element of this sorted object map.

See Also:

lastKey()

get

public Object get(Object key)

Retrieves the value associated with the specified key in this sorted 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 sorted 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 Sorted Collections.

Returns:

The value in the element with the specified key, or null if this sorted 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 sorted 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)

headMap

public SortedMap headMap(Object toKey)

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

Specified by:

headMap in interface SortedMap

indexOf

public int indexOf(Object object,
                   int index)

Searches forward in this sorted object map, starting at the specified index, for the first key that is equal to the specified object.

This method compares the key of 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 a persistent object, namely the key of interest. If this sorted 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 Sorted Collections.

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

Returns:

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

keyIterator

public ooCollectionIterator keyIterator()

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

Overrides:

keyIterator in class ooCollection

Returns:

A collection iterator that finds all the persistent objects used as keys in elements of this sorted object map. The iterator finds the keys in their sorted order.

See Also:

valueIterator()

lastKey

public Object lastKey()

Gets the last key in this sorted object map.

Specified by:

lastKey in interface SortedMap

Returns:

The key of the last element of this sorted object map.

See Also:

firstKey()

keySet

public Set keySet()

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

Specified by:

keySet in interface Map

ooAddAll

public boolean ooAddAll(ooCollection collection)

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

If collection is an object map, its elements are added to this sorted object map. If this sorted 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 sorted object map; the associated values are null. If this sorted 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 sorted object map.

Returns:

True if any elements were added; otherwise, false.

ooRemove

public boolean ooRemove(Object object)

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

Overrides:

ooRemove in class ooCollection

Parameters:

object - The key to be removed.

Typically, object is a persistent object, namely the key of the element to be removed from this sorted object map. If this sorted 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 the element to be removed. See Defining a Comparator Class for Sorted Collections.

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 sorted object map.

If this sorted 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 sorted object map, or null if there was no mapping for key.

Note that a null return might indicate that this sorted 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 sorted object map.

If this sorted 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 sorted 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)

valueIterator

public ooCollectionIterator valueIterator()

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

Returns:

A collection iterator that finds all the persistent objects used as values in elements of this sorted object map. The iterator finds the values in the sorted order of their keys.

See Also:

keyIterator()

values

public Collection values()

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

Specified by:

values in interface Map

remove

public Object remove(Object object)

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

Specified by:

remove in interface Map

Parameters:

object - The key to be removed.

Typically, object is a persistent object, namely the key of the element to be removed from this sorted object map. If this sorted 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 the element to be removed. See Defining a Comparator Class for Sorted Collections.

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 sorted object map previously mapped the key object to null.

subMap

public SortedMap subMap(Object fromKey,
                        Object toKey)

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

Specified by:

subMap in interface SortedMap

tailMap

public SortedMap tailMap(Object fromKey)

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

Specified by:

tailMap in interface SortedMap