| Oracle® Providers for ASP.NET Developer's Guide 11g Release 2 (11.2.0.1.2) for Microsoft Windows Part Number E17192-03 |
|
|
View PDF |
| Oracle® Providers for ASP.NET Developer's Guide 11g Release 2 (11.2.0.1.2) for Microsoft Windows Part Number E17192-03 |
|
|
View PDF |
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.1.2, 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
See Also:
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 |
|---|---|
|
Instantiates a new instance of the |
OraclePersonalizationProvider Static Methods
OraclePersonalizationProvider static methods are listed in Table 8-2.
Table 8-2 OraclePersonalizationProvider Static Methods
| Static Methods | Description |
|---|---|
|
|
Inherited from |
|
|
Inherited from |
OraclePersonalizationProvider Public Properties
OraclePersonalizationProvider public properties are listed in Table 8-3.
Table 8-3 OraclePersonalizationProvider Public Properties
| Public Properties | Description |
|---|---|
|
Gets or sets the name of the application that is used to specify personalization information specific to an application |
|
|
Gets the number of seconds that the command is allowed to execute before it is terminated with an exception |
|
|
|
Inherited from |
|
|
Inherited from |
OraclePersonalizationProvider Public Methods
OraclePersonalizationProvider public methods are listed in Table 8-4.
Table 8-4 OraclePersonalizationProvider Public Methods
| Public Methods | Description |
|---|---|
|
Returns a collection containing zero or more |
|
|
Returns the number of rows in the underlying Oracle database that are within the specified scope |
|
|
Initializes the Oracle personalization provider |
|
|
|
Inherited from |
|
|
Inherited from |
|
Deletes personalization state information from the underlying data source, based on the specified parameters |
|
|
Deletes user personalization data from the underlying Oracle data source, based on the specified parameters |
|
|
|
Inherited from |
|
|
Inherited from |
|
|
Inherited from |
|
|
Inherited from |
|
|
Inherited from |
|
|
Inherited from |
OraclePersonalizationProvider constructors create instances of the OraclePersonalizationProvider class.
Overload List:
OraclePersonalizationProvider()
This constructor creates an instance of the OraclePersonalizationProvider class.
See Also:
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.
See Also:
The OraclePersonalizationProvider static methods are listed in Table 8-5.
Table 8-5 OraclePersonalizationProvider Static Methods
| Static Methods | Description |
|---|---|
|
|
Inherited from |
|
|
Inherited from |
See Also:
The OraclePersonalizationProvider public properties are listed in Table 8-6.
Table 8-6 OraclePersonalizationProvider Public Properties
| Public Properties | Description |
|---|---|
|
Gets or sets the name of the application that is used to specify personalization information specific to an application |
|
|
Gets the number of seconds that the command is allowed to execute before it is terminated with an exception |
|
|
|
Inherited from |
|
|
Inherited from |
See Also:
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.
See Also:
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.
See Also:
The OraclePersonalizationProvider public methods are listed in Table 8-7.
Table 8-7 OraclePersonalizationProvider Public Methods
| Public Methods | Description |
|---|---|
|
Returns a collection containing zero or more |
|
|
Returns the number of rows in the underlying Oracle database that are within the specified scope |
|
|
Initializes the Oracle personalization provider |
|
|
|
Inherited from |
|
|
Inherited from |
|
Deletes personalization state information from the underlying data source, based on the specified parameters |
|
|
Deletes user personalization data from the underlying Oracle data source, based on the specified parameters |
|
|
|
Inherited from |
|
|
Inherited from |
|
|
Inherited from |
|
|
Inherited from |
|
|
Inherited from |
|
|
Inherited from |
See Also:
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.
See Also:
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.
See Also:
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.
See Also:
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 (,).
See Also:
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.
|
 Copyright © 2007, 2010, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|