OraclePersonalizationProvider Class

The OraclePersonalizationProvider class enables ASP.NET developers to store Web parts personalization information in an Oracle database.

Class Inheritance

System.Object

  System.Configuration.Provider.ProviderBase

    System.Web.UI.WebControls.WebParts.PersonalizationProvider

      Oracle.Web.Personalization.OraclePersonalizationProvider

Declaration

// C#
public class OraclePersonalizationProvider: PersonalizationProvider

Thread Safety

All public static methods are thread-safe, although instance members are not guaranteed to be thread-safe.

Remarks

This class allows ASP.NET applications to store and manage personalization information in an Oracle database.

Example

The following is a web.config example for an ASP.NET application that uses an OraclePersonalizationProvider as the default provider. This configuration uses the connection string and default attribute values specified in the machine.config file.

<?xml version="1.0"?>
<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <system.web>
    <webParts>
      <personalization defaultProvider="OraclePersonalizationProvider"/>
    </webParts>
  </system.web>
</configuration>

The following is a web.config example for an ASP.NET application that uses an OraclePersonalizationProvider as the default provider, with customized settings and an application-specific connection string:

<?xml version="1.0"?>
<configuration xmlns=
  "http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <connectionStrings>
    <add name="my_personalization_app_con_string" connectionString=
      "User Id=scott;Password=tiger;Data Source=Oracle"/>
  </connectionStrings>
  <system.web>
    <webParts>
      <!-- Enable and customize OraclePersonalizationProvider -->
      <personalization defaultProvider="CustomOraclePersonalizationProvider">
        <providers>
          <add name="CustomOraclePersonalizationProvider"
               type="Oracle.Web.Personalization.OraclePersonalizationProvider,
                     Oracle.Web, Version=2.112.2.0, Culture=neutral,
                     PublicKeyToken=89b483f429c47342"
               connectionStringName="my_personalization_app_con_string"
               applicationName="my_personalization_app"/>
        </providers>
      </personalization>
    </webParts>
  </system.web>
</configuration>

Note that the applicationName attribute should be set to a unique value for each ASP.NET application.

Requirements

Namespace: Oracle.Web.Personalization

Assembly: Oracle.Web.dll

Oracle Providers for ASP.NET Version: Oracle Providers for ASP.NET 2.0 and Oracle Providers for ASP.NET 4

---

OraclePersonalizationProvider Members

OraclePersonalizationProvider members are listed in the following tables.

OraclePersonalizationProvider Constructors

The OraclePersonalizationProvider constructor is listed in Table 8-1.

OraclePersonalizationProvider Static Methods

OraclePersonalizationProvider static methods are listed in Table 8-2.

OraclePersonalizationProvider Public Properties

OraclePersonalizationProvider public properties are listed in Table 8-3.

OraclePersonalizationProvider Public Methods

OraclePersonalizationProvider public methods are listed in Table 8-4.

---

OraclePersonalizationProvider Constructors

OraclePersonalizationProvider constructors create instances of the OraclePersonalizationProvider class.

Overload List:

• OraclePersonalizationProvider()

  This constructor creates an instance of the OraclePersonalizationProvider class.

OraclePersonalizationProvider()

This constructor creates an instance of the OraclePersonalizationProvider class.

Declaration

// C#
public OraclePersonalizationProvider();

Remarks

ASP.NET applications call this constructor to create an instance of the OraclePersonalizationProvider class as specified in the application configuration file. Initialization values for the OraclePersonalizationProvider instance are passed through the Initialize method.

---

OraclePersonalizationProvider Static Methods

The OraclePersonalizationProvider static methods are listed in Table 8-5.

---

OraclePersonalizationProvider Public Properties

The OraclePersonalizationProvider public properties are listed in Table 8-6.

ApplicationName

This property gets or sets the name of the application that the personalization information is specific to.

Declaration

// C#
public override string ApplicationName{get; set;}

Property Value

The name of the application. If the applicationName attribute is not specified in the application configuration file, or if the value is an empty string, then this property is set to the application virtual path.

Exceptions

HttpException - The caller does not have high trust for ASP.NET hosting.

ProviderException - The ApplicationName string is greater than 256 characters.

Remarks

The main purpose of the ApplicationName property is to scope the data managed by OraclePersonalizationProvider object. Applications that specify the same ApplicationName string when configuring the Web parts personalization service share personalization state, but applications that specify unique ApplicationName strings do not. The OraclePersonalizationProvider must associate the personalization state with application names so operations performed on personalization data sources can be scoped accordingly.

