com.objy.db.util
Class ooCompare

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

All Implemented Interfaces:

Comparator, IooObj, Persistent, PersistentEvents

public abstract class ooCompare

extends ooObj

implements Comparator

Abstract superclass for all comparator classes.

Because this class is abstract, you never instantiate it; instead, you work with instances of its concrete derived classes.

About Comparators

A comparator is an object of a concrete descendant class of ooCompare. It provides a comparison function for ordering elements of sorted collections and comparing elements of unordered collections, and a hashing function for computing the hash value for elements of unordered collections. Comparators can also be used to identify persistent objects based on some class-specific data.

You can define your own subclasses of ooCompare. For details, see Application-Defined Comparator Classes.

Comparing Elements of a Sorted Collection

Every sorted set and every sorted object map has an associated comparator. The comparator of a sorted collection defines a total ordering used by the underlying B-tree. Its compare method is used to compare two persistent objects and indicate their relative position in the total ordering. A sorted collection with a default comparator sorts persistent objects by their OIDs.

If elements of the sorted collection are persistent objects, the elements themselves are compared. If elements are key-value pairs, the element's keys are compared.

Hashing Elements of an Unordered Collection

Every unordered set and every unordered object map has an associated comparator. The comparator of a scalable unordered collection supplies the hash function used by the underlying extendible hash table. Its hash method computes the hash value for a persistent object; its compare method tests two persistent objects for equality. An unordered collection with a default comparator computes hash values for persistent objects from their OIDs and compares objects for equality by comparing their OIDs.

If elements of the unordered collection are persistent objects, hash values are computed from the elements themselves and elements are compared for equality. If elements are key-value pairs, hash values are computed from the element's keys and the keys are compared for equality.

Uniquely Identifying Elements of a Collection

An application-defined comparator class can optionally provide the ability to identify an element (or key) based on class-specific data.

Working With a Comparator

If your application uses an application-defined comparator class, you can instantiate the class to create comparators for your collections. A comparator is transient when it is created; you should make it persistent before you assign it to any collection. You typically make the comparator persistent by clustering it in the desired container.

A comparator is locked whenever you access its associated collection. To avoid locking conflicts, you typically cluster the comparator in a separate container. If the comparator is stored in the same container as the collection, applications may fail to get the necessary read lock on the comparator when another process is updating the collection. For guidelines about clustering, see Assigning Basic Objects to Containers.

After creating a comparator and making it persistent, you can assign it to any collections that need to use the comparator’s particular comparison and hashing methods. You assign a comparator to a collection by passing the comparator as a parameter to the constructor that creates the collection.

Typically, an application uses only comparators that it creates dynamically; it does not explicitly retrieve comparators from the database.

Note: The persistent data for a persistent collection includes a reference to its comparator. Your application should not create other persistent references to any comparator. For example, you should not add a comparator to a collection or reference a comparator in a persistent field of any persistent object.

Constructor Summary

protected

ooCompare() Reserved for internal use.

Method Summary

int	compare(Object obj1, Object obj2) Compares the two persistent objects.
int	hash(Object object) Computes the hash value for a persistent object.

Methods inherited from class com.objy.db.app.ooObj

activate, clearModified, cluster, copy, 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.Comparator

equals

Constructor Detail

ooCompare

protected ooCompare()

Reserved for internal use.

Method Detail

compare

public int compare(Object obj1,
                   Object obj2)

Compares the two persistent objects.

The default implementation for this method compares the OIDs of the two specified persistent objects.

Specified by:

compare in interface Comparator

Parameters:

obj1 - The first of the persistent objects to be compared. This object is an element (or key) of a persistent collection that uses this comparator.

obj2 - The second of the objects to be compared.

Typically, obj2 is the persistent object to be compared with obj1. If this is an instance of an application-defined comparator class that can identify persistent objects based on their persistent data, obj2 can instead be a transient object that identifies the persistent object to be compared with obj1.

Returns:

A negative integer if the first object is less than (sorts before) the second object; zero if the two objects are equal; a positive integer if the first object is greater than (sorts after) the second object.

hash

public int hash(Object object)

Computes the hash value for a persistent object.

The default implementation for this method computes the hash value from the OID of the persistent object.

Parameters:

object - The object from which to calculate the hash value.

Typically, object is an element or key of a persistent collection that uses this comparator. If this comparator is an instance of an application-defined comparator class that can identify persistent objects based on their persistent data, object can instead be a transient object that identifies the persistent object whose hash value is to be computed.

Returns:

The hash value for the specified object.