org.melati.poem
Interface Persistent

All Superinterfaces:

Persistable, Treeable

All Known Implementing Classes:

Capability, CapabilityBase, Category, CategoryBase, Child, ChildBase, ColumnInfo, ColumnInfoBase, Contact, ContactBase, ContactCategory, ContactCategoryBase, Group, GroupBase, GroupCapability, GroupCapabilityBase, GroupMembership, GroupMembershipBase, JdbcPersistent, Parent, ParentBase, Setting, SettingBase, TableCategory, TableCategoryBase, TableInfo, TableInfoBase, User, UserBase, ValueInfo, ValueInfoBase

public interface Persistent
extends Persistable, Treeable

The object representing a single table row; this is the PO in POEM!

Instances are also used to represent selection criteria.

Since:

4 Jul 2007

Author:

timp

Method Summary

void	assertCanCreate()
void	assertCanCreate(AccessToken token) Check that you have create access to the object.
void	assertCanDelete()
void	assertCanDelete(AccessToken token) Check that you have delete access to the object.
void	assertCanRead()
void	assertCanRead(AccessToken token) Check that you have read access to the object.
void	assertCanWrite()
void	assertCanWrite(AccessToken token) Check that you have write access to the object.
void	delete_unsafe() Delete without access checks.
void	delete() Delete this persistent, with default integrity checks, ie disallow deletion if object referred to by others.
void	delete(Map<Column,IntegrityFix> integrityFixOfColumn) Delete the object.
void	deleteAndCommit() Convenience method with default integrity fix.
void	deleteAndCommit(Map<Column,IntegrityFix> integrityFixOfColumn) Delete the object, with even more safety checks for referential integrity.
String	displayString()
String	displayString(PoemLocale locale) Defaults to DateFormat.MEDIUM.
String	displayString(PoemLocale locale, int style) A string describing the object for the purposes of rendering it in lists presented to the user.
String	dump()
void	dump(PrintStream p) Dump to a PrintStream.
Persistent	duplicated() Create a new object like this one.
Persistent	duplicatedFloating() Create a new persistent like this one, regardless of whether this Persistent has been written to the dbms yet.
void	existenceLock() Lock without actually reading.
Enumeration<Field>	fieldsOfColumns(Enumeration<Column> columns) Create Fields from Columns.
Object	getCooked(String name) The `true value' of one of the object's fields.
String	getCookedString(String name, PoemLocale locale, int style) A string representation of the `true value' of one of the object's fields.
Database	getDatabase()
Enumeration<Field>	getDetailDisplayFields() All fields at the detailed display level in display order.
Field	getField(String name) The value of one of the object's fields, wrapped up with type information sufficient for rendering it.
Enumeration<Field>	getFields() The values of all the object's fields, wrapped up with type information sufficient for rendering them.
Field	getPrimaryDisplayField()
Object	getRaw(String name) The `identifying value' of one of the object's fields.
String	getRawString(String name) A string representation of the `identifying value' of one of the object's fields.
boolean	getReadable()
Enumeration<Field>	getRecordDisplayFields() The values of all the object's fields designated for inclusion in full record displays, wrapped up with type information sufficient for rendering them.
Enumeration<Field>	getSearchCriterionFields()
Enumeration<Field>	getSummaryDisplayFields() All fields at the summary display level in display order.
Table	getTable() The Table from which the object comes, complete with metadata.
boolean	isDirty()
void	makePersistent() A convenience method to create this Persistent.
void	postEdit(boolean creating) Optionally called after this instance is edited by a user.
void	postInsert() Called after this persistent is written to the database for the first time.
void	postModify() Called after this persistent is updated and written to the database replacing the existing record it represents.
void	postWrite() Called after this persistent is written to the database on being inserted or modified.
void	preEdit() Optionally called before an instance is edited by the user.
void	setCooked(String name, Object cooked) Set the `true value' of one of the record's fields.
void	setDirty(boolean dirty)
void	setRaw(String name, Object raw) Set the `identifying value' of one of the record's fields.
void	setRawString(String name, String string) Set the `identifying value' of one of the record's fields from a string representation.
boolean	statusExistent()
boolean	statusNonexistent()

Methods inherited from interface org.melati.poem.Persistable

getTroid, troid

Methods inherited from interface org.melati.poem.Treeable

getChildren, getName

Method Detail

statusNonexistent

boolean statusNonexistent()

Returns:

whether this object has been persisted

statusExistent

boolean statusExistent()

Returns:

whether this object has been deleted

makePersistent

void makePersistent()

A convenience method to create this Persistent.

getTable

Table getTable()

The Table from which the object comes, complete with metadata.

Returns:

the Table

getDatabase

Database getDatabase()

Returns:

The database from which the object comes. I.e. getTable().getDatabase().

existenceLock

void existenceLock()

Lock without actually reading.

assertCanRead

void assertCanRead(AccessToken token)
                   throws AccessPoemException

Check that you have read access to the object. Which is to say: the AccessToken associated with the POEM task executing in the running thread confers the Capability required for inspecting the object's fields. The access token is set when the task is invoked using Database.inSession. The capability is determined by getCanRead, which by default means the capability defined in the record's canread field in the database. If that's null, the table's default canread capability is obtained using getTable().getDefaultCanRead(). If that is null as well, access is granted unconditionally.

Although this check can in theory be quite time-consuming, in practice this isn't a problem, because the most recent access token for which the check succeeded is cached; repeat accesses from within the same transaction are therefore quick.

Application programmers can override this method to implement their own programmatic access policies. For instance, POEM's own TableInfo class overrides it with an empty method in order to disable all read protection on TableInfo objects. More interestingly, you could implement a check that depends on the values of the object's fields: for example, you could allow read access to an invoice record to its issuing and receiving parties.

Parameters:

token - the access token on the basis of which readability is being claimed

Throws:

AccessPoemException - if the check fails

See Also:

Database.inSession(org.melati.poem.AccessToken, org.melati.poem.PoemTask), JdbcTable.getDefaultCanRead()

assertCanRead

void assertCanRead()
                   throws AccessPoemException

Throws:

AccessPoemException - if current accessToken does not grant read capability

getReadable

boolean getReadable()

Returns:

Whether the object is readable by current AccessToken

See Also:

assertCanRead()

assertCanWrite

void assertCanWrite(AccessToken token)
                    throws AccessPoemException

Check that you have write access to the object. Which is to say: the AccessToken associated with the POEM task executing in the running thread confers the Capability required for updating the object's fields. The remarks made about assertCanRead apply (mutatis mutandis) here as well.

Throws:

AccessPoemException

See Also:

assertCanRead(), JdbcTable.getDefaultCanWrite()

assertCanWrite

void assertCanWrite()
                    throws AccessPoemException

Throws:

AccessPoemException - if current accessToken does not grant wraite capability

assertCanDelete

void assertCanDelete(AccessToken token)
                     throws AccessPoemException

Check that you have delete access to the object. Which is to say: the AccessToken associated with the POEM task executing in the running thread confers the Capability required for updating the object's fields. The remarks made about assertCanRead apply (mutatis mutandis) here as well.

Throws:

AccessPoemException

See Also:

assertCanRead(), JdbcTable.getDefaultCanDelete()

assertCanDelete

void assertCanDelete()
                     throws AccessPoemException

Throws:

AccessPoemException - if current accessToken does not grant delete capability

assertCanCreate

void assertCanCreate(AccessToken token)

Check that you have create access to the object. Which is to say: the AccessToken associated with the POEM task executing in the running thread confers the Capability required for creating the object. The capability is determined solely by getCanCreate from the table. Unlike assertCanRead and assertCanWrite there is no idea of having a default Capability defined in the table which could be overridden by a canwrite field in the persistent (since the persistent has not yet been been written).

Application programmers can override this method to implement their own programmatic access policies.

See Also:

assertCanRead(), assertCanWrite(), JdbcTable.getCanCreate()

assertCanCreate

void assertCanCreate()
                     throws AccessPoemException

Throws:

AccessPoemException - if current accessToken does not grant create capability

getRaw

Object getRaw(String name)
              throws NoSuchColumnPoemException,
                     AccessPoemException

The `identifying value' of one of the object's fields. This is the value which is actually stored in the database, given to you as a basic Java type; currently, the only fields for which this differs from the `true value' returned from getCooked are reference fields with type ReferencePoemType.

If the field baz is defined in the DSD as part of a table called foo, then the table's records will be represented by an application-specialised subclass of Persistent called Foo which provides a typed getBaz method. So the easiest way to be sure of your types is to predeclare any fields you use in the DSD, use the typed field-access methods, and let the compiler take the strain. When working with generic Persistents, you probably want to use getField.

The value returned is relative to the transaction associated with the calling thread, as set up by Database.inSession. This means that you never see the value of a field change in your transaction because of another transaction's activities, unless you do a PoemThread.commit() or a PoemThread.rollback(). If you need to, you can store a Persistent in a permanent data structure and access it in different sessions over time---or even from concurrently running sessions, though this may slow down access checking; each transaction will see the value it expects.

Parameters:

name - the name of the field (i.e. the name of the column in the RDBMS and DSD)

Returns:

The field's `identifying value'; this will be a String, Boolean, Integer, Double or Date as appropriate. If the field is a reference field, the result is an Integer giving the troid of the referee. If you want references to be resolved transparently to Persistents, use getCooked. If you want a string representation of the field, use getRawString or getCookedString.

