com.jcorporate.expresso.core.dataobjects.jdbc
Class JoinedDataObject

java.lang.Object
  com.jcorporate.expresso.core.dataobjects.jdbc.JoinedDataObject

All Implemented Interfaces:

Cacheable, ContextNested, DataObject, Defineable, NestableDataObject, Securable, Serializable

public class JoinedDataObject

extends Object

implements DataObject, Defineable, Securable, NestableDataObject

DataObject for use with 1:1 joins between database objects. This class provides a multi-dbobject view of the underlying databases. It is similar to MultiDBObject in that it joins several JDBC-based dataobjects together. The biggest differences are:

• XML-defined joins. Use XML definitions in your classpath to define the joins. In accordance with jdbc-join_5_1.dtd
• DBMaint compatible. By refactoring DBMaint so that it is DataObject aware rather than DBObject aware, we gain the ability to manipulate/update the joins in DBMaint directly rather than making readonly database joins.

Limitation: Although the definitions can list LEFT RIGHT and INNER joins, if you are chaining 3 or more tables, you can only LEFT, RIGHT or INNER join the very last relation or all the relations.

Author:

Michael Rimov

Modify by Yves Henri AMAIZO

See Also:

Serialized Form

Field Summary

static int	INNER_JOIN Static variables for join type
static int	LEFT_JOIN Static field to indicate LEFT_JOIN type
protected DBConnection	localConnection Local connection that we use if it's initialized, but if it's null we generate our own connection
protected int	maxRecords Max Records to retrieve in a single query. 0 means no limit
protected int	offsetRecord The number of records we must skip over before we start reading the ResultSet proper in a searchAndRetrieve. 0 means no limit
static int	RIGHT_JOIN Static field to indicate RIGHT_JOIN type
static int	UNSPECIFIED_JOIN

Fields inherited from interface com.jcorporate.expresso.core.dataobjects.DataObject

STATUS_CURRENT, STATUS_DELETED, STATUS_NEW, STATUS_UPDATED

Fields inherited from interface com.jcorporate.expresso.core.dataobjects.Securable

SYSTEM_ACCOUNT

Constructor Summary

JoinedDataObject()
Creates a new JoinedDataObject object, setting db context and UID from thread context (set by servlet filter)

JoinedDataObject(JoinedDataObject definition)
Constructs a new joined data object to have the same definition as the parameter passed in.

JoinedDataObject(JoinedDigesterBean definition, String definitionName)
Constructor for runtime initialization of custom joined data object.

JoinedDataObject(RequestContext request)
Creates a new JoinedDataObject object.

JoinedDataObject(String xmlFileURL)
Uses the classloader to load the given xml file url as the definition of the JoinedDataObject

Method Summary

