com.jcorporate.expresso.core.dataobjects
Interface DataObject

All Superinterfaces:

Cacheable, ContextNested, Serializable

All Known Implementing Classes:

BaseDataObject, JoinedDataObject, SynchronizedDataObject

public interface DataObject

extends Cacheable, ContextNested

This interface represents the basic needs of a dataobject, namely to add, update and delete itself, set it's own fields, and deal with things accordingly

It is currently considered BETA code at this time. It's intention is to provide a refactoring launching point. Until then it is recommended that by and large you use the DBObject class directly unless there is a specific feature that the DataObject interface provides that you need. However, be forewarned that the interface will change. For example, Exceptions will eventually be refactored from DBExceptions to DataExceptions.

Since:

Expresso 5.0

Author:

Michael Rimov

Field Summary

static String	STATUS_CURRENT Status constant indicating that this dbobject currently reflects what's in the database back end.
static String	STATUS_DELETED Status indicating that this DBObject has been deleted.
static String	STATUS_NEW Constant describing that this dbobject is new.
static String	STATUS_UPDATED Status constant indicating that this dbobject has been modified and does not match the back-end database.

Method Summary

void	add() Adds the record to the defined data source.
void	checkField(String fieldName, String fieldValue) Check that a given value is valid for a given field.
void	clear() Clears all currently loaded fields
int	count() Just like find, but only retrieves the count, not the records themselves.
void	delete() Deletes this defined record.
boolean	equals(Object otherObject) Checks to see if two data objects are equal.
boolean	find() Finds a single record based upon the criteria specified by the DataTransferObject
Object	get(String fieldName) Directly gets the DataField Data without having to deal with the DataField itself
Map	getAllAttributes() Returns a Read Only Map containing all the current attributes set for this particular data object instance.
Object	getAttribute(String attributeName) Return an "attribute".
DataField	getDataField(String fieldName) Returns the object embedded within the field keyed by the fieldName parameter.
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
DataFieldMetaData	getFieldMetaData(String fieldName) Retrieves the metadata for a particular field name
org.apache.oro.text.regex.Pattern	getGlobalMask() Retrieve the DBObject's current global mask
Locale	getLocale() Retrieve the DBObject's current locale
String	getMappedDataContext() Returns the name of the physical database that we're talking with.
int	getMaxRecords() A DB Object can be told to only retrieve a certain number of records.
DataObjectMetaData	getMetaData() Retrieve the database object's metadata.
int	getOffsetRecord() Gets the number of records that be skipped.
DataQueryInterface	getQueryInterface() Use this function to acquire the DataQueryInterface that is associated with this data object [Currently unsupported]
String	getStatus() Retrieve the status code of the dataobject.
List	getValidValuesList(String fieldName) Retrieve a list of valid value object for this particular dbobject
boolean	isGlobalMasked() Return boolean if the data object has a mask set
ArrayList	searchAndRetrieveList() Performs a datasource search so that the criteria set in the DataObject is used.
ArrayList	searchAndRetrieveList(String sortOrder) Performs a datasource search so that the criteria set in the DataObject is used.
void	set(String fieldName, Object o) Directly sets the field value without getting the datafield object
void	setAttribute(String attributeName, Object attributeValue) Set an attribute.
void	setFieldsWithDefaults() Sets the fields of this object with the default values defined in the metadata.
void	setGlobalMask(org.apache.oro.text.regex.Pattern newGlobalMask) Sets the DataObject's global mask
void	setLocale(Locale newLocale) Sets the DataObject's locale
void	setMaxRecords(int newMax) Specify a maximum number of records to be retrieved in any subsequent searchAndRetrieve() call.
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	setStatus(String statusValue) Sets the status of the object.
void	update() Updates the record to the defined datasource

Methods inherited from interface com.jcorporate.expresso.core.cache.Cacheable

getKey

Methods inherited from interface com.jcorporate.expresso.core.dataobjects.ContextNested

getDataContext, setDataContext

Field Detail

STATUS_NEW

public static final String STATUS_NEW

Constant describing that this dbobject is new.

See Also:

Constant Field Values

STATUS_CURRENT

public static final String STATUS_CURRENT

Status constant indicating that this dbobject currently reflects what's in the database back end.

See Also:

Constant Field Values

STATUS_UPDATED

public static final String STATUS_UPDATED

Status constant indicating that this dbobject has been modified and does not match the back-end database.

See Also:

Constant Field Values

STATUS_DELETED

public static final String STATUS_DELETED

Status indicating that this DBObject has been deleted.

See Also:

Constant Field Values

Method Detail

getDataField

public DataField getDataField(String fieldName)
                       throws DBException

Returns the object embedded within the field keyed by the fieldName parameter. The DataField object maintains metadata and other key items about the field. Its state should not be messed with by the typical program.

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

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

Returns:

a built DataObjectMetaData for this database object

getFieldMetaData

public DataFieldMetaData getFieldMetaData(String fieldName)

Retrieves the metadata for a particular field name

Parameters:

fieldName - The name of the field to retrieve the metadata for.

Returns:

<сode>DataFieldMetaData the metadata associated with this field.

Throws:

IllegalArgumentException - if the fieldName does not exist.

get

public Object get(String fieldName)
           throws DataException

Directly gets the DataField Data without having to deal with the DataField itself

Parameters:

fieldName - the name of the field to get

