de.mguennewig.pobjects
Class PObject

java.lang.Object
  de.mguennewig.pobjects.Record
      de.mguennewig.pobjects.PObject

Direct Known Subclasses:

Pclass, PclassColumn, PClassCurrency, PClassStock, PClassStockExchange, PClassTransaction

public abstract class PObject
extends Record

Represents a table row with an id that is unique within the table.

Unlike Record, instances of this type have an identity and can be written to. Using store(), changes to the in-memory object are propagated back to the RDBMS.

Author:

Michael Günnewig

Field Summary

static int	CHECK_ALL_FIELDS Constant that specifies that restrictions of all fields will be checked on store(int).
static int	CHECK_CHANGED_ONLY Constant that specifies that only the restrictions of changed fields will be checked on store(int).
static int	CHECK_NOTHING Constant that specifies that no field restrictions will be checked on store(int).
static int	STATE_COMMITED A pseudo state that will not really change state but will clear the getOldValues() hash after a commit has been issued.
static int	STATE_DELETE The object is marked for deletion.
static int	STATE_DIRTY The object has been read from the database, and one or more of its fields have been changed in memory.
static int	STATE_INTERNALIZED The object mirrors an existing database row.
static int	STATE_INVALID
static int	STATE_NEW_OBJECT Container.makePersistent(PObject) has been called on the object, but the object has not been stored yet.
static int	STATE_REFERENCE The object in memory is only a reference to the real data stored in the database.
static int	STATE_TRANSIENT

Constructor Summary

PObject()
Standard-constructor for PObject.

Method Summary

void	checkConstraints() Tests whether the current in memory state violates any Constraints.
void	checkConstraints(int fieldCheck) Tests whether the current in memory state violates any Constraints.
void	copyState(PObject src) Copies the state of the given object into this object.
void	delete() Deletes the object from the RDBMS.
java.util.Map<java.lang.Integer,java.lang.Object>	getChangedValues() Returns a map of changed values where the field index is the key and the new value the value.
abstract ClassDecl	getClassDecl()
Container	getContainer() Returns the database container to which this object belongs.
static int	getDefaultFieldCheckStyle() Returns how strict or loose field restrictions are checked by default on every store() and checkConstraints().
java.lang.String	getId() Returns the unique database identifier within its class if the object is persistent, and null otherwise.
java.lang.String	getIdForVisual()
static java.lang.String	getKey(ClassDecl te, java.lang.String id)
static java.lang.String	getKey(PObject obj)
java.util.Map<java.lang.Integer,java.lang.Object>	getOldValues() Returns a map of changed values, where the field index is the key and the old value the value.
int	getPObjState()
TableExpr	getTableExpr() Returns the metadata declaration for this Record.
boolean	isInstanceOf(ClassDecl table) Tests whether this persistent object is an instance of table expression table.
boolean	isInternalized() Tests whether the object is fully read from the RDBMS.
boolean	isPersistent() Tests whether the object is known to the RDBMS.
boolean	isReference()
void	loadForUpdate()
void	loadIfReference()
void	revert() Reverts the in-memory state to the last committed or read one.
void	set(Column c, java.lang.Object value) Set value of column c.
static void	setDefaultFieldCheckStyle(int fieldCheck) Sets how strict or loose field restrictions are checked by default on every store() and checkConstraints().
void	store() Saves the current in memory state in the RDBMS.
void	store(int fieldCheck) Saves the current in memory state in the RDBMS.
java.lang.String	toString() Returns a textual representation for this class.

Methods inherited from class de.mguennewig.pobjects.Record

format, get, get, set

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

CHECK_ALL_FIELDS

public static final int CHECK_ALL_FIELDS

Constant that specifies that restrictions of all fields will be checked on store(int). This is the default for new objects unless CHECK_NOTHING has been specified.

See Also:

Constant Field Values

CHECK_CHANGED_ONLY

public static final int CHECK_CHANGED_ONLY

Constant that specifies that only the restrictions of changed fields will be checked on store(int). This will speed up storing slightly and will make the application more robust if more strict constraints will be applied at later points in time of the application.

Note that for new objects this is equivalent to CHECK_ALL_FIELDS.

See Also:

Constant Field Values

CHECK_NOTHING

public static final int CHECK_NOTHING

Constant that specifies that no field restrictions will be checked on store(int).

NOTE: That this can lead to inconsistent database content and is highly discouraged to use.

See Also:

Constant Field Values

STATE_INVALID

public static final int STATE_INVALID

See Also:

Constant Field Values

STATE_TRANSIENT

public static final int STATE_TRANSIENT

See Also:

Constant Field Values

STATE_REFERENCE

public static final int STATE_REFERENCE

The object in memory is only a reference to the real data stored in the database. Any access to the object's state must first internalize the data

See Also:

Constant Field Values

STATE_NEW_OBJECT

public static final int STATE_NEW_OBJECT

Container.makePersistent(PObject) has been called on the object, but the object has not been stored yet. Since the object only exists in memory, there can be no external references to it. This means the container is defined, but the id remains null.

See Also:

Constant Field Values

STATE_INTERNALIZED

public static final int STATE_INTERNALIZED

The object mirrors an existing database row. That is, its container and id are set and changes to the object mark it as dirty with respect to the database content.

See Also:

Constant Field Values

STATE_DIRTY

public static final int STATE_DIRTY

The object has been read from the database, and one or more of its fields have been changed in memory. The next store() will execute an UPDATE to bring the database in sync with the in-memory object.

See Also:

Constant Field Values

STATE_DELETE

public static final int STATE_DELETE

The object is marked for deletion. Calling store() on it will trigger a DELETE statement for it in the database.

See Also:

Constant Field Values

STATE_COMMITED

public static final int STATE_COMMITED

A pseudo state that will not really change state but will clear the getOldValues() hash after a commit has been issued.

See Also:

Constant Field Values

Constructor Detail

PObject

public PObject()

Standard-constructor for PObject.

Method Detail

isInstanceOf

public final boolean isInstanceOf(ClassDecl table)

Tests whether this persistent object is an instance of table expression table.

Returns:

true if table is a base table of this, otherwise false.

See Also:

ClassDecl.isExtensionOf(TableExpr)

copyState

public void copyState(PObject src)

Copies the state of the given object into this object.

This method copies only the data defined by the table expression of the given object into this object. The id is skipped in this process.

Throws:

java.lang.IllegalArgumentException - if src is not an instance of a base class of this object.

See Also:

isInstanceOf(ClassDecl)

getOldValues

public final java.util.Map<java.lang.Integer,java.lang.Object> getOldValues()

Returns a map of changed values, where the field index is the key and the old value the value.

See Also:

getChangedValues()

getChangedValues

public final java.util.Map<java.lang.Integer,java.lang.Object> getChangedValues()

Returns a map of changed values where the field index is the key and the new value the value.

See Also:

getOldValues()

getId

public final java.lang.String getId()

Returns the unique database identifier within its class if the object is persistent, and null otherwise.

getIdForVisual

public java.lang.String getIdForVisual()

getContainer

public final Container getContainer()

Returns the database container to which this object belongs.

isPersistent

public final boolean isPersistent()

Tests whether the object is known to the RDBMS.

isInternalized

public final boolean isInternalized()

Tests whether the object is fully read from the RDBMS.

getClassDecl

public abstract ClassDecl getClassDecl()

getTableExpr

public final TableExpr getTableExpr()

Returns the metadata declaration for this Record.

Specified by:

getTableExpr in class Record

See Also:

getClassDecl()

getPObjState

public final int getPObjState()

getDefaultFieldCheckStyle

public static int getDefaultFieldCheckStyle()

Returns how strict or loose field restrictions are checked by default on every store() and checkConstraints().

See Also:

CHECK_ALL_FIELDS, CHECK_CHANGED_ONLY, CHECK_NOTHING

setDefaultFieldCheckStyle

public static void setDefaultFieldCheckStyle(int fieldCheck)

Sets how strict or loose field restrictions are checked by default on every store() and checkConstraints().

See Also:

CHECK_ALL_FIELDS, CHECK_CHANGED_ONLY, CHECK_NOTHING

getKey

public static java.lang.String getKey(PObject obj)

getKey

public static java.lang.String getKey(ClassDecl te,
                                      java.lang.String id)

isReference

public final boolean isReference()

loadIfReference

public void loadIfReference()

loadForUpdate

public void loadForUpdate()

revert

public void revert()

Reverts the in-memory state to the last committed or read one.

set

public void set(Column c,
                java.lang.Object value)

Set value of column c.

This method is primarily intended for use by procedures that work on meta level of de.mguennewig.pobjects. It differs from the per field setXXX() methods in that it does not load the object's data if it is not in memory. If unsure whether the object's state has been internalized, then any call to this method must be preceded by a call to loadIfReference().

Saves old value if changed the first time.

Overrides:

set in class Record

See Also:

saveOldValue(int,Object), revert()

delete

public void delete()
            throws PObjSQLException

Deletes the object from the RDBMS.

If the objects data is not in memory yet, then it will be loaded before actually deleting it. This ensures that access to an object's data after delete() and store() is consistent and always returns "real" data, instead of just null.

Throws:

PObjSQLException

See Also:

loadIfReference()

checkConstraints

public void checkConstraints()
                      throws PObjConstraintException

Tests whether the current in memory state violates any Constraints.

Note: UniqueConstraints can't be checked in memory.

Throws:

PObjConstraintException - when any Constraint is violated.

See Also:

UniqueConstraint

checkConstraints

public void checkConstraints(int fieldCheck)
                      throws PObjConstraintException

Tests whether the current in memory state violates any Constraints.

Note: UniqueConstraints can't be checked in memory.

Parameters:

fieldCheck - Specified how strict or loose the field restrictions should be checked. This will be one of CHECK_ALL_FIELDS, CHECK_CHANGED_ONLY or CHECK_NOTHING.

Throws:

PObjConstraintException - when any Constraint is violated.

See Also:

UniqueConstraint

store

public void store()
           throws PObjConstraintException,
                  PObjSQLException

Saves the current in memory state in the RDBMS.

Throws:

java.lang.IllegalStateException - if this object is new and Container.makePersistent(PObject) has not been called yet.

PObjConstraintException - when any Constraint is violated.

PObjSQLException - when any other database exception occurs.

See Also:

checkConstraints()

store

public void store(int fieldCheck)
           throws PObjConstraintException,
                  PObjSQLException

Saves the current in memory state in the RDBMS.

Parameters:

fieldCheck - Specified how strict or loose the field restrictions should be checked. This will be one of CHECK_ALL_FIELDS, CHECK_CHANGED_ONLY or CHECK_NOTHING.

Throws:

java.lang.IllegalStateException - if this object is new and Container.makePersistent(PObject) has not been called yet.

PObjConstraintException - when any Constraint is violated.

PObjSQLException - when any other database exception occurs.

See Also:

checkConstraints(int)

toString

public java.lang.String toString()

Returns a textual representation for this class.

Overrides:

toString in class java.lang.Object

Returns:

The value of the visualization field if set, else a string of the form [<table>:<id>].