org.pajes.db.entity
Class Entity

java.lang.Object
  org.pajes.db.entity.Entity

All Implemented Interfaces:

java.io.Serializable

public abstract class Entity

extends java.lang.Object

implements java.io.Serializable

A representation of a database entity.

Sub-classes must provide a no-parameter constructor.

For example, given following SQL table:

  create table client
  (
     client                int                   not null,
     clientName            varchar(50)           not null,
     constraint clientPK primary key (client)
  )
 

You would create an Entity sub-class as:

  import org.pajes.db.Entity;
  import org.pajes.db.Registry;
 
  public class Client extends Entity {
      public Client() {
          super(Registry.getManager(ClientManager.class));
      }
 
      public Integer getClient() {
          return (Integer)super.getValue("client");
      }
 
      public String getClientName() {
          return (String)super.getValue("clientName");
      }
 
      public void setClientName(String name) {
          super.setValue("clientName", name);
      }
  }
 

See Also:

Serialized Form

Constructor Summary

protected

Entity(Manager manager) Creates a new entity.

Method Summary

void	assignInputFieldValues(TraversableElement container) Convenience method to assign entity values to Input fields where the name attribute of the Input field matches the attribute name in the entity.
void	assignTagContents(TraversableElement container) Convenience method to assign entity values as the content in a Container where the ID attribute of a Tag in the Container matches the attribute name in the entity.
boolean	equals(java.lang.Object obj) Indicates whether some other entity is "equal to" this one.
java.lang.String	getFormattedValue(java.lang.String name) Retrieves the value of the specified attribute.
java.lang.Object	getInitialValue(java.lang.String name) Retrieves the initial value of the specified attribute.
Manager	getManager() Returns the Manager managing this entity.
java.lang.Object	getValue(java.lang.String name) Retrieves the value of the specified attribute.
protected java.util.HashMap	getValues() Retrieves the entity's values as a HashMap, where the key is the attribute name and the value is the Value object.
int	hashCode() Returns a hash code value for the entity, based on the primary key values.
boolean	isChanged() Returns true if the any of the entity's values have been updated.
boolean	isChanged(java.lang.String name) Returns true if the specified attribute value has been updated.
boolean	isDeleted() Returns true if the entity has been logically deleted.
boolean	isForceUpdateOnPrimaryKey() Determines whether or not updates and deletes use optimistic locking.
boolean	isNew() Returns true if the entity is a new entity.
boolean	isReadOnly() Returns the read only flag.
int	save() Convenience method to save changes to this entity into the database.
int	save(java.sql.Connection connection) Convenience method to save changes to this entity into the database.
Entity	setDeleted(boolean status) Sets the state of this entity.
void	setForceUpdateOnPrimaryKey(boolean force) Normally updates and deletes occur using optimistic locking.
void	setInitialValue(java.lang.String name, java.lang.Object value) Alters the initial value of the nominated Attribute.
protected void	setManager(Manager manager) Sets the manager responsible for this entity.
protected Entity	setNew(boolean status) Sets the state of this entity.
void	setReadOnly(boolean readOnly) Sets the entity to read only.
void	setValue(java.lang.String name, java.lang.Object value) Alters the value of the nominated Attribute.
void	setValue(java.lang.String name, java.lang.Object value, boolean initial) Alters the value of the nominated Attribute.
protected void	setValue(java.lang.String name, java.sql.ResultSet resultSet, int index, int type, boolean initial) Alters the value of the specified attribute of this Entity.
Entity	setValues(org.jdom.Element element, boolean initial) Alters the values of this Entity.
Entity	setValues(Entity entity, boolean initial) Alters the values of this Entity.
Entity	setValues(javax.servlet.http.HttpServletRequest request) Alters the values of this Entity.
Entity	setValues(java.sql.ResultSet resultSet, boolean initial) Alters the values of all attributes of this Entity.
java.lang.String	toString() Returns a String representation of this Entity.
java.lang.String	toXML() Converts the current values of the entity to a String representation of an XML document.
java.lang.String	toXML(boolean attributes) Converts the current values of the entity to a String representation of an XML document.
java.lang.String	toXML(boolean attributes, boolean initial) Converts the entity to a String representation of an XML document.
org.jdom.Document	toXMLDocument() Converts the current values of the entity to an XML document.
org.jdom.Document	toXMLDocument(boolean attributes) Converts the current values of the entity to an XML document.
org.jdom.Document	toXMLDocument(boolean attributes, boolean initial) Converts the current values of the entity to an XML document.
org.jdom.Element	toXMLElement(boolean attributes, boolean initial) Converts the entity to an XML element.
protected void	valueChanged(Value value) Receives notification from a Value when it's value has been changed.

Methods inherited from class java.lang.Object

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

Constructor Detail

Entity

protected Entity(Manager manager)

Creates a new entity.

Parameters:

manager - the Manager instance responsible for this entity.

Method Detail

isChanged

public boolean isChanged()

Returns true if the any of the entity's values have been updated.

Returns:

true if the any of the entity's values have been updated.

isChanged

public boolean isChanged(java.lang.String name)

Returns true if the specified attribute value has been updated.

Parameters:

name - the name of the attribute.

Returns:

true if the specified attribute value has been updated.

setDeleted

public Entity setDeleted(boolean status)

Sets the state of this entity.

Parameters:

status - true if the entity is to be logically deleted. The change is NOT automatically reflected in the database.

Returns:

the modified Entity object.

isDeleted

public boolean isDeleted()

Returns true if the entity has been logically deleted.

Returns:

true if the entity has been logically deleted.

getFormattedValue

public java.lang.String getFormattedValue(java.lang.String name)

Retrieves the value of the specified attribute.

Parameters:

name - the name of the attribute.

Returns:

the value of the attribute, or null if the attribute does not exist.

setInitialValue

public void setInitialValue(java.lang.String name,
                            java.lang.Object value)

Alters the initial value of the nominated Attribute.

Parameters:

name - the name of the attribute.

value - the new value to be assigned.

getInitialValue

public java.lang.Object getInitialValue(java.lang.String name)

Retrieves the initial value of the specified attribute.

Parameters:

name - the name of the attribute.

Returns:

the value of the attribute.

getManager

public Manager getManager()

Returns the Manager managing this entity.

Returns:

the Manager instance.

setForceUpdateOnPrimaryKey

public void setForceUpdateOnPrimaryKey(boolean force)

Normally updates and deletes occur using optimistic locking. This forces the use of the primary key only, ignoring any optimistic lock

Parameters:

force - true if updates and deletes should be based on the primary key only.

isForceUpdateOnPrimaryKey

public boolean isForceUpdateOnPrimaryKey()

Determines whether or not updates and deletes use optimistic locking.

Returns:

true if updates and deletes should be based on the primary key only.

isNew

public boolean isNew()

Returns true if the entity is a new entity.

Returns:

true if the entity is a new entity.

setReadOnly

public void setReadOnly(boolean readOnly)

Sets the entity to read only.

Parameters:

readOnly - true if this entity is read only.

isReadOnly

public boolean isReadOnly()

Returns the read only flag.

Returns:

true if this entity is read only.

setValue

public void setValue(java.lang.String name,
                     java.lang.Object value,
                     boolean initial)

Alters the value of the nominated Attribute.

Parameters:

name - the name of the attribute.

value - the new value to be assigned.

initial - true if the initial value is to be altered.

setValue

public void setValue(java.lang.String name,
                     java.lang.Object value)

Alters the value of the nominated Attribute.

Parameters:

name - the name of the attribute.

value - the new value to be assigned.

getValue

public java.lang.Object getValue(java.lang.String name)

Retrieves the value of the specified attribute.

Parameters:

name - the name of the attribute.

Returns:

the value of the attribute, or null if the attribute does not exist.

setValues

public Entity setValues(org.jdom.Element element,
                        boolean initial)

Alters the values of this Entity. The change is NOT automatically reflected in the database. No changes are affected if the entity has been deleted.

Parameters:

element - the Element from an XML document containing the new values for this entity.

initial - true if the values provided are the initial values of the attributes.

Returns:

the modified Entity object.

setValues

public Entity setValues(Entity entity,
                        boolean initial)

Alters the values of this Entity. The change is NOT automatically reflected in the database. No changes are affected if the entity has been deleted.

Parameters:

entity - the Entity containing the new values for this entity.

initial - true if the values provided are the initial values of the attributes.

Returns:

the modified Entity object.

setValues

public Entity setValues(javax.servlet.http.HttpServletRequest request)

Alters the values of this Entity. The change is NOT automatically reflected in the database. No changes are affected if the entity has been deleted.

Parameters:

request - the request object that contains the updated values. The field names returned from the POST or GET must match EXACTLY the column names of the Attributes of this Entity.

Returns:

the modified Entity object.

Throws:

EntityException - if multiple are found in the request for the same attribute.

setValues

public Entity setValues(java.sql.ResultSet resultSet,
                        boolean initial)
                 throws java.sql.SQLException

Alters the values of all attributes of this Entity. The change is NOT automatically reflected in the database. No changes are effected if the entity has been deleted.

Parameters:

resultSet - the result set source of the new attribute values.

initial - true if the values provided are the initial values of the attributes.

Returns:

the modified Entity object.

Throws:

java.sql.SQLException - if any errors occur retrieving the values from the result set.

assignInputFieldValues

public void assignInputFieldValues(TraversableElement container)

Convenience method to assign entity values to Input fields where the name attribute of the Input field matches the attribute name in the entity.

The primary key fields will be set to read-only for an existing Entity, or to mandatory for a new Entity.

Parameters:

container - the Container sub-class which contains the Input fields. It is most effecient to pass in the lowest level container possible (i.e. the Form instance rather than the Paje instance).

assignTagContents

public void assignTagContents(TraversableElement container)

Convenience method to assign entity values as the content in a Container where the ID attribute of a Tag in the Container matches the attribute name in the entity.

Parameters:

container - the Container containing Tags with ID attributes that match the attributes name of the specified Entity.

equals

public boolean equals(java.lang.Object obj)

Indicates whether some other entity is "equal to" this one.

Parameters:

obj - the reference object with which to compare.

Returns:

true if this entity is the same as the obj argument; false otherwise.

hashCode

public int hashCode()

Returns a hash code value for the entity, based on the primary key values.

Returns:

a hash code value for this object.

save

public int save()
         throws java.sql.SQLException

Convenience method to save changes to this entity into the database.

Returns:

the number of rows affected by the save. If the result is 0, any affects of the save will have been rolled back.

Throws:

java.sql.SQLException - if an error occurs accessing the database

save

public int save(java.sql.Connection connection)
         throws java.sql.SQLException

Convenience method to save changes to this entity into the database.

Parameters:

connection - the connection on which the save is to be executed.

Returns:

the number of rows affected by the save.

Throws:

java.sql.SQLException - if an error occurs accessing the database

EntityException - if the entity has been set to read-only.

toString

public java.lang.String toString()

Returns a String representation of this Entity.

Returns:

this entity as a String

toXML

public java.lang.String toXML()

Converts the current values of the entity to a String representation of an XML document.

Returns:

a String of XML

toXML

public java.lang.String toXML(boolean attributes)

Converts the current values of the entity to a String representation of an XML document.

Parameters:

attributes - if true, the attributes properties will be added to each element.

Returns:

a String of XML

toXML

public java.lang.String toXML(boolean attributes,
                              boolean initial)

Converts the entity to a String representation of an XML document.

Parameters:

attributes - if true, the attributes properties will be added to each element.

initial - if true, the values represented in each element will be the initial values of the entity. If false, the current values will be used.

Returns:

a String of XML

toXMLDocument

public org.jdom.Document toXMLDocument()

Converts the current values of the entity to an XML document.

Returns:

an XML Document.

toXMLDocument

public org.jdom.Document toXMLDocument(boolean attributes)

Converts the current values of the entity to an XML document.

Parameters:

attributes - if true, the attributes properties will be added to each element.

Returns:

an XML Document.

toXMLDocument

public org.jdom.Document toXMLDocument(boolean attributes,
                                       boolean initial)

Converts the current values of the entity to an XML document.

Parameters:

attributes - if true, the attributes properties will be added to each element.

initial - if true, the values represented in each element will be the initial values of the entity. If false, the current values will be used.

Returns:

an XML Document.

toXMLElement

public org.jdom.Element toXMLElement(boolean attributes,
                                     boolean initial)

Converts the entity to an XML element.

Parameters:

attributes - if true, the attributes properties will be added to each element.

initial - if true, the values represented in each element will be the initial values of the entity. If false, the current values will be used.

Returns:

an XML Element.

setManager

protected void setManager(Manager manager)

Sets the manager responsible for this entity.

Parameters:

manager - the Manager instance.

setNew

protected Entity setNew(boolean status)

Sets the state of this entity.

Parameters:

status - true if the entity is a new entity, or false if the entity was retrieved from a data source.

Returns:

the modified Entity object.

setValue

protected void setValue(java.lang.String name,
                        java.sql.ResultSet resultSet,
                        int index,
                        int type,
                        boolean initial)
                 throws java.sql.SQLException

Alters the value of the specified attribute of this Entity. The change is NOT automatically reflected in the database.

Parameters:

name - the name of the attribute.

resultSet - the result set source of the value.

index - the index of the column value in the current ResultSet row.

type - the SQL data type of the specified column in the current ResultSet row.

initial - true if the value provided is the initial value of the attribute.

Throws:

java.sql.SQLException - if any errors occur retrieving the value from the result set.

getValues

protected java.util.HashMap getValues()

Retrieves the entity's values as a HashMap, where the key is the attribute name and the value is the Value object.

Returns:

the values of the entity.

valueChanged

protected void valueChanged(Value value)

Receives notification from a Value when it's value has been changed.

Sub-classes should over-ride this method to perform any attribute-specific processing when it's value changes. The default implementation does nothing.

Parameters:

value - Description of Parameter