com.jcorporate.expresso.core.dataobjects
Class SynchronizedDataObject

java.lang.Object
  com.jcorporate.expresso.core.dataobjects.SynchronizedDataObject

All Implemented Interfaces:

Cacheable, ContextNested, DataObject, Serializable

public class SynchronizedDataObject

extends Object

implements DataObject

This class provides a threadsafe access to a dataobject. To be able to more safely share your dataobjects acrossed multiple threads, simple call.

Typical Usage:

 DataObject myobj = SynchronizedDataObject.newInstance(new MimeTypes(SecuredDBObject.SYSTEM_ACCOUNT));
 

 //We now have a wrapped MimeTypes data object
 myobj.setField("MimeNumber",new Integer(1));
 

 //Retrieves a set of cloned records.
 ArrayList records = myobj.searchAndRetrieveList();
 

Author:

Michael Rimov

See Also:

Serialized Form

Field Summary

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

STATUS_CURRENT, STATUS_DELETED, STATUS_NEW, STATUS_UPDATED

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) Retrieve the native object type for the given field name.
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".
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
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
Iterator	getFieldListIterator() Returna a list of all field names available to this class in order.
DataFieldMetaData	getFieldMetaData(String fieldName) Retrieves the metadata for a particular field name
org.apache.oro.text.regex.Pattern	getGlobalMask() Get the compiled regular expression for this base data object.
String	getKey() Every class that can stay in the system cache must define a way to get a unique key
Iterator	getKeyFieldListIterator() Retrieve iterator of all keys
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
String	getStatus() Retrieve the status code of the dataobject.
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.
boolean	isGlobalMasked() Return boolean if the data object has a mask set
static DataObject	newInstance(DataObject wrappedObject) Call this to wrap your data object in a threadsafe wrapper.
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	setDataContext(String newContext) Sets the data context that this object is residing in.
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) 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 class java.lang.Object

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

Method Detail

newInstance

public static DataObject newInstance(DataObject wrappedObject)

Call this to wrap your data object in a threadsafe wrapper.

Parameters:

wrappedObject - the object to wrap.

Returns:

a DataObject who's implementation is threadsafe.

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

getFieldListIterator

public Iterator getFieldListIterator()

Returna a list of all field names available to this class in order.

Returns:

java.util.Iterator

getKeyFieldListIterator

public Iterator getKeyFieldListIterator()
                                 throws DBException

Retrieve iterator of all keys

Returns:

java.util.Itaerator Each iteration will return the name of the next key in the list.

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

Specified by:

getMetaData in interface DataObject

Returns:

a built DataObjectMetaData for this database object

getFieldMetaData

public DataFieldMetaData getFieldMetaData(String fieldName)

Retrieves the metadata for a particular field name

Specified by:

getFieldMetaData in interface DataObject

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.

set

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

Directly sets the field value without getting the datafield object

Specified by:

set in interface DataObject

Parameters:

fieldName - the name of the field to set

o - the object value to set it to.

Throws:

DataException

equals

public boolean equals(Object otherObject)

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

Specified by:

equals in interface DataObject

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.

Specified by:

add in interface DataObject

Throws:

DBException

update

public void update()
            throws DBException

Updates the record to the defined datasource

Specified by:

update in interface DataObject

Throws:

DBException

delete

public void delete()
            throws DBException

Deletes this defined record.

Specified by:

delete in interface DataObject

Throws:

DBException

clear

public void clear()
           throws DBException

Clears all currently loaded fields

Specified by:

clear in interface DataObject

Throws:

DBException

setDataContext

public void setDataContext(String newContext)

Sets the data context that this object is residing in. This is identical to the pre-Expresso 5.0 setDBName()

Specified by:

setDataContext in interface ContextNested

Parameters:

newContext - the new name of the data context.

Throws:

IllegalArgumentException - if the DataContext does not exist

getDataContext

public String getDataContext()

Returns the name of the currently set DataContext

Specified by:

getDataContext in interface ContextNested

Returns:

java.lang.String

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.

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.

Specified by:

getMappedDataContext in interface DataObject

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.

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)

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

Specified by:

getAttribute in interface DataObject

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.

Specified by:

getAllAttributes in interface DataObject

Returns:

Read Only java.util.Map

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

getQueryInterface

public DataQueryInterface getQueryInterface()

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

Specified by:

getQueryInterface in interface DataObject

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.

Specified by:

checkField in interface DataObject

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.

Specified by:

getStatus in interface DataObject

Returns:

java.lang.String

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.

Returns:

java.util.List of valid values

Throws:

DBException - upon error

setLocale

public void setLocale(Locale newLocale)

Sets the DataObject's locale

Specified by:

setLocale in interface DataObject

Parameters:

newLocale - the New locale object

getLocale

public Locale getLocale()

Retrieve the DBObject's current locale

Specified by:

getLocale in interface DataObject

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.

Specified by:

setMaxRecords in interface DataObject

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.

Specified by:

getMaxRecords in interface DataObject

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.

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

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

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)

searchAndRetrieveList

public ArrayList searchAndRetrieveList(String sortOrder)
                                throws DBException

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

Note: This particular implementation, to be threadsafe, returns a new array instance, so it is particularly slow and memory intensive. However, for the scope of the class, it is at least threadsafe.

Specified by:

searchAndRetrieveList in interface DataObject

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

Note: This particular implementation, to be threadsafe, returns a new array instance, so it is particularly slow and memory intensive. However, for the scope of the class, it is at least threadsafe.

Specified by:

searchAndRetrieveList in interface DataObject

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

Specified by:

find in interface DataObject

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.

Specified by:

count in interface DataObject

Returns:

integer Count of the records matching the criteria

Throws:

DBException - If the search could not be completed

getKey

public String getKey()

Every class that can stay in the system cache must define a way to get a unique key

Specified by:

getKey in interface Cacheable

Returns:

The cache key for this item.

setStatus

public void setStatus(String statusValue)

Sets the status of the object.

Specified by:

setStatus in interface DataObject

Parameters:

statusValue -

get

public Object get(String fieldName)
           throws DataException

Retrieve the native object type for the given field name.

Specified by:

get in interface DataObject

Parameters:

fieldName - the name of the field to retrieve

Returns:

Object or null if the field was null

Throws:

DataException - upon error

IllegalArgumentException - if fieldname is invalid

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

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

hashCode

public int hashCode()

Returns a hash code value for the object.

Returns:

a hash code value for this object.