org.melati.poem
Class JdbcPersistent

java.lang.Object
  org.melati.poem.transaction.Transactioned
      org.melati.poem.JdbcPersistent

All Implemented Interfaces:

Cloneable, Persistable, Persistent, Treeable

Direct Known Subclasses:

CapabilityBase, CategoryBase, ChildBase, ContactBase, ContactCategoryBase, GroupBase, GroupCapabilityBase, GroupMembershipBase, ParentBase, TableCategoryBase, TableInfoBase, UserBase, ValueInfoBase

public class JdbcPersistent
extends Transactioned
implements Persistent, Cloneable

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

Instances are also used to represent selection criteria.

Author:

WilliamC At paneris.org

Field Summary

Fields inherited from class org.melati.poem.transaction.Transactioned

valid

Constructor Summary

JdbcPersistent()
Constructor.

JdbcPersistent(JdbcTable table, Integer troid)
Constructor.

JdbcPersistent(String tableName, String troidString)
Constructor.

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.
protected Object	clone()
protected void	commit(Transaction transaction) Previously deletion was treated as non-rollbackable, as deleteAndCommit was the only deletion mechanism.
protected String	countMatchSQL(boolean includeDeleted, boolean excludeUnselectable) Return a SELECT query to count rows matching criteria represented by this 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.
protected void	deleteLock(SessionToken sessionToken)
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.
boolean	equals(Object object)
void	existenceLock() Lock without actually reading.
protected void	existenceLock(SessionToken sessionToken)
Enumeration<Field>	fieldsOfColumns(Enumeration<Column> columns) Create Fields from Columns.
protected String	fromClause() Return an SQL FROM clause for use when selecting rows using criteria represented by this object.
protected Capability	getCanDelete() The capability required for deleting the object.
protected Capability	getCanRead() The capability required for reading the object's field values.
protected Capability	getCanSelect() The capability required to select the object.
protected Capability	getCanWrite() The capability required for writing the object's field values.
Treeable[]	getChildren()
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.
String	getName() NOTE This will be overridden if the persistent has a field called name.
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.
Integer	getTroid() The object's troid.
int	hashCode()
void	invalidate() Mark as invalid.
boolean	isDirty()
protected void	load(Transaction transaction) Called if not uptodate.
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.
protected void	readLock() Check if we may read this object and then lock it.
protected void	readLock(SessionToken sessionToken)
protected void	readLock(Transaction transaction) This is just to make this method available to Table.
protected void	rollback(Transaction transaction)
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()
String	toString() A string briefly describing the object for diagnostic purposes.
Integer	troid() Get the troid without access checking.
protected boolean	upToDate(Transaction transaction) Whether we are up to date with respect to current Transaction.
protected void	writeDown(Transaction transaction) Write the persistent to the database if this might be necessary.
protected void	writeLock() Check if we may write to this object and then lock it.
protected void	writeLock(SessionToken sessionToken)
protected void	writeLock(Transaction transaction) Get a write lock on the given object if we do not already have one.

Methods inherited from class org.melati.poem.transaction.Transactioned

markValid, reset, setTransactionPool, transactionPool, unSee

Methods inherited from class java.lang.Object

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

Constructor Detail

JdbcPersistent

public JdbcPersistent()

Constructor.

JdbcPersistent

public JdbcPersistent(JdbcTable table,
                      Integer troid)

Constructor.

Parameters:

table - the table of the Persistent

troid - its Table Row Object Id

JdbcPersistent

public JdbcPersistent(String tableName,
                      String troidString)

Constructor.

Parameters:

tableName - String name of a table

troidString - String integer representation

Method Detail

statusNonexistent

public final boolean statusNonexistent()

Specified by:

statusNonexistent in interface Persistent

Returns:

whether this object has been persisted

See Also:

Persistent.statusNonexistent()

statusExistent

public final boolean statusExistent()

Specified by:

statusExistent in interface Persistent

Returns:

whether this object has been deleted

