An object instance is an occurrence of a type defined in an Oracle database.

This section describes how an object instance can be represented in OCI. In OCI, an object instance can be classified based on the type, the lifetime, and referenceability:

• A persistent object is an instance of an object type. A persistent object resides in a row of a table in the server and can exist longer than the duration of a session (connection). Persistent objects can be identified by object references that contain the object identifiers. A persistent object is obtained by pinning its object reference.

• A transient object is an instance of an object type. A transient object cannot exist longer than the duration of a session, and it is used to contain temporary computing results. Transient objects can also be identified by references that contain transient object identifiers.

• A value is an instance of a user-defined type (object type or collection type) or any built-in Oracle type. Unlike objects, values of object types are identified by memory pointers, rather than by references.

A value can be standalone or embedded. A standalone value is usually obtained by issuing a select statement. OCI also allows the client program to select a row of object table into a value by issuing a SQL statement. A referenceable object in the database can be represented as a value that cannot be identified by a reference. A standalone value can also be an out-of-line attribute in an object, such as VARCHAR or RAW, or an out-of-line element in a collection, such as VARCHAR, RAW, or object.

An embedded value is physically included in a containing instance. An embedded value can be an inline attribute in an object (such as number or nested object), or an inline element in a collection.

All values are considered to be transient by OCI, which means that OCI does not support automatic flushing of a value to the database, and the client must explicitly execute a SQL statement to store a value into the database. Embedded values are flushed when their containing instances are flushed.

Figure 27-1 shows how instances can be classified according to their type and lifetime. The type can be an object or the value of an object. The lifetime can be persistent (can exist longer than the duration of a session) or transient (can exist no long than the duration of the session).

The distinction between various instances is further described in Table 27-1.

Describes the terminology used.

The remainder of this chapter uses the following terms:

• An object is generally used to refer to a persistent object, a transient object, a standalone value of object type, or an embedded value of object type.

• A referenceable object refers to a persistent object or a transient object.

• A standalone object refers to a persistent object, a transient object, or a standalone value of object type.

• An embedded object refers to a embedded value of object type.

• An object is dirty if it has been created (newed), marked as updated, or marked as deleted.

  See Also:

  Persistent Objects, Transient Objects, and Values for further discussion of the terms used to refer to different types of objects

Describes the conventions for OCI functions.

See the Conventions for OCI Functions for the conventions used in describing each function. The entries for each function may also contain the following information:

Describes the return values by the function if the function returns something other then the standard codes.

A description of what value is returned by the function if the function returns something other then the standard codes listed in Table 27-3.

Describes the navigational function return values.

Describes the number of server round-trips required for individual OCI cache and object functions.

For a table showing the number of server round-trips required for individual OCI cache and object functions, see Table C-3.

Describes the external Oracle error codes that can be returned by each of the OCI navigational functions.