oracle.jbo
Interface Row

All Superinterfaces:

AttributeList, XMLInterface

All Known Subinterfaces:

Entity

All Known Implementing Classes:

ViewCriteriaRow, RowImpl, ViewRowImpl

public interface Row

extends AttributeList, XMLInterface

This interface provides access to rows. This interface is implemented by View rows and Entity rows. Custom application logic can use this interface to access database table rows independently of the implementation of the underlying row. For example, assume that a custom application is written to perform batch style inserts into a database table. Such an application can reference the Row interface for row access instead of accessing instances of EntityImpl or ViewRowImpl directly. This design would allow changes in a row's implementation (Entity row or View row) without necessitating changes in the application logic.

In addition to providing a base type for View row and Entity row access, this interface provides tier-independent access to rows. Consequently, custom application logic can reference the interface on both the client and middle tiers of a three-tier application.

Note in an application running in the three-tier configuration, Entity rows are not marshalled to the client tier. The client tier has access only to View rows and not Entity rows. Of course, in the middle tier, the business logic has full access to both View rows and Entity rows. This interface should not be implemented by a custom application.

Since:

JDeveloper 3.0

See Also:

RowImpl, EntityImpl, ViewRowImpl

Field Summary

Type	Field
static int	REFRESH_CONTAINEES REFRESH_... constants are used as refresh mode flags to be passed into refresh(int).
static int	REFRESH_REMOVE_NEW_ROWS REFRESH_... constants are used as refresh mode flags to be passed into refresh(int).
static int	REFRESH_UNDO_CHANGES REFRESH_... constants are used as refresh mode flags to be passed into refresh(int).
static int	REFRESH_WITH_DB_FORGET_CHANGES REFRESH_... constants are used as refresh mode flags to be passed into refresh(int).
static int	REFRESH_WITH_DB_ONLY_IF_UNCHANGED REFRESH_... constants are used as refresh mode flags to be passed into refresh(int).

Fields inherited from interface oracle.jbo.XMLInterface

XML_IGNORE_DEPTH_COUNT, XML_OPT_ALL_ROWS, XML_OPT_ASSOC_CONSISTENT, XML_OPT_CHANGES_ONLY, XML_OPT_LIMIT_RANGE

Method Summary

Type	Method
Key	getKey() Returns the row's key.
StructureDef	getStructureDef() Returns the structure of the row.
boolean	isAttributeUpdateable(int index) Tests if an attribute is updateable.
void	lock() Locks the row(s) in the database table.
void	refresh(int refreshMode) Refreshes the row's attributes with values from database.
void	remove() Removes the row from the database table.
void	validate() Validates the row.

Methods inherited from interface oracle.jbo.AttributeList

getAttribute, getAttribute, getAttributeCount, getAttributeIndexOf, getAttributeNames, getAttributeValues, setAttribute, setAttribute

Methods inherited from interface oracle.jbo.XMLInterface

readXML, readXML, writeXML, writeXML, writeXML, writeXML

Field Detail

REFRESH_WITH_DB_FORGET_CHANGES

public static final int REFRESH_WITH_DB_FORGET_CHANGES

REFRESH_... constants are used as refresh mode flags to be passed into refresh(int).

REFRESH_WITH_DB_FORGET_CHANGES forgets edits that the current user made to the row. The row data is refreshed from database. The latest data from database replaces data in the row regardless of whether the row as modified or not.

If the current user had called ApplicationModule#postChanges() REFRESH_WITH_DB_FORGET_CHANGES will pick up the data that he himself wrote through his call to postChanges().

If REFRESH_REMOVE_NEW_ROWS is not specified, REFRESH_WITH_DB_FORGET_CHANGES puts a new row back to blank. If REFRESH_REMOVE_NEW_ROWS is specified, the new row is removed.

REFRESH_WITH_DB_ONLY_IF_UNCHANGED

public static final int REFRESH_WITH_DB_ONLY_IF_UNCHANGED

REFRESH_... constants are used as refresh mode flags to be passed into refresh(int).

REFRESH_WITH_DB_ONLY_IF_UNCHANGED works just like REFRESH_WITH_DB_FORGET_CHANGES for unmodified rows, i.e., the row is refreshed with attribute values from the database. If a row was already modified by this transaction, the row is not refreshed.

If locking mode is pessimistic, the fact that you (this user) were able to change the data means that you were able to lock the row and that you got the latest data.

