OracleDependency Class

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

System.Object

  Oracle.DataAccess.Client.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

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

Comment: Not supported in a .NET stored procedure

---

OracleDependency Members

OracleDependency members are listed in the following tables.

OracleDependency Constructors

OracleDependency constructors are listed in Table 9-1.

OracleDependency Static Fields

The OracleDependency static field is listed in Table 9-2.

OracleDependency Static Methods

OracleDependency static methods are listed in Table 9-3.

OracleDependency Properties

OracleDependency properties are listed in Table 9-4.

OracleDependency Methods

OracleDependency methods are listed in Table 9-5.

OracleDependency Events

The OracleDependency event is listed in Table 9-6.

---

OracleDependency Constructors

OracleDependency constructors create instances of the OracleDependency class.

Overload List:

• OracleDependency ( )

  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.

OracleDependency ( )

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.

OracleDependency(OracleCommand)

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

OracleDependency(OracleCommand, bool, int, bool)

This constructor creates an instance of the OracleDependency class and binds it to the specified OracleCommand instance, while specifying whether or not a registration 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 Continuous Query 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 Continuous Query 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.

---

OracleDependency Static Fields

The OracleDependency static field is listed in Table 9-7.

Port

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 Continuous Query Notifications from the database. One notification listener is capable of listening to all Continuous Query 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

OracleDependency static methods are listed in Table 9-8.

GetOracleDependency

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

OracleDependency properties are listed in Table 9-9.

DataSource

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.

HasChanges

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.

Id

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.

IsEnabled

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.

QueryBasedNotification

This instance property specifies whether the change notification registration is object-based or query-based.

Declaration

// C#
public bool QueryBasedNotification{get; set;}

Property Value

Specifies whether the change notification registration is object-based or not.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

This property value will be ignored if it is set after the command execution that registers the command for change notification.

By default, this property is true.

ODP.NET developers can register their queries on the row level, not just the object level, beginning with Oracle Data Provider for .NET release 11.1 and Oracle Database 11g release 1 (11.1). The application only receives notification when the selected row or rows change. Query-based notifications provide developers more granularity for using client-side cached data, as they can be more specific about what changes the application needs to be notified of.

OracleNotificationType enumeration is set to Query for query-based notifications.

RegisteredQueryIDs

This instance property provides a list of CHANGE_NOTIFICATION_QUERY_IDs.

Declaration

// C#
public ArrayList RegisteredQueryIDs {get;}

Property Value

This property is an ArrayList of CHANGE_NOTIFICATION_QUERY_IDs.

Exceptions

ObjectDisposedException - The object is already disposed.

Remarks

This property provides a list of CHANGE_NOTIFICATION_QUERY_IDs that uniquely identify the query that has been registered for change notification. The notification returned from the database will also contain these IDs, allowing applications to determine the query that the notifications are for.

The QueryId at index n in RegisteredQueryIDs is for the statement at index n the RegisteredResources at index n.

RegisteredResources

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 Continuous Query Notification is registered by a command execution.

RowidInfo

This property specifies whether or not ROWID information is part of change notification events fired whenever data changes on the database.

Declaration

// C#
public OracleRowidInfo RowidInfo {get; set;};
 

Property Value

An OracleRowidInfo enumeration type that determines the inclusion of ROWID in the change notification event.

Remarks

There are three OracleRowidInfo enumeration types that are valid for this property:

• Default includes ROWID information in the change notification event only if OracleCommand.AddRowid property is set to true or if ROWID is in the select list of the query that is registered for change notification.

• Include includes ROWID information regardless of whether or not ROWID is in the select-list for the query.

• Exclude excludes ROWID information regardless of whether or not ROWID is in the select-list.

For change notification registrations that involve stored procedure executions, change notification events related to the REF CURSOR contain ROWID information only if RowidInfo property is set to OracleRowidInfo.Include.

UserName

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 Continuous Query 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 Continuous Query Notification with the database.

---

OracleDependency Methods

OracleDependency methods are listed in Table 9-10.

AddCommandDependency

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

RemoveRegistration

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.

---

OracleDependency Events

The OracleDependency event is listed in Table 9-11.

OnChange

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.