Returns:

Object or null.

Throws:

DataException

set

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

Directly sets the field value without getting the datafield object

Parameters:

fieldName - the name of the field to set

o - the object value to set it to.

Throws:

DataException

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.

Throws:

DataException - upon setField error.

Since:

Expresso 5.6

equals

public boolean equals(Object otherObject)

Checks to see if two data objects are equal. This is extremely important in conflict resolution.

Parameters:

otherObject - the other object to compare to.

Returns:

true if the two objects are considered equal

add

public void add()
         throws DBException

Adds the record to the defined data source.

Throws:

DBException

update

public void update()
            throws DBException

Updates the record to the defined datasource

Throws:

DBException

delete

public void delete()
            throws DBException

Deletes this defined record.

Throws:

DBException

clear

public void clear()
           throws DBException

Clears all currently loaded fields

Throws:

DBException

getMappedDataContext

public String getMappedDataContext()

Returns the name of the physical database that we're talking with. This is opposed to getDataContext() which returns the security context as well. getMappedDataContext() is strictly used to get at the low level database connection.

Returns:

java.lang.String... the context we've mapped to.

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.

Parameters:

attributeName - The name of the attribute being defined

attributeValue - The object to store under this attribute name

getAttribute

public Object getAttribute(String attributeName)

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

Parameters:

attributeName - The attribute name to check

Returns:

the object associated with this attribute

getAllAttributes

public Map getAllAttributes()

Returns a Read Only Map containing all the current attributes set for this particular data object instance.

Returns:

Read Only java.util.Map

getField

public String getField(String fieldName)
                throws DBException

Retrieve the field value as a String

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

getExecutor

public DataExecutorInterface getExecutor()

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

Returns:

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

getQueryInterface

public DataQueryInterface getQueryInterface()

Use this function to acquire the DataQueryInterface that is associated with this data object [Currently unsupported]

Returns:

DataQueryInterface or null if no QueryInterface has been associated with this object

checkField

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

Check that a given value is valid for a given field. This method is overriden by specific DBObjects to do their own field-level validations - they should also call super in order to do the standard stuff. Every field is automatically checked by this method before the database is updated.

Parameters:

fieldName - Name of the field to verify

fieldValue - Value of the field to be evaluated

Throws:

DBException - If the value is not valid

getStatus

public String getStatus()

Retrieve the status code of the dataobject.

Returns:

java.lang.String

setStatus

public void setStatus(String statusValue)

Sets the status of the object.

Parameters:

statusValue - the new status code.

getValidValuesList

public List getValidValuesList(String fieldName)
                        throws DBException

Retrieve a list of valid value object for this particular dbobject

Parameters:

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

Returns:

java.util.List of valid values

Throws:

DBException - upon error

setLocale

public void setLocale(Locale newLocale)

Sets the DataObject's locale

Parameters:

newLocale - the New locale object

getLocale

public Locale getLocale()

Retrieve the DBObject's current locale

Returns:

java.util.Locale

setMaxRecords

public void setMaxRecords(int newMax)
                   throws DBException

Specify a maximum number of records to be retrieved in any subsequent searchAndRetrieve() call. Records will be retrieved (in the specified sort order) until the specified maximum is reached, then the remainder of the result set is discarded. Specifying zero indicates that all records are to be retrieved.

Parameters:

newMax - The maximum number of records to retrieve.

Throws:

DBException - If the max number is less than 0

getMaxRecords

public int getMaxRecords()

A DB Object can be told to only retrieve a certain number of records. If a "max records" value has been specified, this method provides access to it.

Returns:

The maximum number of records that should be retrieved, or zero if no max has been set

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.

Parameters:

newOffset - The maximum number of records to retrieve.

Throws:

DBException - If the max number is less than 0

author Peter Pilgrim

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.

author Peter Pilgrim, Thu Jun 21 10:30:59 BST 2001

Returns:

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

See Also:

setOffsetRecord(int)

searchAndRetrieveList

public ArrayList searchAndRetrieveList(String sortOrder)
                                throws DBException

Performs a datasource search so that the criteria set in the DataObject is used.

Parameters:

sortOrder - A pipe delimited string specifying the field(s) to be sorted upon. May be a single field without any pipes.

Returns:

java.util.List of objects. May be an empty list if no objects were found.

Throws:

DBException - upon error performing the search

searchAndRetrieveList

public ArrayList searchAndRetrieveList()
                                throws DBException

Performs a datasource search so that the criteria set in the DataObject is used. There is no specified sort order for this version of the method

Returns:

java.util.List of objects. May be an empty list if no objects were found.

Throws:

DBException - upon error performing the search

find

public boolean find()
             throws DBException

Finds a single record based upon the criteria specified by the DataTransferObject

Returns:

boolean true if a record was found, and the criteria parameter is filled with the first data object found.

Throws:

DBException - upon error performing the search

count

public int count()
          throws DBException

Just like find, but only retrieves the count, not the records themselves.

Returns:

integer Count of the records matching the criteria

Throws:

DBException - If the search could not be completed

setGlobalMask

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

Sets the DataObject's global mask

Parameters:

newGlobalMask - the New global mask object

getGlobalMask

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

Retrieve the DBObject's current global mask

Returns:

String

isGlobalMasked

public boolean isGlobalMasked()

Return boolean if the data object has a mask set

Returns:

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