void	add() Adds records to all joined tables based upon the values input.
void	addOrUpdate(JDBCDataObject testObject) Determine if a record with these fields exists already - if so, update.
protected String	buildFromClause() Builds the 'FROM' clause without the 'from' part.
protected String	buildOrderByString(String sortKeys) Create the 'ORDER BY' clause in the select statement.
protected String	buildSelectFieldsString() Builds the part of the query that is for describing the fields/names to be selected
protected String	buildUpdateFieldString() Builds the update field string portion setting question marks for all the field values to be formatted and parsed later in a Prepared statement
protected String	buildWhereClauseBuffer(boolean useAllFields, FastStringBuffer myStatement) Build and return a string consisting of an SQL 'where' clause using the current field values as criteria for the search.
boolean	checkAllowed(String requestedFunction) See if the current user has permission to perform the permissions
void	checkField(String fieldName, String fieldValue) Retrieve a list of valid value object for this particular dbobject
void	clear() Clears all currently loaded fields
protected JoinedDataObjectMetaData	constructMetadata() Construction method so that you can create custom derived metadata classes derived from JoinedDataObjectMetaData for custom fields, etc.
int	count() Retrieves the count of any particular join based upon the field values of the data object.
void	delete() Deletes the join.
boolean	equals(Object otherObject) Tests whether two joined DataObjects are equal
boolean	find() Find the object.
Object	get(String fieldName) Get the value object associated with the field specifieed.
Map	getAllAttributes() Retrieves all the attributes for this data object
DataObject[]	getAllNested() Retrieve an array of all nested data objects.
Object	getAttribute(String attributeName) Retrieve the attribute for this particular dataobject.
String	getDataContext() Returns the name of the currently set DataContext
DataField	getDataField(String fieldName) Returns the object embedded within the field keyed by the fieldName parameter
ArrayList	getDataObjects() This function is useful for low level work where you want to modify the underlying data objects in a behavior diffent that the default behavior of the JoinedDataObject.
String	getDefinitionName() Retrieves the definition name in accordance with the
protected String	getDistinct(DBConnectionPool contextPool) Add the DISTINCT keyword to the query if the join is supposed to be distinct.
DataExecutorInterface	getExecutor() Use this function to acquire the Executor interface that is associated with this data object
String	getField(String fieldName) Retrieve the field value as a String
String	getFieldFromNestedName(String fieldName) Often times, field names for the external interface will be different from the of a nested field name in a data object.
DataFieldMetaData	getFieldMetaData(String fieldName) Retrieve the Field MetaData for the specified field name
org.apache.oro.text.regex.Pattern	getGlobalMask() Get the compiled regular expression for this base data object.
JoinedDataObjectMetaData	getJoinMetaData() Type safe return to the metadata for internal use.
String	getKey() Retrieve the key used for this join
Locale	getLocale() Retrieve the Locale of the current object
String	getMappedDataContext() Retrieve the mapped data context for this data object
int	getMaxRecords() Retrieve the maximum number of records.
DataObjectMetaData	getMetaData() Retrieve the database object's metadata.
DataObject	getNestedFromFieldName(String fieldName) Retrieves a nested dataobject based upon the public field name that the DataObject publishes.
int	getOffsetRecord() Gets the number of records that be skipped.
DataQueryInterface	getQueryInterface() Retrieve the QueryInterface... currently not supported
int	getRequestingUid() Retrieve the current UID definition name.
String	getStatus() Retrieve the status of the data object
List	getValidValuesList(String fieldName) Retrieve a list of valid value object for this particular dbobject
int	hashCode() Returns a hash code value for the object.
protected void	init() Initialize the dataobject.
protected void	initializeFromJoinedDigesterBean(JoinedDigesterBean digesterBean, JoinedDataObjectMetaData metadata) Initialization step based upon the digester bean either handed in, or loaded from XML data.
protected void	initializeXML(JoinedDataObjectMetaData metadata) Initialize the metadata based upon XML.
protected void	initWithBean(JoinedDigesterBean digesterBean, String definitionName) Initializes the JoinedDataobject with a digester bean and a definition name This is useful for users creating joins on the fly
void	isAllowed(String requestedFunction) Check if the function is allowed.
boolean	isGlobalMasked() Return boolean if the data object has a mask set
protected boolean	isInitialized() Function that checks if initialized.
ArrayList	searchAndRetrieveList() Retrieve an unsorted array of DataObjects representing the results of the join fields
ArrayList	searchAndRetrieveList(String sortOrder) Simple query method for querying dataobjects.
protected String	selectFieldString(JDBCDataObject oneObj, String fieldName) Build an appropriate String for use in the select part of an SQL statement
void	set(String fieldName, Object o) Sets the name of the field
void	setAttribute(String attributeName, Object attributeValue) Set an attribute.
void	setCaseSensitiveQuery(boolean isCaseSensitiveQuery) This tells the buildWhereClause to either respect case (true) or ignore case (false).
void	setConnection(DBConnection newConnection) Set a specific DB connection for use with this JoinedDataObject.
void	setConnection(DBConnection newConnection, String setupTablesContext) Set a specific DB connection for use with this JoinedDataObject.
void	setCustomWhereClause(String customWhereClause, boolean append) Set a custom WHERE clause
void	setDataContext(String newContext) Sets the data context.
void	setDataField(String fieldName, DataField o) Sets the field data for the named field.
void	setDefinitionName(String definitionName) Use this method to set the key to the definition name for the Defineable database object.
void	setFieldsWithDefaults() Sets the fields of this object with the default values defined in the metadata. The behavior of this function is such that it only populates fields if there is no current value set. This is the same behavior that existed previously in DefaultAutoElement.
void	setGlobalMask(org.apache.oro.text.regex.Pattern newMask) Set a regular expression "mask" for this base data object that specifies it's valid values.
void	setLocale(Locale newLocale) SEt the locale of the object
void	setMaxRecords(int newMax) Set the maximum number of records to receive
void	setOffsetRecord(int newOffset) Specifies the number of records that should be skipped over before any data from the ResultSet is retrieved in any subsequent searchAndRetrieve() call.
void	setRequestingUid(int newUid) Sets the UID for the operations.... also sets the UID for all contained elements.
void	setStatus(String newValue) Sets the status of the joined data object
void	update() Update the current join to the database.

