Skip Headers
Oracle® Application Server Portal Configuration Guide
10g Release 2 (10.1.2)
B14037-03
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

C Using OracleAS Portal Installation and Configuration Scripts

After installing OracleAS Portal as part of the Oracle Application Server installation, several scripts are available for post-installation configuration.

The specific topics covered in this appendix include:

C.1 Managing the Invalidation Message Processing Job Using cachjsub.sql

OracleAS Portal uses caching to improve its performance. One type of caching it uses is the invalidation-based caching. In invalidation-based caching, OracleAS Portal caches various objects (pages, portlets, and so on) for a set amount of time. When these objects are requested, they are retrieved from the cache, if available; otherwise they are regenerated from the Oracle Application Server Metadata Repository. The cache for these objects will expire when the maxcache time has been reached, or when the objects are explicitly invalidated (expired) by invalidation messages.

OracleAS Portal uses invalidation messages when it needs to expire objects in the cache. Invalidation messages are categorized as hard and soft invalidations. Hard invalidations take effect immediately, that is, the objects that they intend to invalidate expire from cache immediately. Soft invalidations take effect when they are processed by the invalidation processing job. The frequency by which the invalidation job executes is configurable. This is done using the cachjsub.sql script.

To change the execution frequency of the invalidation processing job:

  1. Locate the following directory:

    ORACLE_HOME/portal/admin/plsql/wwc

  2. On the database where the portal schema is installed, log on to SQL*Plus with the appropriate user name and password for that schema.

    For example:

    sqlplus portal/portal
    
    
  3. Enter the following command to update the execution frequency of the invalidation job:

    SQL> @cachjsub.sql <start_time> <start_time_fmt> <interval_mins>
    
    

    cachjsub.sql takes three parameters:

    • start_time is either when the first job should be run or START.

    • start_time_fmt is the Oracle date format model to be applied to the value of start_time. Refer to the database documentation library for more information about the Oracle date format model.

    • interval_mins is how many minutes each run is scheduled apart.


      Note:

      If START is provided for the first parameter, the second parameter is ignored, and it will default the start time to the current time.

    Example 1:

    SQL> @cachjsub.sql START null 120
    
    

    Example 2:

    SQL> @cachjsub.sql '02-22-2005 7:30' 'MM-DD-YYYY HH:MI' 1440
    
    

    Example 3:

    SQL> @cachjsub.sql '06-14-2005 15:30' 'MM-DD-YYYY HH24:MI' 60
    
    

    Note: Example 3 shows time in the 24-hour format.

C.2 Disabling the IP Check of Cookie Validation

As part of the process of validating the session cookie of a user's request (even if that user is PUBLIC), OracleAS Portal performs a comparison between the IP address stored in the cookie with the IP address of the current client. Only if the two values are the same will OracleAS Portal consider the request legitimate.

When a proxy exists between the user's client and the portal, the IP address stored in the session cookie is that of the proxy, and not that of the client.

Some proxy systems make use of multiple servers, each with different IP addresses. In these circumstances, it is conceivable that the original request from a user's client (the request that causes the session cookie to be created) is routed through one proxy server and that a subsequent request is routed through another, separate, proxy server. In these cases, the IP addresses compared by OracleAS Portal will differ. The request will raise a security violation during the IP checking step. And access to the page will be denied.

Depending on the network configuration into which the Oracle Application Server is installed, it may be necessary to disable IP checking in cookie validation.

To change the state of IP checking in cookie validation, you must use SQL*Plus to update data in both the portal schema and the SSO schema as detailed in Table C-1.

Table C-1 Enabling and Disabling the IP Check


Portal Schema SSO Schema

Enable

IP Checking

update wwsec_enabler_config_info$

set url_cookie_ip_check = 'Y';

commit;

update wwsec_enabler_config_info$

set url_cookie_ip_check ='Y';

update wwsso_ls_configuration_info$

set cookie_ip_check = 'Y';

commit;

Disable

IP Checking

update wwsec_enabler_config_info$

set url_cookie_ip_check = 'N';

commit;

update wwsec_enabler_config_info$

set url_cookie_ip_check ='N';

update wwsso_ls_configuration_info$

set cookie_ip_check = 'N';

commit;


C.3 Using the secupoid.sql Script

By default, OracleAS Portal connects to Oracle Internet Directory using LDAP without SSL. If the Oracle Internet Directory server is configured for an SSL port, though, OracleAS Portal can be configured to use LDAP over SSL, also known as LDAPS.

To configure OracleAS Portal to use SSL to connect to Oracle Internet Directory, you must run the secupoid.sql script. This script enables you to change the following OracleAS Portal configuration parameters related to Oracle Internet Directory:

When you install OracleAS Portal, it is automatically configured to use an Oracle Internet Directory server. However, you may want to change some settings, such as whether to use SSL, after installation. To change to an SSL connection for Oracle Internet Directory, simply run the ORACLE_HOME/portal/admin/plsql/wwc/secupoid.sql script in the PORTAL schema to specify the LDAPS port instead of the LDAP port, and indicate that you want to use SSL.

Running the secupoid.sql Script

This section shows a sample execution of secupoid.sql from SQL*Plus.