When using this refresh mode, if the locking mode is optimistic, the framework could bring the latest data for unmodified attributes and merge them into the row, while retaining changed attributes as is. However, this could lead to data integrity problems. Thus, for consistency sake and data integrity, we leave the row alone if it was modified even for optimistic locking mode.

If REFRESH_REMOVE_NEW_ROWS is not specified, calling refresh with this mode will be a no-op (treated just like a modified row). If REFRESH_REMOVE_NEW_ROWS is specified, the new row is removed.

REFRESH_UNDO_CHANGES

public static final int REFRESH_UNDO_CHANGES

REFRESH_... constants are used as refresh mode flags to be passed into refresh(int).

REFRESH_UNDO_CHANGES works just like REFRESH_WITH_DB_FORGET_CHANGES for unmodified rows, i.e., the row is refreshed with attribute values from the database.

For a modified row, this mode refreshes the row with attribute values at the beginning of this transaction. This mode will back out changes that have been posted to database through postChanges(), but not yet committed. Suppose a row's attribute value was modified from 'A' to 'B' and 'B' is posted. Suppose further the user changes 'B' to 'C' (after the post). Calling refresh(int) with this mode will restore the attribute value to 'A'.

Out on database, the attribute value is still 'B'. However, the row is marked as modified, so that when the changes are posted later 'A' will replace 'B' out on database.

If REFRESH_REMOVE_NEW_ROWS is not specified, REFRESH_UNDO_CHANGES puts a new row back to blank. If REFRESH_REMOVE_NEW_ROWS is specified, the new is removed.

REFRESH_REMOVE_NEW_ROWS

public static final int REFRESH_REMOVE_NEW_ROWS

REFRESH_... constants are used as refresh mode flags to be passed into refresh(int).

REFRESH_REMOVE_NEW_ROWS is a bit-wise flag that can be OR'ed with other REFRESH_... constants.

If REFRESH_REMOVE_NEW_ROWS is specified, refresh(int) will remove new rows.

REFRESH_CONTAINEES

public static final int REFRESH_CONTAINEES

REFRESH_... constants are used as refresh mode flags to be passed into refresh(int).

REFRESH_CONTAINEES is a bit-wise flag that can be OR'ed with other REFRESH_... constants.

REFRESH_CONTAINEES causes an Entity row to call refresh(int) on its containees (children) with the same refresh mode (if this Entity row is a master is composition association).

Method Detail

getKey

public Key getKey()

Returns the row's key.

Returns:

the row's Key.

validate

public void validate()

Validates the row. The default implementation of this method on a View row calls validate() for each Entity row that makes up the View row.

Throws:

ValidationException - if a validation error is detected.

See Also:

EntityImpl.validate(), ViewRowImpl.validate()

lock

public void lock()

Locks the row(s) in the database table. For a View row, lock() calls lock() on each Entity row that makes up the View row.

Throws:

RowNotFoundException - if the row to be locked no longer exists in the database table. The row was probably deleted by another transaction (and transaction committed).

DeadEntityAccessException - if the row to locked is one that has already been deleted.

TooManyObjectsException - to service the lock request, a SELECT statement is issued against the database table using this row's primary key value. Normally, only one row with matching primary key should be found in the database. If more than one row with the given PK is found, this represents a data inconsistency problem in the table. In that case, this exception is thrown.

RowInconsistentException - after the row is locked in the database table, BC4J retrieves the latest data values from the table. A check is made to see if the row had been changed by another transaction (and committed). If so, this exception is thrown.

AlreadyLockedException - if the row is already locked by another transaction.

DMLException - if the SELECT statement to lock the row is not accepted by the DBMS. Make sure that the statement generated for the Entity Object is correct.

remove

public void remove()

Removes the row from the database table.

Throws:

JboException - a runtime exception, if an exception occurs during access.

isAttributeUpdateable

public boolean isAttributeUpdateable(int index)

Tests if an attribute is updateable.

Parameters:

index - the index of the attribute.

Returns:

true if the row is marked UPDATEABLE, or if the row is marked UPDATEABLE_WHILE_NEW and the current row is new.

getStructureDef

public StructureDef getStructureDef()

Returns the structure of the row.

Returns:

StructureDef that describes the structure of the row.

refresh

public void refresh(int refreshMode)

Refreshes the row's attributes with values from database. refreshMode should be a combination of REFRESH_.... See REFRESH_... constants for further information.

Parameters:

refreshMode - the refresh mode.