The following example shows typical code that the OraclePersonalizationProvider might use to retrieve the personalization state for a user named Scott and an application named App:

SELECT * FROM PersonalizationState
WHERE UserName='Scott' AND Path='~/Default.aspx'
AND ApplicationName='App'

The final AND in the WHERE clause ensures that other applications that contain personalization state keyed by the same user name and path do not conflict with the App application.

If no value is specified for the applicationName attribute in the configuration file, then the default is the ApplicationPath property value for the current request. The attribute name in the configuration file is case-sensitive.

The ApplicationName property is not thread-safe. It is recommended that application code not allow users to set the ApplicationName property in Web applications.

CommandTimeout

This property gets the number of seconds that the command is allowed to execute before it is terminated with an exception.

Declaration

// C#
public int CommandTimeout {get;}
 

Property Value

An int.

Remarks

To customize a provider, ASP.NET developers can set an integer value for this property through the web.config file using the commandTimeout attribute.

The default value is 30 seconds. The attribute name in the configuration file is case-sensitive.

---

OraclePersonalizationProvider Public Methods

The OraclePersonalizationProvider public methods are listed in Table 8-7.

FindState

This method returns a collection containing zero or more PersonalizationStateInfo-derived objects based on scope and specific query parameters.

Declaration

// C#
public override PersonalizationStateInfoCollection FindState(PersonalizationScope
   scope, PersonalizationStateQuery query, int pageIndex, int pageSize, 
   out int totalRecords);

Parameters

• scope

  The scope of query (User or Shared) for personalization information. This cannot be a null reference.

• query

  The query to be used for filtering personalization information. This can be a null reference.

• pageIndex

  The location where the query starts.

• pageSize

  The number of records to return.

• totalRecords

  The total number of records available.

Return Value

A PersonalizationStateInfoCollection object containing zero or more PersonalizationStateInfo-derived objects.

Exceptions

ArgumentOutOfRangeException - The scope contains a value other than PersonalizationScope.User or PersonalizationScope.Shared.

OracleException - An Oracle-related error has occurred.

ArgumentException - One of the following conditions exists:

• The value of the pageSize parameter is 0 or 1.

• The pageIndex or pageSize parameter is less than 0.

• ((pageIndex * pageSize + pageSize) - 1) is greater than Int32.MaxValue. -1 accounts for zero-based indexing of records.

Remarks

The PersonalizationStateInfo-derived objects should be returned in alphabetic order and sorted by a combination of their Path and Username property values, both in ascending order.

This method passes the query wildcard characters to the underlying Oracle database. The database performs a wildcard search on a partial path with the wildcard character appearing at the beginning, the end, or the middle of the search string text in the PathToMatch property of the query parameter. For example, setting the PathToMatch property to ~/appdir% finds all paths that start with ~/appdir.

Likewise, in a wildcard search on a partial user name, the wildcard character can appear at any point in the text string of the UsernameToMatch property of the query parameter. For example, to find all user names that start with scott, the UsernameToMatch parameter looks like scott%.

The following query rules must be followed:

• If only the scope parameter is provided, and the query parameter is null or all the properties on the query parameter return either a null reference or default values, then all records matching the indicated scope parameter are returned.

• If the PathToMatch property is not a null reference, then the returned records are also filtered based on paths that match the PathToMatch value.

• If the UsernameToMatch property is not a null reference, then the returned records are also filtered based on user names that match the UsernameToMatch property value.

• If the UserInactiveSinceDate property is not equal to the MaxValue, then the records returned are also filtered to return only those records associated with inactive users. The comparison includes records where the Last ActivityDate property is less than or equal to the User Inactive Since Date property.

This method does not validate combinations of query parameters. For example, the application code can request a set of personalization state records associated with a specific user name in the shared scope. Because user names are not associated with shared information, the returned collection is empty.

GetCountOfState

This method returns the number of rows in the underlying Oracle database that are within the specified scope.

Declaration

// C#
public override int GetCountOfState(PersonalizationScope scope,
   PersonalizationStateQuery query);

Parameters

• scope

  The scope of query (User or Shared) for personalization information. This cannot be a null reference.

• query

  The query to be used for filtering personalization information. This can be a null reference.

Return Value

The number of rows in the underlying data source that are within the specified scope parameter.

Exceptions

ArgumentException -The PathToMatch or the UsernameToMatch property of query is a non-null reference and is an empty string ("") after trimming.

ArgumentOutOfRangeException - The scope specified is not a valid value from the PersonalizationScope enumeration.

OracleException - An Oracle-related error has occurred.

Remarks

