oracle.jbo.server
Class EntityImpl

java.lang.Object
  oracle.jbo.server.RowImpl
      oracle.jbo.server.EntityImpl

All Implemented Interfaces:

java.util.EventListener, AttributeList, DomainOwnerInterface, JIReservedVarNames, ExprValueSupplier, JboReservedVarNames, Row, Entity, TransactionListener, TransactionPostListener, ValidationListener, ValidationManager, VariableManagerOwnerBase, XMLInterface

Direct Known Subclasses:

DSEntityImpl, EntityFacadeImpl, EntityOverRow, RowIdEntityObjectImpl

public class EntityImpl
extends RowImpl
implements Entity, DomainOwnerInterface

This class implements the middle-tier representations of database rows.

An Entity Object provides an object-oriented representation of the data it caches from a database object, such as a table or view. Database rows are presented as individual Entities, in which attributes typically correspond to columns in the corresponding table.

The status of an Entity Object's data, relative to the corresponding database data, are indicated by its current post-state and Entity-state. The Entity-state indicates the state of the Entity Object's data relative to the actual database data, and the state of the transaction itself. The Post-state indicates the state of the Entity Object's data relative to the transaction's corresponding database-data.

States are set to one of these values: STATUS_INITIALIZED, STATUS_NEW, STATUS_MODIFIED, STATUS_DELETED and STATUS_DEAD based on whether the Entity Object is being created, updated, deleted, or rolled back, respectively. These operations can set either or both the post-state and the Entity-state. The status values have a slightly different meaning depending on whether they are set for an Entity-state or a post-state:

• For Entity-state:
• STATUS_UNMODIFIED - if this Entity Object originated in the database and is unmodified, or if modifications have been committed to the database.
• STATUS_MODIFIED - if this Entity Object originated in the database, and has been modified in the current transaction.
• STATUS_NEW - if this Entity Object is new in the current transaction.
• STATUS_DELETED - if this Entity Object has been deleted in the current transaction.
• STATUS_DEAD - if this Entity Object is new in the current transaction and has been deleted.
• For post-state:
• STATUS_UNMODIFIED - if this Entity Object has been queried from the database and is unchanged, or if it has been posted to the database.
• STATUS_MODIFIED - if this Entity Object has been queried from the database and has changed.
• STATUS_INITIALIZED - if this Entity Object is new and the client application changed it's state to make this Object temporary.
• STATUS_NEW - if this Entity Object is new in the post-cycle.
• STATUS_DELETED - if this Entity Object has been marked for deletion.
• STATUS_DEAD - if this Entity Object is new, but has been deleted.

The post-state is reset to STATUS_UNMODIFIED when a post operation is invoked. The Entity-state is reset to STATUS_UNMODIFIED when the Entity Object's data is committed or rolled back.

To set/populate an attribute in an entity you could use one of the following apis

• setAttribute apis to set an attribute, invoke it's generated accessor to perform programmatic validation which then calls setAttributeInternal. All attempts to set an attribute on an entity from outside this entity object should use this method to set an attribute value. Primary key attributes should also be set using this method or setAttributeInternal().
• setAttributeInternal api to perform declarative validations on the attribute and then call populateAttributeAsChanged. Most applications will not need to call this method in any place other than the call generated in a generated setter method.
• populateAttributeAsChanged apis to avoid all attribute validations and to still mark the attribute as changed after setting it's value so that this value is picked up in entity DML when the entity is posted. These apis are typically used in new entity defaulting logic when an entity developer knows the value being set is a correct value for an attribute and should avoid validations in the entity-setter method as well as any declarative validation. Primary key attributes should not be set using populateAttribute apis.
• populateAttribute to simply set an attribute value without generating any change notifications nor marking the attribute as modified in this entity. This method is primarily used for populating attribute values when data is fetched for an entity from the datastore.

Since:

JDeveloper 3.0

Field Summary

static byte	CURRENT_VERSION
static int	DML_DELETE Identifies that a Delete operation is to be performed in the doDML() method.
static int	DML_INSERT Identifies that an Insert operation is to be performed in the doDML() method.
static int	DML_UPDATE Identifies that an Update operation is to be performed in the doDML() method.
protected static int	MAXATTRCONST Attribute constants are declared relative to their parent.
protected static java.lang.String	ORACLE_ROWID_COLUMN Identifies the column name for ROWID columns in a table.
static byte	ORIGINAL_VERSION
protected static java.lang.String	SYS_EFFDT_ROW_SPLIT
static java.lang.String	XML_CI_CHANGED
static java.lang.String	XML_PK_CHANGED
static java.lang.String	XML_PK_CHANGED_YES

Fields inherited from interface oracle.jbo.server.Entity

STATUS_DEAD, STATUS_DELETED, STATUS_MODIFIED, STATUS_UNMODIFIED

Fields inherited from interface oracle.jbo.Row

EFFDT_DELETE_FUTURE_CHANGE_MODE, EFFDT_DELETE_MODE, EFFDT_DELETE_NEXT_CHANGE_MODE, EFFDT_DELETE_THIS_CHANGE_MODE, EFFDT_DELETE_ZAP_MODE, EFFDT_EXPERT_MODE, EFFDT_NONE_MODE, EFFDT_UPDATE_CHANGE_INSERT_MODE, EFFDT_UPDATE_CORRECTION, EFFDT_UPDATE_MODE, EFFDT_UPDATE_NEW_EARLIEST_CHANGE_MODE, EFFDT_UPDATE_OVERRIDE_MODE, REFRESH_CONTAINEES, REFRESH_FORGET_NEW_ROWS, REFRESH_REMOVE_NEW_ROWS, REFRESH_UNDO_CHANGES, REFRESH_WITH_DB_FORGET_CHANGES, REFRESH_WITH_DB_ONLY_IF_UNCHANGED, STATUS_INITIALIZED, STATUS_NEW

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

Fields inherited from interface oracle.jbo.JboReservedVarNames

RESERVED_VAR_AGG_AVG, RESERVED_VAR_AGG_COUNT, RESERVED_VAR_AGG_MAX, RESERVED_VAR_AGG_MIN, RESERVED_VAR_AGG_SUM, RESERVED_VAR_AGGVAL_PREFIX, RESERVED_VAR_STRUCTURE_DEF

Fields inherited from interface oracle.jbo.expr.JIReservedVarNames

RESERVED_VAR_VALUE

Constructor Summary

EntityImpl()
Internal: Applications should not use this constructor.

Method Summary

