Add(string)
This method adds a role to the roles list and sets it on a on a newly created connection or a connection coming from connection pool.
Declaration
// C#
public void Add(string Role);Parameters
Role - Role name that will be set on a connection.
Exceptions
ArgumentNullException - It is thrown when role name is provided as Null.
ArgumentException - It is thrown when role name is provided as empty string.
ArgumentException - It is thrown when case sensitive role name is not enclosed properly within double quotes.
InvalidOperationException - It is thrown when the connection is already open.
Remarks
The user must already be granted the database roles before adding those roles to the OracleRoleCollection object. Otherwise, an error occurs indicating the role is not granted or does not exist. The database roles not added to the ODP.NET collection are disabled for the session, except when no roles are added to the collection. In this case, the default roles are enabled in the database session.
To modify an existing connection's enabled roles, close the connection, modify the OracleRoleCollection instance associated with the connection instance, and reopen the connection.
To enable all roles granted, except roles with passwords, add ALL to the OracleRoleCollection instance. To disable all roles including default roles, add NONE to the OracleRoleCollection instance. ALL and NONE are reserved keywords for role names. When using ALL or NONE, make sure no other role names are added to the collection. Otherwise, it results in errors.
Once the session is created after inserting the ALL reserved keyword or when OracleRoleCollection.UseAllExcept property is set to true, ODP.NET does not modify the session's enabled roles if the database modifies the default roles until the OracleRoleCollection is itself modified. This holds true even for the connections which are checked into the pool.
To enable all previously granted user roles except for a particular collection, set OracleRoleCollection.UseAllExcept to true. It enables all the roles except those which are added in OracleRoleCollection object associated with OracleConnection object. If this property is set to True, then the password-based roles are not enabled on the connection. If OracleRoleCollection.UseAllExcept is true and nothing is added in the OracleRoleCollection object, then ODP.NET will not enable or disable any roles on the connection. The connection state with respect to roles enabled remains unchanged.
Note:
For DRCP connections, because random sessions are checked out from server pool and it can have any set of roles enabled on the session, it is necessary to add the ALL keyword in the OracleRoleCollection object associated with the OracleConnection object, if you want to enable all the non-password based roles on the upcoming session.