In the example, Oracle Internet Directory was initially configured to run LDAP on port 389. Later, an LDAPS port was activated on 636. Because the server name does not change, we retain the old value, update the port, and indicate that we want to use SSL by setting the Use SSL? value to Y. When you run the script, it displays the current configuration and lets you replace any of the configurable settings. The script also enables you to update OracleAS Portal's Oracle Internet Directory cache after running it. Because activating SSL does not change any of the Oracle Internet Directory information cached by OracleAS Portal, it is not usually necessary to refresh the cache in this case.

SQL> @secupoid 
Current Configuration 
-------------------- 
OID Host: oid.domain.com 
OID Port: 389 
Application DN: 
orclApplicationCommonName=PORTAL.040820.123756.096286000,cn=Portal,cn=Products,cn=OracleContext 
Application Password: 3E8C2D1B87CB61011757239C5AA9B390 
Use SSL? N 

PL/SQL procedure successfully completed. 

Updating OID Configuration Entries 
Press [Enter] to retain the current value for each parameter 
For SSL Connection to LDAP, specify "Y"es or "N"o 
------------------------------------------------ 
Enter value for oid_host: 
Enter value for oid_port: 636 
Enter value for app_password: 
Enter value for use_ssl_to_connect_to_ldap: Y 
Enter value for refresh_with_new_settings: N 

PL/SQL procedure successfully completed. 

No errors.

After executing the script, OracleAS Portal is configured for LDAPS access of Oracle Internet Directory.

When secupoid.sql is run, it can change the port number of Oracle Internet Directory stored in the portal schema of the OracleAS Metadata Repository. Running secupoid, however, does not change the values stored in iasconfig.xml. You must manually update the LDAPPort and PortSSLEnabled attributes in the OIDComponent element in iasconfig.xml so that subsequent runs of ptlconfig will not reverse the new settings. Refer to Section A.2, "Portal Dependency Settings File" for more information on the Portal Dependency Settings File.

C.4 Using the secjsdom.sql Script

If you have your Oracle Internet Directory and OracleAS Portal servers residing in different domains, you must explicitly set the JavaScript domain for OracleAS Portal such that it can resolve user and group lists of values. To do this, you must use the secjsdom.sql script located in the directory ORACLE_HOME/portal/admin/plsql/wwc.

Suppose your installation has OracleAS Portal configured to use an Oracle HTTP Server other than Oracle Delegated Administration Services. In this situation, you must have a common domain, so that the values can be transferred from the list of values displayed by Oracle Delegated Administration Services to the page displayed by OracleAS Portal.

To create a common domain for this scenario, follow the steps in Example C-1:

Example C-1 Creating a Common Domain

  1. Log in to SQL*Plus as PORTAL.

  2. Run the following SQL script:

    SQL> @secjsdom.sql <domain_name>
    
    

If, in Example C-1, the Oracle Delegated Administration Services servlet is running on a computer infra.abc.com and OracleAS Portal is running on a computer portal.abc.com, then the secjsdom.sql script should be invoked like this:

@ SQL> @secjsdom.sql abc.com

Performing this procedure enables you to run Oracle Internet Directory lists of values from OracleAS Portal in either Netscape, or Internet Explorer. When using lists of values, a transit window is displayed in addition to the list of values itself. The transit window is required to pass values to OracleAS Portal without forcing pages to reset their domain.

To reset a common domain that was defined, run the secjsdom.sql script as shown in Example C-2:

Example C-2 Resetting a Previously Defined Common Domain Using secjsdom.sql

  1. From your operating system command prompt, go to the following directory:

    DESTINATION_MID_TIER_ORACLE_HOME/portal/admin/plsql/wwc
    
    
  2. Using SQL*Plus, connect to the OracleAS Portal schema as the owner and run the following commands:

    @secjsdom ''
    commit;
    
    

C.5 Configuring the Portal Session Cookie

OracleAS Portal uses a session cookie to maintain session state for portal applications. For portal to work correctly, the client browser must be configured to accept cookies from the server. Upon installation, the portal session cookie has a default name, scope, and security that are set appropriately for most installations. This section describes these defaults, and how they can be changed if needed.

C.5.1 Configuring the Cookie Name

By default the portal's session cookie is named portal after the default Database Access Descriptor (DAD) used to access the portal schema. You can use Oracle Enterprise Manager 10g to change the cookie name, if it needs to explicitly be set to something else. To do this, you must access the DAD Edit page in the Oracle Enterprise Manager 10g Application Server Control Console. This page is located under mod_plsql services of the OracleAS Portal middle-tier component. The cookie name can be set on the Document Alias and Session Parameter page. To change the name of the cookie, provide the desired name in the Session Cookie Name field of the Session Cookie section.

C.5.2 Configuring the Scope of the Cookie

In cases where you want access to the same portal from two middle tiers at the same time, or if you want to open the portal cookie domain as required by the PL/SQL Adapter functionality, you must define the scope of the OracleAS Portal session cookie to be sent to all the middle-tier servers involved in the architecture. By default, the session cookie's domain is scoped to the host from which it was generated. The path for the cookie is set to "/".


Note:

You should make these changes when there is no traffic on the portal, otherwise existing sessions will experience session errors (ORA-20000) after you change the session cookie name.

For example, if the cookie was generated from www.company.com, then the cookie domain is www.company.com. However, let's say that another server, portal.company.com is also a middle-tier server that needs access to that session cookie. Then the cookie domain would need to be widened so that the portal.company.com server can also see the cookie.

Follow these steps to modify the scope of the portal session cookie:

  1. Locate the following directory:

    ORACLE_HOME/portal/admin/plsql/wwc 
    
    
  2. On the database where your OracleAS Portal schema is installed, log on to SQL*Plus as the portal schema. For example:

    sqlplus portal/portal_pwd
    
    
  3. Enter the following command:

    SQL> @ctxckupd
    OracleAS Portal
    Current Settings for Portal Session Cookie:
    Cookie Domain : Only send cookie back to originating host:port
    Set Cookie as Secure: Y
    Enter the domain for the session cookie: .company.com
    Should cookie be flagged as secure for HTTPS sessions? (Y/N): N
    Settings changed to
    Cookie Domain : .company.com
    Do not set cookie as secure. (N)
    SQL>
    
    

    This enables you to set the cookie domain for the session cookie. In this example, the cookie domain is set to .company.com.


Notes:

  • If you want to use different listeners or keep the session cookie throughout different domains, specify a Cookie Domain to be the host name only. For example, if you access OracleAS Portal from two computers:

    machine1.us.company.com:3000

    machine2.us.company.com:4000

    When running ctxckupd.sql, set the cookie domain to .us.company.com.

  • The cookie domain also determines the scope of the NLS_LANGUAGE cookie, which is a persistent cookie that determines the user's preferred language. This NLS_LANGUAGE cookie is set when selecting languages in the set language portlet.


C.5.3 Securing the Cookie

In this release of OracleAS Portal, the script ctxckupd.sql contains an additional option, Set Cookie as Secure.

The default location for this script is ORACLE_HOME/portal/admin/plsql/wwc. When you run this script, you see the following output:

SQL> @ctxckupd
OracleAS Portal
Current Settings for Portal Session Cookie:
Cookie Domain : Only send cookie back to originating host:port
Set Cookie as Secure: Y
Enter the domain for the session cookie...
Leave blank to scope to originating host:
Should cookie be flagged as secure for HTTPS sessions? (Y/N): N
Settings changed to
Cookie Domain : Only send cookie back to originating host:port
Do not set cookie as secure. (N)
SQL>

Set Cookie as Secure indicates that the cookie should be sent back to the server if the request is over an HTTPS connection only. This setting ensures that the session cookie is not transmitted over an insecure connection when it needs to be protected. By default, this option is set to Yes and is sufficient for most deployments.

In some cases, you may need to set the Set Cookie as Secure option to No. For example, if your portal is accessed over both HTTP and HTTPS and you want the session cookie to be shared across both protocols (possible if they are running on the default ports 80 (HTTP) and 443 (HTTPS)). In this instance, when Set Cookie as Secure is set to No, the same cookie produced over an HTTPSrequest, is sent over any subsequent HTTP requests.

C.6 Managing the Session Cleanup Job

OracleAS Portal and OracleAS Single Sign-On perform session management similar to other Web-based applications. Sessions are tracked with cookies. Session information is stored in a table in the OracleAS Portal and OracleAS Single Sign-On schema. When a user logs out, the session information is marked inactive. A DBMS job subsequently cleans up the inactive rows.

The session table accumulates a number of rows that are flagged as active. When a user shuts down the browser instead of logging out, the row is "active", even though it is not actually in use. The cleanup job cleans up the active rows that are older than a specified duration.

When OracleAS Portal is installed, a DBMS job is installed to perform session cleanup of the session table, WWCTX_SSO_SESSION$. The cleanup job is set to run every 24 hours. The first scheduled cleanup occurs 24 hours after the installation of the job.

When the job runs, it deletes all inactive sessions and all sessions marked active (WWCTX_SSO_SESSION$.ACTIVE = 1), that are older than 7 days (WWCTX_SSO_SESSION$.SESSION_START_TIME < sysdate - 7).

These default settings can be modified by running some job management scripts in the OracleAS Portal schema to manage portal sessions, or in the OracleAS Single Sign-On schema to manage OracleAS Single Sign-On sessions. They utilize the same session management infrastructure.

Follow these steps to obtain the current cleanup job information:

  1. Locate the following directory:

    ORACLE_HOME/portal/admin/plsql/wwc
    
    
  2. On the database where the OracleAS Portal or OracleAS Single Sign-On schema is installed, log in to SQL*Plus with the appropriate user name and password for that schema.

    For example:

    sqlplus portal/portal
    
    
  3. Enter the following command to get the current job information:

    SQL> @ctxjget
    
    

    The command results in the display of the currently installed job information, as returned by the DBMS_JOB package:

    The session cleanup job is job ID 7381
    dbms_job.isubmit(job=>7381,what=>'begin execute immediate''begin
    wwctx_sso.cleanup_sessions(p_hours_old => 168); end;''; exception when
    others then null; end;',next_date=>to_date('2001-04-17:14:07:20',
    'YYYY-MM-DD:HH24:MI:SS'),interval=>'SYSDATE + 24/24',no_parse=>TRUE);
    
    PL/SQL procedure successfully completed.
    
    

The results indicate which procedure is executed, what parameters are passed to it, and when the next invocation is to occur. This particular example indicates that the job is to clean up active sessions that are a week old (168 hours). It also indicates that the next scheduled job execution is on 4/17/2001 at 5:14 pm, and the job should run every 24 hours thereafter.

If the job execution must be modified, either to adjust the age of sessions that should be deleted, or to increase or decrease the frequency of cleanup, you can run the ctxjsub.sql script to submit modified execution parameters.

