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.
System.Object
System.MarshalByRefObject
Oracle.DataAccess.Types.OracleRef
// C# public sealed class OracleRef : MarshalByRefObject,ICloneable, IDisposable, INullable
All public static methods are thread-safe, although instance methods do not guarantee thread safety.
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.
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
Microsoft .NET Framework Version: 1.0 or later
See Also:
OracleRef members are listed in the following tables.
OracleRef constructors are listed in Table 14-30.
Table 14-30 OracleRef Constructors
| Constructor | Description |
|---|---|
|
Instantiates a new instance of |
OracleRef static methods are listed in Table 14-31
Table 14-31 OracleRef Static Fields
| Static Field | Description |
|---|---|
|
Represents a null value that can be assigned to an |
OracleRef static methods are listed in Table 14-32.
Table 14-32 OracleRef Static Methods
| Method | Description |
|---|---|
|
|
Inherited from |
OracleRef instance properties are listed in Table 14-33.
Table 14-33 OracleRef Instance Properties
| Property | Description |
|---|---|
|
References the connection used by the |
|
|
References the connection used by the |
|
|
Indicates whether or not the |
|
|
Indicates whether or not the Oracle |
|
|
Returns the fully qualified object table name that is associated with the |
|
|
Returns a .NET representation of this Oracle |
OracleRef instance methods are listed in Table 14-34.
Table 14-34 OracleRef Instance Methods
| Method | Description |
|---|---|
|
Clones the |
|
|
Deletes the referenced object from the database |
|
|
Releases resources allocated for the |
|
|
|
Inherited from |
|
Flushes changes made on the |
|
|
Returns the object that the specified REF references as a custom type (Overloaded) |
|
|
Returns the object that the specified REF references as a custom type (Overloaded) |
|
|
|
Inherited from |
|
|
Inherited from |
|
Compares two |
|
|
Locks the |
|
|
|
Inherited from |
|
Updates the object referenced by the specified |
OracleRef constructors instantiate new instances of OracleRef class.
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
This constructor creates an instance of the OracleRef class with a connection and a HEX string that represents an REF instance in the database.
// C# public OracleRef(OracleConnection con, string hexStr);
con
An OracleConnection instance.
hexStr
A HEX string that represents an REF instance in the database.
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.
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.
This constructor creates an instance of the OracleRef class using the specified OracleConnection object, user-defined type name, and an object table name.
// C# public OracleRef(OracleConnection con, string udtTypeName, string objTabName);
con
An OracleConnection instance.
udtTypeName
A user-defined type name.
objTabName
An object table name.
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.
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 are listed in Table 14-35.
Table 14-35 OracleRef Static Fields
| Static Field | Description |
|---|---|
|
Represents a null value that can be assigned to an |
This static field represents a null value that can be assigned to an OracleRef instance.
// C# public static readonly OracleRef Null;
OracleRef static methods are listed in Table 14-36.
Table 14-36 OracleRef Static Methods
| Method | Description |
|---|---|
|
|
Inherited from |
OracleRef instance properties are listed in Table 14-37.
Table 14-37 OracleRef Instance Properties
| Property | Description |
|---|---|
|
References the connection used by the |
|
|
References the connection used by the |
|
|
Indicates whether or not the |
|
|
Indicates whether or not the Oracle |
|
|
Returns the fully qualified object table name that is associated with the |
|
|
Returns a .NET representation of this Oracle |
This instance property references the connection used by the OracleRef.
// C#
public OracleConnection Connection{get;}
An OracleConnection object associated with the REF.
ObjectDisposedException - The object is already disposed.
Once the Dispose method is invoked, this property is set to null.
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.
// C#
public bool HasChanges {get;}
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.
ObjectDisposedException - The object is already disposed.
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.
This instance property indicates whether or not the REF is locked.
// C#
public bool IsLocked {get;}
Returns true if the REF is locked; otherwise returns false.
ObjectDisposedException - The object is already disposed.
This instance property indicates whether or not the Oracle REF is NULL.
// C#
public bool IsNull {get;}
Returns true if the REF is NULL; otherwise, returns false.
ObjectDisposedException - The object is already disposed.
If the Oracle REF is NULL, this property returns true. Otherwise, it returns false.
This instance property returns the fully-qualified object table name that is associated with the REF.
// C#
public string ObjectTableName{get;}
A fully-qualified object table name that is associated with the REF.
ObjectDisposedException - The object is already disposed.
The object table name is in the form schema_Name.Table_Name.
This instance property returns a .NET representation of this Oracle REF.
// C#
public string Value{get;}
A .NET representation of the Oracle REF.
ObjectDisposedException - The object is already disposed.
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.
See Also:
OracleRef instance methods are listed in Table 14-38.
Table 14-38 OracleRef Instance Methods
| Method | Description |
|---|---|
|
Clones the |
|
|
Deletes the referenced object from the database |
|
|
Releases resources allocated for the |
|
|
|
Inherited from |
|
Flushes changes made on the |
|
|
Returns the object that the specified REF references as a custom type (Overloaded) |
|
|
Returns the object that the specified REF references as a custom type (Overloaded) |
|
|
|
Inherited from |
|
|
Inherited from |
|
Compares two |
|
|
Locks the |
|
|
|
Inherited from |
|
Updates the object referenced by the specified |
This instance method clones the REF.
// C# public OracleRef Clone();
A clone of the current instance.
ICloneable
InvalidOperationException - The associated connection is not open.
This method deletes the referenced object from the database.
// C#
public void Delete(bool bFlush);
bFlush
A bool that specifies whether or not the REF is flushed immediately.
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.
See Also:
OracleConnection "FlushCache"
This instance method releases resources allocated for the OracleRef instance.
// C# public void Dispose();
IDisposable
The object cannot be reused after it is disposed. Although some properties can still be accessed, their values may not be up-to-date.
This instance method flushes changes made on the REF object to the database, such as updates or deletes.
// C# public void Flush();
InvalidOperationException - The associated connection is not open.
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 methods return the object that the specified REF references as a custom type.
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.
This method returns the object that the specified REF references, as a custom type, using the specified fetch option.
// C#
public object GetCustomObject(OracleUdtFetchOption fetchOption);
fetchOption
An OracleUdtFetchOption value.
A custom object that represents the object that the specified REF references.
InvalidOperationException - The specified connection is not open, or a valid custom type has not been registered for the type of the referenced object.
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.
See Also:
This method returns the object that the specified REF references, as a custom type, using the specified fetch option and depth level.
// C#
public object GetCustomObject(OracleUdtFetchOption fetchOption, int depthLevel);
fetchOption
An OracleUdtFetchOption value.
depthLevel
The number of levels to be fetched for nested REF attributes.
A custom object that represents the object that the specified REF references.
InvalidOperationException - The specified connection is not open, or a valid custom type has not been registered for the type of the referenced object.
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.
See Also:
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.
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.
// C#
public object GetCustomObjectForUpdate(bool bWait);
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.
A custom object that represents the object that the specified REF references.
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.
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.
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
public object GetCustomObjectForUpdate(bool bWait, int depthlevel);
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.
A custom object that represents the object that the specified REF references.
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.
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.
This instance method compares two OracleREF objects.
// C#
public bool IsEqual(OracleRef oraRef);
oraRef
The provided OracleRef object.
bool
This instance method returns true if the OracleRef instance and the OracleRef parameter both reference the same object. Otherwise, it returns false.
This instance method locks the REF in the database.
// C#
public bool Lock(bool bWait);
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.
A boolean value that indicates whether or not the lock has been acquired.
InvalidOperationException - The associated connection is not open.
ObjectDisposedException - The object is already disposed.
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.
This method updates the object referenced by the specified REF in the database using the specified custom object.
// C# public void Update(object customObject, bool bFlush);
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.
InvalidOperationException - The specified connection is not open or the custom object does not map to the type of referenced object.
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.