org.jlf.dataMap
Class DataMappedObject

java.lang.Object
  |
  +--org.jlf.dataMap.DataObject
        |
        +--org.jlf.dataMap.DataMappedObject

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

CachedObject

public abstract class DataMappedObject

extends DataObject

Abstract class used as the base of all objects in the data mapping framework.

DataMappedObject is composed of four major capabilities:

    1. The ability to store and retrieve attributes (primitive data types
       like Integer, Boolean, Date, ...)
    2. The ability to store and retrieve related objects
       (other DataMappedObjects)
    3. The ability to return the correct subclass when you read
       from an abstract superclass with many subclasses.
    4. The ability to use the above capabilities to read attributes and
       related objects from a data source and write them out to
       a data sink.
 

See Also:

DataObject, Relationship, RelationshipDescriptor, DataLocation, DataMapper, Serialized Form

Field Summary

protected static java.lang.String	DATA_LOCATION_KEY_PROPERTY_SUFFIX Property file key constant, appended to the name of the class, telling the default data location to use when none is specified.
protected static java.lang.String	DEFAULT_DATA_LOCATION_KEY This is the property file key to the default data location.
protected boolean	deleteOnWrite Flag to delete an object previously read from a database the next time the object is synchronized with the database.
protected static java.lang.String	FIND_ALL_CRITERIA_KEY Default search criteria key for the framework to use when searching for information on how to query a data source for all objects of a particular object type.
protected static java.lang.String	FIND_BY_PRIMARY_KEY_CRITERIA_KEY Default search criteria key for the framework to use when searching for information on how to query a data source for a particular object based on that object's primary key.
protected boolean	hasBeenReadFromDataSource Flag to tell if the object has previously been read from the database.
protected static java.lang.String	HIERARCHY_HASHTABLE_VARIABLE_NAME
protected static java.lang.String	HIERARCHY_TABLE_KEY_VECTOR_VARIABLE_NAME
protected static int	INITIAL_HIERARCHY_HASHTABLE_SIZE
protected static int	INITIAL_HIERARCHY_TABLE_KEY_VECTOR_SIZE
protected static int	INITIAL_RELATIONSHIP_DESCRIPTOR_HASHTABLE_SIZE
protected static int	INITIAL_RELATIONSHIPS_HASHTABLE_SIZE
protected DataMappedObjectKey	key Holds the key for the object.
protected static java.lang.String	RELATIONSHIP_DESCRIPTOR_VECTOR_VARIABLE_NAME

Fields inherited from class org.jlf.dataMap.DataObject

ATTRIBUTE_DESCRIPTOR_VECTOR_VARIABLE_NAME, attributes, INITIAL_ATTRIBUTE_DESCRIPTOR_HASHTABLE_SIZE, INITIAL_ATTRIBUTE_HASHTABLE_SIZE

Constructor Summary

DataMappedObject()

Method Summary

