D Configuring the Parallel Page Engine

The Oracle Application Server Portal architecture is designed around a three-tier architecture that allows any browser to connect to it. This flexible architecture allows each component (browser, Oracle HTTP Server listener, Oracle Database 10g, and OracleAS Portal) to be upgraded individually as required.

A part of the OracleAS Portal middle-tier, the Parallel Page Engine (PPE) is a shared server process servlet engine that runs in the Oracle Application Server Containers for J2EE and services page requests. The PPE reads page metadata, calls providers for portlet content, accepts provider responses, and assembles the requested page in the specified page layout.

D.1 Configuring Parallel Page Engine Parameters

When a page is requested from OracleAS Portal, the request is made from the browser to the Oracle HTTP Server listener. The returned page is comprised of many types of portlets. A portlet is an area on a portal page that contains data from a particular data source.

The Parallel Page Engine (PPE) obtains the page metadata from the Oracle Application Server Metadata Repository and is responsible for assembling the portlets on the page.

D.1.1 Setting PPE Configuration Parameters

With the release of Oracle9iAS version 9.0.2 and later, all of the servlets are installed under OC4J, based upon the application deployment. All of the configuration parameters for PPE are entered in the web.xml file, in a section related to the PPE Deployment. In the default installation, this file can be found at the following location:

MID_TIER_ORACLE_HOME/j2ee/OC4J_Portal/applications/portal/portal/WEB-INF/

D.1.2 Parallel Page Engine Configuration Settings

The following table describes each of the different configuration parameters available for use with the Parallel Page Engine (PPE). Each parameter affects the operation of the PPE in a different manner. Some are simply for logging, while others can affect the performance of the engine or OracleAS Portal itself. In most cases, the default values should be sufficient; however, there may be configurations where this is not the case. Each parameter is described with its syntax, description, and default.

Table D-1 Parallel Page Engine (PPE) Parameters