This method passes the query wildcard characters to the underlying Oracle database. The database performs a wildcard search on a partial path with the wildcard character appearing at the beginning, the end, or the middle of the search string text in the PathToMatch property of the query parameter. For example, setting the PathToMatch property to ~/appdir% finds all paths that start with ~/appdir.

Likewise, in a wildcard search on a partial user name, the wildcard character can appear at any point in the text string of the UsernameToMatch property of the query parameter. For example, to find all user names that start with scott, the UsernameToMatch parameter looks like scott%

The following query constraints must be followed:

• If only the scope parameter is provided, and the query parameter is a null reference or all the properties on the query parameter return either a null reference or default values, then all records matching the indicated scope parameter are returned.

• If the PathToMatch property is not a null reference, then the records returned are also filtered based on paths that match the PathToMatch value.

• If the UsernameToMatch property is not a null reference, then the returned records are also filtered based on user names that match the UsernameToMatch property value.

• If the UserInactiveSinceDate property is not equal to the MaxValue, then the returned records are also filtered to return only those records associated with inactive users. The comparison includes records where the LastActivityDate property is less than or equal to the UserInactiveSinceDate property.

Initialize

This method initializes the OraclePersonalizationProvider with the property values specified in the ASP.NET application configuration file (web.config).

Declaration

// C#
public override void Initialize(string name, NameValueCollection config);

Parameters

• name

  The friendly name of the provider.

• config

  A collection of the name/value pairs configuration options for this provider.

Exceptions

HttpException - The current trust level is less than Low.

InvalidOperationException - An attempt is made to call the Initialize method on a provider that has already been initialized.

ArgumentNullException - The config parameter is a null reference.

System.Configuration.Provider.ProviderException - One of the following conditions exists in the application configuration file:

• The connectionStringName attribute is empty or does not exist in the application configuration file.

• The value of the connection string for the connectionStringName attribute value is empty, or the specified connectionStringName attribute does not exist in the application configuration file.

• The applicationName attribute value exceeds 256 characters.

• The application configuration file for this OraclePersonalizationProvider instance contains an unrecognized attribute.

Remarks

The Initialize method is not intended to be called directly by the application.

ResetState

This method deletes personalization state information from the underlying data source, based on the specified parameters.

Declaration

// C#
public override int ResetState(PersonalizationScope scope, string[] paths,
   string[] usernames);

Parameters

• scope

  A PersonalizationScope type indicating the personalization information to be queried. This value cannot be a null reference.

• paths

  The paths for personalization information in the shared scope parameter to be deleted.

• usernames

  The user names for personalization information in the user scope parameter to be deleted.

Return Value

The number of rows deleted.

Exceptions

ArgumentOutOfRangeException - The scope parameter specified is not a member of the PersonalizationScope enumeration value.

OracleException - An Oracle-related error has occurred.

ArgumentException - Either of the following conditions exists:

• The paths or usernames parameter is an empty array.

• Elements of the paths or usernames arrays do not meet the validation rules. Validation rules are discussed in the following Remarks section.

Remarks

This method performs its operations as a single, atomic transaction.

Any paths and usernames elements contained within the respective arrays must meet the following validation rules. If a validation rule fails for any member of the parameter arrays, then an ArgumentException exception is thrown. The validation rules are:

• Null reference values are not allowed.

• An empty string ("") is not allowed. Parameters should be trimmed prior to performing an empty string check.

• The usernames array cannot contain a comma (,).

ResetUserState

This method deletes user personalization data from the underlying Oracle data source, based on the specified parameters.

Declaration

// C#
public override int ResetUserState(string path, DateTime userInactiveSinceDate);

Parameters

• path

  The path of the personalization data to be deleted. This value can be a null reference but cannot be an empty string ("").

• userInactiveSinceDate

  The date that indicates the last activity.

Return Value

The count of rows deleted from the underlying Oracle data source.

Exceptions

ArgumentException - The path parameter is an empty string.

OracleException - An Oracle-related error has occurred.

Remarks

The parameters of this method have the following restrictions:

• The path parameter cannot contain wildcard characters.

• If the path parameter is a non-null reference, then only per-user personalization records associated with the path parameter are deleted.

• Only per-user personalization records associated with users that are considered inactive since the date specified in the userInactiveSinceDate parameter are deleted. The exact comparison deletes records where the Last Activity Date property is less than or equal to the userInactiveSinceDate parameter.

• If both parameters are provided, then records that match both constraints are deleted.

• The path parameter can be a null reference.

• The path parameter cannot be an empty string after trimming.

• The userInactiveSinceDate parameter cannot be a null reference.