Methods inherited from class java.lang.Object

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

Field Detail

UNSPECIFIED_JOIN

public static final int UNSPECIFIED_JOIN

See Also:

Constant Field Values

INNER_JOIN

public static final int INNER_JOIN

Static variables for join type

See Also:

Constant Field Values

RIGHT_JOIN

public static final int RIGHT_JOIN

Static field to indicate RIGHT_JOIN type

See Also:

Constant Field Values

LEFT_JOIN

public static final int LEFT_JOIN

Static field to indicate LEFT_JOIN type

See Also:

Constant Field Values

localConnection

protected transient DBConnection localConnection

Local connection that we use if it's initialized, but if it's null we generate our own connection

offsetRecord

protected int offsetRecord

The number of records we must skip over before we start reading the ResultSet proper in a searchAndRetrieve. 0 means no limit

maxRecords

protected int maxRecords

Max Records to retrieve in a single query. 0 means no limit

Constructor Detail

JoinedDataObject

public JoinedDataObject()

Creates a new JoinedDataObject object, setting db context and UID from thread context (set by servlet filter)

JoinedDataObject

public JoinedDataObject(RequestContext request)

Creates a new JoinedDataObject object.

Parameters:

request - based on the controller request object as most likely implemented.

JoinedDataObject

public JoinedDataObject(String xmlFileURL)
                 throws DataException

Uses the classloader to load the given xml file url as the definition of the JoinedDataObject

Parameters:

xmlFileURL - the name of the XML file URL

Throws:

DataException - upon error

JoinedDataObject

public JoinedDataObject(JoinedDataObject definition)
                 throws DataException

Constructs a new joined data object to have the same definition as the parameter passed in.

Parameters:

definition - the definition to duplicate

Throws:

DataException - upon initialization error

JoinedDataObject

public JoinedDataObject(JoinedDigesterBean definition,
                        String definitionName)
                 throws DataException

Constructor for runtime initialization of custom joined data object. The definition MUST be unique across the application lifetime, and this constructor has to be only called once. The definition will exist for the lifetime of the object.

Note:You may get strange errors if the definition already exists, it will appear that this constructor didn't 'take' and you'll get a different definition.

Parameters:

definition - the definition bean to utilize

definitionName - the name of the definition

Throws:

DataException - upon error

Method Detail

getDefinitionName

public String getDefinitionName()

Retrieves the definition name in accordance with the

Specified by:

getDefinitionName in interface Defineable

Returns:

java.lang.String

init

protected void init()
             throws DataException

Initialize the dataobject.

Throws:

DataException - upon error

constructMetadata

protected JoinedDataObjectMetaData constructMetadata()

Construction method so that you can create custom derived metadata classes derived from JoinedDataObjectMetaData for custom fields, etc.

Returns:

JoinedDataObjectMetaData or derived class.

initWithBean

protected void initWithBean(JoinedDigesterBean digesterBean,
                            String definitionName)
                     throws DataException