PPE Setting	Syntax	Description	Default Value
poolSize	<init-param> <param-name>poolSize</param-name> <param-value>25</param-value> </init-param>	This represents the number of connections that the Parallel Page Engine is capable of making at any one time. This value can be raised or lowered based upon performance needs. Setting the number higher makes more threads and connections available for use; however, this uses more resources.	25
requesttime	<init-param> <param-name>requesttime</param-name> <param-value>30</param-value> </init-param>	This is the default time out assigned to portlet requests that do not have their own time out value specified. It is applied as the amount of time (in seconds) allowed before response headers are returned by the server. Time outs are weighted by where they originate. If the portlet sets its own time out value, then that is the time out that is used. If no portlet time out is available, then the provider registration time out is used. If neither of these is present, then the requesttime is used. Note that the upper limit of this parameter should be set to a response time acceptable by a Web user (typically a few seconds).	30 sec
minTimeout	<init-param> <param-name>minTimeout</param-name> <param-value>5</param-value> </init-param>	This is the minimum timeout allowed to be used by a Portlet. Thus, if the minTimeout is set to 5, and a portlet sends a timeout of 2, the minTimeout value of 5 would be applied to that portlet.	5 sec
stall	<init-param> <param-name>stall</param-name> <param-value>120</param-value> </init-param>	If the response headers are returned, but the data itself lags behind, then a stall comes into affect. This value keeps the Parallel Page Engine from holding on to connections forever. Once the response headers are received, the PPE makes every effort to wait as long as is feasible to retrieve all of the data. Set this value appropriately if the portlets being requested are large, or running over a slow network. Note that the upper limit of this parameter should be set to a response time acceptable by a Web user (typically a few seconds).	120 sec
prefix	<init-param> <param-name>prefix</param-name> <param-value>/pls</param-value> </init-param>	The string used to indicate to where mod_plsql is located. The default matches the default Oracle Application Server installation configuration, but it must be changed if the Oracle Application Server configuration has changed.	/pls
proxyHost proxyPort	<init-param> <param-name>proxyHost</param-name> <param-value>ph.comp.com</param-value> </init-param> <init-param> <param-name>proxyPort</param-name> <param-value>8888</param-value> </init-param>	This is the host name and port number of a proxy server that may be required to request data from the Oracle Application Server. These parameters are only required if a proxy server is in use between PPE and the Oracle Application Server listener.	N/a
offlinePathHtml offlinePathMxml	<init-param> <param-name>offlinePath</param-name> <param-value>/path/offline.html</param-value> </init-param> <init-param> <param-name>offlinePathMxml</param-name> <param-value>/path/offline.xml</param-value> </init-param>	By setting either of these, the PPE is set to display the desired off-line message. There are two available messages: one for an HTML browser and one for a mobile enabled device.	null
showError	<init-param> <param-name>showError</param-name> <param-value>true</param-value> </init-param>	When a portlet times out, or something within the Parallel Page Engine goes wrong with a particular portlet request, an error is displayed to the user. The messages tend to be generic, but do give the user some information and an indication that the page did not display as expected. If you set this to false, no messages are displayed to the user.	true
cacheBuffer	<init-param> <param-name>cacheBuffer</param-name> <param-value>32768</param-value> </init-param>	This parameter sets the number of bytes to use for buffering when reading a completed page from the cache. By determining the size of pages generally used in a portal, this value can be adjusted to fit the portal configuration. By setting the value higher, a larger page can be read quickly, but more resources are needed. If the value is set low, then reading the cache file is slower.	32768 Bytes
cacheEncryptionKey	<init-param> <param-name>cacheEncryptionKey</param-name> <param-value>KEY</param-value> </init-param>	This key is used to obscure the headers used for caching using OracleAS Web Cache. This allows for a more secure cache key, and makes retrieving a cached object more difficult for unwanted requests.	Server Context information
enableWebCacheStaticRules	<init-param> <param-name>enableWebCacheStaticRules</param-name> <param-value>false</param-value> </init-param>	If set to false, PPE includes the no-store directive in the surrogate control response header of an assembled page. This overrides any static cacheability rule defined in OracleAS Web Cache, and ensures that the assembled page is not cached in the Web Cache. If set to true, PPE does not include the no-store directive in the surrogate control response header of an assembled page. This allows the use of static cacheability rules for caching the assembled page in OracleAS Web Cache.	false
showPageDebug	<init-param> <param-name>showPageDebug</param-name> <param-value>false</param-value> </init-param>	If you set showPageDebug to true, the Page timing information is shown on every request. Refer to Section C.7, "Timing and Caching Statistics" for a description of the timing and caching statistics.	false
dmsLogging	<init-param> <param-name>dmsLogging</param-name> <param-value>false</param-value> </init-param>	If you set dmsLogging to true, the PPE outputs data for DMS Logging.	true
queueTimeout	<init-param> <param-name>queueTimeout</param-name> <param-value>10</param-value> </init-param>	The amount of time a request should stay in the queue before being timed out. This parameter can be used if requests for portlets are timing out, but the requests are never being sent. Although this points to other performance problems that could be solved by alternative configurations, this option is available to allow requests to stay in the queue for longer or shorter periods of time.	10 sec
cacheDir	<init-param> <param-name>cacheDir</param-name> <param-value>c:\iAS904\Apache\modplsql\cache\</param-value> </init-param>	The cacheDir parameter value points to a directory in the file system where cache files are stored and retrieved. The PPE caches portlet contents and fully assembled page contents into this directory. Note that if this is not specified, it will default to the default deployment location: ORACLE_HOME/Apache/modplsql/cache If a value is specified, it should be an absolute path rather than the relative path. Since this directory is shared by mod_plsql and the PPE, make sure that the directory has adequate privileges for the Oracle HTTP Server and OC4J processes to write into it. If you want to change the location of the cache files, it is recommended that you use symbolic links so that the location of the cache directory is still ORACLE_HOME/Apache/modplsql/cache. If your operating system does not support symbolic links, make sure that corresponding changes are done to the mod_plsql cache configuration file (ORACLE_HOME/Apache/modplsql/conf/cache.conf).	Default deployment location
jspRoot	<init-param> <param-name>jspRoot</param-name> <param-value>/JSP PATH/</param-value> </init-param>	The relative path where JSP files for JSP Pages can be found.	jsp
jspSrcAlias	<init-param> <param-name>jspSrcAlias</param-name> <param-value>/PATH</param-value> </init-param>	The Alias for the jsp engine, like /portal/jsp or some other path.	/jsp/
urlDebugMode	<init-param> <param-name>urlDebugMode</param-name> <param-value>1</param-value> </init-param>	Specifies the highest value of the _debug URL parameter that the PPE should honor. Possible values for _debug are: none, 0, 1, 2, 3, 4, and 5 If a value higher than that allowed is received by the PPE, it is reduced to the highest value permitted, or ignored if no value is allowed. The values build incrementally. For example, at debug value 2, values for debug level 1 and 0 are also recorded.	1
urlDebugUsers	<init-param> <param-name>urlDebugUsers</param-name> <param-value>fred,bill,ben</param-value> </init-param>	This is specified to indicate the list of users allowed to use the _debug URL parameter, subject to the value restriction in the urlDebugMode parameter. If this is not specified, all users can use it subject to the value restriction. The format is a comma-delimited list of portal user names, with leading and trailing spaces being ignored.	none required
useWebCache	<init-param> <param-name>useWebCache</param-name> <param-value>true</param-value> </init-param>	Indicates whether Web Cache is being used with the PPE. Allowed values are true and false.	true
dadFilePath	<init-param> <param-name>dadFilePath</param-name> <param-value>c:\iAS904\Apache\modplsql\conf\dads.conf</param-value> </init-param>	The absolute filename and path of the dads.conf file used by mod_plsql and read by the PPE. If not specified, it defaults to: ORACLE_HOME/Apache/modplsql/conf/dads.conf	ORACLE_HOME/Apache/modplsql/conf/dads.conf
logmode	<init-param> <param-name>logmode</param-name> <param-value>debug</param-value> </init-param>	Enables the Parallel Page Engine to run in debug mode. This mode writes debug information to the Parallel Page Engine log file. This mode does cause some degradation in performance because large amounts of information are being written to disk. The Parallel Page Engine log file (application.log) by default is located at: ORACLE_HOME/j2ee/OC4J_Portal/application-deployments/portal/ Allowed values are: none - No debug messages perf - Performance messages only debug - General debug messages request - Details of requests made by the PPE content - Details of the content of requests made by the PPE parsing - Details of metadata parsing all - All debug messages The values build incrementally. For example, at logging level request, the output for logging levels debug and perf will also be recorded.	none - no debug messages
maxParallelPortlets	<init-param> <param-name>maxParallelPortlets</param-name> <param-value>20</param-value> </init-param>	Used to specify the maximum number of portlet requests for a given page, that should be allowed, to execute at the same time. Allowed values are: 0 - Indicates no restriction (beyond the number of fetchers available). Any positive integer - Indicates a restriction on simultaneous requests.	20
httpsports	<init-param> <param-name>httpsports</param-name> <param-value>433:444</param-value> </init-param>	This is a colon (':') separated list of ports on which the PPE should use SSL to communicate with the Portlet Repository. The Event servlet, which is also configured through web.xml, has the httpsports setting that should be set to the same value as the httpsports parameter in PPE. This is the only configuration for the Event servlet, and is only applicable if SSL is being used. If you change the parameter in the PPE settings, you must make the same change in the httpsports setting of the Event servlet.	null
useScheme	<init-param> <param-name>useScheme</param-name> <param-value>http</param-value> </init-param>	Overrides the scheme (HTTP or https) used when the PPE makes requests to the portal. The default, if not specified, is to always use the page request scheme. Note that you must set the useScheme and usePort parameters. You need to specify these in scenarios where public access is through https on port A, and you want to set PPE requests to use a faster http connection on port B.	Use page request scheme
usePort	<init-param> <param-name>usePort</param-name> <param-value>8888</param-value> </init-param>	Overrides the port used when the PPE makes requests to the portal. The default, if not specified, is to always use the page request port. Note that you must set the useScheme and usePort parameters. You need to specify these in scenarios where public access is through https on port A, and you want to set PPE requests to use a faster http connection on port B.	Use page request port
x509certfile	<init-param> <param-name>x509certfile</param-name> <param-value>c:\certificates\trustedcerts.txt</param-value> </init-param>	Specifies a file containing a list of certificates to be implicitly trusted by HTTPClient. These certificates are added as trust points to all connections made by HTTPClient using SSL. Once this setting is in use, all SSL connections must be trusted. Otherwise, HTTPClient will throw an exception in the PPE. Note that SSL connections are made from the PPE for two reasons, and this configuration affects both: loopback requests to the portal, for example, for PMD. show calls to Providers. Note that the file specified here can be obtained from a wallet by exporting all trusted certificates, but the comments in the resultant file must be removed. Alternatively, it can be created manually.	trust points not used