Follow these steps to submit modified job execution parameters:

  1. Locate the following directory:

    ORACLE_HOME/portal/admin/plsql/wwc
    
    
  2. On the database where the OracleAS Portal or OracleAS Single Sign-On schema is installed, log on to SQL*Plus with the appropriate user name and password for that schema. For example:

    sqlplus portal/portal
    
    
  3. Enter the following command to submit new cleanup job information:

    @ctxjsub <hours_old> <start_time> <time_format> <interval_hours>
    
    

Table C-2 lists the ctxjsub parameters.

Table C-2 ctxjsub Parameters

Parameter Description

hours_old

The age of an active session that should be deleted.

start_time

The time that the next job should run.

time_format

The time format string that specifies how start_time is formatted.

interval_hours

The amount of time, in hours, between runs of the cleanup job.


For example:

SQL> @ctxjsub 200 '04/17/2001 10:00' 'MM/DD/YYYY HH24:MI' 12

The job information is displayed, similar to:

Created path for job id.
DBMS_JOB id = 7381
Cleanup job updated. Job ID = 7381

PL/SQL procedure successfully completed.

The cleanup job submission script can be run any number of times to modify the execution parameters. Each invocation updates the job information associated with the job ID for the cleanup job. This job ID is maintained in the preference store so that the job information is updated instead of submitting multiple jobs.

You can also specify a start_time of START, in which case, the time_format parameter is ignored, but you still need to pass it a value (such as NOW). The result is to run the job <interval_hours> hours from now:

SQL> @ctxjsub 168 START NOW 24

This submits the job as it does in the installation.

If you want the cleanup job to execute immediately, then obtain the job ID by calling ctxjget.sql. Once you know the job ID, you can execute the job by issuing the following command in the product schema:

SQL> exec dbms_job.run(7381);

In the preceding example, 7381 is the job ID returned by the call to ctxjget.sql. When you execute a job in this manner, the next automated invocation of the job occurs at interval_hours after this manual invocation. To run the job on the original schedule, resubmit the start_time desired using ctxjsub.sql.

C.7 Timing and Caching Statistics

All OracleAS Portal pages can be run in a special mode in which timing and caching information is displayed. If you want to see this debug information on every page you can set the Parallel Page Engine Parameter showPageDebug to true in the web.xml file.

If you want to see the debug information for just a few select pages and portlets, you can control the logging level by the _debug URL parameter. For example, to see the timing statistics for the following OracleAS Portal page:

http://abc.com/servlet/page?_pageid=21

You can manually insert &_debug=3

To make:

http://abc.com/servlet/page?_pageid=21&_debug=3

Possible values for _debug are 0, 1, 2, 3, 4, and 5.

Values greater than 1 will potentially raise the logmode value for the duration of the request, and trigger all request log messages to be echoed into the page response.


Note:

All values greater than 0 cause _debug=1 to be propagated in back end requests.

Table C-3 shows the results of _debug values:

Table C-3 _debug Values for Timing and Caching Statistics

Value Timing and Caching Statistics? Flag Forwarded to Providers? (as value 1) logmode Raised to a Minimum of Log Messages Written to Page Response?

0

Yes

-

-

-

1

Yes

Yes

-

-

2

Yes

Yes

debug

Yes

3

Yes

Yes

request

Yes

4

Yes

Yes

content

Yes

5

Yes

Yes

parsing

Yes


urlDebugMode and urlDebugUsers are additional parameters that can be used to restrict the use of _debug on a URL. See Appendix D, "Configuring the Parallel Page Engine" for more information.

The following statistics are available when the portal page is run in debug mode:

Figure C-1 shows a page that is running in the _debug=0 mode:

Figure C-1 Portal Page Running in Debug Mode

Description of Figure C-1  follows
Description of "Figure C-1 Portal Page Running in Debug Mode"

C.7.1 Portlet Statistics

In Figure C-1, you can see a number of Portlet related statistics listed under each portlet. Each Portlet has a unique internal reference identification number. This number is used in the "Information for Portlet" summary. For the portlet in the top left corner of Figure C-1, you can see that this number is 6256.

For each portlet the following statistics are listed:

C.7.1.1 Portlet Timing Information

  • Portlet Timing (msecs) (wait msecs)

    Indicates how many milliseconds it took to retrieve the portlet, and how long the request was queued, also in milliseconds.

  • Timing Status

    This is deprecated and no longer in use.

  • XSLT Timing (msecs)

    Displays the number of milliseconds that were needed to retrieve the XSL style sheet, in case the portlet is an XML portlet.

C.7.1.2 Portlet Caching Information

  • Portlet Cache status Web Cache (values) File System Cache (values)

    This is the Cache status from both OracleAS Web Cache and the portal cache.

    Valid values for OracleAS Web Cache are:

    • MISS, or NEW [M] indicating a cache miss in OracleAS Web Cache and that the content that is generated by the portlet is new.

    • MISS, or STALE [G] indicating a cache miss, due to stale content in OracleAS Web Cache.

    • HIT [H] indicating an OracleAS Web Cache hit.

    Valid values for File System Cache are:

    • HIT_PING indicating a cache hit for a validation-based portlet.

    • HIT_EXPIRES indicating a cache hit for an expiry-based portlet.

    • MISS_STALE indicating a cache miss due to stale content in the Cache. This applies to both expiry, and validation-based portlets.

    • MISS_NEW indicating a cache miss and that the content that is generated by the portlet is new. This applies to both expiry, and validation-based portlets.

    If a portlet uses the File System Cache, then the information mentioned in the preceding text will be listed. Otherwise it will be null.

    If there is a hit on OracleAS Web Cache, no details about File System Cache will be displayed because the content is served directly out of OracleAS Web Cache. Additionally, if a portlet does not use OracleAS Web Cache, then no Web Cache information will be printed.

  • From Cache:Web Cache Cache Expires (seconds), Age in Cache (secs), File System Cache (values).

    Information from both OracleAS Web Cache and File System Cache will be printed here based on the type of caching that the portlet uses.

    "Cache Expires" lists the number of seconds after which the portlet content in OracleAS Web Cache will expire.

    "Age in Cache" lists the number of seconds that the portlet content has been Cached in OracleAS Web Cache.

    "File System Cache" displays the information obtained from the File System Cache about Cache Key, Cache Expiry and about the Cache Level in case of a cache hit, with the Cache Status of either HIT_PING, or HIT_EXPIRES.

    In case of a cache hit, the Cache Key and Cache Level (for Validation-based portlets) and Cache Expires and Cache Level (for expiry-based portlets) are displayed, with the Cache Status value of either HIT_PING or HIT_EXPIRES.

    For Validation-based and Expires-based portlets, "None" is printed when there is a cache miss due to the portlet content being new. (Cache Status: MISS_NEW) The portlet is contacted to get the new Cache Key, Cache Expiry and Cache Level.

    For Validation-based portlets, if the content in the Cache has become stale resulting in a cache miss, the current values in the cache for Cache Key and Cache Level are displayed. In this case, the portlet is contacted to get the updated Cache Key and the level (Cache Status: MISS_STALE).

    For Expires-based portlets, when the content in the cache has become stale resulting in a cache miss, a value of INVALID in the Expires field and Cache Level are displayed. In this case, the portlet is contacted to get the updated Cache Expiry and Cache Level (Cache Status: MISS_STALE).

  • From Portlet: (Cache Key) (Cache Level)

    This is the information obtained from the portlet about File System Cache Key, Cache Expiry, and Cache Level when there is a cache miss and when portlet is contacted for the updated, or new values (Cache Status: MISS_NEW, or MISS_STALE). Note that there is no OracleAS Web Cache related information displayed in this section.

    For Validation-based portlets, when there is a cache hit and if the ping is successful, meaning the content in the Cache is still valid, then the portlet does not return a new Cache Key and Cache Level; instead it will indicate that the cache is still valid. In this case, "Ping Success" is displayed (Cache Status: HIT_PING).

    For Expires-based portlets, when there is a cache hit and if the content has not expired, then the portlet is not contacted for the content. In this case, "Not contacted" is displayed (Cache Status: HIT_EXPIRES).

    Following are a few examples that show different caching scenarios and the resulting output. Note that the other page and portlet related output is not shown here.

    Example Caching Information Debug Output 1

    • Portlet Cache: File System Cache, Caching Type: Validation-based, Status: MISS, STALE.

      Caching information for portlet: 
      Portlet Cache status: File System Cache:- MISS,STALE 
      From Cache: File System Cache:- Cache Key: 42, Cache Level: USER 
      From Portlet: Cache Key: 44, Cache Level: USER 
      
      

    Example Caching Information Debug Output 2

    • Portlet Cache: File System Cache, Caching Type: Expires-based, Status: MISS, NEW.

      Caching information for portlet: 
      Portlet Cache status:File System Cache:-  MISS,NEW 
      From Cache: File System Cache:-None 
      From Portlet: Cache Expires: 1, Cache Level: USER 
      
      

    Example Caching Information Debug Output 3

    • Portlet Cache: File System Cache, Web Cache, Caching Type: Validation and Invalidation-based, Status: MISS, NEW in File System Cache and Web Cache.

      Caching information for portlet: 
      Portlet Cache status: Web Cache:- MISS,NEW [M], File System Cache:- MISS,NEW 
      From Cache: Web Cache:- Cache Expires: 86400 secs, Age in Cache: 0 secs , File System Cache:- None 
      From Portlet: Cache Key: 9.0.2.2.1502:04:18:09:19:56, Cache Level: SYSTEM 
      
      

    Example Caching Information Debug Output 4

    • Portlet Cache: Web Cache, Caching Type: Invalidation-based, Status: HIT in Web Cache.

      Caching information for portlet: 
      Portlet Cache status: Web Cache:- HIT [H] 
      From Cache: Web Cache:- Cache Expires: 86400 secs, Age in Cache: 58 secs 
      From Portlet: - 
      
      

C.7.2 Page Statistics

Every page has a unique internal reference identification number, similar to the portlets on the page, shown in Figure C-1.