Initializes the JoinedDataobject with a digester bean and a definition name This is useful for users creating joins on the fly

Parameters:

digesterBean - Filled out metadata Bean

definitionName - the name of the definition

Throws:

DataException - upon error

initializeFromJoinedDigesterBean

protected void initializeFromJoinedDigesterBean(JoinedDigesterBean digesterBean,
                                                JoinedDataObjectMetaData metadata)
                                         throws DataException

Initialization step based upon the digester bean either handed in, or loaded from XML data.

Parameters:

digesterBean - the digester bean with populated data

metadata - the meatadata to load the digester bean into

Throws:

DataException - upon error

initializeXML

protected void initializeXML(JoinedDataObjectMetaData metadata)
                      throws DataException

Initialize the metadata based upon XML.

Parameters:

metadata - the metadata object to fill out with the XML data

Throws:

DataException

getAllAttributes

public Map getAllAttributes()

Retrieves all the attributes for this data object

Specified by:

getAllAttributes in interface DataObject

Returns:

a map of all the attributes for this instance of the data object

setAttribute

public void setAttribute(String attributeName,
                         Object attributeValue)

Set an attribute. Attributes are temporary (e.g. not stored in the DBMS) values associated with this particular DB object instance.

Specified by:

setAttribute in interface DataObject

Parameters:

attributeName - The name of the attribute being defined

attributeValue - The object to store under this attribute name

getAttribute

public Object getAttribute(String attributeName)

Retrieve the attribute for this particular dataobject.

Specified by:

getAttribute in interface DataObject

Parameters:

attributeName - the name of the attribute to get

Returns:

the object value of the attribute or null if it doesn't exist.

setCaseSensitiveQuery

public void setCaseSensitiveQuery(boolean isCaseSensitiveQuery)

This tells the buildWhereClause to either respect case (true) or ignore case (false). You can call this method before doing a search and retreive if you want to match without worrying about case. For example if you where to call this method with isCaseSensitiveQuery = FALSE then this comparison would match in the search: vendor_name actual value = "My Name" query value = "my name" This would match in a search and retrieve.

Parameters:

isCaseSensitiveQuery - boolean

setCustomWhereClause

public void setCustomWhereClause(String customWhereClause,
                                 boolean append)

Set a custom WHERE clause

Parameters:

customWhereClause - the custom where clause to use.

append - if true the supplied WHERE clause will be appended to the one generated, else it will replace it

setDataContext

public void setDataContext(String newContext)

Sets the data context. Also sets the data context for all the nested data obejcts

Specified by:

setDataContext in interface ContextNested

Parameters:

newContext - A valid data context name.

getDataContext

public String getDataContext()

Returns the name of the currently set DataContext

Specified by:

getDataContext in interface ContextNested

Returns:

java.lang.String

setDataField

public void setDataField(String fieldName,
                         DataField o)
                  throws DataException

Sets the field data for the named field. This particular implementation assumes that the proper data fields have already been created, and we're only resetting the appropriate types.

Parameters:

fieldName - The data field to set. It is defined by [shortname].[fieldname]

o - The Object to set it by.

Throws:

DataException

getDataField

public DataField getDataField(String fieldName)
                       throws DBException

Returns the object embedded within the field keyed by the fieldName parameter

Specified by:

getDataField in interface DataObject

Parameters:

fieldName - The name of the field to get

Returns:

The object if it isn't null for the data value or null.

Throws:

DBException - upon error

getExecutor

public DataExecutorInterface getExecutor()

Use this function to acquire the Executor interface that is associated with this data object

Specified by:

getExecutor in interface DataObject

Returns:

DataExecutorInterface or null if no Executor has been associated with this object

getFieldMetaData

public DataFieldMetaData getFieldMetaData(String fieldName)

Retrieve the Field MetaData for the specified field name

Specified by:

getFieldMetaData in interface DataObject

Parameters:

fieldName - The name of the field in a 'alias.fieldname' format.

Returns:

The metadata for the field name.

set

public void set(String fieldName,
                Object o)
         throws DataException