protected void	addToTransactionManager() Adds this Entity object to its transaction manager (either another Entity object based on the containership model, or the transaction object for this session).
void	addToValidationListeners(ValidationListener listener) Adds a listener to the list of validation listeners and marks this Entity Object invalid.
void	addTransactionPostListener(TransactionPostListener listener) Adds a listener to the list of post operation listeners.
void	addTransactionPostListenerNoCheck(TransactionPostListener listener) Internal: Applications should not use this method.
void	afterCommit(TransactionEvent e) Called to report that a Commit operation has occurred.
void	afterRemove(TransactionEvent e) A cleanup routine to be invoked by transaction manager when this transaction listener is removed from the manager's list.
void	afterRollback(TransactionEvent e) Internal: Applications should not call this method.
protected void	appendXMLElementNodes(Document xmlDoc, Node node, int nContainees, long options, AttributeDefImpl[] attrs) Writes XML-element nodes for each attribute in this row and appends it to the given row-node.
protected void	appendXMLElementNodesForAttrs(Document xmlDoc, Node node, long options, AttributeDefImpl[] attrs) Applications may override this method to customize passivation of attributes by limiting or adding attributes to the given set.
void	beforeCommit(TransactionEvent e) Polls transaction listeners before a commit operation.
void	beforeRollback(TransactionEvent e) Polls transaction listeners before a rollback operation.
protected int	bindDMLStatement(int operation, java.sql.PreparedStatement stmt, AttributeDefImpl[] allAttrs, AttributeDefImpl[] retCols, AttributeDefImpl[] retKeys, java.util.HashMap retrList, boolean batchMode) Advanced: Most applications should not use this method. This method binds current attribute values to the given jdbc PreparedStatement.
protected int	bindWhereClause(java.sql.PreparedStatement stmt, AttributeDefImpl[] keyCols, java.lang.Object rowid, int bindIndex) Bind the Primary key values for the designated Statement.
protected java.lang.StringBuffer	buildDMLStatement(int operation, AttributeDefImpl[] allAttrs, AttributeDefImpl[] retCols, AttributeDefImpl[] retKeys, boolean batchMode) Advanced: Most applications should not use this method. This method constructs the DML statement and returns it as a StringBuffer.
protected AttributeDefImpl[]	buildRefreshSQL(java.lang.StringBuffer sqlBuffer, int operation, AttributeDefImpl[] columns, AttributeDefImpl[] retKeycols, boolean withInto) Builds the sql SELECT statement to fetch refresh-on-insert or update attributes and uses getRefreshSQLKeyAttrs() to create WHERE clause for this SELECT statement.
protected void	buildWhereClause(java.lang.StringBuffer buffer, AttributeDefImpl[] keyCols, java.lang.Object rowid) Construct a SQL WHERE clause for the Entity into the designated Buffer.
protected boolean	checkConsistency(SparseArray target, boolean lock) Override this method to speed up comparing the attribute values of fetched entity data with this entity's data.
protected void	clearAttributeException(int index) Cleans any exception of an attribute of the given name was set earlier and threw an exception which was cached as the transaction is in deferred mode.
protected boolean	compare(SparseArray target) Compares the data in this row with that of another.
protected void	copyChangedNonKeyAttributes(EntityImpl targetRow) This method copies all the changed attributes from one entity to another.
protected EntityImpl	copyEffDtEntity() Make a copy of this Entity for Effective Date Updates.
protected void	create(AttributeList nameValuePair) This method should be subclassed to supply programmatic default values to various attributes of a new Entity Object.
protected EntityRowSetImpl	createAssociationAccessorRS(AssociationDefImpl assocDef, ViewObjectImpl accessorVO, Row masterRow, java.lang.Object[] values)
protected ViewObjectImpl	createAssociationAccessorVO(AssociationDefImpl assocDef, java.lang.String voName, EntityAssociation eoAssoc)
protected ViewRowSetImpl	createEntityViewLinkAccessorRS(AssociationDefImpl assocDef, ViewObjectImpl accessorVO, Row masterRow, java.lang.Object[] values)
protected ViewObjectImpl	createEntityViewLinkAccessorVO(AssociationDefImpl assocDef, java.lang.String voName, ViewDefImpl vDef, ViewLinkDefImpl vlDef)
RowSet	createUnqualifiedRowSet() Creates a ViewObject over the full table behind this entity and returns a rowset of entities that belong to the source table.
protected RowSet	createViewAccessorRS(java.lang.String vaName) Internal: Applications should not use this method.
protected RowSet	createViewAccessorRS(ViewAccessorDef va) Internal: Applications should not use this method.
protected oracle.adf.share.security.authorization.PrivilegeHolder	doAllowsOperation(java.lang.String operationName)
protected void	doDML(int operation, TransactionEvent e) Performs INSERT/UPDATE/DELETE processing for the row.
protected void	doDMLForCascadeUpdate(TransactionEvent e, java.util.ArrayList tpl, java.util.ArrayList ecList, boolean startingEntity) Advanced method: Applications should typically not use this method.
protected void	doDMLWithLOBs(int operation, TransactionEvent e) Performs INSERT/UPDATE/DELETE processing for Entity Objects that contain LOBs.
void	domainToBeModified(DomainInterface d) Locks the domain object and notifies the Domain owner that the value is about to be modified.
protected void	donePostingAll(TransactionEvent e)
protected void	doRefreshSQL(int operation, java.util.ArrayList refreshAttrs) This method is called after the entity is posted to the database to refresh the required attributes.
protected void	doSelect(boolean lock) Advanced: Most applications should not use this method.
protected void	doSelectForAltKey(int keyIndex)
boolean	eventsDebugOnly() Indicates whether events are being tested.
protected ViewObjectImpl	findAssociationAccessorVO(AssociationDefImpl assocDef, java.lang.String voName, EntityAssociation eoAssoc)
protected ViewObjectImpl	findEntityViewLinkAccessorVO(AssociationDefImpl assocDef, java.lang.String voName, ViewDefImpl vDef, ViewLinkDefImpl vlDef)
protected ViewObject	findOrCreateLocalViewObject(ViewAccessorDef vaDef) Find or create the local view instance from the local view usage name.
RowSet	findOrCreateViewAccessorRS(java.lang.String vaName) Internal: Applications should not use this method.
RowSet	findOrCreateViewAccessorRS(ViewAccessorDef va) Internal: Applications should not use this method.
ViewAccessorDef	findViewAccessorDef(java.lang.String name) This method returns ViewAccessorDef with the specified name.
protected ViewObject	findViewAccessorVO(ViewAccessorDef va) Internal: Applications should not use this method.
Key	getAltKey(int keyIndex)
java.lang.Object	getAttribute(int index) Returns the value of an attribute, given an integer index value.
java.lang.Object	getAttribute(int index, byte version)
java.lang.Object	getAttribute(java.lang.String name) Returns the value of the named attribute, given a string value.
protected int	getAttributeChangedCount()
int	getAttributeCount() Counts the number of attributes in this Entity Object.
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.
int	getAttributeIndexOf(java.lang.String name) Finds the index of the named attribute.
protected java.lang.Object	getAttributeInternal(int index) Gets the attribute value by index.
java.lang.String[]	getAttributeNames() Returns an array of attribute names in this list.
protected java.lang.Object	getAttributeValue(AttributeDefImpl attr) Internal: Applications should not use this method.
java.lang.Object[]	getAttributeValues() Returns an array of attribute values in this list.
protected java.lang.Object	getAttrInvokeAccessor(int index, AttributeDefImpl attrDef)
int	getBaseAttributeCount()
protected java.lang.Object	getChangeIndicator() Gets the Change indicator attribute's value.
static java.util.Comparator	getComparator()
protected EntityImpl	getContainerEntity() Returns this entity's container in a composition association if any.
DBTransaction	getDBTransaction() Retrieves this Entity Object's database transaction.
protected int	getDynamicAttributeCount()
protected java.lang.Object	getDynamicAttributeValue(int dynAttrIndex)
protected java.lang.Object	getEffDtInitEndDateValue() This method returns the End Date value for the new rows created for the Entity.
java.lang.Object	getEffectiveDate() Obtain the Effective Date Value for the Entity.
EntityCache	getEntityCache() A Convenience for writing a lot of code.
protected EntityDefImpl	getEntityDef() Gets the Entity Definition Object which governs the structure of this Entity Object.
byte	getEntityState() Gets this Entity Object's current Entity-state in the transaction.
protected java.lang.Object	getHistoryContextForAttribute(AttributeDefImpl attr)
Key	getKey() Internal: Applications should not use thid method.
protected RowSetIterator	getListBindingRSI(ListBindingDef def)
protected java.util.List	getListBindings()
protected java.lang.Object	getOrigData(int index)
protected VariableValueManager	getParentVariableManager()
protected java.lang.Object	getPKBasedRef(AttributeDefImpl attr)
protected java.lang.Object	getPostedAttribute(int index) Gets the value originally read for this attribute from the database.
byte	getPostState() Returns this Entity Object's current post-state in the transaction.
Key	getPrimaryKey() Returns the primay key for this Entity Object's row.
protected AttributeDefImpl[]	getRefreshSQLKeyAttrs(int operation) Returns an array of AttributeDefImpl containing attributes that should be used in the where-clause (as key columns) when a select statement is executed to fetch refresh-on attributes.
protected SQLBuilder	getSQLBuilder() Get the SQLBuilderImpl which performs all SQL operations required by this Entity Object.
static java.lang.String	getStateAsString(int state) Utility function to convert the STATE to a string: todo: this is in the wrong place - it belongs in some static utility class as a converstion between byte and string
StructureDef	getStructureDef() Returns the structure of the row.
protected java.util.Vector	getTransactionListeners() Returns a copy of the list of "detail" Entities associated to this Entity Object by a composition association, participating in a transaction post and commit operations.
protected java.util.ArrayList	getTransactionListenersList() Returns a copy of the list of "detail" Entities associated to this Entity Object by a composition association, participating in a transaction post and commit operations.
int	getTransPostHandle() Advanced: Most applications should not use this method.
protected java.util.Vector	getValidationListeners() Return a copy of the list of validation listeners (that is, a list of Entities that must be validated).
protected java.util.ArrayList	getValidationListenersList() Return a copy of the list of validation listeners (that is, a list of Entities that must be validated).
protected boolean	handleActivatedRowNotFound() Returns true if this entity row that is not found anymore in the database (may have been deleted in the database), should be added to the entity-cache on activation.
protected void	handleEffectiveDateOperations() Before posting the row to the database this method is invoked for effective date book-keeping.
protected void	handleEffectiveDateRowCreate() Update the Effective Start Date and Effective End Date based on the Effective Date Transient Attribute Value and the Post state of the Entity.
protected void	handleEffectiveDateRowDelete() Performs the effective date processing for row delete operation.
protected void	handleEffectiveDateRowUpdate() Performs the effective date processing for row update operation.
protected void	handleListBindingMismatch(ListBinding lb, java.util.Map valuesMap, RowIterator listRSI)
protected void	handlePostChangesError() Called when a problem occurs while posting changes and restores an EntityImpl's state.
protected boolean	hasAttributeException(int index) Returns true if an attribute at the given index was set earlier and threw an exception which was cached as the transaction is in deferred mode.
protected boolean	hasListBindings()
protected boolean	hasUpdatePrivilege(int index)
protected void	initBusLogicGroupDefaults()
protected void	initBusLogicGroupDfltExprAttrs(AttributeList nameValuePair)
protected SparseArrayInterface	initData(int attrsCount)
protected void	initDefaultExpressionAttributes(AttributeList nameValuePair) Used to initialize this entity with values from evaluated expressions on the attributedefs.
protected void	initDefaults() Initialize Entity row's default values.
protected void	initialize()
protected boolean	isAttributeChanged(int index) Determines whether the attribute at the index been been changed.
boolean	isAttributeChanged(java.lang.String attrName) Advanced method: Applications should typically not use this method. Invokes isAttributeChanged(index) after looking up the index of an attribute with the given name.
protected boolean	isAttributeChangedInTransaction(int index) Advanced method: Applications should typically not use this method.
protected boolean	isAttributePopulated(int index) Determines whether the attribute at the specified index position is populated.
boolean	isAttributePopulated(java.lang.String attributeName) Determines whether the attribute specified by name is populated.
boolean	isAttributeUpdateable(int index) Checks if the attribute is updateable.
boolean	isDead() An attempt to access a dead view row will lead to a DeadViewRowAccessException.
boolean	isInCache()
boolean	isInvalid() Returns whether this Entity Object is invalid.
boolean	isLocked() Determines whether this Entity Object is locked.
protected boolean	isOrigDataEmpty()
protected boolean	isOrigDataPopulated(int index)
boolean	isPostedToDB() Advanced: Most applications should not use this method. For non-oracle databases, indicates if this entity is posted.
boolean	isTransientTransactionListener() Tests whether this Entity Object's transaction listener is transient or permanent.
boolean	isTransientTransactionPostListener() Tests whether this Entity Object's TransactionPostListener is transient or permanent.
boolean	isValid() Returns whether this Entity Object is valid.
protected boolean	isViewAccessorAttribute(int indexAttribute) Check if an attribute is the attribute to store view accessor RowSetIterator.
void	lock() Locks the row.
protected void	lockTopLevelEntity() Locks the top-most Entity Object by getting the master Entity Object defined by composition associations, and walking-up the chain of containership.
protected void	markViewAccessorsDirty(java.lang.String[] attrNames)
protected void	notifyAttributesAndBlgChanged(int[] attrIndices, java.lang.Object[] values, boolean blg)
protected void	notifyAttributesChanged(int[] attrIndices, java.lang.Object[] values)
protected void	notifyAttributesChanged(int[] attrIndices, java.lang.Object[] values, boolean markQCDirty)
protected void	notifyEntityActivated(boolean bPostRequired) Internal: Applications should not use this method.
void	outputEventString(EventInvocation event)
protected void	populateAttribute(int index, java.lang.Object value) Advanced method: Applications should not use this method.
protected void	populateAttribute(int index, java.lang.Object value, boolean sendNotification, boolean markAsChanged) Deprecated. since 9.0.5. Use populateAttribute(int index, Object value, boolean sendNotification, boolean markAsChanged, boolean saveOriginal) instead.
void	populateAttribute(int index, java.lang.Object value, boolean sendNotification, boolean markAsChanged, boolean saveOriginal) Advanced method: Applications should typically not use this method.
protected void	populateAttributeAsChanged(int index, java.lang.Object value) Advanced method: Applications should typically not call this method from their subclasses other then when performing programmatic attribute defaulting with proper attribute values.
void	postChanges(TransactionEvent e) Initiates a post operation for this Entity Object.
protected void	prepareForBatchDML(int operation, TransactionEvent te) Advanced: Most applications should not use this method. A pre-doDML() step which calls prepareForDML() with the appropriate operation so that applications can perform attribute updates like history column etc.
protected void	prepareForDML(int operation, TransactionEvent e) A pre-doDML() notification that allows subclasses to modify any attributes on this entity that should be updated in the database.
ViewObject	prepareVOToFetchNextEffDtRows() This method prepares NextRowsVO to fetch future effective-dated rows.
ViewObject	prepareVOToFetchNextEffDtRows(int count) Deprecated. use prepareVOToFetchNextEffDtRows().
protected ViewObject	prepareVOToFetchNextEffDtSeqRows() This method prepares NextSeqRowsVO to fetch effective-dated rows with higher sequence values within the same effective start date.
protected ViewObject	prepareVOToFetchNextEffDtSeqRows(int count) Deprecated. use prepareVOToFetchNextEffDtSeqRows().
ViewObject	prepareVOToFetchPrevEffDtRows() This method prepares PrevRowsVO to fetch earlier effective-dated rows.
ViewObject	prepareVOToFetchPrevEffDtRows(int count) Deprecated. use prepareVOToFetchPrevEffDtRows().
protected ViewObject	prepareVOToFetchPrevEffDtSeqRows() This method prepares PrevSeqRowsVO to fetch effective-dated rows with lower sequence values within the same effective start date.
protected ViewObject	prepareVOToFetchPrevEffDtSeqRows(int count) Deprecated. use prepareVOToFetchPrevEffDtSeqRows().
protected boolean	readAttrsFromXML(Element rowElt, AttributeDefImpl[] attrs, int ChangeState) Advanced: Applications should not use this method. * Reads all the attribute values from the xml-element and sets them into this row.
void	readXML(Element elem, int changeState) Reads the content of the row and updates the attributes, from given xml document.
void	refresh(int refMode) Refreshes the row's attributes with values from database.
protected void	refreshFKInNewContainees() This method is invoked by SQLBuilder when one or more of the PrimaryKey attributes are marked refresh-on-insert and DML for this entity has been executed.
protected void	registerAttributeException(AttributeDef attrDef, java.lang.Object val, JboException ex)
void	remove() Removes the row from the database table.
void	removeAndRetain() An Entity row does not support removeAndRetain().
void	removeFromCollection() An Entity row does not support removeFromCollection().
void	removeTransactionPostListener(TransactionPostListener listener) Internal: Applications should not use this method.
protected void	resetPKBasedRef()
void	revert() Reverts the row to the database's state.
protected void	revertChangesToEffDtEntity() Revert changes made to effective dated entity.
void	setAttribute(int index, java.lang.Object val) Sets the value of an attribute, given its index position.
void	setAttribute(java.lang.String name, java.lang.Object val) Sets the value of the named attribute, given its name.
protected void	setAttributeChanged(int index, boolean flag)
protected void	setAttributeInternal(int index, java.lang.Object val) Validates and sets the value of an attribute by index.
void	setAttributeValues(java.util.List names, java.util.List values) Set attribute values for the given list of attributes names.
protected void	setAttrInvokeAccessor(int index, java.lang.Object val, AttributeDefImpl attrDef)
protected void	setDynamicAttributeValue(int dynAttrIndex, java.lang.Object value)
void	setEffectiveDateMode(int mode) Set the Effective Date mode in which the row updates need to be carried out.
protected void	setEntityDef(EntityDefImpl entityDef)
protected void	setInvalid() A helper method that marks this Entity Object invalid and adds it to the ValidationListeners list of the validation manager to which this Entity Object belongs.
protected void	setLocked(boolean lockedState) Sets the locked state.
void	setNewRowState(byte state) Advanced method: Applications should not use this method. Internal method used by ViewRowImpl.setNewRowState() to make all entities that belong to that new row as new or initialized.
void	setPostedToDB(boolean b) Advanced: Most applications should not use this method. For non-oracle databases that do not support savepoint, this method should be called from the custom sql builder to mark the entity as posted so that it's not posted again during a subsequent post cycle (if this entity was already posted but other entity/entities led to an exception in the current post cycle.
void	setTransPostHandle(int hdl) Advanced: Most applications should not use this method.
java.lang.String	toString()
void	validate() Validate this Entity Object.
void	validateDateEffectivity() Validates the Effective Date aspects of an Entity to ensure that gaps or overlaps are not introduced.
protected void	validateEntity() Validates the Entities and other listeners that are members of ValidationListeners list.
protected void	vetoRemoveWithDetails(AttributeDef associationDef) If this Entity Object is a master in a composition association, this method checks that all details have already been removed from the given association attribute.

