bill.util.persist
Class EntityData

java.lang.Object
  |
  +--bill.util.persist.EntityData
Direct Known Subclasses:
EntityDataConfig, EntityDataRDBMS

public abstract class EntityData
extends Object

This class is used to define an entity and to manipulate the entity in the persistent store. For example, in a RDBMS, an entity represents a row in a table.


Field Summary
protected  Hashtable _collectionInfo
          List of defined colections.
protected  Hashtable _collections
          List of collections that have been instantiated for this entity.
protected  Hashtable _elements
          The list of elements that make up this entity.
protected  String _entityName
          The physical name of this entity
protected  EntityKey _keys
          The list of elements that make up the unique key of this entity
protected  short _state
          The current state of the entity, such as new (has never been saved to the persistent store), modified, or deleted
static String ET_BOOLEAN
           
static String ET_DOUBLE
           
static String ET_INTEGER
           
static String ET_LONG
           
static String ET_OID
           
static String ET_REAL
           
static String ET_STRING
           
 
Constructor Summary
EntityData()
          Creator based on the name of the entity.
EntityData(String entityName)
          Creator based on the name of the entity.
EntityData(String entityName, Hashtable keyValues)
          Creator based on the name of the entity and the key elements' values.
 
Method Summary
 boolean addElement(String logicalName, String physicalName, String elementType)
          Adds the specified element to the list of elements that make up this entity.
 boolean containsElement(String logicalElementName)
          Checks to see if the specified logical element name has been defined as an element of this entity.
 EntityCollection getCollection(String collectionName)
          Retrieve a specific collection that has been instantiated.
abstract  String getCollectionClassName()
          Returns the class name of the EntityCollection class associated with this class.
 ElementData getElement(String elementLogicalName)
          Get a specific element.
 Hashtable getElements()
          Returns the list of elements contained in this entity.
 Object getElementValue(String elementLogicalName)
          Get the value of a specific element.
 String getEntityName()
          Getter for the entity name.
 EntityKey getKey()
          Retrieves the name of the element that serves as the key of this entity.
abstract  void identifyElements()
          Identifies the elements to the entity.
 void identifyKeyElement(String element)
          Adds the specified element to the list of elements that make up this entity's key.
 void identifyRequiredElement(String elementLogicalName)
          Adds the specified element to the list of elements that must have a value for this entity.
 EntityCollection instantiateCollection(String collectionName)
          Instantiates the specified collection.
 boolean isDeleted()
          Checks to see if the entity is marked for deletion.
 boolean isModified()
          Checks to see if the entity is marked as modified.
 boolean isNew()
          Checks to see if the entity is new (has never been written to the persistent data store).
 void registerOneToManyCollection(String logicalName, String className, Hashtable mappings)
          Register a collection of this entity.
abstract  void retrieve(Hashtable keyValues)
          Retrieves an entity from the persistent store that is keyed by the given key value.
 int save()
          Controls the updating of the persistent store with the entity's information.
 void setClean()
          Clears the entity's modification state, setting it back to unmodified.
 void setDeleted()
          Identifies an entity as being marked for deletion.
 void setElementValue(String elementLogicalName, Object value)
          Set the value of a specific element to the given value.
 void setElementValues(Hashtable data)
          Mass setter of element values.
 void setEntityName(String entityName)
          Setter for the name of the entity.
 void setModified()
          Identifies an entity as having been modified from its state in the persistent data store.
 void setNew()
          Identifies an entity as being a newly created one.
 String toString()
          Flattens the entity object into a string, listing out the entity's contents.
 void userValidate(Vector errors)
          If the user wishes to perform special validation logic, they should overwrite this method in their subclass.
 Vector validate()
          Verifies (as much as it can) that the entity's data is valid.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ET_INTEGER

public static String ET_INTEGER

ET_LONG

public static String ET_LONG

ET_OID

public static String ET_OID

ET_REAL

public static String ET_REAL

ET_DOUBLE

public static String ET_DOUBLE

ET_STRING

public static String ET_STRING

ET_BOOLEAN

public static String ET_BOOLEAN

_elements

protected Hashtable _elements
The list of elements that make up this entity. The key is the logical name of the element, the result is an ElementData containing details about the element

_entityName

protected String _entityName
The physical name of this entity

_state

protected short _state
The current state of the entity, such as new (has never been saved to the persistent store), modified, or deleted

_keys

protected EntityKey _keys
The list of elements that make up the unique key of this entity

_collections

protected Hashtable _collections
List of collections that have been instantiated for this entity. The key is the collection name, thre result is the EntityCollection object.

_collectionInfo

protected Hashtable _collectionInfo
List of defined colections. the key is the collection name, the result is the data that defines the collection.
Constructor Detail

EntityData

public EntityData()
Creator based on the name of the entity. Populates and defaults class instance variables. The user must call setEntityName before being able to do much with an object created with this creator.

EntityData

public EntityData(String entityName)
Creator based on the name of the entity. Populates and defaults class instance variables.
Parameters:
entityName - The name of the entity.

EntityData

public EntityData(String entityName,
                  Hashtable keyValues)
           throws PersistException
Creator based on the name of the entity and the key elements' values. Populates and defaults class instance variables, the populates the entity's element values from the persistent data store.
Parameters:
entityName - The name of the entity.
keyValues - The key element's values. Keyed by the element's logical name, result is the element's value.
Throws:
PersistException - If a fatal error occurs that causes us to not be able to perform the retrieval.
Method Detail

setEntityName

public void setEntityName(String entityName)
Setter for the name of the entity.
Parameters:
entityName - Value to set the entity name to.

getEntityName

public String getEntityName()
Getter for the entity name.
Returns:
The name of the entity.

identifyKeyElement

public void identifyKeyElement(String element)
                        throws PersistException
Adds the specified element to the list of elements that make up this entity's key. Non OID key elements are marked as required as well. Note that the order the elements are registered is important for some of the other methods, so be sure to be consistent.
Parameters:
element - Then logical name of the element being added to the list of key elements.
Throws:
PersistException - If the specified key element is not a defined element of the entity.

identifyRequiredElement

public void identifyRequiredElement(String elementLogicalName)
                             throws PersistException
Adds the specified element to the list of elements that must have a value for this entity.
Parameters:
element - Then logical name of the element being added to the list of required elements.
Throws:
PersistException - If the specified required element is not a defined element of the entity.

registerOneToManyCollection

public void registerOneToManyCollection(String logicalName,
                                        String className,
                                        Hashtable mappings)
Register a collection of this entity. The collection can contain 0 to many entities in it that are related to this entity via the mapping information supplied.
Parameters:
logicalName - An arbitrary name used to refer to this collection.
className - The textual name of the class the entities contained in this collection are instances of. It is best to use the entire package name of the class, such as com.mycompany.UserData.
mappings - Indicates how the entities are related. Key is an element from the parent (one) class, result is the associated element from the child (many) class.

userValidate

public void userValidate(Vector errors)
If the user wishes to perform special validation logic, they should overwrite this method in their subclass. Validation errors can be added as elements to the Vector that is passed in.
Parameters:
errors - The Vector to add any new errors to.
See Also:
validate()

validate

public Vector validate()
Verifies (as much as it can) that the entity's data is valid. Any errors encountered are stored in the return Vector. If there were no errors found than the size of this Vector will be 0. The errors are stored as String messages. Before performing any automated error checks, userValidate is called for custom error checks. Automated validation checks include:
1) Required elements have a value.
Returns:
The Vector of errors that were encountered (if any).

containsElement

public boolean containsElement(String logicalElementName)
Checks to see if the specified logical element name has been defined as an element of this entity.
Parameters:
logicalElementName - The name to look for.
Returns:
If the name is defined, returns true, otherwise returns false.

getElements

public Hashtable getElements()
Returns the list of elements contained in this entity. The list is key by the element's logical name.
Returns:
The entity's list of elements.

getKey

public EntityKey getKey()
Retrieves the name of the element that serves as the key of this entity.
Returns:
The name of the entity's key element.

addElement

public boolean addElement(String logicalName,
                          String physicalName,
                          String elementType)
Adds the specified element to the list of elements that make up this entity.
Parameters:
logicalName - Logical name of the element.
physicalName - Physical name of the element. In the case of a RDBMS persistent data store this would be the column name.
elementType - The datatype of the element, such as ET_STRING, ET_INTEGER, etc.
Returns:
true if the element is successfully added, false otherwise.