For the page, the following statistics are listed:

  • Elapsed Time (msecs)

    This is the total amount of time required to generate the page calculated in the Parallel Page Engine (PPE). The actual generation time in the browser can be higher, due to network overhead.

    Elapsed time is made up of page meta WAIT time and Stream time. Page meta WAIT time is the time taken to wait on content through an HTTP connection. Stream time is the time taken streaming and assembling the content pieces. Stream time is in turn composed of the following elements:

    • Page meta time

    • Time waiting for portlets to complete

    • Time taken streaming content to the browser

    Effectively, elapsed time is the total amount of time (in milliseconds) that it takes to put the page together, from the time the request was received to the last byte being written to the browser.

  • Page meta-time (msecs) (wait = msecs)

    Displays the time that it takes to retrieve the page meta data. The wait time (msecs) represents how long the request was queued.

  • Page meta Cache Status (Web Cache values), (Cache Expires msecs), (Age in Cache msecs), (File System Cache values)

    Represents the cache status from both OracleAS Web Cache and portal cache. Valid values for OracleAS Web Cache are MISS, or NEW and HIT. Valid values for portal cache are HIT, or PING, and MISS, or STALE. The Web Cache Expires value and the Age in Cache are both measured in milliseconds.

  • Login meta-time (msecs) (wait msecs)

    Displays the time (in milliseconds) that it takes to retrieve the login meta data. The wait time represents the total amount of time (in milliseconds) that the request spends in the request queue.

  • Login meta Cache Status

    Similar to Page meta Cache Status mentioned earlier, represents the cache status for the login meta data from both Web Cache and portal cache.

C.7.3 Additional Summary Statistics

  • Stream info (msecs)

    Represents (in milliseconds) how long it takes for the page to stream to the browser.

  • processing (msecs)

    Processing time (in milliseconds) for streaming.

  • write (msecs)

    The write lines can repeat several times. The lines represent each physical buffer write to the stream itself. This are one set for each buffer write.

  • flush (msecs)

    The flush logs indicate that the writing stream was flushed. This is logged to keep track of the number of network round trips.

C.8 Using the cfgiasw Script to Configure Mobile Settings

If you want to change portal's references to OracleAS Portal or OracleAS Wireless' portal service URLs, you need to use the script cfgiasw.pl to manually update the references. The script file is located here:

ORACLE_HOME/assistants/opca/

Running the script without parameters will print its usage to the screen, which is shown next:

Usage:

perl cfgiasw.pl -s portal_schema 
     -w ias wireless url 
     -h portal home page url 
     -c connect_string

Table C-4 Oracle Application Server Wireless Configuration Parameters

Parameter Description

-s

Oracle Database schema for OracleAS Portal database objects.

Default = PORTAL

-w

The URL of the Oracle Application Server Wireless gateway for mobile requests to OracleAS Portal. This parameter is not mandatory (no default). The value for this parameter must be enclosed in double quotation marks.

-h

The URL of the OracleAS Portal home page. This is used within portal to determine the character set of the OracleAS Portal middle tier. This information is required when creating an Oracle Application Server Wireless service This parameter is not mandatory (no default). The value for this parameter must be enclosed in double quotation marks.

-c

Connect string for database (no default).



Note:

  • Ensure that you are using the Perl version that is available as part of the Oracle Application Server installation, by setting the path variable as follows:

    For Windows:

    PATH ORACLE_HOME\perl\5.6.1\bin\MSWin32-x86
    
    

    For Solaris or Linux:

    PATH ORACLE_HOME/perl/bin
    
    
  • While running the cfgiasw script you are prompted for the password. Specify the portal schema password for the script to proceed.


For non-hosted Portals, the OracleAS Wireless' Portal service URL reference can be set in the Mobile tab of the Global Settings page, except the URL of the OracleAS Portal home page, which can only be set using the cfgiasw script.

This script is used to set references to both the OracleAS Wireless Portal Service URL and the OracleAS Portal home page URL, in OracleAS Portal. It can be used in a hosted environment to set the URL references, and will affect all subscribers, because this information is not configured separately for each subscriber. For example:

perl cfgiasw.pl -s portal -c portal_db -w "http://<iaswhost>:<port>/ptg/rm?PAoid=$wireless_service_id"

In the preceding example, if a mobile device makes a request to the OracleAS Portal directly without being mediated by an Oracle Application Server Wireless server, OracleAS Portal redirects the client to the URL specified here. This URL should be the OracleAS Portal's service URL on the Oracle Application Server Wireless server, in the form:

http://<host>:<port>/ptg/rm?PAoid=<service_id>

If this setting is blank, then mobile client requests made directly to OracleAS Portal receive an HTTP status indicating that their request is not supported.

See Section 4.6, "Configuring Mobile Support in OracleAS Portal" for configuring other mobile settings in OracleAS Portal.

C.9 Using the ptlinvsw.sql Script to Invalidate Portal Container Pages

If a user navigates to a subpage within a page portlet and edits it, the changes are not visible immediately unless the page containing the portlet is invalidated by other means.

Session store lookup helps solve this issue. When a page is edited, the session store is first looked up to determine all the pages that have a portlet which is currently displaying the edited page, and then those pages are invalidated.

Because the session store lookup affects performance, this feature is not enabled by default.

To enable portal container page invalidation:

  1. On the database where the OracleAS Portal schema is installed, navigate to the ORACLE_HOME/portal/admin/plsql/wws directory.

  2. Log on to SQL*Plus with the appropriate user name and password for the portal schema.

    For example:

    sqlplus portal/portal
    
    
  3. Enter the following command:

    SQL> @ptlinvsw.sql TRUE
    
    

    To disable this invalidation option, enter the following command:

    SQL> @ptlinvsw.sql FALSE
    
    

C.10 Using the Category and Perspective Scripts

To ensure that all new category and perspective pages are created without errors and that all existing category and perspective pages display their associated items and pages as expected, you should run the category and perspective scripts.

The scripts required are:

