org.hydrateframework
Class ObjectContext

java.lang.Object
  org.hydrateframework.ObjectContext

public class ObjectContext
extends java.lang.Object

An object context represents a single self-consistent representation of a business model. In order to stay self-consistent, the context manages a set of object indexes that help to guarantee object uniqueness and to resolve objects found in the database that refer to objects already in memory. The context also orchestrates blocking where an attempt is made to resolve a reference where the target object has not yet been loaded from the database.

Version:

@(#)$Revision: 1.9 $

Author:

David Chamberlin

Nested Class Summary

static class

ObjectContext.IndexEntry This class stores an entry in an index.when it needs to be passed to the outside world.

Field Summary

protected java.util.Map<ObjectCollection,java.util.Set<ObjectRelationshipFactory.RelationshipMap>>

m_mtms A Map holding a list of changes to be made to a many-to-many relationship.

Constructor Summary

ObjectContext(boolean isReadWrite)
Construct a new object context.

Method Summary

ObjectIndex	addIndex(ObjectIndex newIdx) Add an index to the context
void	addLoadErrorHandler(ObjectLoadErrorHandler handler)
void	addToIndex(ObjectKey key, java.lang.Object obj) Add a business object to alternate key indexes that it is not already a part of.
void	blockOn(java.lang.Object instOrCls, java.lang.String mbr, boolean add) This call is used to request that the infrastructure block on requests for a particular object member on a particular class.
void	clearAll()
boolean	clearLoadErrorHandler(ObjectLoadErrorHandler handler)
void	constructed(java.lang.Object o) This method is called by a model object on construction and allows the context to take any special required action on object creation.
java.io.PrintStream	dumpIndexes(java.io.PrintStream out) This diagnostic function prints out a list of indexes and their contents.
ObjectAccessEventHandler	getAccessEventHandler(java.lang.Class cls)
java.lang.Class	getBusinessClass(java.lang.Object o) Returns the interface that represents the most-derived class that is part of the current object model that this object supports.
static ObjectContext	getDefaultContext(java.lang.Class familyClass)
ObjectFactory	getFactory(java.lang.Class cls) Return a factory for creating objects of the specified
java.util.Set<ObjectRelationshipFactory.RelationshipMap>	getMTM(ObjectCollection coll, boolean forSave)
java.util.List	getObjectsAsList(java.lang.Class obj, java.lang.Class keyCls) Return the objects in a list - dh
ObjectRelationshipFactory	getRelationshipFactory(java.lang.String name) Return the factory for creating the link between objects with a many-to-many relationship.
RequestContext	getRequestContext()
java.lang.Object	handleClassMismatch(java.lang.Object existing, java.lang.Class newClass, ObjectKey newKey)
boolean	isDirty(java.lang.Object o)
boolean	isForSave() Determine if changes are to be saved in the database.
java.util.Iterator	iterateObjects(java.lang.Class obj, java.lang.Class keyCls) returns an iterator for a particular class of object.
java.util.Iterator	iterateObjects(java.lang.Class obj, java.lang.Class keyCls, boolean concurrent) Iterate through objects in an index.
void	needKeyNow(java.lang.Object obj) This may be needed during batch inserts where a key is required for an object that has been inserted, but whose batch has not yet run.
java.lang.Object	removeObject(ObjectKey key) Drop an object from an index.
java.lang.Object	resolveKey(ObjectKey key) Try to find a business object given its primary key.
java.lang.Object	resolveKeyTo(ObjectKey key, java.lang.Class toCls) Try to find a business object given its primary key.
void	saveAll() Save all changed objects in the context.
void	setAccessEventHandler(java.lang.Class<?> cls, ObjectAccessEventHandler hnd)
static void	setDefaultContext(ObjectContext ctx)
ObjectFactory	setFactory(java.lang.Class cls, ObjectFactory fact) Establish the factory to be used to create a particular object type.
void	setNeedsUpdate(HydrateObject o, boolean needsUpdate)
void	setObjectOrder(java.lang.Class[] classes) Provide a dependency ordering for the objects in the model.
ObjectRelationshipFactory	setRelationshipFactory(java.lang.String name, ObjectRelationshipFactory fact) Establish the factory to be used to create a link between objects
void	setRequestContext(RequestContext rc) Establish the request context for this object context.
void	setUpdateStrategy(int strategy, int batchSize) Establish the update strategy to be used in the database.
HydrateObject	tempProxy(java.lang.Object o) Provides a temporary proxy for a non-hydrate object.
java.lang.Object	tryResolveKey(ObjectKey key) Try to find a business object given its primary key.
boolean	waitForPopulation(java.lang.Object what, HydrateObject obj, java.lang.String mbr) Block the current thread waiting for the population of a particular business object attribute or collection.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

m_mtms

protected java.util.Map<ObjectCollection,java.util.Set<ObjectRelationshipFactory.RelationshipMap>> m_mtms

A Map holding a list of changes to be made to a many-to-many relationship. The way two objects are related in such a relationship is recorded in a like table containing only the primary keys of the two related objects. This vector records the changes to that table before they are committed to the database

Constructor Detail

ObjectContext

public ObjectContext(boolean isReadWrite)

Construct a new object context. Object contexts usually live for the period of a request, but may survive between requests to provide a simple cache.

Parameters:

isReadWrite - true if updates to objects in the context will be saved in the database.

Method Detail

getDefaultContext

public static ObjectContext getDefaultContext(java.lang.Class familyClass)

setDefaultContext

public static void setDefaultContext(ObjectContext ctx)

addLoadErrorHandler

public void addLoadErrorHandler(ObjectLoadErrorHandler handler)

clearLoadErrorHandler

public boolean clearLoadErrorHandler(ObjectLoadErrorHandler handler)

handleClassMismatch

public java.lang.Object handleClassMismatch(java.lang.Object existing,
                                            java.lang.Class newClass,
                                            ObjectKey newKey)
                                     throws SaveException

Throws:

SaveException

getBusinessClass

public java.lang.Class getBusinessClass(java.lang.Object o)

Returns the interface that represents the most-derived class that is part of the current object model that this object supports. This method relies on setObjectOrder(java.lang.Class[]) having been called which happens automatically on a call to <FamilyName>.configureContext(ctx)

Parameters:

o - The object whose class is to be known

Returns:

the interface or null if no interface is found

tempProxy

public HydrateObject tempProxy(java.lang.Object o)

Provides a temporary proxy for a non-hydrate object. Use this method when you need an HydrateObject but have an object that does not implement it. This method returns a new proxy object each time, so it is only useful for stateless uses of HydrateObject.

Parameters:

o - The object for which a proxy is required.

Returns:

The proxy object. It is guaranteed to implement hydrate object, but will not necessarily implement the interfaces of the object it is proxying.

constructed

public void constructed(java.lang.Object o)

This method is called by a model object on construction and allows the context to take any special required action on object creation.

Parameters:

o - the object that was just constructed.

getMTM

public java.util.Set<ObjectRelationshipFactory.RelationshipMap> getMTM(ObjectCollection coll,
                                                                       boolean forSave)

setNeedsUpdate

public void setNeedsUpdate(HydrateObject o,
                           boolean needsUpdate)

setObjectOrder

public void setObjectOrder(java.lang.Class[] classes)

Provide a dependency ordering for the objects in the model. Where dependencies between objects exist, which may be either superclass relationships or -to-one relationships, the dependent class is guaranteed to appear later in the list than the class or classes on which it depends. This method is called automatically in the .configureContext(ctx) method.

Parameters:

classes - the ordered list of classes.

setRequestContext

public void setRequestContext(RequestContext rc)

Establish the request context for this object context. A request context should be constructed with each data request and attached to the object context through this call.

Parameters:

rc - the request context

getFactory

public ObjectFactory getFactory(java.lang.Class cls)

Return a factory for creating objects of the specified

Parameters:

cls - the class (interface) for which a factory is to be returned.

Returns:

the factory

setFactory

public ObjectFactory setFactory(java.lang.Class cls,
                                ObjectFactory fact)

Establish the factory to be used to create a particular object type.

Parameters:

cls - the class (interface) for which the factory is to be set.

fact - the factory class.

Returns:

the previous factory.

getRelationshipFactory

public ObjectRelationshipFactory getRelationshipFactory(java.lang.String name)

Return the factory for creating the link between objects with a many-to-many relationship.

Parameters:

name - the name of the relationship.

Returns:

the factory for creating the relationship.

setRelationshipFactory

public ObjectRelationshipFactory setRelationshipFactory(java.lang.String name,
                                                        ObjectRelationshipFactory fact)

Establish the factory to be used to create a link between objects

Parameters:

name - the name of the relationship to which the factory applies.

fact - the factory object.

Returns:

the old factory object or null if there is none.

blockOn

public void blockOn(java.lang.Object instOrCls,
                    java.lang.String mbr,
                    boolean add)

This call is used to request that the infrastructure block on requests for a particular object member on a particular class. In a one-to-many relationship of manager to employee. This might be used to force requests for the manager from the employee or requests to examine the manager's employee collection to block until a particular query has finished.

Parameters:

instOrCls - this object is an instance of the business on whose member to block or, alternatively the class object that represents the implemented business interface for which blocking should occur for all instances.

mbr - the name of the member to block on. This name should be one of the strings defined in the business object interface to represent object members.

add - true to add the block, false to remove it.

getRequestContext

public RequestContext getRequestContext()

Returns:

a general purpose default persistence context that can be used for retrieving information from the persistent store into this business object context

isForSave

public boolean isForSave()

Determine if changes are to be saved in the database.

Returns:

true if changes are to be saved

clearAll

public void clearAll()

isDirty

public boolean isDirty(java.lang.Object o)

saveAll

public void saveAll()
             throws SaveException

Save all changed objects in the context. This call searches through all primary key indexes and calls the 'save' method on any dirty objects found. Note that because the objects always try to save any objects they themselves reference - this is especially necessary when new objects are being added to make sure that primary key IDs have been created for referenced objects before attempting to add the referencing object - and that the sequential order of indexes is dependent on the hashing algorithm, the actual order in which objects are saved will be rather unpredictable.

Throws:

SaveException - if there was a problem with the save

needKeyNow

public void needKeyNow(java.lang.Object obj)

This may be needed during batch inserts where a key is required for an object that has been inserted, but whose batch has not yet run.

Parameters:

obj - the object that needs a key.

setUpdateStrategy

public void setUpdateStrategy(int strategy,
                              int batchSize)

Establish the update strategy to be used in the database. Different update strategies may have different performance and recovery characteristics with different JDBC drivers. some combinations may not work at all.

Parameters:

strategy - The strategy is one or more of the NamedParameterStatement.STRATEGY_... flags. You may boolean or (|) multiple flags together.

batchSize - the size of the batch. A batch size of other than one automatically sets the NamedParameterStatement.STRATEGY_BATCH flag

addIndex

public ObjectIndex addIndex(ObjectIndex newIdx)

Add an index to the context

Parameters:

newIdx - the index to add

Returns:

an index that was replaced or null

dumpIndexes

public java.io.PrintStream dumpIndexes(java.io.PrintStream out)

This diagnostic function prints out a list of indexes and their contents.

Parameters:

out - the stream to output data to.

Returns:

the stream that data was output to.

iterateObjects

public java.util.Iterator iterateObjects(java.lang.Class obj,
                                         java.lang.Class keyCls)

returns an iterator for a particular class of object. The returned iterator gives access to each of the objects in the context of the given class.

getObjectsAsList

public java.util.List getObjectsAsList(java.lang.Class obj,
                                       java.lang.Class keyCls)

Return the objects in a list - dh

Parameters:

obj -

keyCls -

Returns:

the objects in the given index as a list.

iterateObjects

public java.util.Iterator iterateObjects(java.lang.Class obj,
                                         java.lang.Class keyCls,
                                         boolean concurrent)

Iterate through objects in an index.

Parameters:

obj - the class of object that we want to iterate.

keyCls - the class of the key that indicates the index to iterate.

concurrent - true if the iteration needs to be isolated from concurrent changes to the list (from another thread).

Returns:

the iterator to be used.

addToIndex

public void addToIndex(ObjectKey key,
                       java.lang.Object obj)

Add a business object to alternate key indexes that it is not already a part of. This call is made after an update to an object has supplied enough information to determine an alternate key.

Parameters:

obj - the object to be added to indexes in this context

removeObject

public java.lang.Object removeObject(ObjectKey key)

Drop an object from an index.

Parameters:

key - the key that is being used to index the object. The index from which the object is removed is specific to this key.

Returns:

the object that was removed or null if it wasn't found in the index.

tryResolveKey

public java.lang.Object tryResolveKey(ObjectKey key)

Try to find a business object given its primary key.

Parameters:

key - the primary key of the business object.

Returns:

the object found or null if no object with the given primary key could be found.

resolveKey

public java.lang.Object resolveKey(ObjectKey key)
                            throws NotLoadedException

Try to find a business object given its primary key.

Parameters:

key - the primary key of the business object.

Returns:

the object found.

Throws:

NotLoadedException - if the object could not be found.

resolveKeyTo

public java.lang.Object resolveKeyTo(ObjectKey key,
                                     java.lang.Class toCls)
                              throws NotLoadedException

Try to find a business object given its primary key. Check to see if an object of the correct class has been returned and print a warning if the types do not match.

Parameters:

key - the primary key of the business object.

Returns:

the object found.

Throws:

NotLoadedException - if the object could not be found.

setAccessEventHandler

public void setAccessEventHandler(java.lang.Class<?> cls,
                                  ObjectAccessEventHandler hnd)

getAccessEventHandler

public ObjectAccessEventHandler getAccessEventHandler(java.lang.Class cls)

waitForPopulation

public boolean waitForPopulation(java.lang.Object what,
                                 HydrateObject obj,
                                 java.lang.String mbr)

Block the current thread waiting for the population of a particular business object attribute or collection.

Parameters:

what - the thing that we are waiting for.

obj - the business object instance whose attribute we are waiting to be populated.

mbr - the name of the attribute within the business object.

Returns:

false if the wait timed out, was cancelled. This indicates that the thing being waited for, whatever it was never turned up.