Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Business Components
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## oracle.jbo.server
Class EntityImpl

    java.lang.Object
      |
      +--oracle.jbo.common.BaseObject
            |
            +--oracle.jbo.server.RowImpl
                  |
                  +--oracle.jbo.server.EntityImpl

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_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_NEW` - if this Entity Object is new and not yet posted to the database.
- `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.

Since:
  JDeveloper 3.0

Field Summary
`protected static int` | `DML_DELETE` Identifies that a Delete operation is to be performed in the `doDML()` method.
`protected static int` | `DML_INSERT` Identifies that an Insert operation is to be performed in the `doDML()` method.
`protected 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 java.lang.String` | `XML_PK_CHANGED`
`static java.lang.String` | `XML_PK_CHANGED_YES`

Fields inherited from class oracle.jbo.common.BaseObject
`TRACE_EVERY_ALLOC, TRACE_NONE, TRACE_OCCASIONAL, TRACE_UNINITIALIZED`

Fields inherited from interface oracle.jbo.server.Entity
`STATUS_DEAD, STATUS_DELETED, STATUS_MODIFIED, STATUS_NEW, STATUS_UNMODIFIED`

Fields inherited from interface oracle.jbo.XMLInterface
`XML_OPT_ALL_ROWS, XML_OPT_ASSOC_CONSISTENT, XML_OPT_CHANGES_ONLY, XML_OPT_LIMIT_RANGE`

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(org.w3c.dom.Document xmlDoc, org.w3c.dom.Node node, int nContainees, long options, AttributeDefImpl[] attrs)`
`void` | `beforeCommit(TransactionEvent e)` Polls transaction listeners before a commit operation.
`void` | `beforeRollback(TransactionEvent e)` Polls transaction listeners before a rollback operation.
`protected void` | `create(AttributeList nameValuePair)` This method should be subclassed to supply programmatic default values to various attributes of a new Entity Object.
`protected void` | `doDML(int operation, TransactionEvent e)` Performs INSERT/UPDATE/DELETE processing for the row.
`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` | `doSelect(boolean lock)` Advanced: Most applications should not use this method.
`java.lang.Object` | `getAttribute(int index)` Returns the value of an attribute, given an integer index value.
`java.lang.Object` | `getAttribute(java.lang.String name)` Returns the value of the named attribute, given a string value.
`int` | `getAttributeCount()` Counts the number of attributes in this Entity Object.
`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.
`protected java.lang.Object` | `getAttributeValue(AttributeDefImpl attr)` Internal: Applications should not use this method.
`protected java.lang.Object` | `getChangeIndicator()` Gets the Change indicator attribute's value.
`DBTransaction` | `getDBTransaction()` Retrieves this Entity Object's database transaction.
`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.
`Key` | `getKey()` Internal: Applications should not use thid method.
`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 SQLBuilder` | `getSQLBuilder()` Get the SQLBuilderImpl which performs all SQL operations required by this Entity Object.
`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.
`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 void` | `handlePostChangesError()` Called when a problem occurs while posting changes and restores an `EntityImpl`'s state.
`boolean` | `isAttributeUpdateable(int index)` Checks if the attribute is updateable.
`boolean` | `isInCache()`
`boolean` | `isInvalid()` Returns whether this Entity Object is invalid.
`boolean` | `isLocked()` Determines whether this Entity Object is locked.
`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.
`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` | `notifyEntityActivated(boolean bPostRequired)` Internal: Applications should not use this method.
`protected void` | `populateAttribute(int index, java.lang.Object value)` Advanced method: Applications should 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.
`void` | `postChanges(TransactionEvent e)` Initiates a post operation for this Entity Object.
`protected boolean` | `readAttrsFromXML(org.w3c.dom.Element rowElt, AttributeDefImpl[] attrs, int ChangeState)`
`void` | `readXML(org.w3c.dom.Element elem, int depthCount)` Reads the content of the row and updates the attributes, from given XML document.
`protected void` | `refreshFKInNewContainees()`
`void` | `remove()` Marks the row for deletion.
`void` | `removeTransactionPostListener(TransactionPostListener listener)` Internal: Applications should not use this method.
`protected void` | `resetPKBasedRef()`
`void` | `revert()` Reverts the row to the database's state.
`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` | `setAttributeInternal(int index, java.lang.Object val)` Validates and sets the value of an attribute by index.
`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.
`void` | `setTransPostHandle(int hdl)` Advanced: Most applications should not use this method.
`java.lang.String` | `toString()`
`void` | `validate()` Validate this Entity Object.
`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
`createXMLDefinition, getAttributeInternal, printXMLDefinition, readXML, setAttributeInternal, writeXML, writeXML`

Methods inherited from class oracle.jbo.common.BaseObject
`dumpState, setTraceLevel, setTraceWriter`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### DML_INSERT

    protected static final int DML_INSERT

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

### DML_UPDATE

    protected static final int DML_UPDATE

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

### DML_DELETE

    protected static final int DML_DELETE

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

### 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

### 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

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

  Overrides:
    create in class RowImpl
  Parameters:
    `nameValuePair` - a name providing access to an attribute list.
  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.

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

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

  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.

### setAttribute

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

  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.

### setAttribute

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

  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.

### 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. Override this method to add validation or business logic to your attributes' setter methods.
  Overrides:
    setAttributeInternal in class RowImpl
  Parameters:
    `index` - the index of the attribute.
    `val` - the value of the attribute.

### 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

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

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

### 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 (this.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()`.

  Overrides:
    validate in class RowImpl
  Throws:
    `oracle.jbo.JboException` - if this Entity Object is found to be invalid.

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

  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.

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

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

