org.hydrateframework
Class Assembler

java.lang.Object
  org.hydrateframework.Assembler

All Implemented Interfaces:

AssemblerLink

public abstract class Assembler
extends java.lang.Object
implements AssemblerLink

Assembler objects are responsible for extracting the data for a particular object from a row of ResultSet data. A concrete class of Assembler object is needed for object in the data model. The Hydrate code generation will automatically generate assembler classes for each object described in the class definition file. Efficiency is an important consideration in the design of this class. After a query has been executed, the result set is first presented to the assembler class to allow it to determine whether the results have sufficient information to create an object. The location of any attributes in the query that pertain to this assembler will be noted at this stage. As the result set is iterated, this information is used to create or find objects and populate them with data from the query.

Version:

@(#)$Revision: 1.11 $

Author:

David Chamberlin

Nested Class Summary

static interface	Assembler.AfterBuild Implement this interface if you need to be called back each time a new object is created during the build process.
static interface	Assembler.Discriminator This interface is used to determine whether an object should be built or not.
static class	Assembler.PrefixMap An implementation of the map interface that behaves as if it contains a value for any key supplied that is the same as the key but with a specified prefix prepended to it.
static class	Assembler.TestCol A Discriminator implementation that decides whether or not to build an object based on whether a particular column has a particular value.
static class	Assembler.TestKey A Discriminator implementation for class hierarchies.

Field Summary

static int	BUILD_CHECKDB
static int	BUILD_CHECKMEM
static int	BUILD_CHECKMEMCREATE look in memory, create if not found
static int	BUILD_CHECKMEMDBCREATE look in memory, then in the database, create if not found
static int	BUILD_CHECKMEMDBONLY look in memory, then in the database for existing object and discard data from query if found
static int	BUILD_CHECKMEMDBREFRESH look in memory, then in the database and update object from query
static int	BUILD_CHECKMEMONLY look in memory for an existing object and discard data from query if object is found
static int	BUILD_CHECKMEMREFRESH look in memory and update from the query (default)
static int	BUILD_CREATE create new object
static int	BUILD_NOCHECK do nothing at all
static int	BUILD_REFRESH
protected boolean	m_autoFixup
protected int	m_bldType
java.util.Map	m_columns
protected java.lang.Object	m_lastBuilt
protected java.lang.Object[]	m_lastBuiltArray
protected static org.apache.commons.logging.Log	m_log
protected java.util.Set<java.lang.String>	m_usedColumns

Constructor Summary

Assembler(ObjectContext ctx, java.lang.String name, java.lang.Class<java.lang.Object> cls, ObjectFactory fact, KeyAssembler kb, java.util.Map columns, Assembler.Discriminator incl, int buildType, boolean autoFixup)
The constructor sets the class type to be built and the factory to do the job

Method Summary

java.lang.Object	buildOneObject(java.sql.ResultSet rs) This method instructs this assembler to try to build one object of the class implied by the assembler's concrete class from the current row of the results set.
abstract void	delete(java.lang.Object obj, NamedParameterStatement stmt, java.lang.Class keyClass) This method is overridden by class specific implementations of the assembler to use the results set retrieved from the given statement to delete this object's database representation.
java.lang.Object	getBuiltObject() Get the object that this assembler, or assemblers have just built or null if none has been built yet.
java.lang.Object[]	getBuiltObjects() If mroe than one assembler is active in a particular query, more than one object may be returned.
java.lang.Class<java.lang.Object>	getClassToBuild() Returns a class object that represents the interface of the object that will be built by this assembler.
java.util.Map	getColumns() Return the map that is owned by this assembler to map attribute names into column names.
ObjectContext	getContext()
ObjectFactory	getFactory() Returns the factory object that should be used to construct instances of the object built by this assembler
java.sql.ResultSet	getInsertResultSet(java.lang.Object obj, NamedParameterStatement stmt) This is a helper method that is used to create a results set that can be used to insert objects through this assembler into a database.
KeyAssembler	getKeyAssembler() Return the KeyAssembler used to build the object's key from the query
java.lang.String	getName() Return the name of the assembler.
java.sql.ResultSet	getResultSet() Return the ResultSet object that was used in preparing the assembler.
NamedParameterStatement	getStatement(RequestContext rc) Get the default query.
java.sql.ResultSet	getUpdateResultSet(java.lang.Object obj, NamedParameterStatement stmt, java.lang.Class keyCls) This is a helper method that is used to create a results set that can be used to update objects through this assembler into a database.
protected abstract boolean	initObject(java.lang.Object oo, ObjectKey key) Initialize the object now with values read from the query.
abstract void	insert(java.lang.Object obj, NamedParameterStatement stmt) This method is overridden by class specific implementations of the assembler to write the internals of a given business object to the 'forUpdate' results set retrieved from the given statement, ready for creating a new object in the database.
static java.lang.String	mapColumns(java.util.Map columns, java.lang.String value) Static method to map the attribute name of an object to the column name of the query.
java.lang.String	mapColumns(java.lang.String value) Map the attribute name of an object to the column name of the query.
void	postCreate(java.sql.ResultSet rs, java.lang.Object o, boolean isNew) A function that is called after an object has been built by this assembler.
boolean	prepareToProcessResults(java.sql.ResultSet rs, java.sql.Statement stmt, boolean forUpdate) This method is called after running the SQL statement, but before starting to iterate through the restuls set.
void	setConnection(java.sql.Connection conn) Establish the connection that is being used with this assembler.
abstract void	setLink(java.lang.String linkName, Assembler other) This method is used to establish a link between assemblers during the build process.
void	setPostBuild(Assembler.AfterBuild pb) Register a class to be called back each time a new object is created.
boolean	shouldBuild(java.sql.ResultSet rs) Determine if we should build an object or not, based on the content of of the current QueryResults
protected boolean	shouldInitExisting()
void	startNewRow() This method must be called on each assembler each time anew row is started in the results set.
abstract void	update(java.lang.Object obj, NamedParameterStatement stmt, java.lang.Class keyClass) This method is overridden by class specific implementations of the assembler to write the internals of a given business object to the 'forUpdate' results set retrieved from the given statement, ready for updating an existing object in the database.

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

BUILD_NOCHECK

public static final int BUILD_NOCHECK

do nothing at all

See Also:

Constant Field Values

BUILD_CHECKMEMONLY

public static final int BUILD_CHECKMEMONLY

look in memory for an existing object and discard data from query if object is found

See Also:

Constant Field Values

BUILD_CHECKMEMREFRESH

public static final int BUILD_CHECKMEMREFRESH

look in memory and update from the query (default)

See Also:

Constant Field Values

BUILD_CHECKMEMDBONLY

public static final int BUILD_CHECKMEMDBONLY

look in memory, then in the database for existing object and discard data from query if found

See Also:

Constant Field Values

BUILD_CHECKMEMDBREFRESH

public static final int BUILD_CHECKMEMDBREFRESH

look in memory, then in the database and update object from query

See Also:

Constant Field Values

BUILD_CHECKMEMCREATE

public static final int BUILD_CHECKMEMCREATE

look in memory, create if not found

See Also:

Constant Field Values

BUILD_CHECKMEMDBCREATE

public static final int BUILD_CHECKMEMDBCREATE

look in memory, then in the database, create if not found

See Also:

Constant Field Values

BUILD_CREATE

public static final int BUILD_CREATE

create new object

See Also:

Constant Field Values

BUILD_REFRESH

public static final int BUILD_REFRESH

See Also:

Constant Field Values

BUILD_CHECKDB

public static final int BUILD_CHECKDB

See Also:

Constant Field Values

BUILD_CHECKMEM

public static final int BUILD_CHECKMEM

See Also:

Constant Field Values

m_bldType

protected int m_bldType

m_autoFixup

protected boolean m_autoFixup

m_columns

public java.util.Map m_columns

m_usedColumns

protected java.util.Set<java.lang.String> m_usedColumns

m_lastBuiltArray

protected java.lang.Object[] m_lastBuiltArray

m_lastBuilt

protected java.lang.Object m_lastBuilt

Constructor Detail

Assembler

public Assembler(ObjectContext ctx,
                 java.lang.String name,
                 java.lang.Class<java.lang.Object> cls,
                 ObjectFactory fact,
                 KeyAssembler kb,
                 java.util.Map columns,
                 Assembler.Discriminator incl,
                 int buildType,
                 boolean autoFixup)

The constructor sets the class type to be built and the factory to do the job

Parameters:

ctx - the Object context into which this assembler will build objects

name - the name of the assembler - this is used to distinguish two assemblers of the same class in the same query.

cls - The class object that represents the interface of the business object that will be built by this assembler.

fact - The object factory that determines the concrete class that will be constructed that supports the 'cls' interface

kb - the KeyAssembler determines which key is used to identify the object

columns - a map that maps attribute names in the object to column names in the query

incl - an implementation of this interface determines whether the assembler should build an object from the current row.

buildType - one of the BUILD_... values

autoFixup - determines whether this Assembler should attempt to automatically resolve foreign key references. If such a foreign key is read from the results of a query, the assembler has enough information to create an empty object (or find an existing one in memory) with the key set to the value of the foreign key from the query, and link it up to the object whose foreign key it was. However, this only works for many-to-one relationships and when using the alternative approach of explicitly naming the links as part of a mapped query, would end up doing the link-up twice. This value should be set to true for builders that are using with non-MappedStatements.

Method Detail

getKeyAssembler

public KeyAssembler getKeyAssembler()

Return the KeyAssembler used to build the object's key from the query

Returns:

the key assembler object

getName

public java.lang.String getName()

Return the name of the assembler. This is used in particular when writing self-referencing many-to-many relationship tables in which a key to the same object appears twice. The infrastructure needs a way of determining which key is which.

mapColumns

public java.lang.String mapColumns(java.lang.String value)

Map the attribute name of an object to the column name of the query. For example, the attribute Name of a class might be represented in the query with the field PERSON_NAME. In this case a call to this method with the attribute name would return PERSON_NAME. Calling the method twice with the same value in the same build session returns null. This feature means that if a column is mapped into the object's key, it is not read again as an attribute (since the key will have already populated that attribute). This was done for performance reasons.

Parameters:

value - the attribute name to be mapped to a column name

Returns:

the column name.

mapColumns

public static java.lang.String mapColumns(java.util.Map columns,
                                          java.lang.String value)

Static method to map the attribute name of an object to the column name of the query. For example, the attribute Name of a class might be represented in the query with the field PERSON_NAME. In this case a call to this method with the attribute name would return PERSON_NAME.

Parameters:

columns - the map to use if this is null, the given value is returned unchanged.

value - the attribute name to be mapped to a column name

Returns:

the column name.

getColumns

public java.util.Map getColumns()

Return the map that is owned by this assembler to map attribute names into column names.

Returns:

the map

setConnection

public void setConnection(java.sql.Connection conn)

Establish the connection that is being used with this assembler. This is only used for non-prepared statements since prepared statements generally keep track of their own connection.

Parameters:

conn -

setLink

public abstract void setLink(java.lang.String linkName,
                             Assembler other)

This method is used to establish a link between assemblers during the build process. Each class-specific assembler will have a member variable per link which points to a AssemblerLink implementation. This method is called while the query map is being set up to initialize these variables.

setPostBuild

public void setPostBuild(Assembler.AfterBuild pb)

Register a class to be called back each time a new object is created.

Parameters:

pb - the object to be called which must support the Assembler.AfterBuild interface

prepareToProcessResults

public boolean prepareToProcessResults(java.sql.ResultSet rs,
                                       java.sql.Statement stmt,
                                       boolean forUpdate)

This method is called after running the SQL statement, but before starting to iterate through the restuls set. The method gives an opportunity for the assembler class to read and record the column indexes of the fields that will be read from the query, so that those columns can be accessed as quickly as possible when the query results are read.

Parameters:

rs - the results set that was returned from executing the statement.

forUpdate - true if this method is being called with a query that will be used to update a database.

getResultSet

public java.sql.ResultSet getResultSet()

Return the ResultSet object that was used in preparing the assembler.

Returns:

the ResultSet object

getUpdateResultSet

public java.sql.ResultSet getUpdateResultSet(java.lang.Object obj,
                                             NamedParameterStatement stmt,
                                             java.lang.Class keyCls)
                                      throws SaveException

This is a helper method that is used to create a results set that can be used to update objects through this assembler into a database.

Parameters:

obj - the object that is to be updated

stmt - the statement that will be used to update the object. This statement must be compatible with the object to be updated and the specified key type. In other words, the statement must be updateable and the column names produced by it must match the attributes of the given object.

keyCls - the class of key that will be used to identify the record to update in the underlying database. The statement must support constraints that match the attributes of the key class.

Throws:

SaveException

getInsertResultSet

public java.sql.ResultSet getInsertResultSet(java.lang.Object obj,
                                             NamedParameterStatement stmt)
                                      throws SaveException

This is a helper method that is used to create a results set that can be used to insert objects through this assembler into a database.

Parameters:

obj - the object that is to be updated

stmt - the statement that will be used to update the object. This statement must be compatible with the object to be updated and the specified key type. In other words, the statement must be updateable and the column names produced by it must match the attributes of the given object.

Throws:

SaveException

getClassToBuild

public java.lang.Class<java.lang.Object> getClassToBuild()

Returns a class object that represents the interface of the object that will be built by this assembler.

Returns:

the business interface

getFactory

public ObjectFactory getFactory()

Returns the factory object that should be used to construct instances of the object built by this assembler

Returns:

the factory object

startNewRow

public void startNewRow()

This method must be called on each assembler each time anew row is started in the results set.

shouldBuild

public final boolean shouldBuild(java.sql.ResultSet rs)

Determine if we should build an object or not, based on the content of of the current QueryResults

Returns:

true if we should build an object.

buildOneObject

public java.lang.Object buildOneObject(java.sql.ResultSet rs)
                                throws SaveException

This method instructs this assembler to try to build one object of the class implied by the assembler's concrete class from the current row of the results set. As well as returning the object that was built, you can also use the callback interface installed through the setPostBuild(org.hydrateframework.Assembler.AfterBuild) method to catch new objects as they are created.

Parameters:

rs - the results set that is being read. This must match the results set that was passed in when prepareToProcessResults(java.sql.ResultSet, java.sql.Statement, boolean) was called.

Returns:

the object that was created or found in an index.

Throws:

SaveException

initObject

protected abstract boolean initObject(java.lang.Object oo,
                                      ObjectKey key)
                               throws SaveException

Initialize the object now with values read from the query.

Parameters:

oo - the object to be initialized

Throws:

SaveException

getStatement

public NamedParameterStatement getStatement(RequestContext rc)
                                     throws SaveException

Get the default query.

Parameters:

rc - the request context that might have the required query in cache

Returns:

a query that can be used to retrieve objects of the type built by this assembler.

Throws:

SaveException

shouldInitExisting

protected boolean shouldInitExisting()

Returns:

true if existing objects are to be reinitialised

getContext

public ObjectContext getContext()

Returns:

the object context to which this assembler belongs.

getBuiltObject

public java.lang.Object getBuiltObject()

Description copied from interface: AssemblerLink

Get the object that this assembler, or assemblers have just built or null if none has been built yet.

Specified by:

getBuiltObject in interface AssemblerLink

getBuiltObjects

public java.lang.Object[] getBuiltObjects()

Description copied from interface: AssemblerLink

If mroe than one assembler is active in a particular query, more than one object may be returned.

Specified by:

getBuiltObjects in interface AssemblerLink

postCreate

public void postCreate(java.sql.ResultSet rs,
                       java.lang.Object o,
                       boolean isNew)

A function that is called after an object has been built by this assembler. This implementation dumps out the contents of new objects to the log and notifies the Assembler.AfterBuild listener that the object the object has been created

Parameters:

rs - the ResultSet being read

o - the object that has just been built

isNew - true if this is a newly created object, false if it was read from an index.

insert

public abstract void insert(java.lang.Object obj,
                            NamedParameterStatement stmt)
                     throws SaveException

This method is overridden by class specific implementations of the assembler to write the internals of a given business object to the 'forUpdate' results set retrieved from the given statement, ready for creating a new object in the database.

Parameters:

obj - the object to be inserted

stmt - the statement to use to insert the object. The statement must be compatible with the object to be updated in that its columns must match the attributes of the object.

Throws:

SaveException

update

public abstract void update(java.lang.Object obj,
                            NamedParameterStatement stmt,
                            java.lang.Class keyClass)
                     throws SaveException

This method is overridden by class specific implementations of the assembler to write the internals of a given business object to the 'forUpdate' results set retrieved from the given statement, ready for updating an existing object in the database.

Parameters:

obj - the object to be updated

stmt - the statement to use to update the object. The statement must be compatible with the object to be updated in that its columns must match the attributes of the object.

keyClass - the key class to use to identify the object in the database. The statement must support constraints that match the attributes of the key class.

Throws:

SaveException

delete

public abstract void delete(java.lang.Object obj,
                            NamedParameterStatement stmt,
                            java.lang.Class keyClass)
                     throws SaveException

This method is overridden by class specific implementations of the assembler to use the results set retrieved from the given statement to delete this object's database representation.

Parameters:

obj - the object to be deleted

stmt - the statement to use to delete the object.

keyClass - the key class to use to identify the object in the database. The statement must support constraints that match the attributes of the key class.

Throws:

SaveException