de.mathema.pride
Class RecordDescriptor

java.lang.Object
  de.mathema.pride.RecordDescriptor

public class RecordDescriptor
extends java.lang.Object

A RecordDescriptor defines the mapping of relation database records to JAVA objects

Author:

Jan Lessner

Nested Class Summary

static interface

RecordDescriptor.ExtractionMode Defined constants for the ResultSet extraction mode of this descriptor and its depending AttributeDescriptors.

Field Summary

protected de.mathema.pride.AttributeDescriptor[]	attrDescriptors
protected RecordDescriptor	baseDescriptor
protected java.lang.String	dbContext
protected java.lang.String	dbtable
protected java.lang.Class	objectType
static java.lang.String	REVISION_ID

Constructor Summary

RecordDescriptor(java.lang.Class objectType, java.lang.String dbtable, RecordDescriptor baseDescriptor, java.lang.String[][] attributeMap)
Creates a new mapping descriptor like constructor above but always uses the current DB context of DatabaseFactory and auto extraction mode.

RecordDescriptor(java.lang.Class objectType, java.lang.String dbtable, RecordDescriptor baseDescriptor, java.lang.String[][] attributeMap, int extractionMode)
Creates a new mapping descriptor like constructor above but always uses the current DB context of DatabaseFactory.

RecordDescriptor(java.lang.Class objectType, java.lang.String dbContext, java.lang.String dbtable, RecordDescriptor baseDescriptor, java.lang.String[][] attributeMap)

RecordDescriptor(java.lang.Class objectType, java.lang.String dbContext, java.lang.String dbtable, RecordDescriptor baseDescriptor, java.lang.String[][] attributeMap, int extractionMode)
Creates a new mapping descriptor

RecordDescriptor(RecordDescriptor red, java.lang.String alias)
Like copy constructor above but without alternate table name

RecordDescriptor(RecordDescriptor red, java.lang.String alias, java.lang.String altTable)
Copy constructor

Method Summary

java.lang.String	getConstraint(java.lang.Object obj, java.lang.String[] dbfields, boolean byLike, Database db) Constructs a constraint for a database query
int	getConstraint(java.lang.Object obj, java.lang.String[] dbfields, PreparedOperation pop, java.lang.String table, int position) Similar to function above but instead writes the values into a passed PreparedOperation.
java.lang.String	getContext()
java.lang.String	getCreationValues(java.lang.Object obj, java.lang.String[] excludeAttrs, Database db) Returns a comma-seperated list of all attribute values of the passed object as required for an SQL insert operation
int	getCreationValues(java.lang.Object obj, java.lang.String[] excludeAttrs, PreparedOperation pop, java.lang.String table, int position) Similar to function above but instead writes the values into a passed PreparedOperation.
java.lang.String	getFieldNames(java.lang.String[] excludeAttrs) Returns a comma-seperated list of all attribute names as required for an SQL insert operation
java.lang.Class	getObjectType()
java.lang.Object	getPrimaryKey(java.lang.Object obj) Get the passed object's primary key value, assuming that this is the value of the very first attribute mapping.
java.lang.String	getPrimaryKeyField() Get the name of the database field making up the primary key.
protected java.lang.String	getResultFields() Returns the list of fields to be looked up in a query, which is by default the list of all fields registered in this descriptor and its base descriptors and thus the same list as returned by getFieldNames(java.lang.String[]).
java.lang.String	getTableName()
java.lang.String	getUpdateValues(java.lang.Object obj, Database db) Returns a database update clause for the passed object's attribute.
java.lang.String	getUpdateValues(java.lang.Object obj, java.lang.String[] excludeAttrs, java.lang.String[] includeAttrs, Database db) Like the function above except that all attributes listed in excludeAttrs are left off instead of the first one.
int	getUpdateValues(java.lang.Object obj, java.lang.String[] excludeAttrs, java.lang.String[] includeAttrs, PreparedOperation pop, java.lang.String table, int position) Similar to function above but instead writes the values into a passed PreparedOperation.
java.lang.Object	getWhereValue(java.lang.Object obj, java.lang.String dbfield, boolean byLike, Database db) Runs getWhereValue on the attribute descriptor, representing the attribute specified by parameter dbfield
void	getWhereValue(java.lang.Object obj, java.lang.String dbfield, PreparedOperation pop, java.lang.String table, int position) Similar to function above but instead writes the value into a passed PreparedOperation.
int	record2object(java.lang.Object obj, java.sql.ResultSet results, int position) Extract result values from a result set according to the field mappings The extraction is by default performed in auto-mode. i.e. first by-name if possible and by-index otherwise.
int	record2object(java.lang.Object obj, java.sql.ResultSet results, int position, de.mathema.pride.AttributeDescriptor attrDesc)
int	record2object(java.lang.Object obj, java.sql.ResultSet results, int position, java.lang.String[] includeAttrs) Function used to inject auto-generated field values after an insertion operation.
int	totalAttributes() Returns the total number of attributes being mapped by this descriptor and all of its base descriptors.
protected java.lang.String	trim(java.lang.String value)

Methods inherited from class java.lang.Object

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

Field Detail

objectType

protected java.lang.Class objectType

dbContext

protected java.lang.String dbContext

dbtable

protected java.lang.String dbtable

attrDescriptors

protected de.mathema.pride.AttributeDescriptor[] attrDescriptors

baseDescriptor

protected RecordDescriptor baseDescriptor

REVISION_ID

public static final java.lang.String REVISION_ID

See Also:

Constant Field Values

Constructor Detail

RecordDescriptor

public RecordDescriptor(java.lang.Class objectType,
                        java.lang.String dbContext,
                        java.lang.String dbtable,
                        RecordDescriptor baseDescriptor,
                        java.lang.String[][] attributeMap,
                        int extractionMode)
                 throws IllegalDescriptorException

Creates a new mapping descriptor

Parameters:

objectType - JAVA object type being mapped by the descriptor

dbtable - Database table to refer to

attributeMap - Description of field mappings used to instantiate AttributeDescriptors. Each inner array is passed as parameter attrInfo to the constructor of AttributeDescriptor.

extractionMode - The ResultSet extraction mode according to the constants defined in interface RecordDescriptor.ExtractionMode.

Throws:

IllegalDescriptorException

RecordDescriptor

public RecordDescriptor(java.lang.Class objectType,
                        java.lang.String dbtable,
                        RecordDescriptor baseDescriptor,
                        java.lang.String[][] attributeMap)
                 throws IllegalDescriptorException

Creates a new mapping descriptor like constructor above but always uses the current DB context of DatabaseFactory and auto extraction mode.

Throws:

IllegalDescriptorException

RecordDescriptor

public RecordDescriptor(java.lang.Class objectType,
                        java.lang.String dbtable,
                        RecordDescriptor baseDescriptor,
                        java.lang.String[][] attributeMap,
                        int extractionMode)
                 throws IllegalDescriptorException

Creates a new mapping descriptor like constructor above but always uses the current DB context of DatabaseFactory.

Throws:

IllegalDescriptorException

RecordDescriptor

public RecordDescriptor(java.lang.Class objectType,
                        java.lang.String dbContext,
                        java.lang.String dbtable,
                        RecordDescriptor baseDescriptor,
                        java.lang.String[][] attributeMap)
                 throws IllegalDescriptorException

Throws:

IllegalDescriptorException

RecordDescriptor

public RecordDescriptor(RecordDescriptor red,
                        java.lang.String alias,
                        java.lang.String altTable)

Copy constructor

Parameters:

red - The descriptor which to copy data from

alias - An optional alias name to use for database access. This is of interest if this descriptor is supposed to be used in an aggregation of multiple descriptors for accessing full table joins. May be null;

altTable - An optional alternative table name to use for database access. If both alias and table name are specified, the alias is not applied to the alternate table name.

RecordDescriptor

public RecordDescriptor(RecordDescriptor red,
                        java.lang.String alias)

Like copy constructor above but without alternate table name

Method Detail

totalAttributes

public int totalAttributes()

Returns the total number of attributes being mapped by this descriptor and all of its base descriptors. This function is useful to skip non-existent parts of an outer join.

Returns:

The number of mapped attributes

getTableName

public java.lang.String getTableName()

getObjectType

public java.lang.Class getObjectType()

getContext

public java.lang.String getContext()

getPrimaryKeyField

public java.lang.String getPrimaryKeyField()

Get the name of the database field making up the primary key. Currently just returns the first attribute mapping's field name, so make shure to always put the description of the primary key field at the very beginning of the mappings passed in the constructor.

record2object

public int record2object(java.lang.Object obj,
                         java.sql.ResultSet results,
                         int position,
                         de.mathema.pride.AttributeDescriptor attrDesc)
                  throws java.sql.SQLException,
                         java.lang.IllegalAccessException,
                         java.lang.reflect.InvocationTargetException

Throws:

java.sql.SQLException

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

record2object

public int record2object(java.lang.Object obj,
                         java.sql.ResultSet results,
                         int position)
                  throws java.sql.SQLException,
                         java.lang.IllegalAccessException,
                         java.lang.reflect.InvocationTargetException

Extract result values from a result set according to the field mappings The extraction is by default performed in auto-mode. i.e. first by-name if possible and by-index otherwise. This is the only reliable way in all JDBC drivers to support not only access of single tables but also joins and alias fields. Joins turned out to cause some JDBC drivers to provide no field names at all in the ResultSet. Alias names for function-based fields turned out not to be provided in a reliable order.
The index-based extraction requires function {RecordDescriptor#getResultFields} to provide the attributes in the same order they are traversed by this function.

Parameters:

obj - The objet where to transfer the data to

results - The result set to extract the data from

position - The start index for data extraction

Returns:

The next index for subsequent extractions or -1 to force extraction by name (see class AttributeDescriptor for details).

Throws:

java.sql.SQLException

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

record2object

public int record2object(java.lang.Object obj,
                         java.sql.ResultSet results,
                         int position,
                         java.lang.String[] includeAttrs)
                  throws java.sql.SQLException,
                         java.lang.IllegalAccessException,
                         java.lang.reflect.InvocationTargetException

Function used to inject auto-generated field values after an insertion operation. The function works similar as the one above except that extraction from the result set is limited to a list of specified attributes. Extraction is done by-position because some JDBC drivers don't support the standard JDBC function Statement.getGeneratedKeys() but use strange retrieval selections to fetch auto field values.

Parameters:

obj - The objet where to transfer the data to

results - The result set to extract the data from

includeAttrs - An array of attribute names to consider

Throws:

java.sql.SQLException

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

getPrimaryKey

public java.lang.Object getPrimaryKey(java.lang.Object obj)
                               throws java.lang.IllegalAccessException,
                                      java.lang.reflect.InvocationTargetException

Get the passed object's primary key value, assuming that this is the value of the very first attribute mapping.

Throws:

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

getWhereValue

public java.lang.Object getWhereValue(java.lang.Object obj,
                                      java.lang.String dbfield,
                                      boolean byLike,
                                      Database db)
                               throws java.lang.IllegalAccessException,
                                      java.lang.reflect.InvocationTargetException

Runs getWhereValue on the attribute descriptor, representing the attribute specified by parameter dbfield

Throws:

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

getWhereValue

public void getWhereValue(java.lang.Object obj,
                          java.lang.String dbfield,
                          PreparedOperation pop,
                          java.lang.String table,
                          int position)
                   throws java.lang.IllegalAccessException,
                          java.lang.reflect.InvocationTargetException,
                          java.sql.SQLException

Similar to function above but instead writes the value into a passed PreparedOperation.

Parameters:

obj - the value object from which to take the value from

dbfield - the field to fetch the value for

pop - the PreparedOperation to pass the value to

table - the name of the database table, the operation refers to. See AttributeDescriptor for the nasty reason

position - index of the prepared statements next parameter to set

Throws:

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

java.sql.SQLException

getConstraint

public java.lang.String getConstraint(java.lang.Object obj,
                                      java.lang.String[] dbfields,
                                      boolean byLike,
                                      Database db)
                               throws java.lang.IllegalAccessException,
                                      java.lang.reflect.InvocationTargetException

Constructs a constraint for a database query

Parameters:

dbfields - the database fields for which to take a constraint value from the passed value object. If this is null, the first registered attribute is used.

obj - the value object from which to take the constraint values

byLike - if false, builds the constraint from equality checks, otherwise by using operator like

Throws:

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

getConstraint

public int getConstraint(java.lang.Object obj,
                         java.lang.String[] dbfields,
                         PreparedOperation pop,
                         java.lang.String table,
                         int position)
                  throws java.lang.IllegalAccessException,
                         java.lang.reflect.InvocationTargetException,
                         java.sql.SQLException

Similar to function above but instead writes the values into a passed PreparedOperation.

Parameters:

obj - the value object from which to take the constraint values

dbfields - the database fields for which to take a constraint value from the passed value object. If this is null, the first registered attribute is used.

pop - the PreparedOperation to pass the value to

table - the name of the database table, the operation refers to. See AttributeDescriptor for the nasty reason

position - index of the prepared statements next parameter to set

Returns:

the next pending position

Throws:

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

java.sql.SQLException

trim

protected java.lang.String trim(java.lang.String value)

getUpdateValues

public java.lang.String getUpdateValues(java.lang.Object obj,
                                        Database db)
                                 throws java.lang.IllegalAccessException,
                                        java.lang.reflect.InvocationTargetException

Returns a database update clause for the passed object's attribute. The very first attribute is assumed to make up the primary key and is therefore left off

Throws:

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

getUpdateValues

public java.lang.String getUpdateValues(java.lang.Object obj,
                                        java.lang.String[] excludeAttrs,
                                        java.lang.String[] includeAttrs,
                                        Database db)
                                 throws java.lang.IllegalAccessException,
                                        java.lang.reflect.InvocationTargetException

Like the function above except that all attributes listed in excludeAttrs are left off instead of the first one.

Throws:

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

getUpdateValues

public int getUpdateValues(java.lang.Object obj,
                           java.lang.String[] excludeAttrs,
                           java.lang.String[] includeAttrs,
                           PreparedOperation pop,
                           java.lang.String table,
                           int position)
                    throws java.lang.IllegalAccessException,
                           java.lang.reflect.InvocationTargetException,
                           java.sql.SQLException

Similar to function above but instead writes the values into a passed PreparedOperation.

Parameters:

obj - the value object from which to take the data from

excludeAttrs - an array of field names which are to be ignored.

pop - the PreparedOperation to pass the value to

table - the name of the database table, the operation refers to. See AttributeDescriptor for the nasty reason

position - index of the prepared statements next parameter to set

Returns:

the next pending position

Throws:

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

java.sql.SQLException

getCreationValues

public java.lang.String getCreationValues(java.lang.Object obj,
                                          java.lang.String[] excludeAttrs,
                                          Database db)
                                   throws java.lang.IllegalAccessException,
                                          java.lang.reflect.InvocationTargetException

Returns a comma-seperated list of all attribute values of the passed object as required for an SQL insert operation

Throws:

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

getCreationValues

public int getCreationValues(java.lang.Object obj,
                             java.lang.String[] excludeAttrs,
                             PreparedOperation pop,
                             java.lang.String table,
                             int position)
                      throws java.lang.IllegalAccessException,
                             java.lang.reflect.InvocationTargetException,
                             java.sql.SQLException

Similar to function above but instead writes the values into a passed PreparedOperation.

Parameters:

obj - the value object from which to take the creation values

pop - the PreparedOperation to pass the value to

table - the name of the database table, the operation refers to. See AttributeDescriptor for the nasty reason

position - index of the prepared statements next parameter to set

Returns:

the next pending position

Throws:

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

java.sql.SQLException

getFieldNames

public java.lang.String getFieldNames(java.lang.String[] excludeAttrs)

Returns a comma-seperated list of all attribute names as required for an SQL insert operation

getResultFields

protected java.lang.String getResultFields()

Returns the list of fields to be looked up in a query, which is by default the list of all fields registered in this descriptor and its base descriptors and thus the same list as returned by getFieldNames(java.lang.String[]). Overriding this function must be done with great care. The extraction of data from a result set in record2object(java.lang.Object, java.sql.ResultSet, int, de.mathema.pride.AttributeDescriptor) is performed by index and relies on the number and order of fields defined by this function. If it returns '*' for example, make shure to call AttributeDescriptor.record2object(java.sql.ResultSet, int) with index -1 to force data extraction by name.