### 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);
              }
           }

  Overrides:
    getAttributeCount in class RowImpl
  Returns:
    the number of attributes.

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

  Overrides:
    getAttributeInternal in class RowImpl
  Parameters:
    `index` - the index of the attribute.
  Returns:
    attribute value at given index.

### getDBTransaction

    public final DBTransaction getDBTransaction()

  Retrieves this Entity Object's database transaction.

  This method should not be overridden.

  Returns:
    the database transaction.

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

### 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_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.

### 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 `EntityImpl`s 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.
  Overrides:
    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.

### 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)`

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

  Overrides:
    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.

### refreshFKInNewContainees

    protected void refreshFKInNewContainees()

### 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` 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);
         }

  Parameters:
    `e` - this Entity Object's transaction event.
  See Also:
    `doDML(int, TransactionEvent)`, `TransactionPostListener.postChanges(TransactionEvent e)`, `TransactionPostListener`

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

  Overrides:
    populateAttribute in class RowImpl
  Parameters:
    `index` - the index of the attribute to populate.
    `value` - the value to place in the attribute.

### populateAttributeAsChanged

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

  Advanced method: Applications should typically not call this method from their subclasses.

  Sets an attribute's value and also marks 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 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.

  Parameters:
    `index` - the index of the attribute to populate.
    `value` - the value to place in the attribute.
  See Also:
    `populateAttribute(int index, Object value)`

### afterCommit

    public void afterCommit(TransactionEvent e)

  Description copied from interface: TransactionListener
  Called to report that a Commit operation has occurred.
  Tags copied from interface: TransactionListener
  Parameters:
    `e` - a transaction event.

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

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

  Returns:
    `true` if the listener is transient.

### beforeCommit

    public void beforeCommit(TransactionEvent e)

  Polls transaction listeners before a commit operation.
  Parameters:
    `e` - this Entity Object's transaction event.
  See Also:
    `TransactionListener`

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

  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.

  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.

  Returns:
    `true` if the listener is transient.
  See Also:
    `TransactionPostListener`

### beforeRollback

    public void beforeRollback(TransactionEvent e)

  Polls transaction listeners before a rollback operation.
  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"

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

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

  Marks the row for deletion.

  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 remove routine. For example, you can implement a routine that throws exceptions that report why an Entity Object cannot be removed.

  Overrides:
    remove in class RowImpl
  Throws:
    RemoveWithDetailsException - if an attempt is made to remove the master Entity Object before removing its children.

### getKey

    public Key getKey()

  Internal: Applications should not use thid method.

  Gets the Entity Object's Primary Key.

  Overrides:
    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.

  Overrides:
    isAttributeUpdateable in class RowImpl
  Parameters:
    `index` - the attribute's index.
  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.

### 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(org.w3c.dom.Document xmlDoc,
                                         org.w3c.dom.Node node,
                                         int nContainees,
                                         long options,
                                         AttributeDefImpl[] attrs)

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

### readAttrsFromXML

    protected boolean readAttrsFromXML(org.w3c.dom.Element rowElt,
                                       AttributeDefImpl[] attrs,
                                       int ChangeState)

### readXML

    public final void readXML(org.w3c.dom.Element elem,
                              int depthCount)

  Description copied from class: RowImpl
  Reads the content of the row and updates the attributes, from given XML document. If there's a process instruction in the row like: <?bc4j remove?> then calls `RowImpl.remove()` on this row.
  Overrides:
    readXML in class RowImpl
  Tags copied from class: RowImpl
  Parameters:
    `elem` - name of the XML element.
    `depthCount` - the number of child levels deep to which data should be read.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Business Components
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD