uk.ac.ed.epcc.webapp.model.data

Class DataObject

java.lang.Object

uk.ac.ed.epcc.webapp.model.data.DataObject

All Implemented Interfaces:

Contexed, ContextIndexed, Identified, Indexed, Releasable

Direct Known Subclasses:

AbstractRequestFactory.AbstractRequest, AbstractUserSettingFactory.UserSetting, AppUser, BadKeyFactory.BadKey, Classification, DataObjectDataProducer.MimeData, FileData, HistoryFactory.HistoryRecord, IndexedLinkManager.Link, LogFactory.Entry, MessageDataObject, MultiLinkManager.MultiLink, MultiNameFactory.Name, PartConfigFactory.Config, PartOwner, Property, ResponseManager.Response, TextData, TextFileOverlay.TextFile, WtmpManager.Wtmp

public abstract class DataObject
extends java.lang.Object
implements ContextIndexed, Identified, Releasable

DataObject is the application facing view of a row in a database table.

This class is sub-classed to create objects corresponding to particular tables. Essentially this class is implemented as a wrapper round the Repository.Record class. Where Repository.Record accesses database fields as named properties a DataObject subclass will typically provide conventional get and set methods. Sub-classes should implement these methods by calling record.setProperty/record.get(Type)Property.

The primary constructor is one that takes a Record Unless the objects are only to be created from the appropriate factory sub-classes need constructors that create new records or retrieve existing ones. DataObject contains several protected static methods returning Record that can be used to implement these.

In most cases there is a one to one correspondance between a Java class and a SQL table. In these cases the table name can be hardwired into the constructors. In a few cases we may want multiple tables to map to the same class. In this case the constructors that specify the table name must be used or the objects should only be created via a factory.

Though it is possible to refer to DataObjects via their integer handle this should be done sparingly. Any method call that takes an integer handle as a parameter is intrinsically less type safe then one that takes a reference to the appropriate object. The IndexedReference class exists to implement type-safe lightweight references to objects (like DataObject) that implement Indexed

Most sub-classes will also override the getIdentifier() method. This generates a unique text identifier for the DataObject. This is used in pull down menus etc. so typically should reflect the end users concept of an objects name.

Field Summary

Fields

Modifier and Type	Field and Description
protected static boolean	DEBUG
Repository.Record	record All the fields for this record.

Fields inherited from interface uk.ac.ed.epcc.webapp.forms.Identified

MAX_IDENTIFIER

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DataObject(Repository.Record r) create an object using an existing Record this is for use within the Factory class when a factory may return different sub-types.

Method Summary