void	addRelatedObject(java.lang.String name, DataMappedObject dmo) Convenience method to passthrough a related object to the relationship so it can track it.
void	addRelatedObjects(java.lang.String name, java.util.Vector dmos) Convenience method to passthrough a Vector of related objects to the relationship so it can track it.
boolean	areAllKeyAttributesPresent() Checks to see if all key attributes are present.
boolean	areAllRequiredAttributesPresent() Checks to see if all required attributes are present.
protected java.util.Hashtable	basicGetHierarchyTable() Returns a hash table of DataMappedObjectKey objects pertinent to the DataMappedObject.
protected java.util.Vector	basicGetHierarchyTableKeyAttributes() Returns a vector of Strings which are the attribute names of any attributes in the hierarchy table.
protected DataMappedObjectKey	basicGetKey() Creates a key from a list of all attribute descriptors that say that they are key attributes.
protected java.util.Hashtable	basicGetRelationshipDescriptors() Returns a hash table of RelationshipDescriptor objects pertinent to the DataMappedObject.
void	cleanupAfterWrite(DataMapper dataMapper) Performs cleanup work after a write is committed to the database (for example, resets attribute values).
void	deleteOnWrite() Sets a flag so that the next time you write your object to a data store, it will attempt to delete it.
java.util.Vector	findAll() Quick accessor method to read all of this particular object's type from the default data location.
java.util.Vector	findAll(DataMapper dataMapper) Quick accessor method to read all of this particular object's type from a specified data location.
DataMappedObject	findByPrimaryKey() Quick accessor method to read one object of this particular object's type from the default data location, using its already populated primary key.
DataMappedObject	findByPrimaryKey(DataMapper dataMapper) Quick accessor method to read one object of this particular object's type from a specified data mapper, using its already populated primary key.
java.util.Vector	findByRelationship(Relationship relationship, DataMapper dataMapper) Reads objects involved in a relationship that is not read in the same query as its primary object.
java.util.Vector	findManyBySearchCriteria(java.lang.String criteriaKey) Helper method to read objects of a specific type and search criteria from a the default data mapper for the object.
java.util.Vector	findManyBySearchCriteria(java.lang.String criteriaKey, DataMapper dataMapper) Main kickoff method to read objects of a specific type and search criteria from a data mapper to a data location.
DataMappedObject	findOneBySearchCriteria(java.lang.String criteriaKey) Helper method to read one object of a specific search criteria.
DataMappedObject	findOneBySearchCriteria(java.lang.String criteriaKey, DataMapper dataMapper) Helper method to read one object of a specific search criteria.
java.util.Set	getAllRelationshipNames() Returns a set of relationship names (Strings) for all of the relationship descriptors available to the object.
static DataMapper	getDataMapper(java.lang.String dataLocationKey) Convenience method to return an instance of a data mapper to the data location named by the key given.
protected java.lang.String	getDefaultDataLocationKey() Returns the data location key to the properties file for this object's default data location.
DataMapper	getDefaultDataMapper() Returns an instance of the default data mapper to the default data location.
java.util.Vector	getDeletedRelatedObjects(java.lang.String name) Passthrough method for Relationship.getDeletedRelatedObjects(), given a particular relationship name.
protected DataMappedObjectKey	getHierachyTableKeyForDataArray(DataArray dataArray) Retrieves a hierarchy table key for the current object given a data array.
protected java.util.Hashtable	getHierarchyTable() Returns a lazy-initialized hierarchy table used to map incoming DataArray data to an object of the correct subclass in an inheritance hierarchy.
protected java.util.Vector	getHierarchyTableKeyAttributes() Returns a lazy-initialized vector of attribute names used to map to the hierarchy table.
DataMappedObjectKey	getKey() Retrieves the key for this object.
DataMappedObject	getNewInstance() Creates a new instance of a concrete subclass class of this object
DataMappedObject	getNewInstance(boolean reuseThisInstance) Creates a new instance of a concrete subclass class of this object if the reuseThisInstance flag is false.
DataMappedObject	getNewInstance(DataArray dataArray) Creates a new instance of a concrete subclass class of this object, taking into consideration the hierarchy table if one is defined.
DataMappedObject	getRelatedObject(java.lang.String name) Passthrough method for Relationship.getRelatedObject(), given a particular relationship name.
java.util.Vector	getRelatedObjects(java.lang.String name) Passthrough method for Relationship.getRelatedObjects(), given a particular relationship name.
Relationship	getRelationship(java.lang.String name) Returns a relationship object for a particular relationship name.
RelationshipDescriptor	getRelationshipDescriptor(java.lang.String name) Returns a relationship descriptor for a particular relationship name.
protected java.util.Hashtable	getRelationshipDescriptors() Returns a lazy-initialized collection of RelationshipDescriptor objects pertinent to the DataMappedObject.
java.util.Vector	getUndeletedRelatedObjects(java.lang.String name) Passthrough method for Relationship.getUndeletedRelatedObjects(), given a particular relationship name.
boolean	hasBeenReadFromDataSource() Returns a flag telling if the object has previously been read from the database.
protected boolean	hasHierarchyTable() Signifies whether the class has a hierarchy table.
boolean	hasKey() Checks to see if the object has any key fields.
protected DataMappedObject	newInstanceForDataArray(DataArray dataArray) Creates a new instance of a concrete subclass class of this object, taking into consideration the hierarchy table defined.
void	populateFromDataArray(DataArray dataArray, Relationship relationship) Reads as many attributes as it can from the DataArray under the context of a particular relationship if available.
protected void	populateKeyFromParentRelationship(Relationship relationship, DataMapper dataMapper) Helper method to populate the key for this object as best as possible from a primary object/parent object's data.
void	preWriteValidation() Hook method for data mapped objects to perform pre-write validation.
void	processRelationshipsFromDataArray(DataArray dataArray) Processes any relationships from the DataArray to populate related DataMappedObjects.
void	setHasBeenReadFromDataSource(boolean hasBeenRead) Sets a flag to tell if the object has previously been read from the database.
boolean	shouldDeleteOnWrite() Returns a flag telling if an object previously read from a database should be deleted the next time the object is synchronized with the database.
void	validateRequiredAttributesPresent() Checks to see if all required attributes are present.
void	write(DataMapper dataMapper) Writes an object out to a data source after it validates the object.

Methods inherited from class org.jlf.dataMap.DataObject

attributeEquals, basicGetAttributeDescriptors, equals, getAllAttributeNames, getAttribute, getAttributeDescriptor, getAttributeDescriptors, getAttributeValue, getDoubleAttribute, getLongAttribute, getStringAttribute, hasAttributeDefined, hashCode, setAttributeValue, setDoubleAttribute, setLongAttribute, setStringAttribute

Methods inherited from class java.lang.Object

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

Field Detail

key

protected DataMappedObjectKey key

Holds the key for the object.

INITIAL_RELATIONSHIP_DESCRIPTOR_HASHTABLE_SIZE

protected static final int INITIAL_RELATIONSHIP_DESCRIPTOR_HASHTABLE_SIZE

See Also:

Constant Field Values

INITIAL_RELATIONSHIPS_HASHTABLE_SIZE

protected static final int INITIAL_RELATIONSHIPS_HASHTABLE_SIZE

See Also:

Constant Field Values

RELATIONSHIP_DESCRIPTOR_VECTOR_VARIABLE_NAME

protected static final java.lang.String RELATIONSHIP_DESCRIPTOR_VECTOR_VARIABLE_NAME

See Also:

Constant Field Values

INITIAL_HIERARCHY_TABLE_KEY_VECTOR_SIZE

protected static final int INITIAL_HIERARCHY_TABLE_KEY_VECTOR_SIZE

See Also:

Constant Field Values

HIERARCHY_TABLE_KEY_VECTOR_VARIABLE_NAME

protected static final java.lang.String HIERARCHY_TABLE_KEY_VECTOR_VARIABLE_NAME

See Also:

Constant Field Values

INITIAL_HIERARCHY_HASHTABLE_SIZE

protected static final int INITIAL_HIERARCHY_HASHTABLE_SIZE

See Also:

Constant Field Values

HIERARCHY_HASHTABLE_VARIABLE_NAME

protected static final java.lang.String HIERARCHY_HASHTABLE_VARIABLE_NAME

See Also:

Constant Field Values

DATA_LOCATION_KEY_PROPERTY_SUFFIX

protected static final java.lang.String DATA_LOCATION_KEY_PROPERTY_SUFFIX

Property file key constant, appended to the name of the class, telling the default data location to use when none is specified. The default value for this key is below.

See Also:

Constant Field Values

DEFAULT_DATA_LOCATION_KEY

protected static final java.lang.String DEFAULT_DATA_LOCATION_KEY

This is the property file key to the default data location. If no data location is explicitly identified, the framework will try to find properties for this key suffix, create a connection to it, and map objects to and from it. The key which tries to find this value is above.

See Also:

Constant Field Values

FIND_ALL_CRITERIA_KEY

protected static final java.lang.String FIND_ALL_CRITERIA_KEY

Default search criteria key for the framework to use when searching for information on how to query a data source for all objects of a particular object type.

See Also:

Constant Field Values

FIND_BY_PRIMARY_KEY_CRITERIA_KEY

protected static final java.lang.String FIND_BY_PRIMARY_KEY_CRITERIA_KEY

Default search criteria key for the framework to use when searching for information on how to query a data source for a particular object based on that object's primary key.

See Also:

Constant Field Values

hasBeenReadFromDataSource

protected boolean hasBeenReadFromDataSource

Flag to tell if the object has previously been read from the database. If it has, then when trying to write any updates out, the object should not do a create, but rather an update or delete.