Methods inherited from class oracle.jbo.server.RowImpl

addListBindingsForAttribute, clearAllExceptions, clearAttributeException, clearRowExceptions, createXMLDefinition, doAutoClearAttribute, ensureVariableManager, findAttrAndGetIndex, getAllExceptions, getAttributeInternal, getAttributeSecurityHints, getAttributeSecurityHints, getCombinedAttrNames, getEffectiveDateMode, getExprMethodVal, getExprVarVal, getHints, getMessageBundleClass, getMethodKind, getResourceBundleDef, getRowExceptions, getSecurityHints, getVariableManager, hasAttributeException, hasDeferredExceptions, hasVariables, isRefreshRequired, isRefreshRequired, isRefreshRequired, printXMLDefinition, readXML, refreshViewAccessor, refreshViewAccessor, refreshViewAccessor, registerRowException, setAttributeInternal, setExprVarVal, setInMultiSetter, writeXML, writeXML, writeXML, writeXML

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface oracle.jbo.Row

getAttributeSecurityHints, getAttributeSecurityHints, getEffectiveDateMode, getSecurityHints

Methods inherited from interface oracle.jbo.XMLInterface

readXML, writeXML, writeXML, writeXML, writeXML

Field Detail

DML_INSERT

public static final int DML_INSERT

Identifies that an Insert operation is to be performed in the doDML() method.

See Also:

Constant Field Values

DML_UPDATE

public static final int DML_UPDATE

Identifies that an Update operation is to be performed in the doDML() method.

See Also:

Constant Field Values

DML_DELETE

public static final int DML_DELETE

Identifies that a Delete operation is to be performed in the doDML() method.

See Also:

Constant Field Values

ORACLE_ROWID_COLUMN

protected static final java.lang.String ORACLE_ROWID_COLUMN

Identifies the column name for ROWID columns in a table.

MAXATTRCONST

protected static final int MAXATTRCONST

Attribute constants are declared relative to their parent. this is the origin of the constants

See Also:

Constant Field Values

SYS_EFFDT_ROW_SPLIT

protected static final java.lang.String SYS_EFFDT_ROW_SPLIT

See Also:

Constant Field Values

CURRENT_VERSION

public static final byte CURRENT_VERSION

See Also:

Constant Field Values

ORIGINAL_VERSION

public static final byte ORIGINAL_VERSION

See Also:

Constant Field Values

XML_CI_CHANGED

public static java.lang.String XML_CI_CHANGED

XML_PK_CHANGED

public static java.lang.String XML_PK_CHANGED

XML_PK_CHANGED_YES

public static java.lang.String XML_PK_CHANGED_YES

Constructor Detail

EntityImpl

public EntityImpl()

Internal: Applications should not use this constructor.

Creates an Entity Object instance. Note that initialization of most of the internal state attributes are performed in the init method invoked by the framework after an instance of this class is created. Most applications need not invoke this constructor directly.

Method Detail

initialize

protected void initialize()

setEntityDef

protected void setEntityDef(EntityDefImpl entityDef)

initData

protected SparseArrayInterface initData(int attrsCount)

create

protected void create(AttributeList nameValuePair)

This method should be subclassed to supply programmatic default values to various attributes of a new Entity Object. For example, to create a sequence.

Instances of subclasses should call super.create() before performing any operations.

By default, if this Entity Object is part of a composition, and is a detail, this method checks for a valid foreign-key value in the given nameValuePair and sets the foreign-key value into its attributes appropriately. This logic validates that a detail Entity Object has a master Entity Object if the two are related by composition association.

If this method is overridden, the developer must ensure that in the case of composition, the nameValuePair belongs to the master Entity or that the nameValuePair contains all of the foreign keys required to create the Entity.

Parameters:

nameValuePair - a list of attribute values (name-value pairs) to be used in initializing the row. If the jbo.903.compatible property is specified, nameValuePair will never be null when this method is called by the view row's create. If jbo.903.compatible is not specified, the user must check for the possibility of nameValuePair being null, which means no attribute value is being passed in.

Throws:

oracle.jbo.InvalidOwnerException - if an attempt is made to create a detail row without a master, when the association between the master and detail is marked as composition.

initDefaultExpressionAttributes

protected void initDefaultExpressionAttributes(AttributeList nameValuePair)

Used to initialize this entity with values from evaluated expressions on the attributedefs. No events are generated and evaluated values replace any existing values in the relevant attributes unless it was overridden via nameValuePair

initBusLogicGroupDfltExprAttrs

protected void initBusLogicGroupDfltExprAttrs(AttributeList nameValuePair)

initDefaults

protected void initDefaults()

Initialize Entity row's default values. It walks through all entity definitions and initializes the attribute with the default value (from the definition).

initBusLogicGroupDefaults

protected void initBusLogicGroupDefaults()

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Returns the value of the named attribute, given a string value.

If there is a get method for this attribute in a subclass of this Entity Object, that method is invoked. The get method name is derived from the attribute name: for example, the method getDeptNo() pertains to an attribute named "Deptno".

This method should not be overridden. Instead, override getAttribute(int index).

Specified by:

getAttribute in interface AttributeList

Parameters:

name - the name of the attribute.

Returns:

the value of the attribute. The class of the returned value a Java type determined by this Entity Object's definition object.

See Also:

getAttribute(int index)

getAttribute

public java.lang.Object getAttribute(int index)

Returns the value of an attribute, given an integer index value.

If there is a get method for this attribute in a subclass of this Entity Object, that method is invoked. The get method name is derived from the attribute name: for example, the method getDeptNo() pertains to an attribute named "Deptno".

Specified by:

getAttribute in interface AttributeList

Parameters:

index - the index of the attribute.

Returns:

the value of the attribute. The class of the returned value a Java type determined by this Entity Object's definition object.

getAttrInvokeAccessor

protected java.lang.Object getAttrInvokeAccessor(int index,
                                                 AttributeDefImpl attrDef)
                                          throws java.lang.Exception

Throws:

java.lang.Exception

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object val)

Sets the value of the named attribute, given its name.

If there is a set method for this attribute in a subclass of this Entity Object, that method is invoked. The set method name is derived from the attribute name: for example, the method getDeptNo() pertains to an attribute named "Deptno".

This method should not be overridden; override setAttributeInternal instead.

Specified by:

setAttribute in interface AttributeList

Parameters:

name - the name of the attribute.

val - the value to be assigned to the attribute. The class of the returned value a Java type determined by this Entity Object's definition object.

registerAttributeException

protected void registerAttributeException(AttributeDef attrDef,
                                          java.lang.Object val,
                                          JboException ex)

Specified by:

registerAttributeException in class RowImpl

setAttribute

public void setAttribute(int index,
                         java.lang.Object val)

Sets the value of an attribute, given its index position.

If there is a set method for this attribute in a subclass of this Entity Object, that method is invoked. The set method name is derived from the attribute name: for example, the method getDeptNo() pertains to an attribute named "Deptno".

This method should not be overridden; override setAttributeInternal instead.

Specified by:

setAttribute in interface AttributeList

Parameters:

index - the index of the attribute.

val - the value to be assigned to the attribute. The class of the returned value a Java type determined by this Entity Object's definition object.

setAttrInvokeAccessor

protected void setAttrInvokeAccessor(int index,
                                     java.lang.Object val,
                                     AttributeDefImpl attrDef)
                              throws java.lang.Exception

Throws:

java.lang.Exception

setAttributeInternal

protected void setAttributeInternal(int index,
                                    java.lang.Object val)

Validates and sets the value of an attribute by index. Used by generated code from JDeveloper wizards to set an attribute value after validating the value against declarative-validators set for that attribute.

Specified by:

setAttributeInternal in class RowImpl

Parameters:

index - the index of the attribute.

val - the value of the attribute.

getStructureDef

public StructureDef getStructureDef()

Description copied from interface: Row

Returns the structure of the row.

Specified by:

getStructureDef in interface Row

Specified by:

getStructureDef in class RowImpl

Returns:

StructureDef that describes the structure of the row.

getEntityDef

protected EntityDefImpl getEntityDef()

Gets the Entity Definition Object which governs the structure of this Entity Object. This method should not be overridden.

Returns:

the EntityDefImpl.

getSQLBuilder

protected SQLBuilder getSQLBuilder()

Get the SQLBuilderImpl which performs all SQL operations required by this Entity Object.

Returns:

the SQLBuilderImpl

getTransactionListenersList

protected java.util.ArrayList getTransactionListenersList()

Returns a copy of the list of "detail" Entities associated to this Entity Object by a composition association, participating in a transaction post and commit operations.

This method can be overridden, for example, to re-order the list of detail Entities in a specified order such as "post" order.

Returns:

ArrayList containing modified children Entities that are either validated or need to be validated.

getTransactionListeners

protected java.util.Vector getTransactionListeners()

Returns a copy of the list of "detail" Entities associated to this Entity Object by a composition association, participating in a transaction post and commit operations.

This method can be overridden, for example, to re-order the list of detail Entities in a specified order such as "post" order.

Returns:

vector containing modified children Entities that are either validated or need to be validated.

getValidationListenersList

protected java.util.ArrayList getValidationListenersList()

Return a copy of the list of validation listeners (that is, a list of Entities that must be validated).

This list contains modified child Entities which must be validated before this Entity Object is validated.

This method should not be overridden.

Returns:

a list of child Entities which need to be validated.

getValidationListeners

protected java.util.Vector getValidationListeners()

Return a copy of the list of validation listeners (that is, a list of Entities that must be validated).

This list contains modified child Entities which must be validated before this Entity Object is validated.

This method should not be overridden.

Returns:

a list of child Entities which need to be validated.

clearAttributeException

protected void clearAttributeException(int index)

Cleans any exception of an attribute of the given name was set earlier and threw an exception which was cached as the transaction is in deferred mode.

Overrides:

clearAttributeException in class RowImpl

hasAttributeException

protected boolean hasAttributeException(int index)

Returns true if an attribute at the given index was set earlier and threw an exception which was cached as the transaction is in deferred mode.

Overrides:

hasAttributeException in class RowImpl

validateEntity

protected void validateEntity()

Validates the Entities and other listeners that are members of ValidationListeners list. Once all listeners are validated and removed from the list, invoke declarative validators (if attached to this Entity Object's defintion) to validate this Entity Object instance. For example, JboMandatoryAttributesValidator (if applicable) will be invoked here to perform null-value checks on mandatory attributes.

Applications should subclass this method to perform custom Entity-level validation and call super.validateEntity() to enable the framework to coordinate validation of detail Entities and validation via the declarative validators (that is, Entity validators declared at design-time).

In the case of composition, child Entities are validated from this method.

In the following example, code is added to validateEntity() to throw an exception if the value of the Emp.Ename attribute is "Jerome".

     public void validateEntity() {
       if (getEname().equals("Jerome"))
         throw new JboException("Name cannot be Jerome");
       super.validateEntity();
      }
 

Throws:

JboException - in case validation fails.

validate

public final void validate()
                    throws JboException

Validate this Entity Object.

This method is invoked by the framework during any currency change and during the commit process.

If this Entity Object is marked invalid, validation is performed as follows:

• All validation listeners are first validated. Typically, invalid children or detail Entity Object's related to this Entity Object through composition associations will be members of the validation listeners list.
• Attached declarative validators are notified to validate this Entity Object.

Once all listeners are validated, this Entity Object is then marked valid.

This method should not be overridden. Custom validation logic should be implemented by overriding the validateEntity method, which can be invoked before or after calling super.validateEntity().

Specified by:

validate in interface Row

Specified by:

validate in interface ValidationListener

Specified by:

validate in interface ValidationManager

Specified by:

validate in class RowImpl

Throws:

oracle.jbo.JboException - if this Entity Object is found to be invalid.

JboException - if validation fails.

See Also:

validate(), ViewRowImpl.validate()

getAttributeHints

public AttributeHints getAttributeHints(java.lang.String attrName)

Description copied from interface: Row

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

Specified by:

getAttributeHints in interface Row

Parameters:

attrName - the name of the attribute.

Returns:

AttributeHints that describes the structure of the row.

getAttributeHints

public AttributeHints getAttributeHints(int attrIndex)

Description copied from interface: Row

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

Specified by:

getAttributeHints in interface Row

Parameters:

attrIndex - the index of the attribute.

Returns:

AttributeHints that describes the structure of the row.

addToValidationListeners

public void addToValidationListeners(ValidationListener listener)

Adds a listener to the list of validation listeners and marks this Entity Object invalid.

Subsequent invocation of validate will invoke validate() on each of the listeners in the list.

This method could be overridden to force a child Entity to be validated.

Specified by:

addToValidationListeners in interface ValidationManager

Parameters:

listener - the listener to be added.

See Also:

validate(), ValidationManager

setInvalid

protected void setInvalid()

A helper method that marks this Entity Object invalid and adds it to the ValidationListeners list of the validation manager to which this Entity Object belongs. For example, call this method when there is a possiblity that a value in the Entity Object has changed. The framework calls this method to set the Entity Object's validation state to invalid.

getContainerEntity

protected EntityImpl getContainerEntity()

Returns this entity's container in a composition association if any.

isValid

public boolean isValid()

Returns whether this Entity Object is valid.

An Entity Object is marked valid if it has been validated and not subsequently modified or set invalid.

Specified by:

isValid in interface Entity

Specified by:

isValid in interface ValidationListener

Returns:

true if this Entity Object is valid; false otherwise.

isInvalid

public boolean isInvalid()

Returns whether this Entity Object is invalid.

An Entity Object is marked invalid if it has not been validated or if it has been validated then subsequently modified or set invalid.

Returns:

true if this Entity Object is invalid; false otherwise.

getDynamicAttributeCount

protected int getDynamicAttributeCount()

getDynamicAttributeValue

protected java.lang.Object getDynamicAttributeValue(int dynAttrIndex)

setDynamicAttributeValue

protected void setDynamicAttributeValue(int dynAttrIndex,
                                        java.lang.Object value)

getAttributeValue

protected final java.lang.Object getAttributeValue(AttributeDefImpl attr)

Internal: Applications should not use this method.

Given an attribute definition object, this method gets the value for the attribute. This method should not be overridden; override getAttributeInternal instead.

Parameters:

attr - name of the attribute definition.

Returns:

value of the attribute.

See Also:

getAttributeInternal(int index)

getChangeIndicator

protected final java.lang.Object getChangeIndicator()

Gets the Change indicator attribute's value.

Change indicator columns can be used to indicate that a change has occurred to the underlying Entity Object since we last queried against it. They are typically implemented as TimeStamp or Version (number) columns in the underlying table that are changed by the Database each time the row is updated.

This method returns NULL if:

• this Entity Object does not support change indicator columns

OR

• the change indicator column is not present

A change indicator is especially useful in Entity Objects that contain large objects, such as BLOBs. Comparing a change indicator on a row, is more convenient than comparing BLOBs.

Returns:

the value of the change indicator column or NULL if not present or applicable to this Entity Object.

getPrimaryKey

public Key getPrimaryKey()

Returns the primay key for this Entity Object's row. For example, if you are comparing two Entity Objects, you can compare the keys instead of comparing the Entities.

Typically, this method should not be overridden.

Specified by:

getPrimaryKey in interface Entity

Returns:

the primary key.

getAltKey

public Key getAltKey(int keyIndex)

getAttributeCount

public final int getAttributeCount()

Counts the number of attributes in this Entity Object.

The count includes persistent, transient, and association attributes. Attributes need not presently have values. This method will return the same value for all the Entity Object's rows.

This method should not be overridden.

The following code sample uses this method in a loop to retrieve and print Entity Object attribute names:

     //  Return the first Entity Object Row
     Row r = eo.first();
     // If we have a row, do this...
     if (r != null) {
        // Loop over the attributes in the Row and Print out the values
        for (int i = 0; i < eo.getAttributeCount(); i++ ) {
            String attrName = eo.getAttributeDef(i).getName();
            String attrVal  = r.getAttribute(i).toString();
            out.println(attrName + " = " +attrVal);
        }
     }
 

Specified by:

getAttributeCount in interface AttributeList

Specified by:

getAttributeCount in class RowImpl

Returns:

the number of attributes.

getBaseAttributeCount

public final int getBaseAttributeCount()

getPKBasedRef

protected java.lang.Object getPKBasedRef(AttributeDefImpl attr)

resetPKBasedRef

protected void resetPKBasedRef()

getAttributeInternal

protected java.lang.Object getAttributeInternal(int index)

Gets the attribute value by index. If the attribute is not already queried by using some View Object, fault-in all the attributes for this Entity Object and then return this attribute-value. For attributes that are association accessors, execute a Query if not already executed to return the associated Entities.

This method is not typically overridden. However, it could be overridden, for example, to return numeric values stored as integers, in a two-decimal format.

Specified by:

getAttributeInternal in class RowImpl

Parameters:

index - the index of the attribute.

Returns:

attribute value at given index.

handleListBindingMismatch

protected void handleListBindingMismatch(ListBinding lb,
                                         java.util.Map valuesMap,
                                         RowIterator listRSI)

Specified by:

handleListBindingMismatch in class RowImpl

hasListBindings

protected final boolean hasListBindings()

Specified by:

hasListBindings in class RowImpl

setAttributeValues

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

Specified by:

setAttributeValues in interface Row

Specified by:

setAttributeValues in class RowImpl

getDBTransaction

public final DBTransaction getDBTransaction()

Retrieves this Entity Object's database transaction.

This method should not be overridden.

Returns:

the database transaction.

getListBindings

protected java.util.List getListBindings()

Specified by:

getListBindings in class RowImpl

getListBindingRSI

protected RowSetIterator getListBindingRSI(ListBindingDef def)

Specified by:

getListBindingRSI in class RowImpl

findOrCreateViewAccessorRS

public RowSet findOrCreateViewAccessorRS(ViewAccessorDef va)

Internal: Applications should not use this method.

findViewAccessorVO

protected ViewObject findViewAccessorVO(ViewAccessorDef va)

Internal: Applications should not use this method.

createViewAccessorRS

protected RowSet createViewAccessorRS(ViewAccessorDef va)

Internal: Applications should not use this method.

findOrCreateViewAccessorRS

public RowSet findOrCreateViewAccessorRS(java.lang.String vaName)

Internal: Applications should not use this method.

Overrides:

findOrCreateViewAccessorRS in class RowImpl

createViewAccessorRS

protected RowSet createViewAccessorRS(java.lang.String vaName)

Internal: Applications should not use this method.

getEntityCache

public EntityCache getEntityCache()

A Convenience for writing a lot of code.

isAttributeChanged

protected boolean isAttributeChanged(int index)

Determines whether the attribute at the index been been changed.

Returns true if the the attribute has been changed since it was obtained from the Database. Note that if a Posting operation is performed, and the attribute value is sync'd with the database, that subsequent requests will return false, until the next time the attribute is changed.

Note that this method will return true if the value has been set to the same as the database value since it doesn't perform a value comparison.

After a Commit operation, the flag is also reset to false.

Parameters:

index - index of the attribute.

Returns:

true if the value of the attribute at the given index is changed from it's originally queried value.

isAttributeChanged

public final boolean isAttributeChanged(java.lang.String attrName)

Advanced method: Applications should typically not use this method. Invokes isAttributeChanged(index) after looking up the index of an attribute with the given name. This accessor is exposed for use in expressions only.

setAttributeChanged

protected void setAttributeChanged(int index,
                                   boolean flag)

getAttributeChangedCount

protected int getAttributeChangedCount()

isAttributeChangedInTransaction

protected final boolean isAttributeChangedInTransaction(int index)

Advanced method: Applications should typically not use this method.

Return true if the attribute at given index was modified in this transaction (even if it's current Changed state is false meaning this value was posted to the DB (but has not been committed).

isOrigDataPopulated

protected boolean isOrigDataPopulated(int index)

isOrigDataEmpty

protected boolean isOrigDataEmpty()

getOrigData

protected java.lang.Object getOrigData(int index)

getPostedAttribute

protected java.lang.Object getPostedAttribute(int index)

Gets the value originally read for this attribute from the database.

If the attribute value at the specified index has been changed (whether to the same value or a new value), return the original value as read from the database on first query. The method invokes getAttributeInternal to return the original value.

This method should not be overridden.

Parameters:

index - index of the attribute.

Returns:

attribute value as currently posted in the database.

isAttributePopulated

public boolean isAttributePopulated(java.lang.String attributeName)

Determines whether the attribute specified by name is populated.

Parameters:

attributeName - the name of the attribute.

Returns:

true if the value of the attribute is currently populated.

isAttributePopulated

protected boolean isAttributePopulated(int index)

Determines whether the attribute at the specified index position is populated.

Parameters:

index - the attribute index.

Returns:

true if the value of the attribute at the given index is currently populated.

setLocked

protected void setLocked(boolean lockedState)

Sets the locked state.

This method is protected since users should call lock to place the row into the correct locked state.

Parameters:

lockedState - set to true to lock the row.

isLocked

public boolean isLocked()

Determines whether this Entity Object is locked.

An Entity Object is locked if its corresponding database row is locked. This method should not be overridden.

Specified by:

isLocked in interface Entity

Returns:

true if the row is locked; false otherwise.

isInCache

public boolean isInCache()

getEntityState

public byte getEntityState()

Gets this Entity Object's current Entity-state in the transaction. The possible Entity-states that can be returned are:

• STATUS_UNMODIFIED - if this Entity Object originated in the database and is unmodified, or if modifications have been committed to the database.
• STATUS_MODIFIED - if this Entity Object originated in the database, and has been modified in the current transaction.
• STATUS_NEW - if this Entity Object is new in the current transaction.
• STATUS_DELETED - if this Entity Object has been deleted in the current transaction.
• STATUS_DEAD - if this Entity Object is new in the current transaction and has been deleted.

Specified by:

getEntityState in interface Entity

Returns:

this Entity Object's current Entity-state.

getPostState

public byte getPostState()

Returns this Entity Object's current post-state in the transaction. The possible post-states that can be returned are:

• STATUS_UNMODIFIED - if this Entity Object has been queried from the database and is unchanged, or if it has been posted to the database.
• STATUS_MODIFIED - if this Entity Object has been queried from the database and has changed.
• STATUS_NEW - if this Entity Object is new and not yet posted to the database.
• STATUS_INITIALIZED - if this Entity Object is new and the client code marks it to be temporary by calling Row.setNewRowState method.
• STATUS_DELETED - if this Entity Object has been marked for deletion.
• STATUS_DEAD - if this Entity Object is new, but has been deleted.

Specified by:

getPostState in interface Entity

Returns:

this Entity Object's current post-state.

getStateAsString

public static java.lang.String getStateAsString(int state)

Utility function to convert the STATE to a string: todo: this is in the wrong place - it belongs in some static utility class as a converstion between byte and string

Returns:

The state of this row.

See Also:

Row

markViewAccessorsDirty

protected void markViewAccessorsDirty(java.lang.String[] attrNames)

Overrides:

markViewAccessorsDirty in class RowImpl

donePostingAll

protected void donePostingAll(TransactionEvent e)

handlePostChangesError

protected void handlePostChangesError()

Called when a problem occurs while posting changes and restores an EntityImpl's state.

For example, when a user performs an operation (such as a commit) that posts changes, the framework will go through each EntityImpl instance that was modified during this transaction and call postChanges() to post the changes to database. If something goes wrong during this process and an exception is caught, then the framework notifies those EntityImpls by calling handlePostChangesError. The default implementation of handlePostChangesError essentially restores the EntityImpl's state.

In a composition post cycle, when the posting of one of the detail Entities throws an exception, the framework calls this method on the master Entity which internally calls this method on all of the composite Entities

A user can create a custom EntityImpl (by extending EntityImpl), and handle such an error differently from the default implemention by overriding handlePostChangesError and adding custom error-handling logic.

If this method is overridden, then the default implementation must be called with super.handlePostChangesError() to restore the Entity post states, as well as notify posted "child" Entities to handle post changes errors.

getAttributeIndexOf

public int getAttributeIndexOf(java.lang.String name)

Finds the index of the named attribute.

Specified by:

getAttributeIndexOf in interface AttributeList

Specified by:

getAttributeIndexOf in class RowImpl

Parameters:

name - an attribute name.

Returns:

the index associated with name.

Throws:

NoDefException - if this Entity Object does not have an attribute of the given name.

getAttributeNames

public java.lang.String[] getAttributeNames()

Description copied from interface: AttributeList

Returns an array of attribute names in this list.

Specified by:

getAttributeNames in interface AttributeList

Returns:

an array of attribute names.

getAttributeValues

public java.lang.Object[] getAttributeValues()

Description copied from interface: AttributeList

Returns an array of attribute values in this list.

Specified by:

getAttributeValues in interface AttributeList

Returns:

an array of attribute values.

revert

public void revert()

Reverts the row to the database's state.

Calling this method will either reset the attribute values to their database values or revert them to their default values. If the Entity Object is posted, all the attributes revert to the to unread state, so that a subsequent getAttribute call will refresh all attributes from the database.

Specified by:

revert in interface Entity

See Also:

getAttribute(int index)

refresh

public void refresh(int refMode)

Description copied from interface: Row

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

Specified by:

refresh in interface Row

Parameters:

refMode - the refresh mode.

lock

public void lock()

Locks the row.

If the row is new or already locked by this Entity Object, or if the transaction's locking mode is LOCK_NONE, this method has no effect.

If this Entity Object is contained by another (that is, it is part of a composition association and has a master Entity Object), this method locks the top-most Entity Object in the chain of containers before attempting to lock itself.

This method should not be overridden unless the application is maintaining Entity lock states.

Specified by:

lock in interface Row

Specified by:

lock in class RowImpl

Throws:

AlreadyLockedException - if the row is locked by another user or transaction.

DeadEntityAccessException - if the Entity Object is marked "unusable" or is STATUS_DEAD.

lockTopLevelEntity

protected void lockTopLevelEntity()

Locks the top-most Entity Object by getting the master Entity Object defined by composition associations, and walking-up the chain of containership. Since 9.0.3, the logic to walk up the hierarchy will stop either at the top or when a composition association is found that has the lockTopContainer flag turned off (to indicate a weak aggregation).

refreshFKInNewContainees

protected void refreshFKInNewContainees()

This method is invoked by SQLBuilder when one or more of the PrimaryKey attributes are marked refresh-on-insert and DML for this entity has been executed. In this method, this entity checks for existence of composition containees and if found, sets the foreign key attributes on these composed entities to the new values from this Entity.

addTransactionPostListener

public void addTransactionPostListener(TransactionPostListener listener)

Adds a listener to the list of post operation listeners. Typically, use this method to add the child Entities defined by composition associations to the master Entity's list of post listeners, once they are modified and validated. Can be called to add a detail Entity.

Parameters:

listener - the listener to be added.

addTransactionPostListenerNoCheck

public void addTransactionPostListenerNoCheck(TransactionPostListener listener)

Internal: Applications should not use this method.

Adds a listener to the list of post operation listeners without first checking it the Entity Object is already present. This method is faster than addTransactionPostListener, but should not be used if the listener might already be listed. Typically, child Entities defined by composition associations are added to this list, once they are modified and validated.

Parameters:

listener - the listener to be added.

See Also:

addTransactionPostListener(TransactionPostListener listener)

addToTransactionManager

protected void addToTransactionManager()

Adds this Entity object to its transaction manager (either another Entity object based on the containership model, or the transaction object for this session). This object maintains flags to indicate the status of the object's presence in the transaction manager's post-listener and transaction-listener lists, so as to avoid being in the list(s) more than once.

Subclasses that manage their own transaction ordering should invoke this method to add this Entity instance to its transaction manager instead of calling the manager's add methods.

removeTransactionPostListener

public void removeTransactionPostListener(TransactionPostListener listener)

Internal: Applications should not use this method.

Removes a listener from the list of post operation listeners.

Parameters:

listener - the listener to be removed.

See Also:

DBTransaction, ValidationManager

postChanges

public void postChanges(TransactionEvent e)

Initiates a post operation for this Entity Object.

Depending on the post-state of this Entity Object, this method calls doDML with the DML_DELETE, DML_UPDATE, or DML_INSERT flags.

In case this Entity Object is part of a composition association, this method calls postChanges on all Entities that are part of the TransactionPostListener list. Note that for delete, postChanges() on the child Entities are called before doDML() is called on this Entity Object. For updates and inserts, child Entities are posted after this Entity Object's doDML() is called.

The postChanges method calls doDML and manages the post state. To implement different behavior, it is recommended that developers override doDML or one of it's called methods (see javadoc for doDML), instead of postChanges. For example, the following code sample overrides doDML and uses postChanges to get the detail Entities and post them to the database.

   public void doDML(int operation, TransactionEvent e) {
      RowIterator details = getDetails();
      while (details.hasNext()) {
         ((EntityImpl)details.next()).postChanges(e);
      }
      super.doDML(operation, e);
   }
 

If the requirement is to only set attributes during the DML phase like say history attribute, then it should be done in prepareForDML() method so that it works consistently when this entity is posted in batch-mode or not. prepareForDML() method is invoked by the framework before doDML() and in case of post cycle from the transaction, the transaction calls prepareForDML() on all entities in the transaction list followed by doDML() on all those entities.

Specified by:

postChanges in interface TransactionPostListener

Parameters:

e - this Entity Object's transaction event.

See Also:

doDML(int, TransactionEvent), TransactionPostListener.postChanges(TransactionEvent e), TransactionPostListener

doDMLForCascadeUpdate

protected void doDMLForCascadeUpdate(TransactionEvent e,
                                     java.util.ArrayList tpl,
                                     java.util.ArrayList ecList,
                                     boolean startingEntity)

Advanced method: Applications should typically not use this method.

Special case DML for the case where PK attribute(s) are being updated for an entity which is also a master in an association which has cascade update turned on. In this case, the master needs to first clone it's row in the DB with the new Pk, move all the details to this new row with the new PK and then remove the existing mater row from the DB.

Note that this method should handle DML for this entity's composition children, if any. This list is passed in in 'tpl'.

Parameters:

e - TransactionEvent for this DML

tpl - An array of Transaction Listeners that conatins cascade updated details.

ecList - List of entities with batch mode turned on. This list is prepared by the framework and should not be 'modified'.

startingEntity - true if postChanges() was directly called on this entity.

populateAttribute

protected void populateAttribute(int index,
                                 java.lang.Object value)

Advanced method: Applications should not use this method.

Sets an attribute's value but does not mark it as updated. This method is called by query collection when populating a row with data. This is a framework-internal function and must not be called directly in client code except in the case of a composite Entity.

In a composite Entity, one Entity is comprised of two or more other Entities. An example of a composite Entity would be an Employee Entity which is comprised of a Person Entity and an Assignment Entity. The populateAttribute method could be used to populate Person and Assignment attributes when the Employee attributes are read-in.

Specified by:

populateAttribute in class RowImpl

Parameters:

index - the index of the attribute to populate.

value - the value to place in the attribute.

populateAttribute

protected void populateAttribute(int index,
                                 java.lang.Object value,
                                 boolean sendNotification,
                                 boolean markAsChanged)

Deprecated. since 9.0.5. Use populateAttribute(int index, Object value, boolean sendNotification, boolean markAsChanged, boolean saveOriginal) instead.

Advanced method: Applications should typically not use this method.

Sets an attribute's value and optionally mark it as updated and optionally send events to listeners about the change. Note that this method avoids all validations written in the attribute-setter or rules installed for this attribute.

Invoke this method from a sub-class if the sub-class is implementing it's own data-source. This method may also be used by a sub-class to implement refresh-on-update/refresh-on-insert features if the sub-class is implementing it's own data-sink.

Parameters:

index - a 1-based index into the columns.

value - the value for the column.

sendNotification - notify the dependent ViewObjects that this attribute has changed

markAsChanged - mark this attribute as changed so that it's picked up by doDML() for actual database updates.

populateAttribute

public void populateAttribute(int index,
                              java.lang.Object value,
                              boolean sendNotification,
                              boolean markAsChanged,
                              boolean saveOriginal)

Advanced method: Applications should typically not use this method.

Sets an attribute's value and optionally mark it as updated and optionally send events to listeners about the change. Note that this method avoids all validations written in the attribute-setter or rules installed for this attribute.

Invoke this method from a sub-class if the sub-class is implementing it's own data-source. This method may also be used by a sub-class to implement refresh-on-update/refresh-on-insert features if the sub-class is implementing it's own data-sink.

Parameters:

index - a 1-based index into the columns.

value - the value for the column.

sendNotification - notify the dependent ViewObjects that this attribute has changed

markAsChanged - mark this attribute as changed so that it's picked up by doDML() for actual database updates.

saveOriginal - indicates if this method should cache the original value of this attribute (as fetched) in the entity for refresh, lock and other usages. By default most callers should pass this flag as true when modifying an entity attribute value for updates (without affecting the entity states).

populateAttributeAsChanged

protected void populateAttributeAsChanged(int index,
                                          java.lang.Object value)

Advanced method: Applications should typically not call this method from their subclasses other then when performing programmatic attribute defaulting with proper attribute values.

Sets an attribute's value and also marks the attribute as changed in this row. Primary key attributes should not be set using populateAttribute apis.

This method is called by query collection when populating a row with data. This is a framework-internal function and must not be called directly in client code except in the case of a composite Entity or defaulting. This method avoids all programmatic and declarative validations on an attribute and still sets the data value for the attribute and marks the attribute as changed so that the value is posted during entity DML.

In a composite Entity, one enitity is comprised of two or more other Entities. An example of a composite Entity would be an Employee Entity which is comprised of a Person Entity and an Assignment Entity. The populateAttribute method could be used to populate Person and Assignment attributes when the Employee attributes are read-in.

This method does not change Entity Validation, Post or Transaction States. If this entity is not already marked invalid or not in the transaction's lists, this method will not mark the entity invalid or add it into transaction's lists.

Parameters:

index - the index of the attribute to populate.

value - the value to place in the attribute.

See Also:

populateAttribute(int index, Object value)

checkConsistency

protected boolean checkConsistency(SparseArray target,
                                   boolean lock)

Override this method to speed up comparing the attribute values of fetched entity data with this entity's data. This method is called when the entity is locked or when this entity is being faulted in and the entity is in un-modified state in a non-pessimistic transaction.

In builds before 10.1.2, this method was not called and for modified or removed Entities under optimisitic locking mode that were faulted in, did not go through this consistency check. They would simply faultin any db values on unmodified attributes. To achieve that old behavior, return true in this method's override, when the entity is modified or removed and lock parameter is sent in as false i.e., if (getPostState() != STATUS_UNMODIFIED && !lock) return true;

This method calls compare(SparseArray target) for comparision implementation.

This method returns true the return value from compare(target) call. If this method returns false, SQLBuilder will throw a RowInconsistentException to indicate difference in the database values for this entity.

Returns:

true if the data is the same; false otherwise.

compare

protected boolean compare(SparseArray target)

Compares the data in this row with that of another.

This method returns true if the values are "the same" and false if they are not.

This method uses the ChangeIndicator attribute, if it is present, for the comparison. If ChangeIndicator is not present, then this method compares the data for overlapping columns between the entity and the given array.

Applications should override this method to implement custom comparision of specific attributes and avoid deep comparision of every entity attribute (in case changeIndicator attribute is not defined in this entity). If ChangeIndicator attribute is present only that attribute is compared to check if the target data matches this Entity. Also, if the application has mutli-part ChangeIndicator, this method should be used to implement comparision of multi-part ChangeIndicator attributes to speedup comparision.

Returns:

true if the data is the same; false otherwise.

notifyAttributesChanged

protected void notifyAttributesChanged(int[] attrIndices,
                                       java.lang.Object[] values)

notifyAttributesAndBlgChanged

protected void notifyAttributesAndBlgChanged(int[] attrIndices,
                                             java.lang.Object[] values,
                                             boolean blg)

notifyAttributesChanged

protected void notifyAttributesChanged(int[] attrIndices,
                                       java.lang.Object[] values,
                                       boolean markQCDirty)

afterCommit

public void afterCommit(TransactionEvent e)

Description copied from interface: TransactionListener

Called to report that a Commit operation has occurred.

Specified by:

afterCommit in interface TransactionListener

Parameters:

e - a transaction event.

outputEventString

public void outputEventString(EventInvocation event)

eventsDebugOnly

public boolean eventsDebugOnly()

Indicates whether events are being tested. If it returns true, it implies that Fabric is not present and we should not attempt to actually raise the event. We should just dump its output for testing. If it returns false, the default, Fabric is assumed to be present and we will attempt to raise the appropriate events to Fabric. This is necessary to be able to have adequate error handling in the Fabric case while not interfering with the test case.

afterRollback

public void afterRollback(TransactionEvent e)

Internal: Applications should not call this method.

Initiates a state change and polls listeners following a rollback operation.

Resets the EntityState to STATUS_DEAD or STATUS_UNMODIFIED for new or updated/removed rows respectively. Sets other status flags for this Entity Object so that it behaves just like it was fetched for the first time from the database.

This method should not be overridden.

Specified by:

afterRollback in interface TransactionListener

Parameters:

e - this Entity Object's transaction event.

See Also:

TransactionListener

afterRemove

public void afterRemove(TransactionEvent e)

A cleanup routine to be invoked by transaction manager when this transaction listener is removed from the manager's list.

Specified by:

afterRemove in interface TransactionListener

Parameters:

e - this Entity Object's transaction event.

isTransientTransactionListener

public boolean isTransientTransactionListener()

Tests whether this Entity Object's transaction listener is transient or permanent.

Transient listeners are automatically removed at the end of the transaction cycle; permanent listeners remain.

Specified by:

isTransientTransactionListener in interface TransactionListener

Returns:

true if the listener is transient.

beforeCommit

public void beforeCommit(TransactionEvent e)

Polls transaction listeners before a commit operation.

Specified by:

beforeCommit in interface TransactionListener

Parameters:

e - this Entity Object's transaction event.

See Also:

TransactionListener

isPostedToDB

public boolean isPostedToDB()

Advanced: Most applications should not use this method. For non-oracle databases, indicates if this entity is posted. For use in custom SQLBuilder to check if this entity was posted in a previous post cycle.

Specified by:

isPostedToDB in interface TransactionPostListener

setPostedToDB

public void setPostedToDB(boolean b)

Advanced: Most applications should not use this method. For non-oracle databases that do not support savepoint, this method should be called from the custom sql builder to mark the entity as posted so that it's not posted again during a subsequent post cycle (if this entity was already posted but other entity/entities led to an exception in the current post cycle.

Specified by:

setPostedToDB in interface TransactionPostListener

getTransPostHandle

public int getTransPostHandle()

Advanced: Most applications should not use this method.

Implements the getTransPostHandle method for the transaction post listener (TransactionPostListener) interface.

Transaction post handle is a handle identifying a row object in the transaction post listener list. If the object does not have a transaction post handle, this method returns -1.

Specified by:

getTransPostHandle in interface TransactionPostListener

Returns:

the transaction post listener handle or -1, which means no transaction post handle.

See Also:

TransactionPostListener

setTransPostHandle

public void setTransPostHandle(int hdl)

Advanced: Most applications should not use this method.

Implements the setTransPostHandle method for the transaction post listener (TransactionPostListener) interface.

Transaction post handle is a handle identifying a row object in the transaction post listener list.

Specified by:

setTransPostHandle in interface TransactionPostListener

Parameters:

hdl - the transaction post handle.

See Also:

TransactionPostListener

isTransientTransactionPostListener

public boolean isTransientTransactionPostListener()

Tests whether this Entity Object's TransactionPostListener is transient or permanent.

Transient listeners are automatically removed at the end of the transaction cycle; permanent listeners remain.

Specified by:

isTransientTransactionPostListener in interface TransactionPostListener

Returns:

true if the listener is transient.

See Also:

TransactionPostListener

beforeRollback

public void beforeRollback(TransactionEvent e)

Polls transaction listeners before a rollback operation.

Specified by:

beforeRollback in interface TransactionListener

Parameters:

e - this Entity Object's transaction event.

See Also:

TransactionListener

doSelect

protected void doSelect(boolean lock)

Advanced: Most applications should not use this method.

Performs SELECT/SELECT FOR UPDATE processing for the row. This method faults-in all column-values from the database object for this Entity Object.

This method can be overridden, for example, if you want to fill in the Entity Object values yourself.

Parameters:

lock - true generates a "SELECT for UPDATE"

doSelectForAltKey

protected void doSelectForAltKey(int keyIndex)

prepareForDML

protected void prepareForDML(int operation,
                             TransactionEvent e)

A pre-doDML() notification that allows subclasses to modify any attributes on this entity that should be updated in the database.

In case of batch mode, the modified entities in a Transaction are posted in two steps. First all entities are notified with prepareForDML() so that enties can make changes to any attributes like say history column that needs to be updated right before a DML occurs. Then the doDML() is called on the entities to execute the DML that includes any changes done to this entity during the prepareForDML() phase.

Incase of non-batch mode, postChanges() method on the Entity invokes prepareForDML() followed by doDML() for so that subclasses can consistently write custom setAttribute logic in prepareForDML() which will be posted to the database via a DML statement in doDML().

Parameters:

operation - the integer representation of DML_INSERT, DML_UPDATE, or DML_DELETE.

e - this Entity Object's transaction event.

prepareForBatchDML

protected void prepareForBatchDML(int operation,
                                  TransactionEvent te)

Advanced: Most applications should not use this method. A pre-doDML() step which calls prepareForDML() with the appropriate operation so that applications can perform attribute updates like history column etc.

This method also adjusts count of entities of a particular operation type to figure out if that operation has to be batched or not. Subclasses that override this method should call super.prepareForBatchDML() with the right operation type if this entity has consider batch operations.

doDML

protected void doDML(int operation,
                     TransactionEvent e)

Performs INSERT/UPDATE/DELETE processing for the row. Override this method to provide custom logic for processing inserts, updates, and deletes. Note, do not set any of this Entity's attributes in this method if this entity needs to work alike in both batch and non-batchmode cases. Perform all setAttributes that needs to done in postChanges() phase in prepareForDML().

This method calls buildDMLStatement() to build the DML string based on the DML operation to be performed. For insert and update, the DML statement will only set the values that have been modified/changed. Other attributes do not participate in the DML.

Next, bindDMLStatement() is called to bind the DML statement with values to be updated and any other where-clause and returning parameters. After this, it executes the jdbc-statement or adds the current DML as a batch operation into a batched jdbc-statement, to be executed in Transaction.postChanges().

Here is sample code for overriding the doDML() method of any Entity Object's EntityImpl class to invoke a stored procedure, and pass arguments. For example, given a PL/SQL stored procedure like:

 PROCEDURE updateDepartment( p_Deptno NUMBER,
                             p_Dname  VARCHAR2,
                             p_Loc    VARCHAR2 )
 

The code to call it when an Entity is updated would look like this: Note: The following code assumes only updates are possible, disallowing inserts and deletes by ignoring them in the doDML() method.

    public void doDML(int operation, TransactionEvent e) {
       // Don't call the superclass. This procedure handles only updates
       //super.doDML(operation, e);
       CallableStatement stmt = null;
       // ONLY Perform updates, this Entity won't allow inserts/deletes.
       if (operation == DML_UPDATE)
       {
         // Prepare JDBC CallableStatement with the Stored Procedure Call
         String updateStr = "{call updateDepartment(?,?,?)}";
         stmt = getDBTransaction().createCallableStatement(updateStr, 1);
         try
         {
            // Bind the Statement Parameters and Execute this Statement
            stmt.setString(1, getDeptno().toString());
            stmt.setString(2, getDname().toString());
            stmt.setString(3, getLoc().toString());
            stmt.execute();
          }
          catch (Exception ex)
          {
            throw new oracle.jbo.JboException(ex);
          }
          finally
          {
             try
             {
                stmt.close();
             }
             catch (Exception nex)
             {
          }
        }
      }
    }
 

Parameters:

operation - the integer representation of DML_INSERT, DML_UPDATE, or DML_DELETE.

e - this Entity Object's transaction event.

doDMLWithLOBs

protected void doDMLWithLOBs(int operation,
                             TransactionEvent e)

Performs INSERT/UPDATE/DELETE processing for Entity Objects that contain LOBs. This method is called by doDML when the Entity Object is found to contain LOBs.

The method uses a two stage process to first get the LOB locator, then post the LOB values individually. Typically, you would override this method when you want to take control over how to post the LOB.

Parameters:

operation - DML_INSERT, DML_UPDATE or DML_DELETE

e - this Entity Object's transaction event.

See Also:

doDML(int operation, TransactionEvent e)

vetoRemoveWithDetails

protected void vetoRemoveWithDetails(AttributeDef associationDef)

If this Entity Object is a master in a composition association, this method checks that all details have already been removed from the given association attribute. Typically, this method is used to effectively remove compositions.

Parameters:

associationDef - the association attribute defining the composition.

Throws:

RemoveWithDetailsException - if an attempt is made to remove the master Entity Object before removing its children.

remove

public void remove()

Removes the row from the database table.

In the case of a composition where this Entity is a master, this method calls vetoRemoveWithDetails with an Association attribute that defines the composition, to perform a check for existence of detail Rows.

Override this method to add your own business logic for the remove operation. For example, you can implement business logic that throws an exception that report why an Entity Object cannot be removed.

Specified by:

remove in interface Row

Specified by:

remove in class RowImpl

Throws:

RemoveWithDetailsException - if an attempt is made to is made to remove the master Entity Object before removing its children.

removeFromCollection

public void removeFromCollection()

An Entity row does not support removeFromCollection().

Specified by:

removeFromCollection in interface Row

Throws:

InvalidOperException - it is illegal to call this method on an Entity row.

removeAndRetain

public void removeAndRetain()

An Entity row does not support removeAndRetain().

Specified by:

removeAndRetain in interface Row

Throws:

InvalidOperException - it is illegal to call this method on an Entity row.

getKey

public Key getKey()

Internal: Applications should not use thid method.

Gets the Entity Object's Primary Key.

Specified by:

getKey in interface Row

Specified by:

getKey in class RowImpl

Returns:

the Primary Key.

isAttributeUpdateable

public boolean isAttributeUpdateable(int index)

Checks if the attribute is updateable. This method finds the attribute, given its index, then examines its updateable status which can be READ_ONLY, UPDATEABLE_WHILE_NEW, or UPDATEABLE.

This method can be overridden. For example, override this method if you want to check the updateable status and you have dependencies between two or more attributes.

Specified by:

isAttributeUpdateable in interface Row

Specified by:

isAttributeUpdateable in class RowImpl

Parameters:

index - the attribute's index (0-based).

Returns:

false if the attribute is READ_ONLY; true if attribute is UPDATEABLE or if the attribute is UPDATEABLE_WHILE_NEW and the current row is new.

isDead

public boolean isDead()

Description copied from interface: Row

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

Specified by:

isDead in interface Row

Specified by:

isDead in class RowImpl

Returns:

true if the row is dead.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

domainToBeModified

public void domainToBeModified(DomainInterface d)

Locks the domain object and notifies the Domain owner that the value is about to be modified. This method is called from a struct, composite, or array domain when an attribute is changed. For example, if the value of a BLOB is changed, the framework calls this method to lock the container.

Specified by:

domainToBeModified in interface DomainOwnerInterface

Parameters:

d - name of the domain interface that is being changed.

appendXMLElementNodes

protected void appendXMLElementNodes(Document xmlDoc,
                                     Node node,
                                     int nContainees,
                                     long options,
                                     AttributeDefImpl[] attrs)

Description copied from class: RowImpl

Writes XML-element nodes for each attribute in this row and appends it to the given row-node.

Override this method to perform custom XML-rendering on a Row.

Parameters:

xmlDoc - name of the XML document where the node resides.

node - the name of the Row object node where new nodes will be appended.

nContainees - number of child levels deep to appendrow nodes.

options - a set of bit flags that will control the writeXML behavior.

attrs - an array of AttriubuteDefImpls.

appendXMLElementNodesForAttrs

protected void appendXMLElementNodesForAttrs(Document xmlDoc,
                                             Node node,
                                             long options,
                                             AttributeDefImpl[] attrs)

Applications may override this method to customize passivation of attributes by limiting or adding attributes to the given set.

notifyEntityActivated

protected void notifyEntityActivated(boolean bPostRequired)

Internal: Applications should not use this method.

Notification from the Transaction activation, when a new/inserted entity is activated from a passivation-store. By Default, this method posts this entity to the database if the bPostRequired argument is true, so that subsequent View Objects that are activated will see the new rows when their query is executed. This flag is true when this entity is a top-most entity in a composition and it is a new/inserted entity or one of it's primary key constituent attributes were modified before this entity was passivated.

handleActivatedRowNotFound

protected boolean handleActivatedRowNotFound()

Returns true if this entity row that is not found anymore in the database (may have been deleted in the database), should be added to the entity-cache on activation. Most Applications may log a warning and return false to silently ignore the deleted row. Some Applications may return true to add the entity and on post a RowAlreadyDeletedException will be thrown for this entity.

By default this method returns true so that this entity is cached in the entity cache.

readAttrsFromXML

protected boolean readAttrsFromXML(Element rowElt,
                                   AttributeDefImpl[] attrs,
                                   int ChangeState)

Advanced: Applications should not use this method. * Reads all the attribute values from the xml-element and sets them into this row. If the xml has a process instruction of the form: then, invokes remove() on this row.

At the entity layer, the two meaningful values for this state are: XMLInterface.XML_OPT_CHANGES_ONLY or XMLInterface.XML_OPT_ALL_ROWS As of 904, if the value is CHANGES_ONLY, then the entity is being passivated/activated during the ApplicationModule passivation/activation call. Otherwise the entity is being activated due to commitAndSync() call triggered to sync up all AMs in a pool with the latest commits from the AM in hand.

Returns:

true when the row is good to be added into cache/collection. Returns false when this row has been removed based on the xml element being read.

readXML

public final void readXML(Element elem,
                          int changeState)

Reads the content of the row and updates the attributes, from given xml document. If there's a process instruction in the row like: then calls remove on this row.

Specified by:

readXML in interface XMLInterface

Specified by:

readXML in class RowImpl

Parameters:

elem - name of the XML element.

changeState - the number of child levels deep to which data should be read.

doRefreshSQL

protected void doRefreshSQL(int operation,
                            java.util.ArrayList refreshAttrs)

This method is called after the entity is posted to the database to refresh the required attributes. This method is called for entities that have refresh-on-insert or refresh-on-update attributes in the following cases:

• When Oracle SQLBuilder is in use and this Entity is set to use Batch-mode DML
• When any other SQLBuilder is in use

In both cases however, if refresh-on-insert or update setting is set on an attribute which is a primary key attribute, then this method will fail to fetch the entity as the primary key in the database for the equivalent row would have potentially changed. If that's true, then subclasses need to implement this method and perform "custom" sql to fetch the refresh-attrs based on some unique criteria for this entity.

getRefreshSQLKeyAttrs

protected AttributeDefImpl[] getRefreshSQLKeyAttrs(int operation)

Returns an array of AttributeDefImpl containing attributes that should be used in the where-clause (as key columns) when a select statement is executed to fetch refresh-on attributes.

If the primary key attributes do not have refresh-on flag set for the given operation (Insert or Update), then these attributes are returned.

If one or more of the primary key attributes are also refresh-on-insert or update attributes and unique-key attributes are set on this entity, then this method returns an array of unique-key attributes. If not, then a warning is printed on the diagnostic and this method returns an array of primary keys.

Subclasses should override this method to return a customized list of attributes to use to create a where-clause for the select statement to be used to fetch refresh-on attributes. This method is called for entities that have refresh-on-insert or refresh-on-update attributes in the following cases:

• When Oracle SQLBuilder is in use and this Entity is set to use Batch-mode DML
• When Oracle SQLBuilder is in use and this Entity's definition is set to not use RETURNING clause
• When any other SQLBuilder is in use

buildRefreshSQL

protected AttributeDefImpl[] buildRefreshSQL(java.lang.StringBuffer sqlBuffer,
                                             int operation,
                                             AttributeDefImpl[] columns,
                                             AttributeDefImpl[] retKeycols,
                                             boolean withInto)

Builds the sql SELECT statement to fetch refresh-on-insert or update attributes and uses getRefreshSQLKeyAttrs() to create WHERE clause for this SELECT statement. This method is called for entities that have refresh-on-insert or refresh-on-update attributes in the following cases:

• When Oracle SQLBuilder is in use and this Entity is set to use Batch-mode DML
• When Oracle SQLBuilder is in use and this Entity's definition is set to not use RETURNING clause
• When any other SQLBuilder is in use

Returns:

AttributeDefImpl array containing the attributes that are used in the WHERE clause.

bindDMLStatement

protected int bindDMLStatement(int operation,
                               java.sql.PreparedStatement stmt,
                               AttributeDefImpl[] allAttrs,
                               AttributeDefImpl[] retCols,
                               AttributeDefImpl[] retKeys,
                               java.util.HashMap retrList,
                               boolean batchMode)
                        throws java.sql.SQLException

Advanced: Most applications should not use this method. This method binds current attribute values to the given jdbc PreparedStatement.

Parameters:

operation - The current DML operation.

stmt - A jdbc PreparedStatement containing a SQL statement built in buildDMLStatement()

allAttrs - An array of all attribute definitions for this entity. This is passed in for performance reasons, so that the array is not built again.

retCols - An array of non-primary key attributes that are marked refresh-on-insert or refresh-on-update for an Insert or Update operation respectively. It could be an empty array or null in case of Delete operation.

retKeys - An array of primary key attributes that are marked refresh-on-insert or refresh-on-update for an Insert or Update operation respectively. It could be an empty array or null in case of Delete operation.

retrList - Hashmap of bind-variable indices (as keys) and attribute definitions (as values) that are being returned for refresh-on-insert/update in this DML.

batchMode - True if this DML statement will be used in creating a batchmode jdbc statement.

Returns:

Last index of a jdbc-bind variable

Throws:

java.sql.SQLException

buildDMLStatement

protected java.lang.StringBuffer buildDMLStatement(int operation,
                                                   AttributeDefImpl[] allAttrs,
                                                   AttributeDefImpl[] retCols,
                                                   AttributeDefImpl[] retKeys,
                                                   boolean batchMode)

Advanced: Most applications should not use this method. This method constructs the DML statement and returns it as a StringBuffer.

Parameters:

operation - The current DML operation.

allAttrs - An array of all attribute definitions for this entity. This is passed in for performance reasons, so that the array is not built again.

retCols - An array of non-primary key attributes that are marked refresh-on-insert or refresh-on-update for an Insert or Update operation respectively. It could be an empty array or null in case of Delete operation.

retKeys - An array of primary key attributes that are marked refresh-on-insert or refresh-on-update for an Insert or Update operation respectively. It could be an empty array or null in case of Delete operation.

batchMode - True if this DML statement will be used in creating a batchmode jdbc statement.

Returns:

A StringBuffer containing the INSERT, UPDATE or DELETE SQL-Statememt based on the operation to be performed. This method is called in doDML().

getHistoryContextForAttribute

protected java.lang.Object getHistoryContextForAttribute(AttributeDefImpl attr)

setNewRowState

public void setNewRowState(byte state)

Advanced method: Applications should not use this method. Internal method used by ViewRowImpl.setNewRowState() to make all entities that belong to that new row as new or initialized. Initialized rows are tracked at ViewObject's collection and entities should not be marked as initialized from a context other than the containing ViewRowImpl.

Specified by:

setNewRowState in interface Row

Specified by:

setNewRowState in class RowImpl

Parameters:

state - This could be STATUS_NEW or STATUS_INITIALIZED.

getAttribute

public java.lang.Object getAttribute(int index,
                                     byte version)

hasUpdatePrivilege

protected boolean hasUpdatePrivilege(int index)

buildWhereClause

protected void buildWhereClause(java.lang.StringBuffer buffer,
                                AttributeDefImpl[] keyCols,
                                java.lang.Object rowid)

Construct a SQL WHERE clause for the Entity into the designated Buffer. This routine constructs a SQL WHERE clause in the StringBuffer passed. It does this by appending the various components of the WHERE Clause (based upon Primary Key columns) into the buffer area.

This method is called from SQLBuilder for:

• doEntitySelect
• buildUpdateStatement
• buildDeleteStatement

The presence or absence of the ROWID value determines whether the ROWID will be used for Row access.

Parameters:

buffer - the area into which the WHERE Clause will be placed.

keyCols - the Primary key columns.

rowid - the ROWID for the ROW if known.

bindWhereClause

protected int bindWhereClause(java.sql.PreparedStatement stmt,
                              AttributeDefImpl[] keyCols,
                              java.lang.Object rowid,
                              int bindIndex)
                       throws java.sql.SQLException

Bind the Primary key values for the designated Statement. This routine will perform the bind operation for each of the Primary Key columns.

The presence or absence of the ROWID value determines whether the ROWID will be used for Row access.

Parameters:

stmt - the statement to bind the columns to.

keyCols - the Primary key columns.

rowid - the ROWID for the row if known.

bindIndex - the baseline idx for performing the bind operations.

Throws:

java.sql.SQLException

findAssociationAccessorVO

protected ViewObjectImpl findAssociationAccessorVO(AssociationDefImpl assocDef,
                                                   java.lang.String voName,
                                                   EntityAssociation eoAssoc)

createAssociationAccessorVO

protected ViewObjectImpl createAssociationAccessorVO(AssociationDefImpl assocDef,
                                                     java.lang.String voName,
                                                     EntityAssociation eoAssoc)

createAssociationAccessorRS

protected EntityRowSetImpl createAssociationAccessorRS(AssociationDefImpl assocDef,
                                                       ViewObjectImpl accessorVO,
                                                       Row masterRow,
                                                       java.lang.Object[] values)

findEntityViewLinkAccessorVO

protected ViewObjectImpl findEntityViewLinkAccessorVO(AssociationDefImpl assocDef,
                                                      java.lang.String voName,
                                                      ViewDefImpl vDef,
                                                      ViewLinkDefImpl vlDef)

createEntityViewLinkAccessorVO

protected ViewObjectImpl createEntityViewLinkAccessorVO(AssociationDefImpl assocDef,
                                                        java.lang.String voName,
                                                        ViewDefImpl vDef,
                                                        ViewLinkDefImpl vlDef)

createEntityViewLinkAccessorRS

protected ViewRowSetImpl createEntityViewLinkAccessorRS(AssociationDefImpl assocDef,
                                                        ViewObjectImpl accessorVO,
                                                        Row masterRow,
                                                        java.lang.Object[] values)

getParentVariableManager

protected VariableValueManager getParentVariableManager()

Specified by:

getParentVariableManager in class RowImpl

createUnqualifiedRowSet

public RowSet createUnqualifiedRowSet()

Creates a ViewObject over the full table behind this entity and returns a rowset of entities that belong to the source table.

handleEffectiveDateOperations

protected void handleEffectiveDateOperations()

Before posting the row to the database this method is invoked for effective date book-keeping. For Entity Rows that are created for the first time, the Effective Date values are populated. Entity row update may cause an effective date split. Entity row delete may cause more than one physical row to be deleted. If the Effective Date mode is set to Expert mode the framework assumes that the client has populated all the required values and effective date logic need not be applied. For more information about Effective Date Update and Delete modes refer to setEffectiveDateMode.

validateDateEffectivity

public void validateDateEffectivity()

Validates the Effective Date aspects of an Entity to ensure that gaps or overlaps are not introduced. If the Entity is updated, created or deleted in expert mode no effective date validation is performed.

handleEffectiveDateRowCreate

protected void handleEffectiveDateRowCreate()

Update the Effective Start Date and Effective End Date based on the Effective Date Transient Attribute Value and the Post state of the Entity. [MCPD]: Set sequence value and mark it as the latest changed row.

handleEffectiveDateRowDelete

protected void handleEffectiveDateRowDelete()

Performs the effective date processing for row delete operation. Depending on the delete mode the row delete operation may be converted to an update operation.

See Also:

Row.setEffectiveDateMode(int)

handleEffectiveDateRowUpdate

protected void handleEffectiveDateRowUpdate()

Performs the effective date processing for row update operation. Depending on the update mode the attribute values are updated. New rows may be created by copying the updated row and changing the effective dates.

See Also:

Row.setEffectiveDateMode(int)

prepareVOToFetchPrevEffDtRows

public ViewObject prepareVOToFetchPrevEffDtRows(int count)

Deprecated. use prepareVOToFetchPrevEffDtRows().

prepareVOToFetchPrevEffDtRows

public ViewObject prepareVOToFetchPrevEffDtRows()

This method prepares PrevRowsVO to fetch earlier effective-dated rows.

Returns:

The view object prepared to fetch past effective-dated rows.

prepareVOToFetchNextEffDtRows

public ViewObject prepareVOToFetchNextEffDtRows(int count)

Deprecated. use prepareVOToFetchNextEffDtRows().

prepareVOToFetchNextEffDtRows

public ViewObject prepareVOToFetchNextEffDtRows()

This method prepares NextRowsVO to fetch future effective-dated rows.

Returns:

The view object prepared to fetch future effective-dated rows.

prepareVOToFetchPrevEffDtSeqRows

protected ViewObject prepareVOToFetchPrevEffDtSeqRows(int count)

Deprecated. use prepareVOToFetchPrevEffDtSeqRows().

prepareVOToFetchPrevEffDtSeqRows

protected ViewObject prepareVOToFetchPrevEffDtSeqRows()

This method prepares PrevSeqRowsVO to fetch effective-dated rows with lower sequence values within the same effective start date.

prepareVOToFetchNextEffDtSeqRows

protected ViewObject prepareVOToFetchNextEffDtSeqRows(int count)

Deprecated. use prepareVOToFetchNextEffDtSeqRows().

prepareVOToFetchNextEffDtSeqRows

protected ViewObject prepareVOToFetchNextEffDtSeqRows()

This method prepares NextSeqRowsVO to fetch effective-dated rows with higher sequence values within the same effective start date.

copyEffDtEntity

protected EntityImpl copyEffDtEntity()

Make a copy of this Entity for Effective Date Updates. This method is invoked for Effective Dated Entities only during row split. If the row split is happening during Post (default behavior), then during batch update overriding method should be careful to only change already dirtied attributes. For batch entities the update statement is pre-computed in beforePost so any new dirty attributes in this method will not be taken into account.

Returns:

A copy of this object.

revertChangesToEffDtEntity

protected void revertChangesToEffDtEntity()

Revert changes made to effective dated entity. The changes to the effective dated entity are unique. It is gaurenteed that no primary key/foreign key updating/checking is required during revert.

copyChangedNonKeyAttributes

protected void copyChangedNonKeyAttributes(EntityImpl targetRow)

This method copies all the changed attributes from one entity to another. This method is currently used in effective date operations where the changed values need to be copied to a next row in the effective date time line. The primary row is just end dated where as the next row recieves the actual update.

Parameters:

targetRow - The row that the changed attributes are copied to.

getEffDtInitEndDateValue

protected java.lang.Object getEffDtInitEndDateValue()

This method returns the End Date value for the new rows created for the Entity.

Returns:

endDate value that conforms to the type defined in Effective Date End attribute definition. This default implementation returns the date 31-DEC-4712

getEffectiveDate

public java.lang.Object getEffectiveDate()

Obtain the Effective Date Value for the Entity. A search for a valid value is carried out in the following order:

1. The value of the SysEffectiveDate transient attribute
2. The SysEffectiveDate property value on the Root Application Module
3. Current Date

Overrides:

getEffectiveDate in class RowImpl

Returns:

The effective date for the row

setEffectiveDateMode

public void setEffectiveDateMode(int mode)

Description copied from interface: Row

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.

Specified by:

setEffectiveDateMode in interface Row

Overrides:

setEffectiveDateMode in class RowImpl

Parameters:

mode - One of the effective date mode constants.

See Also:

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

isViewAccessorAttribute

protected boolean isViewAccessorAttribute(int indexAttribute)

Check if an attribute is the attribute to store view accessor RowSetIterator.

Parameters:

indexAttribute - The index of the attribute.

Returns:

true if the attribute stores view accessor RowSetIterator, orelse return false.

findViewAccessorDef

public ViewAccessorDef findViewAccessorDef(java.lang.String name)

This method returns ViewAccessorDef with the specified name.

Overrides:

findViewAccessorDef in class RowImpl

Parameters:

name - The name of the ViewAccessorDef.

Returns:

The ViewAccessorDef

findOrCreateLocalViewObject

protected ViewObject findOrCreateLocalViewObject(ViewAccessorDef vaDef)

Find or create the local view instance from the local view usage name.

Parameters:

vaDef - The ViewAccessorDef.

Returns:

The local view object.

doAllowsOperation

protected oracle.adf.share.security.authorization.PrivilegeHolder doAllowsOperation(java.lang.String operationName)

Overrides:

doAllowsOperation in class RowImpl

getComparator

public static java.util.Comparator getComparator()