Throws:

NoSuchColumnPoemException - if the field named doesn't exist

AccessPoemException - if the calling thread doesn't have read access to the object (see assertCanRead)

See Also:

getCooked(java.lang.String), getRawString(java.lang.String), getCookedString(java.lang.String, org.melati.poem.PoemLocale, int), getField(java.lang.String), Database.inSession(org.melati.poem.AccessToken, org.melati.poem.PoemTask), PoemThread.commit(), PoemThread.rollback(), assertCanRead()

getRawString

String getRawString(String name)
                    throws AccessPoemException,
                           NoSuchColumnPoemException

A string representation of the `identifying value' of one of the object's fields. The value returned is relative to the transaction associated with the calling thread, as set up by Database.inSession: see the remarks made about getRaw.

Parameters:

name - the name of the field (i.e. the name of the column in the RDBMS and DSD)

Returns:

Roughly, the string the underlying RDBMS would display if asked to show the field's value. If you want reference fields to be represented by their referee's displayString() (by default, its primary display field) rather than by its troid, use getCookedString. If you want the field's value as an appropriate Java type like Integer, use getRaw or getCooked---or an equivalent, but type-safe, method derived from the DSD.

Throws:

NoSuchColumnPoemException - if the field named doesn't exist

AccessPoemException - if the calling thread doesn't have read access to the object (see assertCanRead)

See Also:

getCookedString(java.lang.String, org.melati.poem.PoemLocale, int), getRaw(java.lang.String), getCooked(java.lang.String), assertCanRead()

setRaw

void setRaw(String name,
            Object raw)
            throws NoSuchColumnPoemException,
                   AccessPoemException,
                   ValidationPoemException

Set the `identifying value' of one of the record's fields. This is the value which is actually stored in the database, given by you as a basic Java type; currently, the only fields for which this differs from the `true value' expected by setCooked are reference fields with type ReferencePoemType.

If the field baz is defined in the DSD as part of a table called foo, then the table's records will be represented by an application-specialised subclass of Persistent called Foo which provides a typed setBaz method. So the easiest way to be sure of your types is to predeclare any fields you use in the DSD, use the typed field-access methods, and let the compiler take the strain. When working with generic Persistents, you probably mean setRawString anyway.

The change you make to the field's value will only be visible to the calling thread, until it successfully completes the task started by Database.inSession, or does an explicit PoemThread.commit(). Up to that point the change can be undone by calling PoemThread.rollback(), and will be undone automatically if the task terminates with an uncaught exception.

In fact, your changes are not written down to the database, even relative to an uncommitted transaction, until it's actually necessary. So multiple calls to setRaw and relatives will not cause multiple SQL UPDATEs to be issued.

Parameters:

name - the name of the field (i.e. the name of the column in the RDBMS and DSD)

raw - The new value for the field: a String, Boolean, Integer, Double or Date as appropriate. If the field is a reference field: an Integer giving the troid of the referee. If you want to pass referees as actual Persistents, use setCooked. If you want to set the field from a string representation (e.g. typed in by the user), use setRawString.

Throws:

NoSuchColumnPoemException - if the field named doesn't exist

AccessPoemException - if the calling thread doesn't have write access to the object (see assertCanWrite)

ValidationPoemException - if raw is not a valid value for the field (e.g. a string is too long)

See Also:

setCooked(java.lang.String, java.lang.Object), setRawString(java.lang.String, java.lang.String), assertCanWrite(), Database.inSession(org.melati.poem.AccessToken, org.melati.poem.PoemTask), PoemThread.commit(), PoemThread.rollback()

setRawString

void setRawString(String name,
                  String string)
                  throws NoSuchColumnPoemException,
                         AccessPoemException,
                         ParsingPoemException,
                         ValidationPoemException

Set the `identifying value' of one of the record's fields from a string representation. The remarks about sessions (transactions) and DSD-derived type-safe methods made for setRaw apply here too.

