org.hydrateframework
Interface HydrateObject

All Known Implementing Classes:

AbstractHydrateObject

public interface HydrateObject

This is an optional base interface for Hydrate objects and specifies a set of services that need to be supported by an object to fully operate as part of the hydrate framework. Objects that are part of the model are not required to support this interface and business interfaces that represent the data model must not inherit from this interface. The code will test to see if an object it has been asked to use supports the interface and if not it will be proxied into doing so. You are however encouraged to use the code generated objects, all of which do support this interface since the framework will operate more efficiently with these objects. Supporting the interface directly avoids the overhead of having to create a proxy for each object when it is used by the framework. The methods on this base interface fall into three categories: those that store 'shadow' information about the object such as whether it has been persisted to a database, those that present functionality that is available elsewhere in a more efficient or convenient manner, such as methods to retrieve keys, determine whether attributes are populated or update attributes by name, and those that are part of the persistence framework, such as 'save' or 'writeAttributesXML'.

Version:

@(#)$Revision: 1.3 $

Author:

David Chamberlin

Field Summary

static int	ATTR_MANDATORY
static int	ATTR_MULTIPLE
static int	ATTR_MULTIPLEOPTIONAL
static int	ATTR_NONE
static int	ATTR_OPTIONAL
static short	saveALL
static short	savePOST
static short	savePRE
static short	STATECHANGED
static short	STATEPOSTSAVE
static short	STATEPRESAVE
static short	STATEUNCHANGED
static short	STATEUPDATING

Method Summary

int	attributeType(java.lang.String localName) Determine if a particular string represents the name of a valid attribute.
void	forget() Discard this object.
ObjectContext	getContext()
java.lang.String	getDiscriminator()
java.lang.Class	getFamily() Gets the family class associated with this object.
java.lang.Class	getImplementedIfc() Each business object concrete class implements a particular business object interface.
ObjectKey	getKey(java.lang.Class keyCls)
boolean	isChanged()
boolean	isFieldPopulated(java.lang.String id) This call can be used to determine if a field is populated and presents an alternative to catching the NotPopulatedException that is thrown when accessing such fields
boolean	isPersisted() Determine if the object is persisted in the database.
boolean	isPreSaving()
boolean	isRemoved() Determine if a request has been made to remove the object from the database
boolean	isUpdating()
void	mergeDown(java.lang.Object object) Merge the given object into this object.
void	save(SaveContext ctx) This method is called by users of this business object to persist it in a persistent store.
void	save(SaveContext ctx, short saveType) This method should be overridden in derived classes to save this object in a persistent store.
void	setAttrFromString(java.lang.String localName, java.lang.String data) Set an attribute from a string representation of the attribute.
void	setClean() Set the object to a 'clean' state.
void	setContext(ObjectContext ctx) Set the object context associated with the object
void	setDirty() Set the object to a 'dirty' state.
void	setNotPersisted() Call this method to indicate that the object has not been persisted in a database.
void	setPersisted() Call this method to indicate that the object has been persisted in a database.
void	setPostSaving() Set the object to a state indicating that it is finishing the update process on an object
void	setPreSaving() Set the object to a state indicating that it has been partially updated
void	setRemoved(boolean removed) Mark this object as having been deleted from the database.
void	writeAttributesXML(XMLElementWriterParser writerParser, java.lang.String prefix, java.lang.String[] failIfNotPop, java.lang.String[] excludeAttrs) Write all attributes to an XML stream

Field Detail

STATEUNCHANGED

static final short STATEUNCHANGED

See Also:

Constant Field Values

STATECHANGED

static final short STATECHANGED

See Also:

Constant Field Values

STATEUPDATING

static final short STATEUPDATING

See Also:

Constant Field Values

STATEPRESAVE

static final short STATEPRESAVE

See Also:

Constant Field Values

STATEPOSTSAVE

static final short STATEPOSTSAVE

See Also:

Constant Field Values

saveALL

static final short saveALL

See Also:

Constant Field Values

savePRE

static final short savePRE

See Also:

Constant Field Values

savePOST

static final short savePOST

See Also:

Constant Field Values

ATTR_NONE

static final int ATTR_NONE

See Also:

Constant Field Values

ATTR_MANDATORY

static final int ATTR_MANDATORY

See Also:

Constant Field Values

ATTR_OPTIONAL

static final int ATTR_OPTIONAL

See Also:

Constant Field Values

ATTR_MULTIPLE

static final int ATTR_MULTIPLE

See Also:

Constant Field Values

ATTR_MULTIPLEOPTIONAL

static final int ATTR_MULTIPLEOPTIONAL

See Also:

Constant Field Values

Method Detail

isChanged

boolean isChanged()

Returns:

true if the object has changed (or has not yet been added to the database).

isUpdating

boolean isUpdating()

Returns:

true if the object is currently updating

isPreSaving

boolean isPreSaving()

Returns:

true if the object has been partially updated. This will occur when an object is updated by virtue of a dependency on another object.

setPreSaving

void setPreSaving()

Set the object to a state indicating that it has been partially updated

setPostSaving

void setPostSaving()

Set the object to a state indicating that it is finishing the update process on an object

setClean

void setClean()

Set the object to a 'clean' state. isChanged will subsequently return false unless the object is not in the database. isUpdating will subsequently return false.

setDirty

void setDirty()

Set the object to a 'dirty' state. isChanged will subsequently return true.

isFieldPopulated

boolean isFieldPopulated(java.lang.String id)

This call can be used to determine if a field is populated and presents an alternative to catching the NotPopulatedException that is thrown when accessing such fields

save

void save(SaveContext ctx)
          throws SaveException

This method is called by users of this business object to persist it in a persistent store. The call will also save any dependent objects (ie. any that are navigable from this object) that have changed.

Throws:

SaveException

save

void save(SaveContext ctx,
          short saveType)
          throws SaveException

This method should be overridden in derived classes to save this object in a persistent store. The call should also save any dependent objects (ie. any that are navigable from this object) that have changed.

Parameters:

saveType - determines how much of the object to save. This is needed when business objects are recursively saving business objects that they contain or reference. It is important to defer the saving of all many-to-many and one-to-many relationships to the end of the save process. The valid values are saveALL to save the entire object, savePRE to save many-to-one relationships and the object itself - these relationships must be saved before the main object cos it will need primary keys for the referenced objects. savePOST saves one-to-many and many-to-many relationships and marks the object as clean.

Throws:

SaveException

writeAttributesXML

void writeAttributesXML(XMLElementWriterParser writerParser,
                        java.lang.String prefix,
                        java.lang.String[] failIfNotPop,
                        java.lang.String[] excludeAttrs)
                        throws org.xml.sax.SAXException

Write all attributes to an XML stream

Parameters:

writerParser - the writer parser that has information about the stream being written to.

prefix - a text prefix if the elements are being flattened

failIfNotPop - true to fail the write (with a SAX exception) if one or more attributes are not populated

excludeAttrs - a list of field names to be excluded

Throws:

org.xml.sax.SAXException

attributeType

int attributeType(java.lang.String localName)

Determine if a particular string represents the name of a valid attribute.

Parameters:

localName - the name of the attribute

Returns:

ATTR_MANDATORY if the parameter is a mandatory attribute, ATTR_OPTIONAL for an optional attribute and ATTR_NONE for an invalid attribute name

setAttrFromString

void setAttrFromString(java.lang.String localName,
                       java.lang.String data)

Set an attribute from a string representation of the attribute.

Parameters:

localName - the name of the attribute

data - the string data to be parsed or null if the value is to be set to 'Not Set'

forget

void forget()

Discard this object. This causes references to the object to be removed and makes the object a candidate for garbage collection.

getKey

ObjectKey getKey(java.lang.Class keyCls)

Returns:

the named key of this object - if keyName is null then return the primary key.

getDiscriminator

java.lang.String getDiscriminator()

Returns:

a short string (< 4 characters) that uniquely defines this class.

setPersisted

void setPersisted()

Call this method to indicate that the object has been persisted in a database.

setNotPersisted

void setNotPersisted()

Call this method to indicate that the object has not been persisted in a database.

isPersisted

boolean isPersisted()

Determine if the object is persisted in the database.

Returns:

true if the object is persisted.

getContext

ObjectContext getContext()

Returns:

the business object context associated with this object

setContext

void setContext(ObjectContext ctx)

Set the object context associated with the object

Parameters:

ctx - the new context

getImplementedIfc

java.lang.Class getImplementedIfc()

Each business object concrete class implements a particular business object interface. This function must return that interface. Note that this is not necessarily the same as the object's key's key class this.getKey().getKeyClass() since the key class is always the base business class and this method returns the actual interface that is being implemented.

Returns:

the implemented interface

getFamily

java.lang.Class getFamily()

Gets the family class associated with this object.

Returns:

the family class used to initialize an object context.

mergeDown

void mergeDown(java.lang.Object object)

Merge the given object into this object. The objects must be of compatible types.

Parameters:

object - the object to merge.

setRemoved

void setRemoved(boolean removed)

Mark this object as having been deleted from the database. When it is saved down to the database, the data corresponding to it will be removed there.

isRemoved

boolean isRemoved()

Determine if a request has been made to remove the object from the database