Modifier and Type	Method and Description
static java.util.Map<java.lang.String,java.lang.Object>	addToMap(java.util.Map<java.lang.String,java.lang.Object> table, java.util.Map<java.lang.String,java.lang.Object> values) Utility routine to merge 2 Hashtables
static java.util.Map<java.lang.String,java.lang.Object>	addToMap(java.util.Map<java.lang.String,java.lang.Object> table, java.lang.Object[][] values) A utility method for putting values into hashtables in the constructors
static java.util.Map<java.lang.String,java.lang.Object>	addToMap(java.util.Map<java.lang.String,java.lang.Object> table, java.lang.String name, java.lang.Object value) A utility method for putting values into hashtables in the constructors only modifies table if key not already in use.
boolean	commit() Writes any changed values back to the database.
boolean	delete() Used to remove the data from the database - USE WITH CAUTION! In particular deleting records from within an iterator may throw off record chunking.
static boolean	empty(java.lang.String input)
boolean	equals(java.lang.Object o)
void	formUpdate(Form f) update this DataObject based on Form fields.
AppContext	getContext() Get the application context used to create this object.
protected DatabaseService	getDatabaseService()
protected java.lang.String	getFactoryTag()
int	getID() Returns the unique ID for this particular object.
java.lang.String	getIdentifier() produce a unique identifying string for this object for use in forms and pull-down menus and charts.
java.lang.String	getIdentifier(int max_length) Generate Identifier with advisory max length.
protected Logger	getLogger()
java.util.Map<java.lang.String,java.lang.Object>	getMap() create Hashtable of contents of Object
java.util.Map<java.lang.String,java.lang.Object>	getMap(boolean include_null)
static <D extends DataObject> DataObjectFactory<D>	getOwningFactory(D obj) A static method to locate the DataObjectFactory used to create a DataObject This will be necessary when behaviour added as Composites is required but only the DataObject is available.
protected static Repository.Record	getRecord(AppContext ctx, java.lang.String table) Helper method for subclass constructors.
protected static Repository.Record	getRecord(AppContext c, java.lang.String table, int id)
protected static Repository.Record	getRecord(AppContext ctx, java.lang.String table, java.util.Map<java.lang.String,java.lang.Object> values) Helper method for use in Subclass constructors.
protected SQLContext	getSQLContext()
protected java.lang.String	getUniqueIdName() Returns the field name for the unique ID field.
int	hashCode()
protected boolean	isLocked()
protected void	lock() Lock record so it is unmodifiable.
protected void	post_commit(boolean changed) Extension point called at end of commit
protected void	postCreate() extension point to allow sub-classes to add additional setup after an object has been created from a creation form.
protected void	pre_commit(boolean dirty) Extension point called at start of commit.
void	release() This is used like a destructor - means less connections, etc lying around This will also clear the record from the Repository cache if this is enabled
void	setContents(java.util.Map<java.lang.String,java.lang.Object> m) update multiple fields at once using a Map
protected void	setDirty(java.lang.String key, boolean value)
void	setMap(java.util.Map<java.lang.String,java.lang.Object> h) Use Hashtable to update Object.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

DEBUG

protected static final boolean DEBUG

See Also:

Constant Field Values

record

public Repository.Record record

All the fields for this record.

Constructor Detail

DataObject

protected DataObject(Repository.Record r)

create an object using an existing Record this is for use within the Factory class when a factory may return different sub-types.

Parameters:

r -

Method Detail

getRecord

protected static Repository.Record getRecord(AppContext ctx,
                                             java.lang.String table)
                                      throws ConsistencyError

Helper method for subclass constructors. Creates an empty Record.

Parameters:

ctx -

table -

Returns:

uncommitted empty Record

Throws:

ConsistencyError

getRecord

protected static Repository.Record getRecord(AppContext ctx,
                                             java.lang.String table,
                                             java.util.Map<java.lang.String,java.lang.Object> values)
                                      throws ConsistencyError,
                                             DataFault

Helper method for use in Subclass constructors. Make a new object from scratch. The hashtable contains the initial data for the object. It is entirely legal to add additional fields that are not represented in the database. These will simply be ignored. Note that this mechanism only works for pre-existing tables. Use methods on a factory class rather than explicit constructors if you need automatic table creation.

Parameters:

ctx -

values -

Throws:

ConsistencyError

DataFault

getRecord

protected static Repository.Record getRecord(AppContext c,
                                             java.lang.String table,
                                             int id)
                                      throws DataException

Throws:

DataException

commit

public final boolean commit()
                     throws DataFault

Writes any changed values back to the database. Only values actually changed are written.

Returns:

boolean true if changed

Throws:

DataFault

pre_commit

protected void pre_commit(boolean dirty)
                   throws DataFault

Extension point called at start of commit. It is legal to change the record in this call

Parameters:

dirty - is record known to be modified.

Throws:

DataFault

post_commit

protected void post_commit(boolean changed)
                    throws DataFault

Extension point called at end of commit

Parameters:

changed - record was changed by commit.

Throws:

DataFault

delete

public boolean delete()
               throws DataFault

Used to remove the data from the database - USE WITH CAUTION! In particular deleting records from within an iterator may throw off record chunking. Instead the object should implement Removable and be removed from iterator (which will recursively call delete).

Returns:

true if the object was successfully deleted.

Throws:

DataFault

equals

public final boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

formUpdate

public void formUpdate(Form f)

update this DataObject based on Form fields. fields not in both the form and the Object are ignored.

Parameters:

f - Form to use

getSQLContext

protected final SQLContext getSQLContext()
                                  throws java.sql.SQLException

Throws:

java.sql.SQLException

getDatabaseService

protected final DatabaseService getDatabaseService()

Returns:

getContext

public final AppContext getContext()

Get the application context used to create this object.

Specified by:

getContext in interface Contexed

Returns:

AppContext used to create object

getMap

public final java.util.Map<java.lang.String,java.lang.Object> getMap()

create Hashtable of contents of Object

Returns:

Hashtable

getMap

public final java.util.Map<java.lang.String,java.lang.Object> getMap(boolean include_null)

getID

public final int getID()

Returns the unique ID for this particular object.

Specified by:

getID in interface Indexed

Returns:

int the ID number

getIdentifier

public java.lang.String getIdentifier(int max_length)

Description copied from interface: Identified

Generate Identifier with advisory max length.

Specified by:

getIdentifier in interface Identified

Parameters:

max_length - advisory max length

Returns:

String identifier

getIdentifier

public final java.lang.String getIdentifier()

Description copied from interface: Identified

produce a unique identifying string for this object for use in forms and pull-down menus and charts. The string should be kept shorter than MAX_IDENTIFIER if at all possible. This defaults to the ID number for the object but classes should override this with something more sensible.

Specified by:

getIdentifier in interface Identified

Returns:

String

getLogger

protected Logger getLogger()

getFactoryTag

protected final java.lang.String getFactoryTag()

getUniqueIdName

protected final java.lang.String getUniqueIdName()

Returns the field name for the unique ID field.

Returns:

String of the unique ID name

hashCode

public final int hashCode()

Overrides:

hashCode in class java.lang.Object

postCreate

protected final void postCreate()

extension point to allow sub-classes to add additional setup after an object has been created from a creation form.

release

public void release()

This is used like a destructor - means less connections, etc lying around This will also clear the record from the Repository cache if this is enabled

Specified by:

release in interface Releasable

lock

protected void lock()
             throws DataFault

Lock record so it is unmodifiable. This is intended for when DataObjects are being cached to reduce risk

Throws:

DataFault

isLocked

protected boolean isLocked()

setContents

public final void setContents(java.util.Map<java.lang.String,java.lang.Object> m)

update multiple fields at once using a Map

Parameters:

m - Map containing update

setDirty

protected void setDirty(java.lang.String key,
                        boolean value)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

setMap

public final void setMap(java.util.Map<java.lang.String,java.lang.Object> h)

Use Hashtable to update Object. does not check for unchanged fields unforunatly. missing fields are removed

Parameters:

h -

addToMap

public static java.util.Map<java.lang.String,java.lang.Object> addToMap(java.util.Map<java.lang.String,java.lang.Object> table,
                                                                        java.util.Map<java.lang.String,java.lang.Object> values)

Utility routine to merge 2 Hashtables

Parameters:

table - Primary table to be modified

values - additional table to be merged values here never overwrite

Returns:

reference to table.

addToMap

public static java.util.Map<java.lang.String,java.lang.Object> addToMap(java.util.Map<java.lang.String,java.lang.Object> table,
                                                                        java.lang.Object[][] values)

A utility method for putting values into hashtables in the constructors

Parameters:

table -

values - array of key value pairs to be added if not already defined

Returns:

Hashtable

addToMap

public static java.util.Map<java.lang.String,java.lang.Object> addToMap(java.util.Map<java.lang.String,java.lang.Object> table,
                                                                        java.lang.String name,
                                                                        java.lang.Object value)

A utility method for putting values into hashtables in the constructors only modifies table if key not already in use.

Parameters:

table - original Hashtable

name - key to use

value - added

Returns:

Hashtable

empty

public static boolean empty(java.lang.String input)

getOwningFactory

public static <D extends DataObject> DataObjectFactory<D> getOwningFactory(D obj)

A static method to locate the DataObjectFactory used to create a DataObject This will be necessary when behaviour added as Composites is required but only the DataObject is available.

Parameters:

conn -

obj -

Returns: