Skip Headers
Oracle Providers for ASP.NET Developer's Guide
11g Release 1 (11.1.0.6.20)

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

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.111.6.20, 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

Microsoft .NET Framework Version: 2.0 or later


OraclePersonalizationProvider Members

OraclePersonalizationProvider members are listed in the following tables.

OraclePersonalizationProvider Constructors

The OraclePersonalizationProvider constructor is listed in Table 8-1.

Table 8-1 OraclePersonalizationProvider Constructor

Constructor Description

OraclePersonalizationProvider Constructors

Instantiates a new instance of the OraclePersonalizationProvider class


OraclePersonalizationProvider Static Methods

OraclePersonalizationProvider static methods are listed in Table 8-2.

Table 8-2 OraclePersonalizationProvider Static Methods

Static Methods Description

Equals

Inherited from System.Object

ReferenceEquals

Inherited from System.Object


OraclePersonalizationProvider Public Properties

OraclePersonalizationProvider public properties are listed in Table 8-3.

Table 8-3 OraclePersonalizationProvider Public Properties

Public Properties Description

ApplicationName

Gets or sets the name of the application that is used to specify personalization information specific to an application

CommandTimeout

Gets the number of seconds that the command is allowed to execute before it is terminated with an exception

Description

Inherited from System.Configuration.Provider.Providerbase

Name

Inherited from System.Configuration.Provider.Providerbase


OraclePersonalizationProvider Public Methods

OraclePersonalizationProvider public methods are listed in Table 8-4.

Table 8-4 OraclePersonalizationProvider Public Methods

Public Methods Description

FindState

Returns a collection containing zero or more PersonalizationStateInfo-derived objects based on scope and specific query parameters

GetCountOfState

Returns the number of rows in the underlying Oracle database that are within the specified scope

Initialize

Initializes the Oracle personalization provider

Equals

Inherited from System.Object (Overloaded)

ResetPersonalizationState

Inherited from System.Web.UI.WebControls.WebParts. PersonalizationProvider

ResetState

Deletes personalization state information from the underlying data source, based on the specified parameters

ResetUserState

Deletes user personalization data from the underlying Oracle data source, based on the specified parameters

GetHashCode

Inherited from System.Object

GetType

Inherited from System.Object

ToString

Inherited from System.Object

SavePersonalizationState

Inherited from System.Web.UI.WebControls.WebParts.PersonalizationProvider

DetermineInitialScope

Inherited from System.Web.UI.WebControls.WebParts.PersonalizationProvider

DetermineUserCapabilities

Inherited from System.Web.UI.WebControls.WebParts.PersonalizationProvider



OraclePersonalizationProvider Constructors

OraclePersonalizationProvider constructors create instances of the OraclePersonalizationProvider class.

Overload List:

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.

Table 8-5 OraclePersonalizationProvider Static Methods

Static Methods Description

Equals

Inherited from System.Object

ReferenceEquals

Inherited from System.Object



OraclePersonalizationProvider Public Properties

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

Table 8-6 OraclePersonalizationProvider Public Properties

Public Properties Description

ApplicationName

Gets or sets the name of the application that is used to specify personalization information specific to an application

CommandTimeout

Gets the number of seconds that the command is allowed to execute before it is terminated with an exception

Description

Inherited from System.Configuration.Provider.Providerbase

Name

Inherited from System.Configuration.Provider.Providerbase


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.

Table 8-7 OraclePersonalizationProvider Public Methods

Public Methods Description

FindState

Returns a collection containing zero or more PersonalizationStateInfo-derived objects based on scope and specific query parameters

GetCountOfState

Returns the number of rows in the underlying Oracle database that are within the specified scope

Initialize

Initializes the Oracle personalization provider

Equals

Inherited from System.Object (Overloaded)

ResetPersonalizationState

Inherited from System.Web.UI.WebControls.WebParts.PersonalizationProvider

ResetState

Deletes personalization state information from the underlying data source, based on the specified parameters

ResetUserState

Deletes user personalization data from the underlying Oracle data source, based on the specified parameters

GetHashCode

Inherited from System.Object

GetType

Inherited from System.Object

ToString

Inherited from System.Object

SavePersonalizationState

Inherited from System.Web.UI.WebControls.WebParts.PersonalizationProvider

DetermineInitialScope

Inherited from System.Web.UI.WebControls.WebParts.PersonalizationProvider

DetermineUserCapabilities

Inherited from System.Web.UI.WebControls.WebParts.PersonalizationProvider


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

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:

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:

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

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:

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

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:

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

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:

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:

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

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: