oracle.jbo

Interface Row

All Superinterfaces:

AttributeList, ExprWrappable, XMLInterface

All Known Subinterfaces:

Entity

All Known Implementing Classes:

DCCriteriaItemRowImpl, DCCriteriaOperatorRowImpl, DCCriteriaRowImpl, DCCriteriaRowRowImpl, DCCriteriaValueRowImpl, DCDataRow, DSEntityImpl, EntityFacadeImpl, EntityImpl, EntityOverRow, ProgrammaticViewRowImpl, RestDCDataVORow, RestDCEntityImpl, RowIdEntityObjectImpl, RowIdViewObjRowImpl, RowImpl, RowImpl, RowImpl, TransPostEntityRow, ViewCriteria.NestedViewCriteriaRow, ViewCriteriaRow, ViewCriteriaRowImpl, ViewRowImpl

public interface Row
extends AttributeList, XMLInterface, ExprWrappable

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

Fields

Modifier and Type	Field and Description
static int	EFFDT_DELETE_FUTURE_CHANGE_MODE When an effective dated row is deleted in "delete future change" mode, the end date of the row is set to the end of time and all the future rows for the same key values are deleted.
static int	EFFDT_DELETE_MODE When an effective dated row is deleted in "delete" mode, the end date of the row is set to the row's effective date and all the future rows for the same key values are deleted.
static int	EFFDT_DELETE_NEXT_CHANGE_MODE When an effective dated row is deleted in "delete next change" mode, the end date of the row is set to the end date of adjoining row and the adjoining row is deleted.
static int	EFFDT_DELETE_THIS_CHANGE_MODE When an effective dated row is deleted in "delete this change" mode, the current row is removed.
static int	EFFDT_DELETE_ZAP_MODE When an effective dated row is deleted in "zap" mode, all the effective dated rows with the same key values are deleted.
static int	EFFDT_EXPERT_MODE If the row is in a expert mode, the runtime will not carry out any effective date specific logic for row modifications.
static int	EFFDT_NONE_MODE Default state of the effective date mode on the row.
static int	EFFDT_UPDATE_CHANGE_INSERT_MODE When an effective dated row is updated in "change insert" mode, the modified row is end dated on the effective date and a new row is inserted that fits between the effective date and the start date of the next row in the effective date time line.
static int	EFFDT_UPDATE_CORRECTION When an effective dated row is updated in "correction" mode, the effective start date and effective end date is left unchanged.
static int	EFFDT_UPDATE_MODE When an effective dated row is updated in "update" mode, the modified row is end dated on the effective date and a new row is created with the changed values.
static int	EFFDT_UPDATE_NEW_EARLIEST_CHANGE_MODE Updating in "new earliest change" mode is supported only in Multiple Changes Per Day.
static int	EFFDT_UPDATE_OVERRIDE_MODE When an effective dated row is updated in "override" mode, the modified row is end dated on the effective date and the start date of the next row in the effective date time line is set to effective date + 1 day.
static int	REFRESH_CONTAINEES REFRESH_... constants are used as refresh mode flags to be passed into refresh(int).
static int	REFRESH_FORGET_NEW_ROWS 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).
static byte	STATUS_INITIALIZED Indicates that the row is newly created and no setAttribute has been called on it yet.
static byte	STATUS_NEW Indicates that the Row is newly created and this Row's consistuent entities have been added to the transaction.

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, XML_PASSIVATION_USE

Method Summary

Methods

Modifier and Type	Method and Description
AttributeHints	getAttributeHints(int attrIndex) Returns the AttributeHints object for the specified attribute for the row.
AttributeHints	getAttributeHints(java.lang.String attrName) Returns the AttributeHints object for the specified attribute for the row.
SecurityHints	getAttributeSecurityHints(int attrIndex) Returns the SecurityHints object for the specified attribute for the row.
SecurityHints	getAttributeSecurityHints(java.lang.String attrName) Returns the SecurityHints object for the specified attribute for the row.
int	getEffectiveDateMode() Get the current effective date mode.
Key	getKey() Returns the row's key.
SecurityHints	getSecurityHints() Returns the SecurityHints object for the row.
StructureDef	getStructureDef() Returns the structure of the row.
boolean	isAttributeUpdateable(int index) Tests if an attribute is updateable.
boolean	isDead() An attempt to access a dead view row will lead to a DeadViewRowAccessException.
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	removeAndRetain() Removes the row from the collection and then retain it for insertion into another location.
void	removeFromCollection() Removes the row from the collection.
void	setAttributeValues(java.util.List names, java.util.List values) Set attribute values for the given list of attributes names.
void	setEffectiveDateMode(int mode) Set the Effective Date mode in which the row updates need to be carried out.
void	setNewRowState(byte state) Sets a new unposted row, created in this transaction, to either STATUS_NEW or STATUS_INITIALIZED mode.
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

STATUS_INITIALIZED

static final byte STATUS_INITIALIZED

Indicates that the row is newly created and no setAttribute has been called on it yet. Entities that comprise this row have not been added to the ValidationManager's or TransactionManager's lists. Rows in this state are primarily used as scratch-pad/temporary rows and can be placed back into the appropriate lists and made a postable row again by changing the row state to STATUS_NEW using setNewRowState method.

See Also:

Constant Field Values

STATUS_NEW

static final byte STATUS_NEW

Indicates that the Row is newly created and this Row's consistuent entities have been added to the transaction.

See Also:

Constant Field Values

REFRESH_WITH_DB_FORGET_CHANGES

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 was modified or not.

If the current user had called Transaction.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.

See Also:

Constant Field Values

REFRESH_WITH_DB_ONLY_IF_UNCHANGED

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.

See Also:

Constant Field Values

REFRESH_UNDO_CHANGES

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.

See Also:

Constant Field Values

REFRESH_REMOVE_NEW_ROWS

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 through a call to remove(). This means that if this row is the parent in a containership assocation, the children entity rows will be removed as well.

See Also:

Constant Field Values

REFRESH_FORGET_NEW_ROWS

static final int REFRESH_FORGET_NEW_ROWS

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

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

If REFRESH_FORGET_NEW_ROWS is specified, refresh(int) will remove new rows by marking it STATUS_DEAD. The difference between this flag and REFRESH_REMOVE_NEW_ROWS is that this flag will not remove children entity rows.

See Also:

Constant Field Values

REFRESH_CONTAINEES

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

See Also:

Constant Field Values

EFFDT_NONE_MODE

static final int EFFDT_NONE_MODE

Default state of the effective date mode on the row.

See Also:

Constant Field Values

EFFDT_EXPERT_MODE

static final int EFFDT_EXPERT_MODE

If the row is in a expert mode, the runtime will not carry out any effective date specific logic for row modifications.

See Also:

setEffectiveDateMode(int), Constant Field Values

EFFDT_UPDATE_CORRECTION

static final int EFFDT_UPDATE_CORRECTION

When an effective dated row is updated in "correction" mode, the effective start date and effective end date is left unchanged. No new rows are created to track the update.

See Also:

setEffectiveDateMode(int), Constant Field Values

EFFDT_UPDATE_MODE

static final int EFFDT_UPDATE_MODE

When an effective dated row is updated in "update" mode, the modified row is end dated on the effective date and a new row is created with the changed values. The effective start date of the new row is set to effective date + 1 day and effective end date is set to end of time.

See Also:

setEffectiveDateMode(int), Constant Field Values

EFFDT_UPDATE_OVERRIDE_MODE

static final int EFFDT_UPDATE_OVERRIDE_MODE

When an effective dated row is updated in "override" mode, the modified row is end dated on the effective date and the start date of the next row in the effective date time line is set to effective date + 1 day.

See Also:

setEffectiveDateMode(int), Constant Field Values

EFFDT_UPDATE_CHANGE_INSERT_MODE

static final int EFFDT_UPDATE_CHANGE_INSERT_MODE

When an effective dated row is updated in "change insert" mode, the modified row is end dated on the effective date and a new row is inserted that fits between the effective date and the start date of the next row in the effective date time line.

See Also:

setEffectiveDateMode(int), Constant Field Values

EFFDT_UPDATE_NEW_EARLIEST_CHANGE_MODE

static final int EFFDT_UPDATE_NEW_EARLIEST_CHANGE_MODE

Updating in "new earliest change" mode is supported only in Multiple Changes Per Day. It allows creation of a new earliest change in a day.

See Also:

setEffectiveDateMode(int), Constant Field Values

EFFDT_DELETE_MODE

static final int EFFDT_DELETE_MODE

When an effective dated row is deleted in "delete" mode, the end date of the row is set to the row's effective date and all the future rows for the same key values are deleted. The DML operation on the row that was actually removed would be an update whereas for the future rows it would be a delete.

See Also:

setEffectiveDateMode(int), Constant Field Values

EFFDT_DELETE_THIS_CHANGE_MODE

static final int EFFDT_DELETE_THIS_CHANGE_MODE

When an effective dated row is deleted in "delete this change" mode, the current row is removed. If a prior row exists, its end date is set to current row's end date.

See Also:

setEffectiveDateMode(int), Constant Field Values

EFFDT_DELETE_NEXT_CHANGE_MODE

static final int EFFDT_DELETE_NEXT_CHANGE_MODE

When an effective dated row is deleted in "delete next change" mode, the end date of the row is set to the end date of adjoining row and the adjoining row is deleted. The DML operation on the row that was actually removed would be an update whereas for the adjoining row it would be a delete.

See Also:

setEffectiveDateMode(int), Constant Field Values

EFFDT_DELETE_FUTURE_CHANGE_MODE

static final int EFFDT_DELETE_FUTURE_CHANGE_MODE

When an effective dated row is deleted in "delete future change" mode, the end date of the row is set to the end of time and all the future rows for the same key values are deleted. The DML operation on the row that was actually removed would be an update whereas for the future rows it would be a delete.

See Also:

setEffectiveDateMode(int), Constant Field Values

EFFDT_DELETE_ZAP_MODE

static final int EFFDT_DELETE_ZAP_MODE

When an effective dated row is deleted in "zap" mode, all the effective dated rows with the same key values are deleted.

See Also:

setEffectiveDateMode(int), Constant Field Values

Method Detail

getKey

Key getKey()

Returns the row's key.

Returns:

the row's Key.

validate

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

void lock()

Locks the row(s) in the database table.

For a View row, this method 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

void remove()

Removes the row from the database table.

If this method is invoked on a View row or an Entity row, and if the current concurrency control mode is Transaction.LOCK_PESSIMISTIC, this method first locks the Entity row(s), and then removes the Entity row(s). Thus, this method may throw the same exceptions as lock() method.

Throws:

ReadOnlyViewObjectException - the View Object to which this row belongs is marked as read-only. You cannot remove the row.

removeFromCollection

void removeFromCollection()

Removes the row from the collection.

This method differs from remove() in that it just removes the row from the collection. It does not remove the underlying Entity row(s) or database row(s). However, once the row is removed, it cannot be used any more. If you want to remove the row from the collection and insert it elsewhere, call removeAndRetain().

removeAndRetain

void removeAndRetain()

Removes the row from the collection and then retain it for insertion into another location.

This method differs from remove() in that it just removes the row from the collection. It does not remove the underlying Entity row(s) or database row(s).

This method also differs from removeFromCollection() in that after the row is removed from the collection, it can be inserted back into the collection at another location.

refresh

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.

setNewRowState

void setNewRowState(byte state)

Sets a new unposted row, created in this transaction, to either STATUS_NEW or STATUS_INITIALIZED mode. Calling this method on a row in any other state will be a no-op.

This method should be used to create a row and then to mark it temporary (STATUS_INITIALIZED) so that an app can use the created Row to fill UIs like Table UIs with valid default values for rows. Then when the Row values are updated, UIs should once again call this method to turn the Row into new (STATUS_NEW) state before any setAttribute calls on the Row, so that the changes are validated and posted.

When a created row is in STATUS_NEW (by default) state and this method is called to turn the row in to STATUS_INITIALIZED, all updateable entities that this row comprises of, de=registers themselves from their respective transaction and validation managers. Assocation and ViewLink finders will not find/include these rows. Only the collection into which this row was inserted into will contain a reference to this row and when that collection is re-executed this row cannot be reached via the framework. To include this row again an app should call this method again with STATUS_NEW as the method-argument

When this row is in STATUS_INITIALIZED state and this method is called with STATUS_NEW state then, this new row is added back into it's relevant transaction and validation manager and will then participate in validation, transaction cycles.

Note that incase of composition if a master/detail hierarchy is being created with the intention of making them temporary (STATUS_INITIALIZED) then the logic should be: Create Master row, insert Master row into a collection, create Detail row insert detail row into a relevant collection, make detail row initialized, create/insert/change-to-initialized more detail rows and at the end set the master row as initialized.

Parameters:

state - This could be STATUS_NEW or STATUS_INITIALIZED.

Since:

9.0.3.1

isAttributeUpdateable

boolean isAttributeUpdateable(int index)

Tests if an attribute is updateable. Returns false if the attribute is read-only and true if it is updateable.

The following logic is used for determining if the attribute is updateable. If this attribute for a View row and is one which is mapped to an Entity Attribute, and if the Entity base is marked as read-only in the View Object, the attribute is read-only.

If the Entity base is marked updateable, a check is made to see if the the current user has updateable privilege on the underlying Entity row. If not, the attribute is read-only.

After this, we check the View Object's Attribute Definition. If the Attribute Definition indicates that it is READONLY, this method returns false (read-only). If the Attribute Definition says UPDATEABLE, it drops to the Entity level to determine if the Entity level Attribute Definition says it is updateable. If the attribute is UPDATEABLE_WHILE_NEW We check to see if the 'row' is new or not. (If this attribute comes from an Entity Row, the 'row' is the Entity Row. Otherwise, the 'row' is the View Row.) If the row is new, the attribute is updateable.

Parameters:

index - the index of the attribute.

Returns:

true if the attribute is updateable in this row. false if not.

isDead

boolean isDead()

An attempt to access a dead view row will lead to a DeadViewRowAccessException. Using this API method, client code can test the row state.

Returns:

true if the row is dead.

getAttributeHints

AttributeHints getAttributeHints(java.lang.String attrName)

Returns the AttributeHints object for the specified attribute for the row.

Parameters:

attrName - the name of the attribute.

Returns:

AttributeHints that describes the structure of the row.

getAttributeHints

AttributeHints getAttributeHints(int attrIndex)

Returns the AttributeHints object for the specified attribute for the row.

Parameters:

attrIndex - the index of the attribute.

Returns:

AttributeHints that describes the structure of the row.

getStructureDef

StructureDef getStructureDef()

Returns the structure of the row.

Returns:

StructureDef that describes the structure of the row.

setAttributeValues

void setAttributeValues(java.util.List names,
                      java.util.List values)

Set attribute values for the given list of attributes names. This implementation may invoke setAttribute(name, value) for each name, value pair. List size for names and values list should match up. If there are more names than values, then the names with no corresponding value entry in the values list will be ignored.

setEffectiveDateMode

void setEffectiveDateMode(int mode)

Set the Effective Date mode in which the row updates need to be carried out. The mode needs to be set prior to the changes.

Parameters:

mode - One of the effective date mode constants.

See Also:

EFFDT_NONE_MODE, EFFDT_UPDATE_CORRECTION, EFFDT_UPDATE_MODE, EFFDT_UPDATE_OVERRIDE_MODE, EFFDT_UPDATE_CHANGE_INSERT_MODE, EFFDT_UPDATE_NEW_EARLIEST_CHANGE_MODE, EFFDT_DELETE_MODE, EFFDT_DELETE_THIS_CHANGE_MODE, EFFDT_DELETE_NEXT_CHANGE_MODE, EFFDT_DELETE_FUTURE_CHANGE_MODE, EFFDT_DELETE_ZAP_MODE

getEffectiveDateMode

int getEffectiveDateMode()

Get the current effective date mode.

Returns:

The current mode of an effective dated row.

See Also:

setEffectiveDateMode(int)

getAttributeSecurityHints

SecurityHints getAttributeSecurityHints(java.lang.String attrName)

Returns the SecurityHints object for the specified attribute for the row.

Parameters:

attrName - the name of the attribute.

Returns:

SecurityHints of the row.

getAttributeSecurityHints

SecurityHints getAttributeSecurityHints(int attrIndex)

Returns the SecurityHints object for the specified attribute for the row.

Parameters:

attrIndex - the index of the attribute.

Returns:

SecurityHints of the row.

getSecurityHints

SecurityHints getSecurityHints()

Returns the SecurityHints object for the row.

Returns:

SecurityHints of the row.