ORACLE_HOME/portal/admin/plsql/wws/pstdefin.sql
ORACLE_HOME/portal/admin/plsql/wws/pstpgshw.sql
ORACLE_HOME/portal/admin/plsql/wws/pstundef.sql
ORACLE_HOME/portal/admin/plsql/wws/pstpgcre.sql
ORACLE_HOME/portal/admin/plsql/wws/pstprcpg.sql

To run these scripts:

  1. Delete the current category or perspective templates.

  2. Connect to OracleAS Portal using SQL*Plus as the portal schema user.

  3. Configure the pstdefin.sql file with:

    • Page group information. You can re-create the pages in a single page group, several page groups or all page groups.

    • Page information. You can re-create category pages only, perspective pages only, or both.

    Descriptions for these settings are in the pstdefin.sql file.

    • If necessary, use the script pstpgshw.sql to retrieve information from OracleAS Portal to configure the pstdefin.sql file.

    • Run the script pstpgcre.sql to apply the changes. For example:

    • SQL> @pstpgcre.sql
      
      

When the new pages are created, if the template exists in the page group, new category and perspective pages will be created based on the template. If the user deletes the template in the page group before running the scripts, or if the template is missing, then a new template will be created in the page group and the new pages will be based on this template.

C.11 Using the ptlwsrp_data.sql Script to Create the WSRP Portlet Preference Store

The Web Services for Remote Portlets (WSRP) producer is deployed out-of-the-box, but the portlet preference store for this is not created by default. To enable users to register the producer with OracleAS Portal, you must first create the portlet preference store and make entries in the data-sources.xml file.


Note:

WSRP producers are very similar to Web providers. A portlet deployed to a WSRP-enabled container can be rendered on any portal that supports the Java Portlet Specification (JPS) standard.

OracleAS Portal supports the building of JPS portlets but does not yet support consumption of WSRP-enabled portlets.


To create a portlet preference store and make entries in the data-source.xml, perform the following steps:

  1. Stop the OC4J instance in which the portlet container is deployed.

  2. Connect to the database as a user with SYSDBA privileges using the following command:

    sqlplus "sys/<sys_password>@<service_name> AS SYSDBA"
    
    
  3. To create the preference store, run the ptlwsrp_data.sql script using the following command:

    @ptlwsrp_data portlet_prefs portal
    
    

    The portlet_prefs parameter is the name of the user account that stores the data and portal is the name of the default table space to use for that account. By default the password for the user account is the same as the name of the user account.

  4. Edit the data-source.xml file in the <ORACLE_HOME>/j2ee/home/config directory. Add a new entry to map the connection details for the preference store schema by setting the ejb-location to jdbc/portletPrefs, as shown in the following example:

    <data-source 
      class="com.evermind.sql.DriverManagerDataSource" 
      name="OracleDS" location="jdbc/emulatedPortletPrefs"
      xa-location="jdbc/xa/portletPrefs" ejb-location="jdbc/portletPrefs"
      connection-driver="oracle.jdbc.driver.OracleDriver" 
      username="portlet_prefs" password="portlet_prefs" 
      url="jdbc:oracle:thin:@xyz.oracle.com:1521:orcl"
    />
    
    

    Insert valid database details for the url attribute.

  5. Run the dcmctl utility with the following options to make sure that the file is synchronized with the Distributed Configuration Management (DCM) repository:

    <oracle_home>/dcm/bin/dcmctl updateConfig -co home -v
    
    
  6. Restart OC4J.

C.12 Using the Preference Store Migration and Upgrade Utility

A preference store is a mechanism for storing information like user preference data, portlet and provider settings, or even portlet data, while using OracleAS Portal. Currently, PDK-Java has two PreferenceStore implementations, DBPreferenceStore and FilePreferenceStore. DBPreferenceStore persists data using a JDBC compatible relational database and FilePreferenceStore persists data using the file system.

If you have already installed OracleAS PDK, you can manage the information stored in the preference store by using the Preference Store Migration and Upgrade Utility, which is included in the pdkjava.jar file. For a complete description of the syntax of the utility, use the following command:

java -classpath ORACLE_HOME/portal/jlib/pdkjava.jar oracle.portal.provider.v2.preference.MigrationTool

You can run the Preference Store Migration and Upgrade Utility in either of the following modes based on the -mode you select while running the command:


Note:

After running the utility, it is recommended that you restart OC4J_Portal and Oracle HTTP Server to ensure that the latest preference store information is used.

Upgrade Mode

Use an upgrade mode to upgrade data in place, and to modify existing locale-specific preferences in the preference store so that the naming format used is compatible with the current version of OracleAS Portal and a given localePersonalizationLevel setting.

Table C-5 describes the upgrade modes in which you can run the utility.

Table C-5 Upgrade Modes in Which to Run the Utility

Mode Description

file

Use when data in a FilePreferenceStore must be upgraded.

db

Use when data in a DBPreferenceStore must be upgraded.


An upgrade mode can be used in the following scenarios:

When using an upgrade mode, you must use the -remap option to specify the localePersonalizationLevel (language or locale) that you are upgrading to. You can also use the -countries option to specify a prioritized list of ISO country codes, indicating your order of preference in case of a collision between remapped preferences for different countries. For example, if you specify -remap language -countries GB,US in the command, it means that if the utility comes across both US English and British English preferences (en_US and en_GB) in a given preference store, it will remap the British English preference to become the English-wide preference (en).


Note:

While running the utility in db mode, for the pref1User and pref1password properties, use the values specified in the JDBC connection definition in the <j2ee-home>/config/data-sources.xml file.

Migration Mode

Use a migration mode to copy data from a source preference store to a target preference store. When the utility is run in this mode, the preference stores for all the portlet definitions are updated.

Table C-6 describes the migration modes in which you can run the utility.

Table C-6 Migration Modes in Which to Run the Utility

Mode Description

filetodb

Use when data must be copied from a FilePreferenceStore to a DBPreferenceStore.

filetofile

Use when data must be copied from one FilePreferenceStore to another FilePreferenceStore that is in a different location.

dbtofile

Use when data must be copied from a DBPreferenceStore to a FilePreferenceStore.

dbtodb

Use when data must be copied from one DBPreferenceStore to another DBPreferenceStore that is based on a different database table.


When using a migration mode, you can use the -remap and -countries options to specify that the data should be upgraded in the course of being migrated, that is, locale-specific preferences should be remapped appropriately.

The other options accepted by the utility are used to specify the properties of the preference stores involved in the upgrade or migration process. These options must correspond to the tags you specify in provider.xml to describe the preference stores. For more information about the properties you can set on a preference store, refer to the PDK-Java XML Provider Definition Tag Reference document on Portal Studio:

http://portalstudio.oracle.com/pls/ops/docs/folder/community/pdk/jpdk/v2/xml_tag_reference_v2.html

Properties beginning with the prefix -pref1 correspond to properties of the source preference store (in an upgrade mode this is the only preference store). For example, specifying -pref1UseHashing true -pref1RootDirectory j2ee/home/applications/jpdk/jpdk/WEB-INF/providers/sample would set the useHashing and rootDirectory properties of a source FilePreferenceStore.


Note:

If you installed the Oracle Application Server Portal Developer Kit on a standalone Oracle Application Server Containers for J2EE (OC4J) instance, or if you downloaded the preconfigured standalone OC4J with OracleAS PDK, then the source preference store will be available in the following location:

ORACLE_HOME/j2ee/home/applications/jpdk/jpdk/WEB-INF/providers/sample

If you installed OracleAS Portal as part of the Oracle Application Server release, then the source preference store will be available in the following location:

ORACLE_HOME/j2ee/OC4J_Portal/applications/jpdk/jpdk/WEB-INF/providers/sample


When one of the migration basic modes is selected, properties beginning with the prefix -pref2 correspond to properties of the target preference store. For example, specifying -pref2User portlet_prefs -pref2Password portlet_prefs -pref2URL jdbc:oracle:thin:@myserver.mydomain.com:1521:mysid would set the database connection details on a target DBPreferenceStore.

Following are some examples to illustrate the usage of the utility:

java -classpath $ORACLE_HOME/portal/jlib/pdkjava.jar
 oracle.portal.provider.v2.preference.MigrationTool -mode file -remap language
 -countries GB,US -pref1UseHashing true -pref1RootDirectory
 j2ee/home/applications/jpdk/jpdk/WEB-INF/providers/sample

java -classpath $ORACLE_HOME/portal/jlib/pdkjava.jar
 oracle.portal.provider.v2.preference.MigrationTool -mode filetodb -remap locale
 -countries AR,MX -pref1UseHashing true -pref1RootDirectory
 j2ee/home/applications/jpdk/jpdk/WEB-INF/providers/sample -pref2User portlet_
prefs -pref2Password portlet_prefs -pref2URL
 jdbc:oracle:thin:@myserver.mydomain.com:1521:mysid

C.13 Using the Schema Validation Utility

The Schema Validation Utility (SVU) is used to clean up and report any data inconsistencies in the Portal schema. The SVU performs validations on Page Group objects and DB Provider objects.

Some of the benefits of using the SVU are:

You can run the Schema Validation Utility in the following scenarios:

For a more detailed explanation of how the validation is performed, and to download the SVU script, svu_rept.sql, log on to Oracle Metalink at http://metalink.oracle.com and read the article Schema Validation Utility. The Doc ID for this article is 286619.1.

There are two ways of running the Schema Validation Utility, which are:

C.13.1 Using the Schema Validation Utility with OracleAS Portal Export and Import

In OracleAS Portal Export and Import, you can choose to run the utility by selecting the Validate System Tables option during export. See Section 10.2.3.1.2, "Exporting Data" for details. The SVU is run by default in the background during import.

C.13.2 Using the Standalone Schema Validation Utility

The SVU can be run in standalone mode when there are data inconsistencies reported or observed. To run the utility in standalone mode, you need to execute the script svu_rept.sql as the OracleAS Portal schema owner (PORTAL):

SQL> @svu_rept.sql

You will be prompted to specify the mode and type to run the script.

Mode:

  • REPORT - Reports data inconsistencies.

  • CLEANUP - Cleans up data inconsistencies.

Type:

  • ALL - Validates both page group objects and DB Provider objects.

  • PAGEGROUP - Validates page group objects only.

  • DBPROV - Validates DB Provider objects only.

After you have provided the mode and type, you will be prompted to specify a path to save the log file. You can enter a path like c:\temp\svu.log here. Run the SVU in REPORT mode first, before running it in CLEANUP mode.


IMPORTANT:

  • Always take a valid backup of the database before running the SVU in CLEANUP mode.

  • If you run the SVU in CLEANUP mode and then in REPORT mode, inconsistencies should not be reported. If any inconsistencies are reported, you must contact Oracle Support Services.