Parameters:

name - the name of the field (i.e. the name of the column in the RDBMS and DSD)

string - A string that will be parsed to obtain the new value for the field. If it's a reference field, this should be a decimal representation of the referee's troid. If you want to set fields to values defined by appropriate Java types, use setRaw or setCooked.

Throws:

NoSuchColumnPoemException - if the field named doesn't exist

AccessPoemException - if the calling thread doesn't have write access to the object (see assertCanWrite)

ParsingPoemException - if string doesn't parse as a value of the appropriate type

ValidationPoemException - if string parses to an invalid value for the field (e.g. it's too wide)

See Also:

setRaw(java.lang.String, java.lang.Object), setCooked(java.lang.String, java.lang.Object), assertCanWrite()

getCooked

Object getCooked(String name)
                 throws NoSuchColumnPoemException,
                        AccessPoemException

The `true value' of one of the object's fields. This is the fully-interpreted value rather than the one actually stored in the database; currently, the only fields for which this differs from the `identifying value' return from getRaw are reference fields with type ReferencePoemType.

The value returned is relative to the transaction associated with the calling thread, as set up by Database.inSession: see the remarks made about getRaw.

The easiest way to be sure of your types is to predeclare any fields you use in the DSD, or use getField. Again, see the remarks made about getRaw.

Returns:

The field's `true value'; this will be a String, Boolean, Integer, Double, Date, or, if the field is a reference field, a Persistent representing the referee. If you just want to see referees' troids, use getRaw. If you want a string representation of the field, use getRawString or getCookedString.

Throws:

NoSuchColumnPoemException - if the field named doesn't exist

AccessPoemException - if the calling thread doesn't have read access to the object (see assertCanRead)

See Also:

getRaw(java.lang.String), getRawString(java.lang.String), getCookedString(java.lang.String, org.melati.poem.PoemLocale, int), getField(java.lang.String), assertCanRead()

getCookedString

String getCookedString(String name,
                       PoemLocale locale,
                       int style)
                       throws NoSuchColumnPoemException,
                              AccessPoemException

A string representation of the `true value' of one of the object's fields. For example the return value for the user table's category field would be User. The value returned is relative to the transaction associated with the calling thread, as set up by Database.inSession: see the remarks made about getRaw.

Parameters:

name - the name of the field (i.e. the name of the column in the RDBMS and DSD)

locale - A PoemLocale eg PoemLocale.HERE

style - A date format

Returns:

The string the underlying RDBMS would display if asked to show the field's value, except that reference fields are represented by their referee's displayString() (by default, its primary display field) rather than by its troid. If you want to see troids instead, use getRawString. If you want the field's value as an appropriate Java type like Integer, use getRaw or getCooked---or an equivalent, but type-safe, method derived from the DSD.

Throws:

NoSuchColumnPoemException - if the field named doesn't exist

AccessPoemException - if the calling thread doesn't have read access to the object (see assertCanRead)

See Also:

getRawString(java.lang.String), getRaw(java.lang.String), getCooked(java.lang.String), assertCanRead(), displayString(org.melati.poem.PoemLocale, int)

setCooked

void setCooked(String name,
               Object cooked)
               throws NoSuchColumnPoemException,
                      ValidationPoemException,
                      AccessPoemException

Set the `true value' of one of the record's fields. Like setRaw, but reference fields expect to see a Persistent representing their new referee rather than an Integer specifying its troid. The remarks about sessions (transactions) and DSD-derived type-safe methods made for setRaw apply here too.

Parameters:

name - the name of the field (i.e. the name of the column in the RDBMS and DSD)

cooked - the new value for the field: a String, Boolean, Integer, Double, Date or, for a reference field, a Persistent. If you want to pass referees as troids, use setRaw. If you want to set the field from a string representation (e.g. typed in by the user), use setRawString.

Throws:

NoSuchColumnPoemException - if the field named doesn't exist

AccessPoemException - if the calling thread doesn't have write access to the object (see assertCanWrite)

ValidationPoemException - if cooked is not a valid value for the field (e.g. a string is too long)

See Also:

setRaw(java.lang.String, java.lang.Object), setRawString(java.lang.String, java.lang.String), assertCanWrite()

getField

Field getField(String name)
               throws NoSuchColumnPoemException,
                      AccessPoemException

The value of one of the object's fields, wrapped up with type information sufficient for rendering it. Basically, value plus name plus type. This is the form in which Melati's templating facilities expect to receive values for displaying them or creating input boxes.

If the field baz is defined in the DSD as part of a table called foo, then the table's records will be represented by an application-specialised subclass of Persistent called Foo which provides a getBazField method.

Parameters:

name - column name

Returns:

the Field of that name

Throws:

NoSuchColumnPoemException - if there is no column of that name

AccessPoemException - if the current AccessToken does not grant access capability

fieldsOfColumns

Enumeration<Field> fieldsOfColumns(Enumeration<Column> columns)

Create Fields from Columns.

Parameters:

columns - an Enumeration of Columns

Returns:

an Enumeration of Fields

getFields

Enumeration<Field> getFields()

The values of all the object's fields, wrapped up with type information sufficient for rendering them.

Returns:

an Enumeration of Fields

getRecordDisplayFields

Enumeration<Field> getRecordDisplayFields()

The values of all the object's fields designated for inclusion in full record displays, wrapped up with type information sufficient for rendering them.

Returns:

an Enumeration of Fields

See Also:

DisplayLevel.record

getDetailDisplayFields

Enumeration<Field> getDetailDisplayFields()

All fields at the detailed display level in display order.

Returns:

an Enumeration of Fields

See Also:

DisplayLevel.detail

getSummaryDisplayFields

Enumeration<Field> getSummaryDisplayFields()

All fields at the summary display level in display order.

Returns:

an Enumeration of Fields

See Also:

DisplayLevel.summary

getSearchCriterionFields

Enumeration<Field> getSearchCriterionFields()

Returns:

an Enumeration of searchable Fields

getPrimaryDisplayField

Field getPrimaryDisplayField()

Returns:

the Primary Display Column as a Field

delete

void delete(Map<Column,IntegrityFix> integrityFixOfColumn)

Delete the object. Before the record is deleted from the database, POEM checks to see if it is the target of any reference fields. What happens in this case is determined by the integrityfix setting of the referring column, unless that's overridden via the integrityFixOfColumn argument. By default, a DeletionIntegrityPoemException is thrown, but this behaviour can be changed through the admin interface.

Parameters:

integrityFixOfColumn - A map from Column to IntegrityFix which says how referential integrity is to be maintained for each column that can refer to the object being deleted. May be null to mean `empty'. If a column isn't mentioned, the default behaviour for the column is used. (The default is StandardIntegrityFix.prevent.)

See Also:

IntegrityFix, PoemThread.commit()

delete_unsafe

void delete_unsafe()

Delete without access checks.

delete

void delete()

Delete this persistent, with default integrity checks, ie disallow deletion if object referred to by others.

deleteAndCommit

void deleteAndCommit(Map<Column,IntegrityFix> integrityFixOfColumn)
                     throws AccessPoemException,
                            DeletionIntegrityPoemException

Delete the object, with even more safety checks for referential integrity. As delete(java.util.Map), but waits for exclusive access to the database before doing the delete, and commits the session immediately afterwards.

This used to be the only deletion entry point allowed, but now we ensure that the possible race condition involving new pointers to the deleted object created during the deletion process is covered. So it is recommended to use delete(java.util.Map) unless you really want this functionality.

Throws:

AccessPoemException

DeletionIntegrityPoemException

deleteAndCommit

void deleteAndCommit()
                     throws AccessPoemException,
                            DeletionIntegrityPoemException

Convenience method with default integrity fix.

Throws:

AccessPoemException

DeletionIntegrityPoemException

duplicated

Persistent duplicated()
                      throws AccessPoemException

Create a new object like this one. This Persistent must not be floating.

Returns:

A floating clone

Throws:

AccessPoemException

duplicatedFloating

Persistent duplicatedFloating()
                              throws AccessPoemException

Create a new persistent like this one, regardless of whether this Persistent has been written to the dbms yet.

Returns:

A floating clone

Throws:

AccessPoemException

displayString

String displayString(PoemLocale locale,
                     int style)
                     throws AccessPoemException

A string describing the object for the purposes of rendering it in lists presented to the user. Unless overridden, this returns the value picked out by the designated `primary display column' of the table from which the object comes. If there is no such column, the object's troid is returned (as a decimal string).

Parameters:

locale - our locale

style - a DateFormat (only applicable to those rare objects whose summary column is a date)

Returns:

the String to display

Throws:

AccessPoemException - if current User does not have viewing Capability

displayString

String displayString(PoemLocale locale)
                     throws AccessPoemException

Defaults to DateFormat.MEDIUM.

Returns:

Default String for display.

Throws:

AccessPoemException - if current User does not have viewing Capability

displayString

String displayString()
                     throws AccessPoemException

Returns:

Default String for display.

Throws:

AccessPoemException - if current User does not have viewing Capability

dump

String dump()

Returns:

the dump String

dump

void dump(PrintStream p)

Dump to a PrintStream.

Parameters:

p - the PrintStream to dump to

postWrite

void postWrite()

Called after this persistent is written to the database on being inserted or modified.

This is called after postInsert() or postModify().

This is low level and there is a limit to what you can do here without causing infinitely recursive calls.

postInsert

void postInsert()

Called after this persistent is written to the database for the first time.

This is low level and there is a limit to what you can do here without causing infinitely recursive calls.

postModify

void postModify()

Called after this persistent is updated and written to the database replacing the existing record it represents.

Not called when it is written to the database for the first time.

This is low level and there is a limit to what you can do here without causing infinitely recursive calls.

preEdit

void preEdit()

Optionally called before an instance is edited by the user.

See postEdit(boolean) for additional comments. However, it is not called when a newly created row is edited.

postEdit

void postEdit(boolean creating)

Optionally called after this instance is edited by a user.

Unlike postModify() and postInsert() this is not called during write down but can be called by applications after individual field edits by the user have been reflected in the instance.

It can be be overridden to enforce data model constraints such as validity of columns relative to other columns. These will be enforced when the admin system is used.

This is a higher level method than postModify() so is less likely to lead to infinite recursion or other such problems.

Sorry for the lack of signature consistency with the lower level methods but I got tired of having to call my own application specific common method.

Parameters:

creating - Are we in the process of creating a new record?

isDirty

boolean isDirty()

Returns:

the dirty

setDirty

void setDirty(boolean dirty)

Parameters:

dirty - the dirty to set