org.hydrateframework
Class ObjectFactory

java.lang.Object
  org.hydrateframework.ObjectFactory

public class ObjectFactory
extends java.lang.Object

Version:

@(#)$Revision: 1.6 $

Author:

David Chamberlin An object factory is the class used to read and write an object of a particular class to and from the database. This class is making two important decisions about the object construction process

1. The concrete class of object that will be built. The framework assumes that an object that supports the appropriate HydrateObject-derived interface and the code generator supplies a default implementation. However, the designer can sub class the generated implementation, or provide an independent implementation and would use the ObjectFactory class to ensure that it is the customized concrete class that gets created as a result of the object build process. The createObject(org.hydrateframework.ObjectContext, org.hydrateframework.ObjectKey) method can be used to create an object of the designated class.
2. The default database and query that will be used to read and write the object from a database. The loadObject(org.hydrateframework.ObjectContext, org.hydrateframework.ObjectKey, int) method reads a single object from the the database using the default query, and the saveObject(org.hydrateframework.SaveContext, java.lang.Object, java.lang.Class) method writes a changed object back.

Note that in Hydrate, objects are typically retrieved from the database by writing queries and linking the results of the query to the various objects to be created. This process uses the factory to define the constructed object's concrete class, but does not use the default database reading. In fact, the object can subsequently be written back to the default database for faster retrieval later. This model in which the in-memory model is populated from a legacy data store, and then cached into the default database structure has been found to be useful in many situations.

Constructor Summary

ObjectFactory(ObjectContext ctx, java.lang.Class ifcClass, java.lang.Class implClass, java.lang.Class assemblerClass, java.lang.Class queryToUse, java.lang.String dsName, java.lang.Class proxyClass)
Construct a factory for creating Hydrate Objects.

Method Summary

java.lang.Object	createObject(ObjectContext ctx, ObjectKey key) Create an object with a key.
void	deleteObject(SaveContext sc, java.lang.Object obj, java.lang.Class keyClass) Remove an object from the database.
Assembler	getAssembler()
java.lang.String	getDsName() Return the name of the datasource that this factory uses when reading or writing objects from the default database.
NamedParameterStatement	getStatement(RequestContext rc)
java.lang.Object	loadObject(ObjectContext ctx, ObjectKey key, int bldType) Load an object using a key.
HydrateObject	proxyObject(ObjectContext ctx, java.lang.Object o) Provides a temporary proxy for a non-Hydrate object.
void	readKeyBatch(SaveContext sc, NamedParameterStatement stmt, java.util.List objs) Called to get database generated keys for objects that were updated in a batch.
java.lang.Object	reloadObject(ObjectContext ctx, java.lang.Object obj) Reload an existing object.
void	saveObject(SaveContext sc, java.lang.Object obj, java.lang.Class keyClass) Update the database with changes made to a business object.

Methods inherited from class java.lang.Object

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

Constructor Detail

ObjectFactory

public ObjectFactory(ObjectContext ctx,
                     java.lang.Class ifcClass,
                     java.lang.Class implClass,
                     java.lang.Class assemblerClass,
                     java.lang.Class queryToUse,
                     java.lang.String dsName,
                     java.lang.Class proxyClass)

Construct a factory for creating Hydrate Objects.

Parameters:

ctx - the object context into which this factory will be objects by default.

implClass - the concrete class of object that this factory will build

assemblerClass - the class of assembler used to build objects - must be compatible with implClass

queryToUse - the query to use to read and write objects to the database

dsName - the name of the datasource to which objects will be read and written

Method Detail

getDsName

public java.lang.String getDsName()

Return the name of the datasource that this factory uses when reading or writing objects from the default database.

Returns:

the name of the data source e.g. jdbc/Test

proxyObject

public HydrateObject proxyObject(ObjectContext ctx,
                                 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.

Parameters:

ctx - the object context in which the proxy object will reside.

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.

createObject

public java.lang.Object createObject(ObjectContext ctx,
                                     ObjectKey key)

Create an object with a key. This method creates a new object of the class for which this factory has been configured. If a key is supplied the object will be initialized with information from that key.

getStatement

public NamedParameterStatement getStatement(RequestContext rc)
                                     throws SaveException

Returns:

to query object that is used to get data to populate objects

Throws:

SaveException

getAssembler

public Assembler getAssembler()

reloadObject

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

Reload an existing object. This is useful where an object has been incompletely populated or where a cached version of an object has been updated in the database by another party.

Parameters:

obj - The object to be reloaded from the database

Returns:

the call will return the same object reference after it has been refreshed from the database or null if the object was deleted.

Throws:

SaveException

loadObject

public java.lang.Object loadObject(ObjectContext ctx,
                                   ObjectKey key,
                                   int bldType)
                            throws SaveException

Load an object using a key. The call uses the ObjectKey.constrainQuery(org.hydrateframework.sql.NamedParameterStatement, java.lang.String) callback on the key object to restrict the query to a single row.

Parameters:

ctx - the business object context to load the object into.

key - the key to use to load the object.

bldType - one of the Assembler.BUILD_- values.

Returns:

the object loaded from the database or null if no such object existed.

Throws:

SaveException

saveObject

public void saveObject(SaveContext sc,
                       java.lang.Object obj,
                       java.lang.Class keyClass)
                throws SaveException

Update the database with changes made to a business object. This method will only update the scalar and many-to-one relationships (i.e. those that have fields in the corresponding relational database table) in the object. If the object does not exist in the database (has getKey().isPersisted() false), the object will be inserted into the database. As part of this process a new key will be generated and assigned and the object will be re-indexed as a result.

Parameters:

obj - the business object that is to be updated or inserted

Throws:

SaveException

readKeyBatch

public void readKeyBatch(SaveContext sc,
                         NamedParameterStatement stmt,
                         java.util.List objs)
                  throws SaveException

Called to get database generated keys for objects that were updated in a batch. It is called when a referencing object needs the key in order to save down. This doesn't work with any JDBC drivers I've tried :-(

Parameters:

sc - the save context

stmt - the batched statement that will generate keys.

objs - a list of objects that need keys - there should be the same number of objects in the list as update statements in the batch, in the same order.

Throws:

SaveException

deleteObject

public void deleteObject(SaveContext sc,
                         java.lang.Object obj,
                         java.lang.Class keyClass)
                  throws SaveException

Remove an object from the database. This will use the query returned by getStatement(org.hydrateframework.RequestContext) to remove the data for this object from the database. This is purely a database operation. It will not remove the object from memory although the memory version will have its key set to null. It will not remove any references to this object by other objects though if any exist, the delete operation will probably fail due to violated reference integrity constraints.

Parameters:

obj - the object to be removed from the database.

Throws:

SaveException