deleteOnWrite

protected boolean deleteOnWrite

Flag to delete an object previously read from a database the next time the object is synchronized with the database.

Constructor Detail

DataMappedObject

public DataMappedObject()

Method Detail

basicGetKey

protected DataMappedObjectKey basicGetKey()

Creates a key from a list of all attribute descriptors that say that they are key attributes.

getKey

public DataMappedObjectKey getKey()

Retrieves the key for this object.

basicGetRelationshipDescriptors

protected java.util.Hashtable basicGetRelationshipDescriptors()

Returns a hash table of RelationshipDescriptor objects pertinent to the DataMappedObject. This method is not lazy-initialized. Subclasses with relationships SHOULD OVERRIDE this method, calling the superclass method of same name and adding to the Hashtable any RelationshipDescriptor objects pertinent. Use the relationship name as the key and a RelationshipDescriptor object as the value.

At this level in the hierarchy, no relationship descriptors are known. Return an empty hash table that can be populated by the subclass(es).

getRelationshipDescriptors

protected java.util.Hashtable getRelationshipDescriptors()

Returns a lazy-initialized collection of RelationshipDescriptor objects pertinent to the DataMappedObject. This method uses a ClassInstanceVariable as a convenient way to do the lazy-initialization.

getRelationshipDescriptor

public RelationshipDescriptor getRelationshipDescriptor(java.lang.String name)

Returns a relationship descriptor for a particular relationship name.

Returns:

the RelationshipDescriptor if found.

Throws:

DataMapError - if a descriptor for the relationship name not found

getAllRelationshipNames

public java.util.Set getAllRelationshipNames()

Returns a set of relationship names (Strings) for all of the relationship descriptors available to the object.

getRelationship

public Relationship getRelationship(java.lang.String name)

Returns a relationship object for a particular relationship name.

Returns:

the Relationship if found

Throws:

DataMapError - if a relationship descriptor is not found for the relationship name

getRelatedObjects

public java.util.Vector getRelatedObjects(java.lang.String name)

Passthrough method for Relationship.getRelatedObjects(), given a particular relationship name.

Returns:

a Vector of DataMappedObjects if the relationship is found

Throws:

DataMapError - if the relationship descriptor is not found for the relationship

getUndeletedRelatedObjects

public java.util.Vector getUndeletedRelatedObjects(java.lang.String name)

Passthrough method for Relationship.getUndeletedRelatedObjects(), given a particular relationship name.

Returns:

a Vector of DataMappedObjects if the relationship is found

Throws:

DataMapError - if the relationship descriptor is not found for the relationship

getDeletedRelatedObjects

public java.util.Vector getDeletedRelatedObjects(java.lang.String name)

Passthrough method for Relationship.getDeletedRelatedObjects(), given a particular relationship name.

Returns:

a Vector of DataMappedObjects if the relationship is found

Throws:

DataMapError - if the relationship descriptor is not found for the relationship

getRelatedObject

public DataMappedObject getRelatedObject(java.lang.String name)

Passthrough method for Relationship.getRelatedObject(), given a particular relationship name.

Returns:

a DataMappedObject if the relationship is found and at least one object is present in the relationship collection (always picks the first object in the collection). null is returned if the relationship is found and no objects are in the relationship collection

Throws:

DataMapError - if the relationship descriptor is not found for the relationship name

addRelatedObject

public void addRelatedObject(java.lang.String name,
                             DataMappedObject dmo)

Convenience method to passthrough a related object to the relationship so it can track it.

addRelatedObjects

public void addRelatedObjects(java.lang.String name,
                              java.util.Vector dmos)

Convenience method to passthrough a Vector of related objects to the relationship so it can track it.

hasHierarchyTable

protected boolean hasHierarchyTable()

Signifies whether the class has a hierarchy table. This flag is used to increase performance so that hierarchy table look-ups will not have to be done in the normal case where a hierarchy is not desired. The default is false, override this method to return true if you have a hierarchy table.

NOTE: Methods hasHierarchyTable(), basicGetHierarchyTableKeyAttributes(), and basicGetHierarchyTable() must ALL be kept in sync or this will not work!

basicGetHierarchyTableKeyAttributes

