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.
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.
constructMetadata() Construction method so that you can create custom derived metadata classes
derived from JoinedDataObjectMetaData for custom fields, etc.
public int
count() Retrieves the count of any particular join based upon the field values
of the data object.
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.
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.
getFieldMetaData(String fieldName) Retrieve the Field MetaData for the specified field name
Parameters: fieldName - The name of the field in a 'alias.fieldname' format.
public Pattern
getGlobalMask() Get the compiled regular expression for this base data object.
getValidValuesList(String fieldName) Retrieve a list of valid value object for this particular dbobject
Parameters: fieldName - name of the field to retrieve the list for.
public int
hashCode() Returns a hash code value for the object.
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.
public void
setRequestingUid(int newUid) Sets the UID for the operations....
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
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
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 Parameters: definitionName - the name of the definition throws: DataException - upon error
Adds records to all joined tables based upon the values input. If another
record exists [due to relations], the existing record, is skipped.
throws: DBException - upon database access error
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.
Builds the 'FROM' clause without the 'from' part. [That way Update works too]
java.lang.String throws: DataException - upon construction errorModify by Yves Henri AMAIZO since: $DatabaseSchema $Date: 2004/12/01 07:56:43 $
Create the 'ORDER BY' clause in the select statement.
Parameters: sortKeys - pipe delimited field names in the format [alias].[fieldName] 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 $
Builds the part of the query that is for describing the fields/names to
be selected
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 $
Builds the update field string portion setting question marks for
all the field values to be formatted and parsed later in a Prepared
statement
java.lang.String throws: DataException - upon errorModify by Yves Henri AMAIZO since: $DatabaseSchema $Date: 2004/12/01 07:56:43 $
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 Parameters: myStatement - the preallocated buffer to append to java.lang.String.Modify by Yves Henri AMAIZO throws: DBException - upon error since: $DatabaseSchema $Date: 2004/12/01 07:56:43 $
See if the current user has permission to perform the permissions
Parameters: requestedFunction - (A)dd, (U)pdate, (D)elete, (S)earch boolean: true if the operation is allowed, or false if it is not See Also:JoinedDataObject.isAllowed
Retrieve a list of valid value object for this particular dbobject
Parameters: fieldName - name of the field to retrieve the list for. Parameters: fieldValue - the String value of the field throws: DBException - upon error throws: IllegalArgumentException - if unable to parse the fieldName
Construction method so that you can create custom derived metadata classes
derived from JoinedDataObjectMetaData for custom fields, etc.
JoinedDataObjectMetaData or derived class.
Retrieves the count of any particular join based upon the field values
of the data object.
integer for the number of non-null records found. throws: DBException - upon data access error throws: DataException - for metadata access error
Tests whether two joined DataObjects are equal
Parameters: otherObject - the object to compare against true if the objects are equal according to our tests
Get the value object associated with the field specifieed.
Parameters: fieldName - The field name in a [alias].[fieldname] format the object value of the field. throws: DataException - upon error
Retrieve an array of all nested data objects. May be empty if there
are no nested data objects. Ordering is undefined by this function.
Array of DataObjects. Should never return null.
Retrieve the attribute for this particular dataobject.
Parameters: attributeName - the name of the attribute to get the object value of the attribute or null if it doesn't exist.
Returns the object embedded within the field keyed by the fieldName
parameter
Parameters: fieldName - The name of the field to get The object if it isn't null for the data value or null. throws: DBException - upon error
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.
ArrayList in the same order as the DataObjects are specified inthe Join Definition.
Add the DISTINCT keyword to the query if the join is supposed to be
distinct.
Parameters: contextPool - the connection pool for the current context the string including distinct keywords if necessary OR an empty string
Use this function to acquire the Executor interface that is associated
with this data object
DataExecutorInterface or null if no Executor has been associatedwith this object
Retrieve the field value as a String
Parameters: fieldName - the name of the field to retrieve Object or null if the field was null throws: DBException - upon error throws: IllegalArgumentException - if fieldname is invalid
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() Parameters: fieldName - The external name of the field java.lang.String, the field corresponding to the field nameof the data object throws: IllegalArgumentException - if the given field name cannot mapto a field.
Retrieve the Field MetaData for the specified field name
Parameters: fieldName - The name of the field in a 'alias.fieldname' format. The metadata for the field name.
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
a built DataObjectMetaData for this database object
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
Parameters: fieldName - the full field name to get the nested data object. DataObject (Actually JDBCDataObjects) or possibly null. throws: IllegalArgumentException - if the field name does not map to anyDataObject
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.
The maximum number of records that should be skipped over beforereading the data records. See Also:JoinedDataObject.setOffsetRecord(int)
Retrieve a list of valid value object for this particular dbobject
Parameters: fieldName - name of the field to retrieve the list for. Should beof the format [shortname].[fieldname] java.util.List of valid values throws: DBException - upon error
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 Parameters: definitionName - the name of the definition throws: DataException - upon error
Initialization step based upon the digester bean either handed in, or loaded
from XML data.
Parameters: digesterBean - the digester bean with populated data Parameters: metadata - the meatadata to load the digester bean into throws: DataException - upon error
Check if the function is allowed. It does this by checking all the nested
data objects ot make sure that each one is allowed.
Parameters: requestedFunction - the function name to check throws: SecurityException - if the method is not allowed.
Simple query method for querying dataobjects. Retrieve a list of all
objects matching the given criteria.
Parameters: sortOrder - A pipe delimited set of fields to sort the resultsetwith. ArrayList of JoinedDataObjects throws: DBException - upon database access errorModify by Yves Henri AMAIZO since: $DatabaseSchema $Date: 2004/12/01 07:56:43 $
Retrieve an unsorted array of DataObjects representing the results
of the join fields
java.util.ArrayList of JoinedDataObject throws: DBException - upon data access error.
Build an appropriate String for use in the select part of an SQL
statement
Parameters: oneObj - Database object containing the field Parameters: fieldName - The name of the field to be handled The portion of the select clause with the appropriate functionwrapped around it throws: DBException - upon data access errorModify by Yves Henri AMAIZO since: $DatabaseSchema $Date: 2004/12/01 07:56:43 $
Sets the name of the field
Parameters: fieldName - the name of the field to set Parameters: o - the object to set. throws: IllegalArgumentException - if filedName is improperly formatted
setAttribute
public void setAttribute(String attributeName, Object attributeValue)(Code)
Set an attribute. Attributes are temporary (e.g. not stored in the DBMS)
values associated with this particular DB object instance.
Parameters: attributeName - The name of the attribute being defined Parameters: attributeValue - The object to store under this attribute name
setCaseSensitiveQuery
public void setCaseSensitiveQuery(boolean isCaseSensitiveQuery)(Code)
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
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
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 Parameters: setupTablesContext - the data context that is used for the expresso setup tables. See Also:JoinedDataObject.setConnection(DBConnection)
setCustomWhereClause
public synchronized void setCustomWhereClause(String customWhereClause, boolean append)(Code)
Set a custom WHERE clause
Parameters: customWhereClause - the custom where clause to use. Parameters: append - if true the supplied WHERE clause will be appended to the onegenerated, else it will replace it
setDataContext
public void setDataContext(String newContext)(Code)
Sets the data context. Also sets the data context for all the nested
data obejcts
Parameters: newContext - A valid data context name.
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] Parameters: o - The Object to set it by.
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.
Parameters: definitionName - java.lang.String, the actual definition of thedataobject. throws: DataException - if the DataObject is unable to initialize itselfwith the given definition name.
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
Parameters: newMask - The compiled regular expression mask
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.
Parameters: newOffset - The maximum number of records to retrieve. throws: DBException - If the max number is less than 0
Update the current join to the database. All this does is search for exiting
objects and if it finds it, updates, if not, it
throws: DBException - upon database access error