Sets the name of the field

Specified by:

set in interface DataObject

Parameters:

fieldName - the name of the field to set

o - the object to set.

Throws:

IllegalArgumentException - if filedName is improperly formatted

DataException

get

public Object get(String fieldName)
           throws DataException

Get the value object associated with the field specifieed.

Specified by:

get in interface DataObject

Parameters:

fieldName - The field name in a [alias].[fieldname] format

Returns:

the object value of the field.

Throws:

DataException - upon error

getKey

public String getKey()

Retrieve the key used for this join

Specified by:

getKey in interface Cacheable

Returns:

java.lang.String

setLocale

public void setLocale(Locale newLocale)

SEt the locale of the object

Specified by:

setLocale in interface DataObject

Parameters:

newLocale - the new locale

getLocale

public Locale getLocale()

Retrieve the Locale of the current object

Specified by:

getLocale in interface DataObject

Returns:

java.util.Locale

getMappedDataContext

public String getMappedDataContext()

Retrieve the mapped data context for this data object

Specified by:

getMappedDataContext in interface DataObject

Returns:

java.lang.String

setMaxRecords

public void setMaxRecords(int newMax)
                   throws DBException

Set the maximum number of records to receive

Specified by:

setMaxRecords in interface DataObject

Parameters:

newMax - the new maximum number of records to retrieve

Throws:

DBException - If the max number is less than 0

getMaxRecords

public int getMaxRecords()

Retrieve the maximum number of records.

Specified by:

getMaxRecords in interface DataObject

Returns:

the maximum number of records to retreive

getMetaData

public DataObjectMetaData getMetaData()

Retrieve the database object's metadata. Metadata is a description of the database object, so it contains static information such as as description, field names, field types. Etc.

For implementers of this interface: It is best to store the metadata somewhere rather than recreating it each and every time. For low-memory requirements, a WeakHashMap is recommended

Specified by:

getMetaData in interface DataObject

Returns:

a built DataObjectMetaData for this database object

getJoinMetaData

public JoinedDataObjectMetaData getJoinMetaData()

Type safe return to the metadata for internal use.

Returns:

JoinedDataObjectMetaData

getDataObjects

public ArrayList getDataObjects()

This function is useful for low level work where you want to modify the underlying data objects in a behavior diffent that the default behavior of the JoinedDataObject. Because of the nature of the object, if you modify the underlying dataobjects in any way, it is recommended that you discard the join that created them since integrity between the dataobjects might be compromised.

Returns:

ArrayList in the same order as the DataObjects are specified in the Join Definition.

setOffsetRecord

public void setOffsetRecord(int newOffset)
                     throws DBException

Specifies the number of records that should be skipped over before any data from the ResultSet is retrieved in any subsequent searchAndRetrieve() call. Records will be skipped over (in the specified sort order) until the record counts is equal to or greater than the offset record. Specifying zero indicates that no records should be skipped over and the ResultSet immediately from the start.

Specified by:

setOffsetRecord in interface DataObject

Parameters:

newOffset - The maximum number of records to retrieve.

Throws:

DBException - If the max number is less than 0

getOffsetRecord

public int getOffsetRecord()

Gets the number of records that be skipped. The offset records. A DB Object can be told to skip a certain number of records, before reading records from the ResultSet.

Specified by:

getOffsetRecord in interface DataObject

Returns:

The maximum number of records that should be skipped over before reading the data records.

See Also:

setOffsetRecord(int)

getQueryInterface

public DataQueryInterface getQueryInterface()

Retrieve the QueryInterface... currently not supported

Specified by:

getQueryInterface in interface DataObject

Returns:

nothing.

getStatus

public String getStatus()

Retrieve the status of the data object

Specified by:

getStatus in interface DataObject

Returns:

the status of the primary data object. [It is assumed that the other ones have the same status as the primary]

setStatus

public void setStatus(String newValue)

Sets the status of the joined data object

Specified by:

setStatus in interface DataObject

Parameters:

newValue - see BaseDataObject for possible values

getValidValuesList

public List getValidValuesList(String fieldName)
                        throws DBException

Retrieve a list of valid value object for this particular dbobject

Specified by:

getValidValuesList in interface DataObject

Parameters:

fieldName - name of the field to retrieve the list for. Should be of the format [shortname].[fieldname]

Returns:

java.util.List of valid values

Throws:

DBException - upon error

add

public void add()
         throws DBException

Adds records to all joined tables based upon the values input. If another record exists [due to relations], the existing record, is skipped.

Specified by:

add in interface DataObject

Throws:

DBException - upon database access error

checkField

public void checkField(String fieldName,
                       String fieldValue)
                throws DBException

Retrieve a list of valid value object for this particular dbobject

Specified by:

checkField in interface DataObject

Parameters:

fieldName - name of the field to retrieve the list for.

fieldValue - the String value of the field

Throws:

DBException - upon error

IllegalArgumentException - if unable to parse the fieldName

checkAllowed

public boolean checkAllowed(String requestedFunction)
                     throws DBException

See if the current user has permission to perform the permissions

Parameters:

requestedFunction - (A)dd, (U)pdate, (D)elete, (S)earch

Returns:

boolean: true if the operation is allowed, or false if it is not

Throws:

DBException

See Also:

isAllowed(java.lang.String)

clear

public void clear()
           throws DBException

Clears all currently loaded fields

Specified by:

clear in interface DataObject

Throws:

DBException

getDistinct

protected String getDistinct(DBConnectionPool contextPool)

Add the DISTINCT keyword to the query if the join is supposed to be distinct.

Parameters:

contextPool - the connection pool for the current context

Returns:

the string including distinct keywords if necessary OR an empty string

count

public int count()
          throws DBException

Retrieves the count of any particular join based upon the field values of the data object.

Specified by:

count in interface DataObject

Returns:

integer for the number of non-null records found.

Throws:

DBException - upon data access error

DataException - for metadata access error

delete

public void delete()
            throws DBException

Deletes the join. Use with extreme care since you could wipe out referential integrity with other objects.

Specified by:

delete in interface DataObject

Throws:

DBException - upon error

equals

public boolean equals(Object otherObject)

Tests whether two joined DataObjects are equal

Specified by:

equals in interface DataObject

Parameters:

otherObject - the object to compare against

Returns:

true if the objects are equal according to our tests

hashCode

public int hashCode()

Returns a hash code value for the object.

Returns:

a hash code value for this object.

find

public boolean find()
             throws DBException

Find the object.

Specified by:

find in interface DataObject

Returns:

true if the object was found.

Throws:

DBException - upon database access error

See Also:

DataObject.find()

searchAndRetrieveList

public ArrayList searchAndRetrieveList(String sortOrder)
                                throws DBException

Simple query method for querying dataobjects. Retrieve a list of all objects matching the given criteria.

Specified by:

searchAndRetrieveList in interface DataObject

Parameters:

sortOrder - A pipe delimited set of fields to sort the resultset with.

Returns:

ArrayList of JoinedDataObjects

Throws:

DBException - upon database access error

Modify by Yves Henri AMAIZO

Since:

$DatabaseSchema $Date: 2004/12/01 07:56:43 $

searchAndRetrieveList

public ArrayList searchAndRetrieveList()
                                throws DBException

Retrieve an unsorted array of DataObjects representing the results of the join fields

Specified by:

searchAndRetrieveList in interface DataObject

Returns:

java.util.ArrayList of JoinedDataObject

Throws:

DBException - upon data access error.

selectFieldString

protected String selectFieldString(JDBCDataObject oneObj,
                                   String fieldName)
                            throws DBException

Build an appropriate String for use in the select part of an SQL statement

Parameters:

oneObj - Database object containing the field

fieldName - The name of the field to be handled

Returns:

The portion of the select clause with the appropriate function wrapped around it

Throws:

DBException - upon data access error

Modify by Yves Henri AMAIZO

Since:

$DatabaseSchema $Date: 2004/12/01 07:56:43 $

update

public void update()
            throws DBException

Update the current join to the database. All this does is search for exiting objects and if it finds it, updates, if not, it

Specified by:

update in interface DataObject

Throws:

DBException - upon database access error

addOrUpdate

public void addOrUpdate(JDBCDataObject testObject)
                 throws DBException

Determine if a record with these fields exists already - if so, update. If not, add a new record.

Parameters:

testObject - the JDBCObject to add or update.

Throws:

DBException

setDefinitionName

public void setDefinitionName(String definitionName)
                       throws DataException

Use this method to set the key to the definition name for the Defineable database object. The actual meaning of the definitionName may be different. For example, AutoDBObject's definition name is the database table name. JoinedDataObject's definition name is the classpath URL location to the definition XML file.

Specified by:

setDefinitionName in interface Defineable

Parameters:

definitionName - java.lang.String, the actual definition of the dataobject.

Throws:

DataException - if the DataObject is unable to initialize itself with the given definition name.

getRequestingUid

public int getRequestingUid()

Retrieve the current UID definition name.

Specified by:

getRequestingUid in interface Securable

Returns:

integer represeting the user ID

setRequestingUid

public void setRequestingUid(int newUid)

Sets the UID for the operations.... also sets the UID for all contained elements.

Specified by:

setRequestingUid in interface Securable

Parameters:

newUid - the user id for the operation.

isAllowed

public void isAllowed(String requestedFunction)
               throws SecurityException,
                      DBException

Check if the function is allowed. It does this by checking all the nested data objects ot make sure that each one is allowed.

Specified by:

isAllowed in interface Securable

Parameters:

requestedFunction - the function name to check

Throws:

SecurityException - if the method is not allowed.

DBException

isInitialized

protected boolean isInitialized()

Function that checks if initialized.

Returns:

true if the object has been initialized.

buildFromClause

protected String buildFromClause()
                          throws DataException

Builds the 'FROM' clause without the 'from' part. [That way Update works too]

Returns:

java.lang.String

Throws:

DataException - upon construction error

Modify by Yves Henri AMAIZO

Since:

$DatabaseSchema $Date: 2004/12/01 07:56:43 $

buildSelectFieldsString

protected String buildSelectFieldsString()
                                  throws DBException

Builds the part of the query that is for describing the fields/names to be selected

Returns:

java.lang.String

Throws:

DBException - if there's an error creating the string.

Modify by Yves Henri AMAIZO

Since:

$DatabaseSchema $Date: 2004/12/01 07:56:43 $

buildUpdateFieldString

protected String buildUpdateFieldString()
                                 throws DataException

Builds the update field string portion setting question marks for all the field values to be formatted and parsed later in a Prepared statement

Returns:

java.lang.String

Throws:

DataException - upon error

Modify by Yves Henri AMAIZO

Since:

$DatabaseSchema $Date: 2004/12/01 07:56:43 $

buildOrderByString

protected String buildOrderByString(String sortKeys)
                             throws DBException

Create the 'ORDER BY' clause in the select statement.

Parameters:

sortKeys - pipe delimited field names in the format [alias].[fieldName]

Returns:

the order by string to append to the select statement.

Throws:

DBException - Modify by Yves Henri AMAIZO

Since:

$DatabaseSchema $Date: 2004/12/01 07:56:43 $

buildWhereClauseBuffer

protected String buildWhereClauseBuffer(boolean useAllFields,
                                        FastStringBuffer myStatement)
                                 throws DBException

Build and return a string consisting of an SQL 'where' clause using the current field values as criteria for the search. See setCustomWhereClause for information on specifying a more complex where clause.

Parameters:

useAllFields - True if all fields are to be used, false for only key fields

myStatement - the preallocated buffer to append to

Returns:

java.lang.String.

Modify by Yves Henri AMAIZO

Throws:

DBException - upon error

Since:

$DatabaseSchema $Date: 2004/12/01 07:56:43 $

getNestedFromFieldName

public DataObject getNestedFromFieldName(String fieldName)

Retrieves a nested dataobject based upon the public field name that the DataObject publishes. For example, in JoinedDataObjects, the field name ""abcd.efgh" represents DataObject 'abcd', and field name 'efgh'.

The actual usage of the naming convention will differ from the, thus you'll need to use getMetaData().getFieldList() to get the names of the fields of a Nestable object to get a valid field Name

Specified by:

getNestedFromFieldName in interface NestableDataObject

Parameters:

fieldName - the full field name to get the nested data object.

Returns:

DataObject (Actually JDBCDataObjects) or possibly null.

Throws:

IllegalArgumentException - if the field name does not map to any DataObject

getAllNested

public DataObject[] getAllNested()

Retrieve an array of all nested data objects. May be empty if there are no nested data objects. Ordering is undefined by this function.

Specified by:

getAllNested in interface NestableDataObject

Returns:

Array of DataObjects. Should never return null.

getFieldFromNestedName

public String getFieldFromNestedName(String fieldName)

Often times, field names for the external interface will be different from the of a nested field name in a data object. Use this function to get the internal field name for the DataObject returned by getNestedFromFieldName()

Specified by:

getFieldFromNestedName in interface NestableDataObject

Parameters:

fieldName - The external name of the field

Returns:

java.lang.String, the field corresponding to the field name of the data object

Throws:

IllegalArgumentException - if the given field name cannot map to a field.

getField

public String getField(String fieldName)
                throws DBException

Retrieve the field value as a String

Specified by:

getField in interface DataObject

Parameters:

fieldName - the name of the field to retrieve

Returns:

Object or null if the field was null

Throws:

DBException - upon error

IllegalArgumentException - if fieldname is invalid

setConnection

public void setConnection(DBConnection newConnection)
                   throws DBException

Set a specific DB connection for use with this JoinedDataObject. If you do not set a connection, the db object will request it's own connection from the appropriate connection pool & release it again after every operation (e.g. add, update, etc). It is important to use your own explicit connection when dealing with a database transactional environment (e.g. commit(), rollback()).

Parameters:

newConnection - The new DBConnection object to be used by this DB Object

Throws:

DBException

setConnection

public void setConnection(DBConnection newConnection,
                          String setupTablesContext)
                   throws DBException

Set a specific DB connection for use with this JoinedDataObject. If you do not set a connection, the object will request it's own connection from the appropriate connection pool & release it again after every operation (e.g. add, update, etc). It is important to use your own explicit connection when dealing with a database transactional environment (e.g. commit(), rollback()).

The difference between this and setConnection(DBConnection) is that this is used for using otherDB capabilities within a transaction. So you use a dbconnection from your other pool, but the setup tables are in a different context

Parameters:

newConnection - The new DBConnection object to be used by this DB Object

setupTablesContext - the data context that is used for the expresso setup tables.

Throws:

DBException

See Also:

setConnection(DBConnection)

setGlobalMask

public void setGlobalMask(org.apache.oro.text.regex.Pattern newMask)

Set a regular expression "mask" for this base data object that specifies it's valid values. The mask should already be compiled by the regular expression compiler

Specified by:

setGlobalMask in interface DataObject

Parameters:

newMask - The compiled regular expression mask

getGlobalMask

public org.apache.oro.text.regex.Pattern getGlobalMask()

Get the compiled regular expression for this base data object.

Specified by:

getGlobalMask in interface DataObject

Returns:

the precompiled regular expression mask

isGlobalMasked

public boolean isGlobalMasked()

Return boolean if the data object has a mask set

Specified by:

isGlobalMasked in interface DataObject

Returns:

True if the data object mask is set, else false if it is not

setFieldsWithDefaults

public void setFieldsWithDefaults()
                           throws DataException

Sets the fields of this object with the default values defined in the metadata. The behavior of this function is such that it only populates fields if there is no current value set. This is the same behavior that existed previously in DefaultAutoElement.

Specified by:

setFieldsWithDefaults in interface DataObject

Throws:

DataException - upon setField error.