getElement

public ElementData getElement(String elementLogicalName)
                       throws PersistException
Get a specific element.
Parameters:
elementLogicalName - The logical name of the element to get the value of.
Throws:
PersistException - If the specified element is not a defined element of the entity.

getElementValue

public Object getElementValue(String elementLogicalName)
                       throws PersistException
Get the value of a specific element.
Parameters:
elementLogicalName - The logical name of the element to get the value of.
Throws:
PersistException - If the specified element is not a defined element of the entity.

setElementValue

public void setElementValue(String elementLogicalName,
                            Object value)
                     throws PersistException
Set the value of a specific element to the given value.
Parameters:
elementLogicalName - The logical name of the element to set the value of.
value - The value to set the element to.
Throws:
PersistException - If the specified element is not a defined element of the entity.

setElementValues

public void setElementValues(Hashtable data)
                      throws PersistException
Mass setter of element values.
Parameters:
data - List of elements to set and values to set them to. Keyed by the logical element name.
Throws:
PersistException - If any of the specified elements are not a defined element of the entity. Note that when this is thrown some of the elements may have had their value set, so the entity object is likely now in a corrupted state.

setNew

public void setNew()
Identifies an entity as being a newly created one. This implies it has not been written to a persistent data store.

setDeleted

public void setDeleted()
Identifies an entity as being marked for deletion. This implies that when the persistent data store is updated this entity will be removed.

setModified

public void setModified()
Identifies an entity as having been modified from its state in the persistent data store. If the entity is also marked as new or deleted then being also marked as modified will be ignored when the persistent data store is updated.

setClean

public void setClean()
Clears the entity's modification state, setting it back to unmodified. This is called after an entity is written to the persistent store.

isNew

public boolean isNew()
Checks to see if the entity is new (has never been written to the persistent data store).
Returns:
true if the entity is new, false otherwise.

isDeleted

public boolean isDeleted()
Checks to see if the entity is marked for deletion.
Returns:
true if the entity is marked for deletion, false otherwise.

isModified

public boolean isModified()
Checks to see if the entity is marked as modified.
Returns:
true if the entity is marked as modified, false otherwise.

save

public int save()
         throws PersistException
Controls the updating of the persistent store with the entity's information. This method must be overwritten by the derived class with logic specific to the data store type.
Returns:
The number of rows affected by the persistent store update.
Throws:
PersistException - If a fatal error occurs that causes us to not be able to perform the retrieval.

instantiateCollection

public EntityCollection instantiateCollection(String collectionName)
                                       throws PersistException
Instantiates the specified collection. The collection must have been previously registered. If the collection had been previously instantiated than we do not do it again, we just return the previous collection.
Parameters:
collectionName - Name of the collection to instantiate.
Returns:
The newly instantiated collection.
Throws:
PersistException - Thrown for a number of reasons; collection was not registered, the collection object could not be instantiated, the collection contents could not be instantiated, etc.

getCollection

public EntityCollection getCollection(String collectionName)
Retrieve a specific collection that has been instantiated.
Parameters:
collectionName - Name of the instantiated collection to retrieve.
Returns:
The instantiated collection, or null if no collection by that name has been instantiated.

identifyElements

public abstract void identifyElements()
Identifies the elements to the entity. This must be overwritten in a descendant class with the actual addElement, identifyKeyElement, identifyRequired, etc method calls.

retrieve

public abstract void retrieve(Hashtable keyValues)
                       throws PersistException
Retrieves an entity from the persistent store that is keyed by the given key value. This method must be overwritten in a descendant class with the logic to access the persistent store.
Parameters:
keyValues - The key element's values. Keyed by the element's logical name, result is the element's value.
Throws:
PersistException - If a fatal error occurs that causes us to not be able to perform the retrieval.

getCollectionClassName

public abstract String getCollectionClassName()
Returns the class name of the EntityCollection class associated with this class. Must be overridden by any subclasses the extend this one.
Returns:
The full package name of the collection class, such as bill.util.EntityCollectionXYZ.

toString

public String toString()
Flattens the entity object into a string, listing out the entity's contents.
Overrides:
toString in class Object
Returns:
The flattened string representation of the entity.