OracleRef Class

An OracleRef instance represents an Oracle REF, which references a persistent, standalone, referenceable object that resides in the database. The OracleRef object provides methods to insert, update, and delete the Oracle REF.

Class Inheritance

System.Object

  System.MarshalByRefObject

    Oracle.DataAccess.Types.OracleRef

Declaration

// C#
public sealed class OracleRef : MarshalByRefObject,ICloneable, IDisposable,  
  INullable 

Thread Safety

All public static methods are thread-safe, although instance methods do not guarantee thread safety.

Remarks

If two or more OracleRef objects that refer to the same Oracle object in the database are retrieved through the same OracleConnection, then their operations on the referenced object must be synchronized.

Requirements

Namespace: Oracle.DataAccess.Types

Assembly: Oracle.DataAccess.dll

ODP.NET Version: ODP.NET for .NET Framework 2.0 or ODP.NET for .NET Framework 4

---

OracleRef Members

OracleRef members are listed in the following tables.

OracleRef Constructors

OracleRef constructors are listed in Table 16-30.

OracleRef Static Fields

OracleRef static methods are listed in Table 16-31

OracleRef Static Methods

OracleRef static methods are listed in Table 16-32.

OracleRef Instance Properties

OracleRef instance properties are listed in Table 16-33.

OracleRef Instance Methods

OracleRef instance methods are listed in Table 16-34.

---

OracleRef Constructors

OracleRef constructors instantiate new instances of OracleRef class.

Overload List:

• OracleRef(OracleConnection, string)

  This constructor creates an instance of the OracleRef class with a connection and a HEX string that represents an REF instance in the database.

• OracleRef(OracleConnection, string, string)

  This constructor creates an instance of the OracleRef class using the specified OracleConnection object, user-defined type name, and an object table name

OracleRef(OracleConnection, string)

This constructor creates an instance of the OracleRef class with a connection and a HEX string that represents an REF instance in the database.

Declaration

// C#
public OracleRef(OracleConnection con, string hexStr);

Parameters

• con

  An OracleConnection instance.

• hexStr

  A HEX string that represents an REF instance in the database.

Exceptions

ArgumentException - The HEX string does not represent a valid REF in the database.

ArgumentNullException - The connection or HEX string is null.

InvalidOperationException - The OracleConnection object is not open.

Remarks

When an OracleRef instance is created, it is referenced to a specific table in the database.

The connection must be opened explicitly by the application. OracleRef does not open the connection implicitly.

OracleRef(OracleConnection, string, string)

This constructor creates an instance of the OracleRef class using the specified OracleConnection object, user-defined type name, and an object table name.

Declaration

// C#
public OracleRef(OracleConnection con, string udtTypeName, string objTabName);

Parameters

• con

  An OracleConnection instance.

• udtTypeName

  A user-defined type name.

• objTabName

  An object table name.

Exceptions

ArgumentException - The object type name or the object table name is not valid.

ArgumentNullException - The object type name or the table name is null.

InvalidOperationException - The OracleConnection object is not open.

Remarks

When an OracleRef instance is created, this OracleRef instance is associated with the specific table in the database. In other words, it represents a persistent REF.

This constructor creates a reference to the object table. However, it does not cause any entries to be made in database tables until the object is flushed to the database, that is, until the OracleRef.Flush or the OracleConnection.FlushCache method is called on the OracleRef Connection. Therefore, any operation that attempts to operate on the database copy of the object before flushing the object, such as, lock the object or fetch the latest copy of the object from the database, results in an OracleException.

The connection must be opened explicitly by the application. OracleRef does not open the connection implicitly.

---

OracleRef Static Fields

OracleRef static fields are listed in Table 16-35.

Null

This static field represents a null value that can be assigned to an OracleRef instance.

Declaration

// C#
public static readonly OracleRef Null;

---

OracleRef Static Methods

OracleRef static methods are listed in Table 16-36.

---

OracleRef Instance Properties

OracleRef instance properties are listed in Table 16-37.

Connection

This instance property references the connection used by the OracleRef.

Declaration

// C#
public OracleConnection Connection{get;}

Property Value

An OracleConnection object associated with the REF.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

Once the Dispose method is invoked, this property is set to null.

HasChanges

This instance property indicates whether or not the object referenced by the Oracle REF in the object cache has any changes that can be flushed to the database.

Declaration

// C#
public bool HasChanges {get;}

Property Value

Returns true if the object referenced by the Oracle REF in the object cache has any changes that can be flushed to the database; otherwise, returns false.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

This property returns true if a copy of the referenced object in the object cache is updated or deleted.

If there is no copy of the referenced object in the object cache, the latest copy of the referenced object in the database is cached in the object cache and false is returned.

IsLocked

This instance property indicates whether or not the REF is locked.

Declaration

// C#
public bool IsLocked {get;}

Property Value

Returns true if the REF is locked; otherwise returns false.

Exceptions

ObjectDisposedException - The object is already disposed.

IsNull

This instance property indicates whether or not the Oracle REF is NULL.

Declaration

// C#
public bool IsNull {get;}

Property Value

Returns true if the REF is NULL; otherwise, returns false.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

If the Oracle REF is NULL, this property returns true. Otherwise, it returns false.

ObjectTableName

This instance property returns the fully-qualified object table name that is associated with the REF.

Declaration

// C#
public string ObjectTableName{get;}

Property Value

A fully-qualified object table name that is associated with the REF.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

The object table name is in the form schema_Name.Table_Name.

Value

This instance property returns a .NET representation of this Oracle REF.

Declaration

// C#
public string Value{get;}

Property Value

A .NET representation of the Oracle REF.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

This property returns a HEX string that represents the REF.

The returned string can be used to create a new OracleRef instance by using the OracleRef(OracleConnection, string) constructor.

---

Oracle Ref Instance Methods

OracleRef instance methods are listed in Table 16-38.

Clone

This instance method clones the REF.

Declaration

// C#
public OracleRef Clone();

Return Value

A clone of the current instance.

Implements

ICloneable

Exceptions

InvalidOperationException - The associated connection is not open.

Delete

This method deletes the referenced object from the database.

Declaration

// C#
public void Delete(bool bFlush);

Parameters

• bFlush

  A bool that specifies whether or not the REF is flushed immediately.

Remarks

This method marks the specified REF for deletion.

Depending on whether the value of bFlush is set to true or false, the following occurs:

• True

  The object referenced by the specified REF is deleted immediately from the database.

  Before flushing objects, it is required that the application has explicitly started a transaction by executing the BeginTransaction method on the OracleConnection object. This is because if the object being flushed has not already been locked by the application, an exclusive lock is obtained implicitly for the object. The lock is only released when the transaction commits or rollbacks.

• False

  The object referenced by the REF is not deleted immediately from the database, but only when a subsequent Flush method is invoked for the specified REF or the FlushCache method is invoked on the OracleRef or the FlushCache method is invoked on the OracleRef connection.

Dispose

This instance method releases resources allocated for the OracleRef instance.

Declaration

// C#
public void Dispose();

Implements

IDisposable

Remarks

The object cannot be reused after it is disposed. Although some properties can still be accessed, their values may not be up-to-date.

Flush

This instance method flushes changes made on the REF object to the database, such as updates or deletes.

Declaration

// C#
public void Flush();

Exceptions

InvalidOperationException - The associated connection is not open.

Remarks

Before flushing objects, it is required that the application has explicitly started a transaction by executing the BeginTransaction method on the OracleConnection object. This is because if the object being flushed has not already been locked by the application, an exclusive lock is obtained implicitly for the object. The lock is only released when the transaction commits or rollbacks.

GetCustomObject

GetCustomObject methods return the object that the specified REF references as a custom type.

Overload List

• GetCustomObject(OracleUdtFetchOption)

  This method returns the object that the specified REF references as a custom type using the specified fetch option.

• GetCustomObject(OracleUdtFetchOption, int)

  This method returns the object that the specified REF references as a custom type using the specified fetch option and depth level.

GetCustomObject(OracleUdtFetchOption)

This method returns the object that the specified REF references, as a custom type, using the specified fetch option.

Declaration

// C#
public object GetCustomObject(OracleUdtFetchOption fetchOption);

Parameters

• fetchOption

  An OracleUdtFetchOption value.

Return Value

A custom object that represents the object that the specified REF references.

Exceptions

InvalidOperationException - The specified connection is not open, or a valid custom type has not been registered for the type of the referenced object.

Remarks

This method returns a custom type determined by the UDT mappings on the specified connection.

The connection must be opened explicitly by the application. This method does not open the connection implicitly.

The application can use the OracleUdtFetchOption method to control the copy of the Object that is returned according to the specified option:

• OracleUdtFetchOption.Cache option

  If this option is specified, and there is a copy of the referenced object in the object cache, it is returned immediately. If no cached copy exists, the latest copy of the referenced object in the database is cached in the object cache and returned.

• OracleUdtFetchOption.Server option

  If this option is specified, the latest copy of the referenced object from the database is cached in the object cache and returned. If a copy of the referenced object already exists in the cache, the latest copy overwrites the existing one.

• OracleUdtFetchOption.TransactionCache option

  If this option is specified, and a copy of the referenced object is cached in the current transaction, the copy is returned. Otherwise, the latest copy of the referenced object from the database is cached in the object cache and returned. If a copy of the referenced object already exists in the cache, the latest copy overwrites the existing one.

  Note that if a cached copy of the referenced object was modified before the current transaction began, that is, if the OracleRef.HasChanges property returns true, then the Recent option returns the cached copy of the referenced object. Outside of a transaction, the Recent option behaves like the Any option.

GetCustomObject(OracleUdtFetchOption, int)

This method returns the object that the specified REF references, as a custom type, using the specified fetch option and depth level.

Declaration

// C#
public object GetCustomObject(OracleUdtFetchOption fetchOption, int depthLevel);

Parameters

• fetchOption

  An OracleUdtFetchOption value.

• depthLevel

  The number of levels to be fetched for nested REF attributes.

Return Value

A custom object that represents the object that the specified REF references.

Exceptions

InvalidOperationException - The specified connection is not open, or a valid custom type has not been registered for the type of the referenced object.

Remarks

This method returns a custom type determined by the UDT mappings on the specified connection.

If the object that the REF references contains nested REF attributes, the depthLevel can be specified to optimize the subsequent object retrieval. The value of depthLevel determines the number of levels that are optimized.

For example, if the depthLevel is specified as two, the optimization is applied to all top-level nested REF attributes in the object being fetched and also to all nested REF attributes within the objects referenced by the top-level nested REF attributes.

The connection must be opened explicitly by the application. This method does not open the connection implicitly.

The application can use the OracleUdtFetchOption method to control the copy of the Object that is returned according to the specified option:

• OracleUdtFetchOption.Cache option

  If this option is specified, and there is a copy of the referenced object in the object cache, it is returned immediately. If no cached copy exists, the latest copy of the referenced object in the database is cached in the object cache and returned.

• OracleUdtFetchOption.Server option

  If this option is specified, the latest copy of the referenced object from the database is cached in the object cache and returned. If a copy of the referenced object already exists in the cache, the latest copy overwrites the existing one.

• OracleUdtFetchOption.TransactionCache option

  If this option is specified, and a copy of the referenced object is cached in the current transaction, the copy is returned. Otherwise, the latest copy of the referenced object from the database is cached in the object cache and returned. If a copy of the referenced object already exists in the cache, the latest copy overwrites the existing one.

  Note that if a cached copy of the referenced object was modified before the current transaction began, that is, if the OracleRef.HasChanges property returns true, then the Recent option returns the cached copy of the referenced object. Outside of a transaction, the Recent option behaves like the Any option.

GetCustomObjectForUpdate

GetCustomObjectForUpdate methods return the object that the specified REF references as a custom type.

• GetCustomObjectForUpdate(bool)

  This method locks the specified REF in the database and returns the object that the specified REF references as a custom type using the specified wait option.

• GetCustomObjectForUpdate(bool, int)

  This method locks the specified REF in the database and returns the object that the specified REF references as a custom type using the specified wait option and depth level.

  See Also:

  • "Oracle.DataAccess.Types Namespace"

  • OracleRef Class

  • OracleRef Members

GetCustomObjectForUpdate(bool)

This method locks the specified REF in the database and returns the object that the specified REF references, as a custom type, using the specified wait option.

Declaration

// C#
public object GetCustomObjectForUpdate(bool bWait);

Parameters

• bWait

  Specifies if the REF is to be locked with the no-wait option. If wait is set to true, this method invocation does not return until the REF is locked.

Return Value

A custom object that represents the object that the specified REF references.

Exceptions

InvalidOperationException - The specified connection is not open, or a valid custom type has not been registered for type of the referenced object.

OracleException - bWait is set to false, and the lock cannot be acquired.

Remarks

This method returns the latest copy of the referenced object, as a custom type, determined by the custom types registered on the OracleRef connection.

To be able to release the lock on the REF appropriately after flushing the REF using the Flush method on the OracleRef or FlushCache method on the OracleConnection, the application must commit or rollback the transaction. Therefore, it is required that, before invoking this method, a transaction is explicitly started by executing the BeginTransaction method on the OracleConnection object.

This method makes a network round-trip to lock the REF in the database. After this call, programmers can modify the associated row object exclusively. Then a call to the Flush method on the OracleRef or FlushCache method on the OracleConnection flushes the changes to the database.

If true is passed, this method blocks until the lock can be acquired. If false is passed, this method immediately returns. If the lock cannot be acquired, an OracleException is thrown.

The connection must be opened explicitly by the application. This method does not open the connection implicitly.

GetCustomObjectForUpdate(bool, int)

This method locks the specified REF in the database and returns the object that the specified REF references, as a custom type, using the specified wait option and depth level

Declaration

public object GetCustomObjectForUpdate(bool bWait, int depthlevel);

Parameters

• bWait

  A boolean value that specifies if the REF is to be locked with the no-wait option. If wait is set to true, this method invocation does not return until the REF is locked.

• depthLevel

  The number of levels to be fetched for nested REF attributes.

Return Value

A custom object that represents the object that the specified REF references.

Exceptions

InvalidOperationException - The specified connection is not open, or a valid custom type has not been registered for type of the referenced object.

OracleException - bWait is set to false, and the lock cannot be acquired.

Remarks

This method returns the latest copy of the referenced object, as a custom type, determined by the custom types registered on the OracleRef connection.

To be able to release the lock on the REF appropriately after flushing the REF using the Flush method on the OracleRef or FlushCache method on the OracleConnection, the application must commit or rollback the transaction. Therefore, it is required that, before invoking this method, a transaction is explicitly started by executing the BeginTransaction method on the OracleConnection object.

This method makes a network round-trip to lock the REF in the database. After this call, programmers can modify the associated row object exclusively. Then a call to the Flush method on the OracleRef or FlushCache method on the OracleConnection flushes the changes to the database.

If true is passed, this method blocks until the lock can be acquired. If false is passed, this method immediately returns. If the lock cannot be acquired, an OracleException is thrown.

If the object that the REF references contains nested REF attributes, the depthLevel can be specified to optimize the subsequent object retrieval. The value of depthLevel determines the number of levels that are optimized.

For example, if the depthLevel is specified as 2, the optimization is applied to all top-level nested REF attributes in the object being fetched and also to all nested REF attributes within the objects referenced by the top-level nested REF attributes.

The connection must be opened explicitly by the application. This method does not open the connection implicitly.

IsEqual

This instance method compares two OracleREF objects.

Declaration

// C#
public bool IsEqual(OracleRef oraRef);

Parameters

• oraRef

  The provided OracleRef object.

Return Value

bool

Remarks

This instance method returns true if the OracleRef instance and the OracleRef parameter both reference the same object. Otherwise, it returns false.

Lock

This instance method locks the REF in the database.

Declaration

// C#
public bool Lock(bool bWait);

Parameters

• bWait

  Specifies if the lock is set to the no-wait option. If bWait is set to true, the method invocation does not return until the REF is locked.

Return Value

A boolean value that indicates whether or not the lock has been acquired.

Exceptions

InvalidOperationException - The associated connection is not open.

ObjectDisposedException - The object is already disposed.

Remarks

In order for the application to release the lock on the REF appropriately after the Flush invocation on the OracleRef or FlushCache methods, the application must commit or rollback the transaction. Therefore, it is required that, before invoking a lock on an OracleRef object, a transaction is explicitly started by executing the BeginTransaction method on the OracleConnection object.

This instance method makes a network round-trip to lock the REF in the database. After this call, programmers can modify the attribute values of the associated row object exclusively. Then a call to the Flush instance method on the OracleRef or FlushCache method on the OracleConnection flushes the changes to the database.

If true is passed, this method blocks, that is, does not return, until the lock is acquired. Consequently, the return value is always true.

If false is passed, this method immediately returns. The return value indicates true if the lock is acquired, and false if it is not.

Update

This method updates the object referenced by the specified REF in the database using the specified custom object.

Declaration

// C#
public void Update(object customObject, bool bFlush);

Parameters

• customObject

  The custom object used to update the referenced object.

• bFlush

  A boolean that specifies if the changes must be flushed immediately. If bFlush is set to true, this method invocation flushes the changes immediately.

Exceptions

InvalidOperationException - The specified connection is not open or the custom object does not map to the type of referenced object.

Remarks

This method marks the specified REF for update. Depending on whether the value of bFlush is set to true or false, the following occurs:

• True

  The object referenced by the specified REF is updated immediately in the database.

  Before flushing objects, it is required that the application has explicitly started a transaction by executing the BeginTransaction method on the OracleConnection object. This is because if the object being flushed has not already been locked by the application, an exclusive lock is obtained implicitly for the object. The lock is only released when the transaction commits or rollbacks.

• False

  The object referenced by the REF is not updated immediately in the database, but only when a subsequent Flush method is invoked for the specified REF or the FlushCache method is invoked for the specified connection.

The connection must be opened explicitly by the application. This method does not open the connection implicitly.