Skip Headers
Oracle® Data Provider for .NET Developer's Guide
10g Release 2 (10.2)

B14307-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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

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

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

OracleDependency constructors create instances of the OracleDependency class.

Overload List:

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.


Note:

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.

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

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:

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 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

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:


OracleDependency Static Fields

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

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 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

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

GetOracleDependency

This static method returns an OracleDependency instance based on the specified unique identifier.

Declaration

// C#
public static OracleDependency GetOracleDependency(string guid)

Parameters

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 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

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.

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 database change notification is registered by a command execution.

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 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

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

AddCommandDependency

This instance method binds the OracleDependency instance to the specified OracleCommand instance.

Declaration

// C#
Public void AddCommandDependency (OracleCommand cmd);

Parameters

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:

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.

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

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 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

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.