See Also:

Persistent.statusExistent()

load

protected void load(Transaction transaction)

Called if not uptodate. Load the transactioned object from its backing store.

Specified by:

load in class Transactioned

See Also:

load(org.melati.poem.transaction.Transaction)

upToDate

protected boolean upToDate(Transaction transaction)

Whether we are up to date with respect to current Transaction.

Return the inherited validity flag. Whether this instance is up-to-date.

This is a hook to enable subtypes to define under what circumstances an instance needs to be reloaded when it is marked as invalid, however the two known subtypes just return the inherited valid flag.

Specified by:

upToDate in class Transactioned

See Also:

upToDate(org.melati.poem.transaction.Transaction)

writeDown

protected void writeDown(Transaction transaction)

Write the persistent to the database if this might be necessary.

It may be necessary if field values have been set since we last did a write i.e. this persistent is dirty. It will not be necessary if this persistent is deleted. An exception will occur if it does not exist in the database.

Specified by:

writeDown in class Transactioned

writeLock

protected void writeLock(Transaction transaction)

Get a write lock on the given object if we do not already have one.

This will block until no other transactions have write locks on the object before claiming the next write lock. Then it will block until none have read locks.

Finally it calls Transactioned.ensureValid(Transaction).

Overrides:

writeLock in class Transactioned

See Also:

Transactioned.writeLock(org.melati.poem.transaction.Transaction)

readLock

protected void readLock(Transaction transaction)

This is just to make this method available to Table.

Overrides:

readLock in class Transactioned

commit

protected void commit(Transaction transaction)

Previously deletion was treated as non-rollbackable, as deleteAndCommit was the only deletion mechanism.

Overrides:

commit in class Transactioned

See Also:

commit(org.melati.poem.transaction.Transaction)

rollback

protected void rollback(Transaction transaction)

Overrides:

rollback in class Transactioned

makePersistent

public void makePersistent()

A convenience method to create this Persistent.

Specified by:

makePersistent in interface Persistent

See Also:

Persistent.makePersistent()

getTable

public final Table getTable()

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

Specified by:

getTable in interface Persistent

Returns:

the Table

See Also:

Persistent.getTable()

getDatabase

public final Database getDatabase()

Specified by:

getDatabase in interface Persistent

Returns:

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

See Also:

Persistent.getDatabase()

troid

public final Integer troid()

Description copied from interface: Persistable

Get the troid without access checking.

Specified by:

troid in interface Persistable

Returns:

The Table Row Object Id for this Persistent. FIXME This shouldn't be public because we don't in principle want people to know even the troid of an object they aren't allowed to read. However, I think this information may leak out elsewhere. To fix is not simple, as generated setters rely upon a lock-free read of the object to set. the troid

See Also:

Persistable.troid()

getTroid

public final Integer getTroid()
                       throws AccessPoemException

The object's troid.

Specified by:

getTroid in interface Persistable

Returns:

Every record (object) in a POEM database must have a troid (table row ID, or table-unique non-nullable integer primary key), often but not necessarily called id, so that it can be conveniently `named' for retrieval.

Throws:

AccessPoemException - if assertCanRead fails

See Also:

Table.getObject(java.lang.Integer), assertCanRead()

existenceLock

protected void existenceLock(SessionToken sessionToken)

readLock

protected void readLock(SessionToken sessionToken)
                 throws AccessPoemException

Throws:

AccessPoemException

writeLock

protected void writeLock(SessionToken sessionToken)
                  throws AccessPoemException

Throws:

AccessPoemException

deleteLock

protected void deleteLock(SessionToken sessionToken)
                   throws AccessPoemException

Throws:

AccessPoemException

existenceLock

public void existenceLock()

Lock without actually reading.

Specified by:

existenceLock in interface Persistent

See Also:

Persistent.existenceLock()

readLock

protected void readLock()
                 throws AccessPoemException

Check if we may read this object and then lock it.

Throws:

AccessPoemException - if current AccessToken does not give read Capability

writeLock

protected void writeLock()
                  throws AccessPoemException

Check if we may write to this object and then lock it.

Throws:

AccessPoemException - if current AccessToken does not give write Capability

getCanRead

protected Capability getCanRead()

The capability required for reading the object's field values. This is used by assertCanRead (unless that's been overridden) to obtain a Capability for comparison against the caller's AccessToken.

NOTE If a canRead column is defined then it will override this method.

Returns:

the capability specified by the record's canread field, or null if it doesn't have one or its value is SQL NULL

See Also:

assertCanRead(org.melati.poem.AccessToken)

assertCanRead

public 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.

Specified by:

assertCanRead in interface Persistent

Parameters:

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

Throws:

AccessPoemException - if the check fails

See Also:

Persistent.assertCanRead(org.melati.poem.AccessToken)

assertCanRead

public final void assertCanRead()
                         throws AccessPoemException

Specified by:

assertCanRead in interface Persistent

Throws:

AccessPoemException - if current accessToken does not grant read capability

See Also:

Persistent.assertCanRead()

getReadable

public final boolean getReadable()

Specified by:

getReadable in interface Persistent

Returns:

Whether the object is readable by current AccessToken

See Also:

Persistent.getReadable()

getCanWrite

protected Capability getCanWrite()

The capability required for writing the object's field values. This is used by assertCanWrite (unless that's been overridden) to obtain a Capability for comparison against the caller's AccessToken.

NOTE If a canWrite column is defined then it will override this method.

Returns:

the capability specified by the record's canwrite field, or null if it doesn't have one or its value is SQL NULL

See Also:

assertCanWrite(org.melati.poem.AccessToken)

assertCanWrite

public 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.

Specified by:

assertCanWrite in interface Persistent

Throws:

AccessPoemException

See Also:

Persistent.assertCanWrite(org.melati.poem.AccessToken)

assertCanWrite

public final void assertCanWrite()
                          throws AccessPoemException

Specified by:

assertCanWrite in interface Persistent

Throws:

AccessPoemException - if current accessToken does not grant wraite capability

See Also:

Persistent.assertCanWrite()

getCanDelete

protected Capability getCanDelete()

The capability required for deleting the object. This is used by assertCanDelete (unless that's been overridden) to obtain a Capability for comparison against the caller's AccessToken.

NOTE If a canDelete column is defined then it will override this method.

Returns:

the capability specified by the record's candelete field, or null if it doesn't have one or its value is SQL NULL

See Also:

assertCanDelete(org.melati.poem.AccessToken)

assertCanDelete

public 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.

Specified by:

assertCanDelete in interface Persistent

Throws:

AccessPoemException

See Also:

Persistent.assertCanDelete(org.melati.poem.AccessToken)

assertCanDelete

public final void assertCanDelete()
                           throws AccessPoemException

Specified by:

assertCanDelete in interface Persistent

Throws:

AccessPoemException - if current accessToken does not grant delete capability

See Also:

Persistent.assertCanDelete()

getCanSelect

protected Capability getCanSelect()

The capability required to select the object.

Any persistent which has a canSelect field will override this method.

There is no assertCanSelect() yet because I don't understand this stale token stuff!

Returns:

the capability the user needs to select this record

To do something:

document use-case or delete

assertCanCreate

public 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.

Specified by:

assertCanCreate in interface Persistent

See Also:

Persistent.assertCanCreate(org.melati.poem.AccessToken)

assertCanCreate

public final void assertCanCreate()
                           throws AccessPoemException

Specified by:

assertCanCreate in interface Persistent

Throws:

AccessPoemException - if current accessToken does not grant create capability

See Also:

Persistent.assertCanCreate()

getRaw

public 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.

Specified by:

getRaw in interface Persistent

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:

Persistent.getRaw(java.lang.String)

getRawString

public final 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.

Specified by:

getRawString in interface Persistent

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:

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

NoSuchColumnPoemException - if the field named doesn't exist

See Also:

Persistent.getRawString(java.lang.String)

setRaw

public 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.

Specified by:

setRaw in interface Persistent

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:

Persistent.setRaw(java.lang.String, java.lang.Object)

setRawString

public final 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.

Specified by:

setRawString in interface Persistent

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:

Persistent.setRawString(java.lang.String, java.lang.String)

getCooked

public 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.

Specified by:

getCooked in interface Persistent

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:

Persistent.getCooked(java.lang.String)

getCookedString

public final 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.

Specified by:

getCookedString in interface Persistent

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:

Persistent.getCookedString(java.lang.String, org.melati.poem.PoemLocale, int)

setCooked

public 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.

Specified by:

setCooked in interface Persistent

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

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

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

See Also:

Persistent.setCooked(java.lang.String, java.lang.Object)

getField

public final 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.

Specified by:

getField in interface Persistent

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

See Also:

Persistent.getField(java.lang.String)

fieldsOfColumns

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

Create Fields from Columns.

Specified by:

fieldsOfColumns in interface Persistent

Parameters:

columns - an Enumeration of Columns

Returns:

an Enumeration of Fields

See Also:

Persistent.fieldsOfColumns(java.util.Enumeration)

getFields

public Enumeration<Field> getFields()

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

Specified by:

getFields in interface Persistent

Returns:

an Enumeration of Fields

See Also:

Persistent.getFields()

getRecordDisplayFields

public 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.

Specified by:

getRecordDisplayFields in interface Persistent

Returns:

an Enumeration of Fields

See Also:

Persistent.getRecordDisplayFields()

getDetailDisplayFields

public Enumeration<Field> getDetailDisplayFields()

All fields at the detailed display level in display order.

Specified by:

getDetailDisplayFields in interface Persistent

Returns:

an Enumeration of Fields

See Also:

Persistent.getDetailDisplayFields()

getSummaryDisplayFields

public Enumeration<Field> getSummaryDisplayFields()

All fields at the summary display level in display order.

Specified by:

getSummaryDisplayFields in interface Persistent

Returns:

an Enumeration of Fields

See Also:

Persistent.getSummaryDisplayFields()

getSearchCriterionFields

public Enumeration<Field> getSearchCriterionFields()

Specified by:

getSearchCriterionFields in interface Persistent

Returns:

an Enumeration of searchable Fields

See Also:

Persistent.getSearchCriterionFields()

getPrimaryDisplayField

public Field getPrimaryDisplayField()

Specified by:

getPrimaryDisplayField in interface Persistent

Returns:

the Primary Display Column as a Field

See Also:

Persistent.getPrimaryDisplayField()

delete

public 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.

Specified by:

delete in interface Persistent

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:

Persistent.delete(java.util.Map)

delete_unsafe

public void delete_unsafe()

Delete without access checks.

Specified by:

delete_unsafe in interface Persistent

See Also:

Persistent.delete_unsafe()

delete

public final void delete()

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

Specified by:

delete in interface Persistent

See Also:

Persistent.delete()

deleteAndCommit

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

Delete the object, with even more safety checks for referential integrity. As Persistent.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 Persistent.delete(java.util.Map) unless you really want this functionality.

Specified by:

deleteAndCommit in interface Persistent

Throws:

AccessPoemException

DeletionIntegrityPoemException

See Also:

Persistent.deleteAndCommit(java.util.Map)

deleteAndCommit

public final void deleteAndCommit()
                           throws AccessPoemException,
                                  DeletionIntegrityPoemException

Convenience method with default integrity fix.

Specified by:

deleteAndCommit in interface Persistent

Throws:

AccessPoemException

DeletionIntegrityPoemException

See Also:

Persistent.deleteAndCommit()

duplicated

public Persistent duplicated()
                      throws AccessPoemException

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

Specified by:

duplicated in interface Persistent

Returns:

A floating clone

Throws:

AccessPoemException

See Also:

Persistent.duplicated()

duplicatedFloating

public Persistent duplicatedFloating()
                              throws AccessPoemException

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

Specified by:

duplicatedFloating in interface Persistent

Returns:

A floating clone

Throws:

AccessPoemException

See Also:

Persistent.duplicatedFloating()

toString

public String toString()

A string briefly describing the object for diagnostic purposes. The name of its table and its troid.

Overrides:

toString in class Object

See Also:

Object.toString()

displayString

public 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).

Specified by:

displayString in interface Persistent

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

See Also:

Persistent.displayString(org.melati.poem.PoemLocale, int)

displayString

public String displayString(PoemLocale locale)
                     throws AccessPoemException

Defaults to DateFormat.MEDIUM.

Specified by:

displayString in interface Persistent

Returns:

Default String for display.

Throws:

AccessPoemException - if current User does not have viewing Capability

See Also:

Persistent.displayString(org.melati.poem.PoemLocale)

displayString

public String displayString()
                     throws AccessPoemException

Specified by:

displayString in interface Persistent

Returns:

Default String for display.

Throws:

AccessPoemException - if current User does not have viewing Capability

See Also:

Persistent.displayString()

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

See Also:

Object.hashCode()

equals

public final boolean equals(Object object)

Overrides:

equals in class Object

See Also:

Object.equals(java.lang.Object)

invalidate

public void invalidate()

Mark as invalid.

Overrides:

invalidate in class Transactioned

See Also:

Transactioned.invalidate()

clone

protected Object clone()

Overrides:

clone in class Object

See Also:

Object.clone()

dump

public String dump()

Specified by:

dump in interface Persistent

Returns:

the dump String

See Also:

Persistent.dump()

dump

public void dump(PrintStream p)

Dump to a PrintStream.

Specified by:

dump in interface Persistent

Parameters:

p - the PrintStream to dump to

See Also:

Persistent.dump(java.io.PrintStream)

postWrite

public 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.

Specified by:

postWrite in interface Persistent

See Also:

Persistent.postWrite()

postInsert

public 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.

Specified by:

postInsert in interface Persistent

See Also:

Persistent.postInsert()

postModify

public 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.

Specified by:

postModify in interface Persistent

See Also:

Persistent.postModify()

preEdit

public void preEdit()

Optionally called before an instance is edited by the user.

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

Specified by:

preEdit in interface Persistent

See Also:

Persistent.preEdit()

postEdit

public void postEdit(boolean creating)

Optionally called after this instance is edited by a user.

Unlike Persistent.postModify() and Persistent.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 Persistent.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.

Specified by:

postEdit in interface Persistent

Parameters:

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

See Also:

Persistent.postEdit(boolean)

countMatchSQL

protected String countMatchSQL(boolean includeDeleted,
                               boolean excludeUnselectable)

Return a SELECT query to count rows matching criteria represented by this object.

Parameters:

includeDeleted - whether to include soft deleted records

excludeUnselectable - Whether to append unselectable exclusion SQL

Returns:

an SQL query string

fromClause

protected String fromClause()

Return an SQL FROM clause for use when selecting rows using criteria represented by this object.

By default just the table name is returned, quoted as necessary for the DBMS.

Subtypes must ensure the result is compatible with the result of #appendWhereClause(StringBuffer, JdbcPersistent).

Returns:

an SQL snippet

getChildren

public Treeable[] getChildren()

Specified by:

getChildren in interface Treeable

Returns:

an Array of Treeable children

getName

public String getName()

NOTE This will be overridden if the persistent has a field called name. This should not return null.

Specified by:

getName in interface Treeable

Returns:

the name of the object, used as node label

See Also:

Treeable.getName()

isDirty

public boolean isDirty()

Specified by:

isDirty in interface Persistent

Returns:

the dirty

setDirty

public void setDirty(boolean dirty)

Specified by:

setDirty in interface Persistent

Parameters:

dirty - the dirty to set