org.hydrateframework
Class SaveContext

java.lang.Object
  org.hydrateframework.SaveContext

public class SaveContext
extends java.lang.Object

The SaveContext class keeps track of the state of Hydrate Objects as they are saved in the database. You need to create one of these objects before starting a save session, and you need to wrap the save activity with calls to beginSave()/beginTran(java.lang.String) and finishSave()/finishTran(String, boolean). The class keeps track of what has been saved so far, ensures that recursive relationships are saved efficiently, many-to-many tables are updated correctly and that non-HydrateObjects are tracked.

Version:

@(#)$Revision: 1.5 $

Author:

David Chamberlin

Field Summary

protected static org.apache.commons.logging.Log

m_log

Constructor Summary

SaveContext(ObjectContext ctx, RequestContext rc)
Create a new SaveContext

Method Summary

void	beginSave() Start a save process without a transaction.
boolean	beginTran(java.lang.String name) Start a save process with a transaction.
void	deferReadKey(NamedParameterStatement stmt, java.lang.Object obj) Defer the reading of a database generated key.
void	dump(java.io.PrintStream out) Dump out the details of the save context showing how many objects have been saved and how many are scheduled for later saving.
void	finishSave() Complete a non transactional save process, or one in which the transaction is controlled externally.
boolean	finishTran(java.lang.String name, boolean commit) Complete a transactional save process.
void	flushStatement(ObjectContext ctx, java.lang.Class cls) Flush a statement that was used to update or insert objects in batch mode.
RequestContext	getRequestContext() Get the request context
boolean	isInTransaction(java.lang.String name) return the transaction status of the save session
boolean	isSaved(java.lang.Object bo) Determine if the given object has been saved in this session
void	needKeyNow(ObjectContext ctx, java.lang.Object obj) Call this method when a generated key is accessed.
HydrateObject	proxy(java.lang.Object o) Proxy a non-hydrate object with an HydrateObject.
void	saveLater(java.lang.Object bo) Add an object to the list of objects that must be saved at the end of the session if not already saved.
void	saveLaterMTM(java.lang.String relationshipName, java.util.Collection<ObjectRelationshipFactory.RelationshipMap> coll) Add a many to many relationship that will be saved at the end of the session.
void	saveMTMs(ObjectCollection<HydrateObject> coll)
void	setSaved(java.lang.Object bo) Establish an object as having been saved
void	unsetSaved(java.lang.Object bo) Mark an object as not having been saved.

Methods inherited from class java.lang.Object

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

Field Detail

m_log

protected static final org.apache.commons.logging.Log m_log

Constructor Detail

SaveContext

public SaveContext(ObjectContext ctx,
                   RequestContext rc)

Create a new SaveContext

Parameters:

ctx - the object context from which objects will be saved.

rc - the request context that has the connections and queries for the save.

Method Detail

getRequestContext

public RequestContext getRequestContext()

Get the request context

Returns:

the request context

proxy

public HydrateObject proxy(java.lang.Object o)

Proxy a non-hydrate object with an HydrateObject.

Parameters:

o - the object to be proxied. If it is already an HydrateObject, the method simply returns a reference to this object.

Returns:

the proxied object which is guaranteed to implement HydrateObject. If proxy has been called before on this SaveContext on this object, the same object will be returned.

isSaved

public boolean isSaved(java.lang.Object bo)

Determine if the given object has been saved in this session

Parameters:

bo - the object for which save status is required

Returns:

true if the object has been saved, false if not.

setSaved

public void setSaved(java.lang.Object bo)

Establish an object as having been saved

Parameters:

bo - the object that has been saved.

unsetSaved

public void unsetSaved(java.lang.Object bo)

Mark an object as not having been saved.

Parameters:

bo - the object to be marked

saveLater

public void saveLater(java.lang.Object bo)

Add an object to the list of objects that must be saved at the end of the session if not already saved.

Parameters:

bo -

saveLaterMTM

public void saveLaterMTM(java.lang.String relationshipName,
                         java.util.Collection<ObjectRelationshipFactory.RelationshipMap> coll)

Add a many to many relationship that will be saved at the end of the session.

Parameters:

relationshipName - the name of the relationship to be saved

coll - the collection that holds the references

isInTransaction

public boolean isInTransaction(java.lang.String name)

return the transaction status of the save session

Parameters:

name - the name of the connection that is the commit agent

Returns:

true if the given connection is in a transaction.

saveMTMs

public void saveMTMs(ObjectCollection<HydrateObject> coll)

beginSave

public void beginSave()

Start a save process without a transaction. This method or the beginTran(String) method must be called after creating the SaveContext, but before saving any objects.

finishSave

public void finishSave()
                throws SaveException

Complete a non transactional save process, or one in which the transaction is controlled externally. This method must be called when the object save session is complete if it was started with beginSave().

Throws:

SaveException

beginTran

public boolean beginTran(java.lang.String name)

Start a save process with a transaction. This method or the beginSave() method must be called after creating the SaveContext, but before saving any objects.

Parameters:

name - the name of the transaction.

Returns:

true if the transaction was started successfully.

finishTran

public boolean finishTran(java.lang.String name,
                          boolean commit)
                   throws SaveException

Complete a transactional save process. This method must be called when the object save session is complete if it was started with beginTran(java.lang.String).

Parameters:

name - the name of the transaction.

commit - true if the transaction is being committed, false otherwise.

Returns:

true if the transaction was completed successfully.

Throws:

SaveException

dump

public void dump(java.io.PrintStream out)

Dump out the details of the save context showing how many objects have been saved and how many are scheduled for later saving.

Parameters:

out - the stream to write to.

needKeyNow

public void needKeyNow(ObjectContext ctx,
                       java.lang.Object obj)
                throws SaveException

Call this method when a generated key is accessed. In the case where the key reading has been deferred because we are in batch update mode, this method will resolve those keys.

Parameters:

ctx - the object context containing objects and factories

obj - the object that needs a key - all outstanding objects of this type will be resolved

Throws:

SaveException

flushStatement

public void flushStatement(ObjectContext ctx,
                           java.lang.Class cls)
                    throws SaveException

Flush a statement that was used to update or insert objects in batch mode.

Parameters:

ctx - the object context used in the save

cls - the class of object that is to be flushed

Throws:

SaveException

deferReadKey

public void deferReadKey(NamedParameterStatement stmt,
                         java.lang.Object obj)

Defer the reading of a database generated key. This method is used when a statement is executing several inserts as a batch. The new generated keys are not immediately available. This will be resolved when the batch is executed

Parameters:

stmt - the statement that is being batched up.

obj - the object that won't have a key because of the batching process.