An OracleDependency
class represents a dependency between an application and an Oracle database, enabling the application to get notifications whenever the data of interest or the state of the Oracle database changes.
Class Inheritance
Object
OracleDependency
Declaration
// C# public sealed class OracleDependency
Thread Safety
All public static methods are thread-safe, although methods do not guarantee thread safety.
Requirements
Namespace: Oracle.DataAccess.Client
Assembly: Oracle.DataAccess.dll
Comment: Not supported in a .NET stored procedure
OracleDependency
members are listed in the following tables:
OracleDependency Constructors
OracleDependency
constructors are listed in Table 7-1.
Table 7-1 OracleDependency Constructors
Constructors | Description |
---|---|
OracleDependency Constructors | Instantiates a new instance of OracleDependency class (Overloaded) |
OracleDependency Static Fields
The OracleDependency
static field is listed in Table 7-2.
Table 7-2 OracleDependency Static Field
Static Field | Description |
---|---|
Port | Indicates the port number that the notification listener listens on, for database notifications |
OracleDependency Static Methods
OracleDependency
static methods are listed in Table 7-3.
Table 7-3 OracleDependency Static Methods
Static Methods | Description |
---|---|
Equals |
Inherited from Object |
GetOracleDependency | Returns an OracleDependency instance based on the specified unique identifier |
OracleDependency Properties
OracleDependency
properties are listed in Table 7-4.
Table 7-4 OracleDependency Properties
Properties | Description |
---|---|
DataSource | Indicates the data source associated with the OracleDependency instance |
HasChanges | Indicates whether or not there is any change in the database associated with this dependency |
Id | Represents the unique identifier for the OracleDependency instance |
IsEnabled | Specifies whether or not the dependency is enabled between the application and the database |
RegisteredResources | Indicates the database resources that are registered in the notification registration |
UserName | Indicates the database user name associated with the OracleDependency instance |
OracleDependency Methods
OracleDependency
methods are listed in Table 7-5.
Table 7-5 OracleDependency Methods
Methods | Description |
---|---|
AddCommandDependency | Binds the OracleDependency instance to the specified OracleCommand instance |
Equals |
Inherited from Object |
GetHashCode |
Inherited from Object |
GetType |
Inherited from Object |
RemoveRegistration | Removes the specified dependency between the application and the database |
ToString |
Inherited from Object |
OracleDependency Events
The OracleDependency
event is listed in Table 7-6.
Table 7-6 OracleDependency Events
Event | Description |
---|---|
OnChange | An event that is sent when a database notification associated with the dependency is received from the database |
OracleDependency
constructors create instances of the OracleDependency
class.
Overload List:
This constructor creates an instance of the OracleDependency
class.
OracleDependency(OracleCommand)
This constructor creates an instance of the OracleDependency
class and binds it to the specified OracleCommand
instance.
OracleDependency(OracleCommand, bool, int, bool)
This constructor creates an instance of the OracleDependency
class and binds it to the specified OracleCommand
instance, specifying whether or not a notification is to be removed upon notification, the timeout value of the notification registration, and the persistence of the notification.
This constructor creates an instance of the OracleDependency
class.
Declaration
// C# public OracleDependency ()
Remarks
Using this constructor does not bind any OracleCommand
to the newly constructed OracleDependency
. Use the AddCommandDependency
method to do so.
Note: The dependency between the application and the database is not established when theOracleDependency instance is created. The dependency is established when the command that is associated with this dependency is executed. |
This constructor creates an instance of the OracleDependency
class and binds it to an OracleCommand
instance.
Declaration
// C#
public OracleDependency (OracleCommand cmd)
Parameters
cmd
The command that the OracleDependecy
object binds to.
Exceptions
ArgumentNullException
- The cmd
parameter is null.
InvalidOperationException
- The specified OracleCommand
instance already contains a notification request.
Remarks
When this OracleDependency
constructor binds the OracleCommand
instance to an OracleDependency
instance, it causes the creation of an OracleNotificationRequest
instance and then sets that OracleNotificationRequest
instance to the OracleCommand.
Notification
property.
The database change notification is registered with the database, when the command is executed. Any of the command execution methods (for example, ExecuteNonQuery
, ExecuteReader
, and so on) will register the notification request. An OracleDependency
may be bound to more than one OracleCommand
. When one of these OracleCommand
object statements is executed, the statement is registered with the associated OracleCommand
. Although the registration happens on each OracleCommand
separately, one OracleDependency
can be responsible for detecting and sending notifications that occur for all OracleCommand
objects that the OracleDependency
is associated with. The OnChangeEventArgs
that is passed to the application for the OnChange
event provides information on what has changed in the database.
The OracleNotificationRequest
instance that is created by this constructor has the following default property values:
IsNotifiedOnce
is set to the value True
.
Timeout
is set to 50,000 seconds.
IsPersistent
is set to the value False
, that is, the invalidation message is not persistent, but is stored in an in-memory queue before delivery.
This constructor creates an instance of the OracleDependency
class and binds it to the specified OracleCommand
instance, while specifying whether or not a notification is to be removed upon notification, the timeout value of the notification registration, and the persistence of the notification.
Declaration
// C# public OracleDependency (OracleCommand cmd, bool isNotifiedOnce, long timeout, bool isPersistent)
Parameters
cmd
The command associated with the Database Change Notification request.
isNotifiedOnce
An indicator that specifies whether or not the registration is removed automatically once the notification occurs.
timeout
The amount of time, in seconds, that the registration stays active. When timeout
is set to 0
, the registration never expires. The valid values for timeout
are between 0
and 4294967295
.
isPersistent
Indicates whether or not the invalidation message should be queued persistently in the database before delivery. If the isPersistent
parameter is set to True
, the message is queued persistently in the database and cannot be lost upon database failures or shutdowns. If the isPersistent
property is set to False
, the message is stored in an in-memory queue before delivery and might be lost.
Database performance is faster if the message is stored in an in-memory queue rather than in the database queue.
Exceptions
ArgumentNullException
- The cmd
parameter is null.
ArgumentOutOfRangeException
- The specified timeout
is invalid.
InvalidOperationException
- The specified OracleCommand
instance already contains a notification request.
Remarks
When this OracleDependency
constructor binds the OracleCommand
instance to an OracleDependency
instance, it causes the creation of an OracleNotificationRequest
instance and then sets that OracleNotificationRequest
instance to the OracleCommand.
Notification
property.
The database change notification is registered with the database, when the command is executed. Any of the command execution methods (for example, ExecuteNonQuery
, ExecuteReader
, and so on) will register the notification request. An OracleDependency
may be bound to more than one OracleCommand
. When one of these OracleCommand
object statements is executed, the statement is registered with the associated OracleCommand
. Although the registration happens on each OracleCommand
separately, one OracleDependency
can be responsible for detecting and sending notifications that occur for all OracleCommand
objects that the OracleDependency
is associated with. The OnChangeEventArgs
that is passed to the application for the OnChange
event provides information on what has changed in the database.
The OracleNotificationRequest
instance that is created by this constructor has the following default property values:
IsNotifiedOnce
is set to the specified value.
Timeout
is set to the specified value.
IsPersistent
is set to the specified value.
The OracleDependency
static field is listed in Table 7-7.
Table 7-7 OracleDependency Static Field
Static Field | Description |
---|---|
Port | Indicates the port number that the notification listener listens on, for database notifications |
This static field indicates the port number that the notification listener listens on, for database notifications.
Declaration
// C# public static int Port{get; set}
Property Value
An int
value that represents the number of the port that listens for the database notifications. If the port number is set to -1
, a random port number is assigned for the listener when the listener is started. Otherwise, the specified port number is used to start the listener.
Exceptions
ArgumentOutOfRangeException
- The port number is set to a negative value.
InvalidOperationException
- The port number is being changed after the listener has started.
Remarks
The port number specified by the OracleDependency.Port
static field is used by the notification listener that runs within the same application domain as ODP.NET. This port number receives database change notifications from the database. One notification listener is capable of listening to all database change notifications and therefore, only one notification listener is created for each application domain. The notification listener is created when a command associated with an OracleDependency
object is executed for the first time during the application domain lifetime. The port number specified for the OracleDependency.Port
static field is used by the listener for its lifetime. The OracleDependency.Port
static field can be changed after the creation of the notification listener, but doing so does not affect the actual port number that the notification listener listens on.
OracleDependency
static methods are listed in Table 7-8.
Table 7-8 OracleDependency Static Methods
Static Methods | Description |
---|---|
Equals |
Inherited from Object |
GetOracleDependency | Returns an OracleDependency instance based on the specified unique identifier |
This static method returns an OracleDependency
instance based on the specified unique identifier.
Declaration
// C#
public static OracleDependency GetOracleDependency(string guid)
Parameters
guid
The string representation of the unique identifier of an OracleDependency
instance.
Exceptions
ArgumentException
- The specified unique identifier cannot locate an OracleDependency
instance.
Return Value
An OracleDependency
instance that has the specified guid
parameter.
OracleDependency
properties are listed in Table 7-9.
Table 7-9 OracleDependency Properties
Properties | Description |
---|---|
DataSource | Indicates the data source associated with the OracleDependency instance |
HasChanges | Indicates whether or not there is any change in the database associated with this dependency |
Id | Represents the unique identifier for the OracleDependency instance |
IsEnabled | Specifies whether or not the dependency is enabled between the application and the database |
RegisteredResources | Indicates the database resources that are registered in the notification registration |
UserName | Indicates the database user name associated with the OracleDependency instance |
This property indicates the data source associated with the OracleDependency
instance.
Declaration
// C# public string DataSource{get;}
Property Value
A string that indicates the data source associated with the OracleDependency
instance.
Remarks
The DataSource
property is populated with the data source once the OracleCommand
associated with the OracleDependency
executes and registers for the notification successfully.
This property indicates whether or not there is any change in the database associated with this dependency.
Declaration
// C# public bool HasChanges{get;}
Property Value
A bool
value that returns True
if the database has detected changes that are associated with this dependency; otherwise, returns False
.
Remarks
As an alternative to using the OnChange
event, applications can check the HasChanges
property to determine if there are any changes in the database associated with this dependency.
Once the HasChanges
property is accessed, its value is reset to False
so that the next notification can then be acknowledged.
This property represents the unique identifier for the OracleDependency
instance.
Declaration
// C# public string Id{get;}
Property Value
A string that represents the unique identifier that was generated for the OracleDependency
instance when it was created.
Remarks
This property is set when the OracleDependency
instance is created.
This property specifies whether or not the dependency is enabled between the application and the database.
Declaration
// C# public bool IsEnabled {get;}
Property Value
A bool
value that specifies whether or not dependency is enabled between the application and the database.
Remarks
The dependency between the application and the database is not established when the OracleDependency
instance is created. The dependency is established when the command that is associated with this dependency is executed, at which time the notification request is registered with the database. The dependency ends when the notification registration is removed from the database or when it times out.
This property indicates the database resources that are registered in the notification registration.
Declaration
// C# public ArrayList RegisteredResources{get;}
Property Value
The registered resources in the notification registration.
Remarks
The ArrayList
contains all the command statement or statements that are registered for notification through this OracleDependency
object. It is appropriately updated when the database change notification is registered by a command execution.
This property indicates the database user name associated with the OracleDependency
instance.
Declaration
// C# public string UserName{get;}
Property Value
A string that indicates the database user name associated with the OracleDependency
instance. This database user registers the database change notification request with the database.
Remarks
The UserName
property is populated with the user name once the OracleCommand
associated with the OracleDependency
executes and registers for the notification successfully. Only the database user who creates the notification registration, or the database system administrator, can remove the registration.
The user specified by this property must have the CHANGE
NOTIFICATION
privilege to register successfully for the database change notification with the database.
OracleDependency
methods are listed in Table 7-10.
Table 7-10 OracleDependency Methods
Methods | Description |
---|---|
AddCommandDependency | Binds the OracleDependency instance to the specified OracleCommand instance |
Equals |
Inherited from Object |
GetHashCode |
Inherited from Object |
GetType |
Inherited from Object |
RemoveRegistration | Removes the specified dependency between the application and the database |
ToString |
Inherited from Object |
This instance method binds the OracleDependency
instance to the specified OracleCommand
instance.
Declaration
// C#
Public void AddCommandDependency (OracleCommand cmd);
Parameters
cmd
The command that is to be bound to the OracleDependency
object.
Exceptions
ArgumentNullException
- The cmd
parameter is null.
InvalidOperationException
- The specified OracleCommand
instance already contains a notification request.
Remarks
An OracleDependency
instance can bind to multiple OracleCommand
instances.
While it binds an existing OracleDependency
instance to an OracleCommand
instance, the AddCommandDependency
method creates an OracleNotificationRequest
instance, and sets it to the specified OracleCommand.Notification
property.
When this method creates an OracleNotificationRequest
instance, the following OracleNotificationRequest
properties are set:
IsNotifiedOnce
is set to the value True
.
Timeout
is set to 50,000 seconds.
IsPersistent
is set to the value False
, indicating that the invalidation message is stored in an in-memory queue before delivery.
With this method, multiple commands can be associated with a single database change notification registration request. Furthermore, the OracleNotificationRequest
attribute values assigned to the OracleCommand
can be changed once the association between the OracleCommand
and the OracleDependency
is established.
However, when multiple OracleCommand
objects are associated with a single OracleDependency
object, the OracleNotificationRequest
attributes (Timeout
, IsPersistent
, and IsNotifiedOnce
) of the first executed OracleCommand
object are used for registration, the attributes associated with subsequent OracleCommand
executions will be ignored.
Furthermore, once a command associated with an OracleDependency
is executed and registered, all other subsequent command executions and registration associated with the same OracleDependency
must use a connection with the same "User
Id"
and "Data
Source"
connection string attribute value settings.
Otherwise, an exception will be thrown.
This instance method removes the specified dependency between the application and the database. Once the registration of the dependency is removed from the database, the OracleDependency
is no longer able to detect any changes that the database undergoes.
Declaration
// C#
public void RemoveRegistration(OracleConnection con)
Parameters
con
The connection associated with the OracleDependency
instance.
Exceptions
InvalidOperationException
- The associated connection is not open.
Remarks
The notification registration associated with the OracleDependency
instance is removed from the database.
The OracleConnection
parameter must be in an opened state. This instance method does not open the connection implicitly for the application.
An exception is thrown if the dependency is not valid.
The OracleDependency
event is listed in Table 7-11.
Table 7-11 OracleDependency Event
Event | Description |
---|---|
OnChange | An event that is sent when a database notification associated with the dependency is received from the database |
The OnChange
event is sent when a database notification associated with the dependency is received from the database. The information related to the notification is stored in the OracleChangeNotificationEventArgs
class.
Declaration
// C# public event OnChangeEventHandler OnChange;
Remarks
The OnChange
event occurs if any result set associated with the dependency changes. For objects that are part of a Transaction, notifications will be received for each modified object. This event also occurs for other actions related to database or registration status, such as database shutdowns and startups, or registration timeouts.