protected java.util.Vector basicGetHierarchyTableKeyAttributes()

Returns a vector of Strings which are the attribute names of any attributes in the hierarchy table. This vector is needed by the framework to extract values from data arrays.

This method is not lazy-initialized. Subclasses with hierarchy tables SHOULD OVERRIDE this method, calling the superclass method of same name and adding to the vector any attribute names appropriate.

At this level in the hierarchy, no hierarchy table members are known. Return an empty vector that can be populated by the subclass(es).

NOTE: Methods hasHierarchyTable(), basicGetHierarchyTableKeyAttributes(), and basicGetHierarchyTable() must ALL be kept in sync or this will not work!

getHierarchyTableKeyAttributes

protected java.util.Vector getHierarchyTableKeyAttributes()

Returns a lazy-initialized vector of attribute names used to map to the hierarchy table.

This method uses a ClassInstanceVariable as a convenient way to do the lazy-initialization.

basicGetHierarchyTable

protected java.util.Hashtable basicGetHierarchyTable()

Returns a hash table of DataMappedObjectKey objects pertinent to the DataMappedObject. The key to the table is the DataAttribute which must match attributes in the DataMappedObject. The value is the Java Class which should be instantiated, when the key matches. That Java Class must be a the same or a subclass of the current class.

This method is not lazy-initialized. Subclasses with hierarchy tables SHOULD OVERRIDE this method, calling the superclass method of same name and adding to the Hashtable any DataMappedObjectKey and Class key/value pairs pertinent. Use the DataMappedObjectKey as the key and a Class object as the value.

At this level in the hierarchy, no hierarchy table members are known. Return an empty hash table that can be populated by the subclass(es).

NOTE: Methods hasHierarchyTable(), basicGetHierarchyTableKeyAttributes(), and basicGetHierarchyTable() must ALL be kept in sync or this will not work!

getHierarchyTable

protected java.util.Hashtable getHierarchyTable()

Returns a lazy-initialized hierarchy table used to map incoming DataArray data to an object of the correct subclass in an inheritance hierarchy.

This method uses a ClassInstanceVariable as a convenient way to do the lazy-initialization.

getHierachyTableKeyForDataArray

protected DataMappedObjectKey getHierachyTableKeyForDataArray(DataArray dataArray)

Retrieves a hierarchy table key for the current object given a data array.

newInstanceForDataArray

protected DataMappedObject newInstanceForDataArray(DataArray dataArray)

Creates a new instance of a concrete subclass class of this object, taking into consideration the hierarchy table defined.

Returns:

a new instance of the appropriate DataMappedObject subclass

hasBeenReadFromDataSource

public boolean hasBeenReadFromDataSource()

Returns a flag telling if the object has previously been read from the database. If it has, then when trying to write any updates out, the object should not do a create, but rather an update or delete.

setHasBeenReadFromDataSource

public void setHasBeenReadFromDataSource(boolean hasBeenRead)

Sets a flag to tell if the object has previously been read from the database. If it has, then when trying to write any updates out, the object should not do a create, but rather an update or delete.

shouldDeleteOnWrite

public boolean shouldDeleteOnWrite()

Returns a flag telling if an object previously read from a database should be deleted the next time the object is synchronized with the database.

deleteOnWrite

public void deleteOnWrite()

Sets a flag so that the next time you write your object to a data store, it will attempt to delete it.

getDefaultDataLocationKey

protected java.lang.String getDefaultDataLocationKey()

Returns the data location key to the properties file for this object's default data location. Override this method in your class if more than one data location is being used for your objects!!!

getDataMapper

public static DataMapper getDataMapper(java.lang.String dataLocationKey)

Convenience method to return an instance of a data mapper to the data location named by the key given. A call to this method MUST be inside a try block with a finally block to close the data mapper when finished!!!

getDefaultDataMapper

public DataMapper getDefaultDataMapper()

Returns an instance of the default data mapper to the default data location. A call to this method MUST be inside a try block with a finally block to close the data mapper when finished!!!

getNewInstance

public DataMappedObject getNewInstance()

Creates a new instance of a concrete subclass class of this object

Returns:

a new instance of DataMappedObject

getNewInstance

public DataMappedObject getNewInstance(boolean reuseThisInstance)

Creates a new instance of a concrete subclass class of this object if the reuseThisInstance flag is false. If true, return this. This is a helper method useful when constructing a number of instances, so you can reuse the first object.

Returns:

a new instance of DataMappedObject

getNewInstance

public DataMappedObject getNewInstance(DataArray dataArray)

Creates a new instance of a concrete subclass class of this object, taking into consideration the hierarchy table if one is defined. The DataArray is required as input so that a subclass can be found given a hierarchy key match to the data array row. If no hierarchy table is defined, just returns a new instance of this class.

Returns:

a new instance of the appropriate DataMappedObject subclass

populateFromDataArray

public void populateFromDataArray(DataArray dataArray,
                                  Relationship relationship)

Reads as many attributes as it can from the DataArray under the context of a particular relationship if available. If the relationship is null, the data is read directly from the array with mapping properties taken into account.

processRelationshipsFromDataArray

public void processRelationshipsFromDataArray(DataArray dataArray)

Processes any relationships from the DataArray to populate related DataMappedObjects.

validateRequiredAttributesPresent

public void validateRequiredAttributesPresent()

Checks to see if all required attributes are present.

Throws:

RequiredAttributeNotPresent

areAllRequiredAttributesPresent

public boolean areAllRequiredAttributesPresent()

Checks to see if all required attributes are present.

hasKey

public boolean hasKey()

Checks to see if the object has any key fields.

areAllKeyAttributesPresent

public boolean areAllKeyAttributesPresent()

Checks to see if all key attributes are present.

findAll

public java.util.Vector findAll()

Quick accessor method to read all of this particular object's type from the default data location.

findByPrimaryKey

public DataMappedObject findByPrimaryKey()

Quick accessor method to read one object of this particular object's type from the default data location, using its already populated primary key.

findAll

public java.util.Vector findAll(DataMapper dataMapper)

Quick accessor method to read all of this particular object's type from a specified data location.

findByPrimaryKey

public DataMappedObject findByPrimaryKey(DataMapper dataMapper)

Quick accessor method to read one object of this particular object's type from a specified data mapper, using its already populated primary key.

populateKeyFromParentRelationship

protected void populateKeyFromParentRelationship(Relationship relationship,
                                                 DataMapper dataMapper)

Helper method to populate the key for this object as best as possible from a primary object/parent object's data.

findByRelationship

public java.util.Vector findByRelationship(Relationship relationship,
                                           DataMapper dataMapper)

Reads objects involved in a relationship that is not read in the same query as its primary object. The default implementation is to do a findByPrimaryKey, where the primary key of the roleB object is populated from attributes in the primary object.

You MUST override the default implemetation of this method if you want any other behavior, and since relationships are very tricky, you are likely to have to do so.

findOneBySearchCriteria

public DataMappedObject findOneBySearchCriteria(java.lang.String criteriaKey)

Helper method to read one object of a specific search criteria. If more than one object is found, a warning is sent to the log. If none found, null is returned. Grabs a default data mapper connection to execute the query.

findOneBySearchCriteria

public DataMappedObject findOneBySearchCriteria(java.lang.String criteriaKey,
                                                DataMapper dataMapper)

Helper method to read one object of a specific search criteria. If more than one object is found, a warning is sent to the log. If none found, null is returned.

findManyBySearchCriteria

public java.util.Vector findManyBySearchCriteria(java.lang.String criteriaKey)

Helper method to read objects of a specific type and search criteria from a the default data mapper for the object.

findManyBySearchCriteria

public java.util.Vector findManyBySearchCriteria(java.lang.String criteriaKey,
                                                 DataMapper dataMapper)

Main kickoff method to read objects of a specific type and search criteria from a data mapper to a data location.

preWriteValidation

public void preWriteValidation()

Hook method for data mapped objects to perform pre-write validation. The default implementation is to make sure all required attributes are present.

Typically you should override this method, calling the super first, then adding your own extra validation logic.

write

public void write(DataMapper dataMapper)

Writes an object out to a data source after it validates the object.

cleanupAfterWrite

public void cleanupAfterWrite(DataMapper dataMapper)

Performs cleanup work after a write is committed to the database (for example, resets attribute values).