Release 2 (9.0.2) for Sun SPARC Solaris
Part Number A96157-03
 Home |
 Contents |
 Index |
| Oracle9i Application Server Migrating from Oracle9iAS Release 1 (1.0.2.2.x) to Release 2 (9.0.2) Release 2 (9.0.2) for Sun SPARC Solaris Part Number A96157-03 |
|
This chapter explains how to change the necessary configuration files and application deployment files necessary to migrate Portals components. It contains these major sections:
This section explains how to migrate Oracle9iAS Portal. It is divided into the following sub-sections:
This section describes the process of migrating the Portal mid-tier from Portal 3.0.9 to 9.0.2. It contains the following topics:
Oracle Portal 9.0.2 is based on Oracle9iAS Release 2 (9.0.2), which contains a new J2EE-compliant servlet container (OC4J), replacing the old servlet container (JServ). Manual steps are necessary to migrate the mid-tier from the old architecture to the new architecture.
mod_oc4j to forward requests of type /servlet/page/* to the OC4J Portal instance:
/Apache/Apache/conf/mod_oc4j.conf and add the following line:
OC4JMount /servlet/page OC4J_Portal
|
Note:
Place this directive next to the other OC4JMount directives in this file. The added entry must be inside the <IfModule mod_oc4j.c> block. |
/Apache/Jserv/etc/jserv.conf and modify the ApJServMount directive so that JServ does not also use the /servlet mount point. The default servlet zone uses the /servlet mount point.
Change this directive:
ApJServMount /servlet /root
to specify a different mount point for JServ, for example:
ApJServMount /anotherMountPoint /root
/servlet/page requests:
/j2ee/OC4J_Portal/config/default-web-site.xml and add the following line:
<web-app application="portal" name="portal" root="/" />
|
Note:
Place this directive next to the other <web-app application> directives in this file. The added entry must be inside the <web-site> block. |
The Parallel Page Engine (PPE), which ships with the Oracle Portal 9.0.2, is backward-compatible and works with Oracle Portal 3.0.9 (Oracle9iAS Release 1 (1.0.2.2.x). All the new settings that are required for Oracle Portal 9.0.2 are configured automatically. Manual steps are required to migrate custom settings to the new environment. Table 4-1 lists parameters in Oracle Portal 3.0.9 that can be modified in the PPE:
To migrate the parameters above, copy the parameter names and values to the ORACLE_HOME_2/j2ee/OC4J_Portal/applications/portal/portal/WEB-INF/web.xml file. The examples below show the location and format of the names and values in version 3.0.9 and version 9.0.2:
The 3.0.9 parameter syntax is:
servlet.name.initArgs=NAME=VALUE
To configure the httpsports parameter with a value of 443:
servlet.page.initArgs=httpsports=443
The 9.0.2 parameter syntax is:
<servlet> <servlet-name>xxxx</servlet-name> <servlet-class>aaa.bbb</servlet-class> <init-param> <param-name>NAME</param-name> <param-value>VALUE</param-value> </init-param> </servlet>
To configure the httpsports parameter with a value of 443:
<servlet> <servlet-name>page</servlet-name> <servlet-class>oracle.webdb.page.ParallelServlet</servlet-class> <init-param> <param-name>httpsports</param-name> <param-value>443</param-value> </init-param> </servlet>
mod_plsql DADs now use the Oracle HTTP Server Location directive for configuration. In this syntax, parameter names and values are separated by white space instead of the equal sign. Table 4-2 lists the Release 1 parameters and their Release 2 equivalents. Values are also compared for selected parameters.
|
See Also:
Oracle HTTP Server Administration Guide. for complete documentation of all DAD parameters. |
This section provides details about using the Release 2 parameters.
The following parameters are deprecated because there are no longer any administration pages for mod_plsql.
defaultDad parameter is removed, since you can use Oracle HTTP Server rewrite rules to get the same results.
PlsqlCompatibilityMode to 1. Setting this flag prevents you from downloading documents with a plus (+) sign in them.
An example of the DAD in the Release 1 configuration file ORACLE_HOME_1/Apache/modplsql/cfg/wdbsvr.app is shown below:
; [DAD_portal30] username = portal30 password = portal30 connect_string = pk.us.oracle.com default_page = portal30.home document_table = portal30.wwdoc_document document_path = docs document_proc = portal30.wwdoc_process.process_download upload_as_long_raw = txt, gif upload_as_blob = * ;name_prefix = always_describe = No ;before_proc = ;after_proc = reuse = Yes pathalias = url pathaliasproc = portal30.wwpth_api_alias.process_download enablesso = Yes ;sncookiename = ;stateful = ;custom_auth = ;response_array_size = ;exclusion_list = ;cgi_env_list = ;error_style = ;nls_lang = ;
The migration process converts it to the following arguments in a Location directive:
<Location /pls/portal30> SetHandler pls_handler Order allow, deny Allow from All AllowOverride None PlsqlDatabaseUsername portal30 PlsqlDatabasePassword portal30 PlsqlDatabaseConnectString pk.us.oracle.com PlsqlDefaultPage portal30.home PlsqlDocumentTable portal30.wwdoc_document PlsqlDocumentPath docs PlsqlDocumentProc portal30.wwdoc_process.process_download PlsqlUploadAsLongRaw txt PlsqlUploadAsLongRaw gif PlsqlMaxRequestsPerSession 1000 PlsqlAuthenticationMode SingleSignOn PlsqlPathAlias url PlsqlPathAliasProcedure portal30.wwpth_alias.process_download </Location>
The Portal and Login Server DADs have changed significantly between releases, and there is a migration tool for migrating the DADs. This section explains how to use the migration tool to migrate DADs, and describes the differences between the mod_plsql parameters.
Running the dadMigration Script
This section explains how to migrate Database Access Descriptors (DADs) from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle9iAS Release 2 (9.0.2). The information in the DAD configuration file in Oracle9iAS Release 1 (1.0.2.2.x), wdbsvr.app, must be migrated to the Oracle9iAS Release 2 (9.0.2) configuration file, dads.conf. As a result of this operation, Web DAV entries are created in oradav.conf.
The migration is performed using the Portal Configuration Interface (PCI) via the dadMigration script. The full path and file name of the script is shown below.
ORACLE_HOME_2/bin/dadMigration.csh (UNIX)
ORACLE_HOME_2/bin/dadMigration.cmd (Windows)
The migration script reads in the old format DADs, and creates new DADs and corresponding Web DAV entries. It takes two parameters, targetOracleHome (-t) and migrationSource (-s). Follow the steps below to run the script.
dadMigration.csh -t ORACLE_HOME_2 -s ORACLE_HOME_1/Apache/modplsql/cfg/wdbsvr.app
On Windows:
dadMigration.cmd -t ORACLE_HOME_2 -s ORACLE_HOME_1/Apache/modplsql/cfg/wdbsvr.app
where ORACLE_HOME_2 specifies the target Oracle home (the default is the value of the ORACLE_HOME environment variable)
and ORACLE_HOME_1 specifies the location of the v.3.0.9 DAD format file to be migrated (the default is wdbsvr.app).
Migration changes may be lost if another migration action or a Portal configuration action is performed before the EMD is restarted.
Note:
The cache configuration migration process is manual, and requires that you change the value of parameters based on their configured values in the Oracle9iAS Release 1 (1.0.2.2.x) Oracle home.
The Release 1 session cache settings and PL/SQL cache settings have been collapsed into one single setting for cache. See the examples below.
Note:
The ORACLE_HOME_1/Apache/modplsql/cfg/cache.cfg file is shown below:
[PLSQL CACHE] enabled = yes cache_dir = /u01/app/oracleproduct/IAS1022/Apache/modplsql/cache/plsql total_size = 25600000 cleanup_size = 10240000 cleanup_interval = 43200 max_size = 1024000 ; [Cookie Cache] enabled = yes cache_dir = /u01/app/oracleproduct/IAS1022/Apache/modplsql/cache/session total_size = 25600000 cleanup_size = 10240000 cleanup_interval = 43200 max_size = 1024000
The Release 1 file will get converted to ORACLE_HOME_2/Apache/modplsql/conf/cache.conf as follows:
PlsqlCacheEnable On PlsqlCacheDirectory /u01/app/oracle/product/IAS1022/Apache/modplsql/cache PlsqlCacheTotalSize 25600000 PlsqlCacheCleanupSize 10240000 PlsqlCacheCleanupInterval 720 PlsqlCacheMaxSize 1024000
This section describes how to upgrade your PDK-Java v3.0.9 provider to PDK-Java (9.0.x). The increase in version numbers reflects the synchronization of version numbers withOracle9iAS Release 2 (9.0.2), of which the PDK-Java is a component. This section contains the following topics:
Installing the PDK-Java Framework and Samples
Migrating from PDK-Java 3.0.9.x to PDK-Java 9.0.x (v1)
Migrating from PDK-Java 3.0.9.x to PDK-Java 9.0.x (v2)
Packaging and Deploying Your Provider
The PDK-Java Framework (included with Oracle9iAS in ORACLE_HOME/portal/pdkjava/v2/) includes the tools and documentation necessary to build Web portlets. The PDK-Java Framework and Web Provider Samples will help you get started. Included in the PDK-Java Framework is the provider framework; portlets will use this framework and build upon it.
This section provides installation and configuration information for the PDK-Java Framework and samples. It explains how to configure the Oracle HTTP Server to run the PDK-Java Framework, the samples, and your own portlets.
The PDK-Java Framework includes these application files:
jpdk.ear - Contains the sample provider applications including Java libraries, JSP files, HTML files and other resources necessary to run the sample applications.
template.ear - A template EAR file to help you deploy providers.
You must have Oracle9iAS with Oracle9iAS Containers for J2EE (OC4J) installed and configured in order to run the framework and samples.
Follow these steps to deploy the sample providers:
jpdk.ear into your OC4J applications subdirectory (typically, ORACLE_HOME_2/j2ee/OC4J_Portal/applications).
/j2ee/OC4J_Portal/config/server.xml file:
<application name="jpdk" path="../applications/jpdk.ear" />
/j2ee/OC4J_Portal/config/default-web-site.xml file:
<web-app application="jpdk" name="jpdk" path="/jpdk/" />
The application will be automatically deployed based on the information specified in Step 3.
http://server:port/jpdk/providers/sample/provider name
There are several sample providers included with the PDK-Java. They are described in Table 4-4.
After setting up the Web Provider Sample with the Oracle HTTP Server, you must register the provider with Oracle9iAS Portal before adding the sample portlet(s) to a page.
Name - SampleWebProvider
Display Name - Sample Web Provider
Timeout - 100
Timeout Message - Application Timed Out
Implementation Style - Web
Register on Remote Nodes - No
Provider Login Frequency - Once per User Session
URL:
http://myserver.mydomain.com:port/jpdk/providers/sample
(Replace this with your provider URL.)
Click the radio button for this selection:
The user has the same identity in the Web providers application as in the Single Sign-On identity.
Require Proxy - No (If no proxy is required to contact the Provider Adapter).
Once registered, all the sample portlets are displayed in the Portlet Repository.
Follow these steps to add sample portlets to a page:
You can preview the portlets in the Portlet Repository.
Oracle recommends that you secure access to providers when using the PDK-Java framework in a production environment. Oracle9iAS (via the Oracle HTTP Server configuration file httpd.conf) has the capability to deny access by IP address or hostname, as shown in the examples below:
Accepting Requests only from Portal
To make your provider accept requests only from Oracle Portal, you can allow access only from the Portal IP addresses in a Location directive for the provider path. Include the following in your httpd.conf file:
<Location provider path> order deny, allow deny from all allow from ip address 1 allow from ip address 2 </Location>
where IP address 1 and IP address 2 are the IP addresses of the computer on which Portal resides.
Securing a Path
You may also want to secure the /servlet or other paths. To do this, add similar directives for those paths.
<Location /servlet > order deny, allow deny from all allow from ip address 1 allow from ip address 2 </Location>
Securing a Servlet on a Path
To restrict access for a single servlet called "provider", so that it can only be accessed from my.oracle.com or portal.oracle.com, use a directive similar to the following:
<Location /servlet/provider > order deny, allow deny from all allow from my.oracle.com allow from portal.oracle.com </Location>
PDK-Java 9.0.x includes two versions of the PDK-Java framework:
Version 1 extends the framework that was included in PDK-Java 3.0.9, adding more complete support for mobile or wireless content providers and portlets. This version of the framework runs in the JServ servlet container.
Version 2 enables you to create web providers that run in the J2EE-compliant, OC4J servlet container. In addition to J2EE support, version 2 has been modified to make the framework more object-oriented and easier to extend without breaking existing web providers.These changes required the addition of some new classes, and some API changes, so any existing web providers will have to be modified before they can use the new framework.
PDK-Java v9.0.2 includes several changes that are designed to increase the overall stability of the framework and make it easier to introduce new features with minimal impact on existing code. These changes include:
During the development of earlier releases of the PDK-Java, it became evident that the use of Java interfaces to define top level APIs made adding new features difficult. This was because new features often required API changes and those API changes had to be reflected in changes to the Java interfaces.
For developers using the default implementations, these changes were not invasive. However, for developers writing more complex providers, any interface change could cause their code to break, because their implementations no longer matched the interface definitions.
To resolve this issue, most of the Java interfaces have been replaced with abstract classes. The switch to abstract classes allows new features to be added without breaking any existing code. While this change does reduce flexibility (due to the lack of support for multiple inheritance in Java) and requires code changes to adopt the new release of PDK-Java, the long term gains in stability are worth the cost.
In addition to replacing Java interfaces with abstract classes, the package structure of the JPDK has been modified to include a new version number and to organize the classes based on functionality.
All packages now include "v2" in the package name to indicate that the package belongs to version 2 of the PDK-Java. The inclusion of a version number in the package name allows different versions of the PDK-Java to be included in the same classpath without causing collisions.
In addition to the version number change, the classes have been re-organized into a more logical structure. The new structure groups classes based on functionality. This makes it easier to find existing classes, and organize new classes as new functionality is added.
To make the code more understandable for developers and create a clean separation between the provider APIs that developers implement and the underlying code that communicates with Oracle Portal, the provider and portlet interfaces have been modified.
Previously, the provider and portlet APIs were not very object-oriented, and API calls from the communication layer of the framework sometimes bypassed these objects and accessed the "controller" objects directly. In the new API, several changes have been made: the Provider interface has been split into 2 abstract classes: ProviderInstance and ProviderDefinition.
The old Provider interface represented:
Splitting the information in this way makes the usage of the classes clearer for developers and allows a single set of metadata to be shared by many registered instances. It creates a platform for supporting provider instance-specific behavior (for example, provider configuration settings that are specific to a registered instance of that provider).
The Portlet interface has been split into 2 abstract classes: PortletInstance and PortletDefinition. The old Portlet interface really represented only the portlet metadata. All API calls that affected a portlet were actually routed directly to the appropriate controller. This architecture did not create a clean interface with the communication layer of the framework and made it difficult for developers working with more complex portlets to understand the flow of control within the framework.
To solve this problem, the PortletInstance and PortletDefinition were created. The PortletDefinition represents the sharable definition of the portlet and the PortletInstance represents a specific instance of that portlet being accessed by, or on behalf of, a specific user. The result of this split is that all APIs that affect an instance of a portlet (rendering, copying, security etc.) have been brought together in the PortletInstance class.
This change in architecture also allows developers more freedom because they are not forced to use the rendering, personalization and security frameworks provided by the PDK-Java. The default implementation of PortletInstance continues to use the familiar rendering, personalization and security controllers introduced in earlier versions of the PDK-Java. All calls from the communication layer are now made via the ProviderInstance and (if necessary) the PortletInstance.
With cleanly defined classes that represent instances of a provider and portlet, all the API calls from the communication layer of the PDK-Java can be neatly funneled through the ProviderInstance and PortletInstance interfaces, making the framework easier to understand for new developers.
Since there are two versions of the framework, there are three migration options:
Option 1 is the simplest, because it does not require any changes to existing web providers. However, you must configure the JServ servlet container in Oracle9iAS. This approach allows you to migrate to Oracle9iAS Release 2 (9.0.2) and implement existing web providers quickly. However, you will not be able to use any of the features of OC4J.
Option 2 is slightly more involved, since you must modify web providers to use the new framework. For most web providers, the necessary changes are straightforward (i.e., modifying the import statements in Java classes, and changing the classes used for some method calls). In general, the methods that existed in version 1 of the framework are still there, and their function has not changed--but the class in which they are contained may have changed. Option 2 enables you to take advantage of the features of the OC4J servlet container and the new functionality in version 2 of the framework. Most new features will only be added to version 2 of the framework.
Option 3 combines Options 1 and 2. Using this migration approach, you can quickly get web providers running on Oracle9iAS Release 2 (9.0.2), and then migrate them to version 2 of the framework at your convenience.
This section explains how to migrate a PDK-Java 3.0.9 provider to PDK-Java 9.0 version 1. This migration path does not require any changes to the provider code or provider definition file. The migration primarily involves configuring JServ and declaring the servlet that represents the web provider.
jserv.conf file in ORACLE_HOME_2/Apache/Apache/conf/httpd.conf.
#include "/ORACLE_HOME_2/Apache/Jserv/etc/jserv.conf"
jserv.conf to set directives as appropriate for how you want to use JServ. (jserv.conf contains Include directives for mod_jserv and mod_oprocmgr, an Oracle module that provides process management and load balancing services.)
Oracle HTTP Server Administration Guide in the Oracle9i Application Server documentation library.
See Also:
/Apache/Jserv/etc/jserv.properties file, if needed.
/Apache/Jserv/etc/zone.properties file, if needed.
You can specify that some applications execute on JServ and some on OC4J. Suppose you have these URLs:
/application1/file1.jsp to execute on JServ, and
/application2/file2.jsp to execute on OC4J.
You must rewrite the URL for application1.
/Apache/Apache/conf/httpd.conf and ensure that the following directives are active (uncommented) and present:
LoadModule rewrite_module libexec/mod_rewrite.so RewriteEngine on
ORACLE_HOME_2/Apache/jsp/conf/ojsp.conf to add these directives:
RewriteRule /application1/(.*)/(.*)\.jsp$ /application1/$1/$2.jsp1 ApJServAction .jsp1 /servlets/oracle.jsp.JspServlet
ApJServAction .jsp /servlets/oracle.jsp.JspServlet
/Apache/Jserv/etc/jserv.conf and mount /servlets to the JVM that will service the JSP requests. Use the ApJServMount or ApJServGroupMount directive (depending on how the JServ processes are started).
/portal/pdkjava/v1/jpdkv1.zip. You can unzip this file in any location, but this document will assume ORACLE_HOME_2/portal/pdkjava/v1.
/portal/pdkjava/v1/jpdk/v1/lib/provider.jar to the wrapper.classpath in the ORACLE_HOME_2/Apache/Jserv/etc/jserv.properties file.
/Apache/Jserv/etc/zone.properties file. (Copy and paste the servlet entries from ORACLE_HOME_1/Apache/Jserv/etc/zone.properties file.)
The file now resembles that shown in Example 4-5. The following typographical conventions are used in the example:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?providerDefinition version="2.0"?> <!DOCTYPE provider [ <!ENTITY virtualRoot "/jpdk/"> <!ENTITY physicalRoot "E:\9iAS\Apache\Apache\htdocs\jpdk\"> ]> <provider class="oracle.portal.provider.v1.http.DefaultProvider"> <session>true</session> <containerRenderer class="oracle.portal.provider.v1.DefaultContainerRenderer" /> <portlet class="oracle.portal.provider.v1.http.DefaultPortlet"> <id>1</id> <name>samplePortlet</name> <title>Sample Portlet</title> <shortTitle>Sample</shortTitle> <description>PDK-Java version 1 portlet definition</description> <timeout>10</timeout> <timeoutMessage>Sample Portlet timed out</timeoutMessage> <hasHelp>true</hasHelp> <hasAbout>true</hasAbout> <showDetails>true</showDetails> <showEdit>true</showEdit> <showEditDefault>true</showEditDefault> <acceptContentType>text/html</acceptContentType> <renderer class="oracle.portal.provider.v1.RenderManager"> <resourcePath>&virtualRoot;samplePortlet</resourcePath> <appRoot>&physicalRoot;samplePortlet</appRoot> <contentType>text/html</contentType> <showPage class="oracle.portal.provider.v1.http.JspRenderer"> <name>showPage.jsp</name> </showPage> <helpPage class="oracle.portal.provider.v1.http.FileRenderer"> <name>help.html</name> </helpPage> <editPage class="oracle.portal.provider.v1.http.Servlet20Renderer"> <servletClass>your.package.EditServlet</servletClass> </editPage> <editDefaultsPage class="oracle.portal.provider.v1.http.Servlet20Renderer"> <servletClass>your.package.EditServlet</servletClass> </editDefaultsPage> <aboutPage class="oracle.portal.provider.v1.http.FileRenderer"> <name>about.html</name> </aboutPage> <showDetailsPage class="oracle.portal.provider.v1.http.JspRenderer"> <name>details.jsp</name> </showDetailsPage> </renderer> <personalizationManager class="oracle.portal.provider.v1.FilePersonalizationManager"> <dataClass>your.package.DataClass</dataClass> <useHashing>true</useHashing> </personalizationManager> <securityManager class="oracle.portal.provider.v2.security.DefaultSecurityManager"> <authLevel>STRONG</authLevel> </securityManager> </portlet> </provider>
This section outlines the necessary changes to an existing (PDK-Java 3.0.9) provider.
Updating Java classes, Servlets or JSPs
For this section, refer to the JavaDoc for the new framework. The JavaDoc is installed with the PDK-Java sample providers and is accessible at
http://host:port/jpdk/apidoc
where host is the name of the computer on which Oracle9iAS Release 2 (9.0.2) is installed and port is the port on which the Oracle HTTP Server is listening.
import statements in Java classes and JSPs to reflect the new package organization. The package hierarchy is now more structured with packages organized based on functional areas such as rendering, security, personalization etc.
oracle.portal.provider.v1.Provider with oracle.portal.provider.v2.ProviderInstance or oracle.portal.provider.v2.ProviderDefinition, depending on the method being called. Review the JavaDoc to determine which of these classes contains the specific method being called.
oracle.portal.provider.v1.Portlet with oracle.portal.provider.v2.PortletInstance or oracle.portal.provider.v2.PortletDefinition, depending on the method being called. Review the JavaDoc to determine which of these classes contains the specific method being called.
oracle.portal.provider.v1.DefaultSecurityManager with oracle.portal.provider.v2.security.AuthLevelSecurityManager
providerId from long to java.lang.String. (The datatype was changed to allow more flexibility in future releases of the API.)
Updating Provider Definition Files (provider.xml)
oracle.portal.provider.v1.DefaultProvider with oracle.portal.provider.v2.DefaultProviderDefinition (or your own class that extends oracle.portal.provider.v2.ProviderDefinition).
oracle.portal.provider.v1.DefaultPortlet with oracle.portal.provider.v2.DefaultPortletDefinition (or your own class that extends oracle.portal.provider.v2.PortletDefinition).
oracle.portal.provider.v1.http.JspRenderer and oracle.portal.provider.v1.http.Servlet20Renderer with oracle.portal.provider.v2.render.http.ResourceRenderer.
racle.portal.provider.v1.render.FileRenderer with oracle.portal.provider.v2.render.FileRenderer or oracle.portal.provider.v2.render.http.ResourceRenderer. ResourceRenderer can be used for JSPs, Servlets and static files. However, FileRenderer is recommended for static files because it caches the content of the specified file in memory instead of accessing the file system each time the file needs to be rendered.
Version 2 of the PDK-Java framework includes two personalization managers:
oracle.portal.provider.v2.personalize.PrefStorePersonalizationManager
and
oracle.portal.provider.v2.personalize.DBPersonalizationManager
PrefStorePersonalizationManager replaces both FilePersonalizationManager and DBPersonalizationManager2, using the new Preference Store functionality. To use the PrefStorePersonalizationManager, you must declare one or more preference stores in your provider definition file. The preference stores can be either file based or database-based. File or database preference stores are compatible with the personalization managers included in PDK-Java 3.0.9.
Declaring a File-based Preference Store
To declare a file-based preference, use XML similar to that shown below. The rootDirectory should be the same as the that used with the FilePersonalizationManager. If you did not specify a root directory when you declared your FilePersonalizationManager, then rootDirectory should be the same as the provider_root argument passed to the provider servlet. If you want to move your personalization data to a new location, zip or tar the contents of the original root directory (including all the subdirectories) and the unzip or untar into the new location. (The new value for rootDirectory will be the path of the directory into which the data was unzipped or untarred.)
<preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore"> <name>prefStore1</name> <rootDirectory>d:\root\directory</rootDirectory> <useHashing>true</useHashing> </preferenceStore>
Declaring a Database-based Preference Store
To declare a database-based preference store, use XML similar to that shown below. If you are using the DBPreferenceStore, you must declare a datasource in the j2ee/home/config/datasources.xml of the OC4J instance in which your provider will be deployed. The DBPreferenceStore will use JNDI to locate the datasource to use for the preference store.
<preferenceStore class="oracle.portal.provider.v2.preference.DBPreferenceStore"> <name>prefStore2</name> <connection>oc4jDataSourceName</connection> <table>databaseTableName</table> </preferenceStore>
|
Note: Preference stores must be declared inside of the <provider> element at the same level as <portlet> elements. |
oracle.portal.provider.v1.DefaultSecurityManager
with
oracle.portal.provider.v2.security.AuthLevelSecurityManager
The file now resembles the file shown in Example 4-6. The following typographical conventions are used in the example:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?providerDefinition version="3.1"?> <provider class="oracle.portal.provider.v2.DefaultProviderDefinition"> <session>false</session> <containerRenderer class="oracle.portal.provider.v2.render.DefaultContainerRenderer" /> <preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore"> <name>prefStore1</name> <rootDirectory>d:\root\directory</rootDirectory> <useHashing>true</useHashing> </preferenceStore> <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition"> <id>1</id> <name>samplePortlet</name> <title>Sample Portlet</title> <shortTitle>Sample</shortTitle> <description>PDK-Java version 2 portlet definition</description> <timeout>10</timeout> <timeoutMessage>Sample timed out</timeoutMessage> <hasHelp>true</hasHelp> <hasAbout>true</hasAbout> <showDetails>true</showDetails> <showEdit>true</showEdit> <showEditDefault>true</showEditDefault> <acceptContentType>text/html</acceptContentType> <renderer class="oracle.portal.provider.v2.render.RenderManager"> <contentType>text/html</contentType> <showPage class="oracle.portal.provider.v2.render.ResourceRenderer"> <resourcePath>/jsps/showPage.jsp</resourcePath> </showPage> <helpPage class="oracle.portal.provider.v2.render.http.FileRenderer"> <appRoot>file path</appRoot> <name>help.html</name> </helpPage> <editPage>/servlet/editServlet</editPage> <editDefaultsPage>/servlet/editServlet</editDefaultsPage> <aboutPage>/htdocs/submitServlet/about.html</aboutPage> <showDetailsPage>/jsps/showDetails.jsp</showDetailsPage> </renderer> <personalizationManager class="oracle.portal.provider.v2.personalize.PrefStorePersonalizationManager" > <dataClass>your.package.DataClass</dataClass> </personalizationManager> <securityManager class="oracle.portal.provider.v2.security.AuthLevelSecurityManager"> <authLevel>STRONG</authLevel> </securityManager> </portlet> </provider>
This section describes the steps necessary to package your provider for deployment. It contains the following topics:
With the PDK-Java, you can deploy multiple providers under a single adapter servlet. The providers are identified by a service name or service identifier (equivalent to the SOAP service identifier). When you deploy a new provider, you must assign a service name to the provider and use that service name when creating the provider WAR file.
After deployment, the correct service name must be used when registering your provider in Oracle Portal to ensure that requests are sent to the correct provider. For older releases of Oracle Portal that do not include a service name, you can choose one of your providers to be the default. If the adapter servlet receives a request that does not specify a service name, the request will be forwarded to the default provider.
WAR (Web Application Archive) and EAR (Enterprise Application Archive) files are standardized mechanisms used to deploy applications in a J2EE application server such as OC4J. The purpose of the WAR and EAR files is to encapsulate all the components necessary to run an application in a single file. This makes deployment simple and consistent across applications, and reduces errors when applications are moved from development to test to production environments.
WAR files include all the components of a web application, including Java libraries or classes, servlet definitions and parameter settings, JSP files, static HTML files and any other resources the application might need.
An EAR file represents an enterprise application. EAR files provide a grouping mechanism for web applications.
Prepare Working Directories
Follow these steps to prepare directories for your WAR and EAR files:
deploy/ear.
deploy/ear with the command:
jar -xvf ORACLE_HOME_2/portal/pdkjava/v2/lib/template.ear
deploy/ear/template.ear to the deploy directory.
deploy/ear/template.war to deploy/war.
deploy/war.
deploy/war with the command:
jar -xvf deploy/war/template.war
deploy/war/template.war to the deploy directory.
Two working directories now exist with the structure and files needed to create your own WAR and EAR files.
Specifying the Contents of Your WAR File
To deploy your provider, you first create the WAR file that contains the provider and all the resources it needs to execute. The steps below explain how to do this manually; you can also use a software utility.
deploy/war/WEB-INF/lib directory. This directory already contains the PDK-Java jar files.
deploy/war/WEB-INF/classes directory. Ensure that the class files are saved in a directory structure that corresponds to their Java package names.
deploy/war.
_default.properties file to serviceid.properties and edit it to reflect the provider's configuration.
_default.properties so that the configuration settings reflect the default provider (the provider that will be accessed if a service id is not specified in a request from a portal).
Release 3.0.9 and earlier portals cannot specify a service id, so requests will always be directed to the default provider.
Note:
WEB-INF/web.xml to add your servlets to the list of pre-defined servlets. Be careful not to remove the entries for servlets that are required by the PDK-Java.
Specifying Your Default Service
The default service is the provider that should receive any request that does not specify a service name. This feature is provided to allow you to register your provider on release 3.0.9 of Oracle Portal.
The default provider is specified in the _default.properties file in the deployment directory of your WAR file. The _default.properties file looks something like this:
serviceClass=oracle.portal.provider.v2.adapter.soapV1.ProviderAdapter loaderClass=oracle.portal.provider.v2.http.DefaultProviderLoader definition=providers/sample/provider.xml autoReload=true
definition= entry so that it points to the provider definition file that for the default provider. The directory path should be based on the contents of the WAR file, not the physical location of the file on the filesystem.
ProviderLoader interface and edit the "loaderClass" entry.
Creating a WAR File
Once you have specified the contents of your WAR file, you are ready to create the WAR file itself. Follow these steps to create the WAR file:
deploy/war.
jar -cvf warfilename.war
where warfilename is the name of your WAR file.
Creating an EAR File
Follow the steps below to manually configure an EAR file. You can also use a software utility to create the EAR file.
deploy/ear.
META-INF/application.xml file (extracted from the EAR file template into the working directory). The file resembles that shown below:
<?xml version "1.0"> <!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN" "http://java.sun.com/j2ee/dtds/application_1_2.dtd"> <application> <display-name>this is the display name of the application</display-name> <description>this is a description of the application</description> <module> <web> <web-uri>yourwarfile.war</web-uri> <context-root>/</context-root> </web> </module> </application>
<display-name> element to the display name for your application.
<description> element so that it describes your application.
<web-uri> element to the name of your WAR file.
application.xml file to its original name and location.
deploy/ear directory.
deploy/war.
jar -cvf earfilename.ear
where earfilename is the name of your EAR file.
Follow these steps to deploy the provider to OC4J:
/oc4j/j2ee/home/applications).
/oc4j/j2ee/home/config/server.xml:
<application name="application name" path="../applications/ear file name" />
where application name is the name of the application and ear file name is the name of the .ear file containing the provider.
/oc4j/j2ee/home/config/default-web-site.xml:
<web-app application="application name" name="deployment name" path="/{application path}/" />
where application name is the name of the application as specified in server.xml and deployment name is the name associated with this deployment of the application.
The application is automatically deployed based on the information specified in Step 3.
http://host:port/application path/servlet/soaprouter
where host is the name of the server hosting the Oracle9iAS listener, port is the port for the Oracle9iAS listener, and application path is the relative URI for the application defined in Step 3. For example:
http://iashost:80/newProvider/servlet/soaprouter
http://iashost:80/newProvider/servlet/soaprouter/sample
Web providers have service names or identifiers as well as a URL. The URL represents the location of the adapter servlet and the service name identifies a provider deployed on that adapter.
Since service names did not exist in release 3.0.9 of Oracle Portal, the registration process is slightly different.
When registering your web provider on Oracle Portal 9.0.2, the registration wizard now includes fields for both the provider URL and service name. The URL is the URL of the adapter servlet and the service name is the name of the provider service you want to register. You should specify both the URL and the service name. If you omit the service name, you will, in effect, be registering the default provider. You should always use the service name, to eliminate ambiguity.
When registering on Oracle Portal 3.0.9, the service name is specified by appending it to the adapter URL For example:
service name: sample
servlet URL: http://iashost:80/newProvider/servlet/soaprouter
registration URL: http://iashost:80/newProvider/servlet/soaprouter/sample
If you omit /sample from the registration URL, then any requests will be forwarded to the provider specified in _default.properties (see Specifying Your Default Service). This feature is provided so you can upgrade existing providers to the new version of PDK-Java and deploy them using the original URL, without impacting any portals that were using the provider.
Other than the cache setting changes described here, Oracle9iAS Release 2 (9.0.2) installs Web Cache by default, and Oracle Portal 9.0.2 uses the features of Web Cache.
When you upgrade a version 3.0.x Portal to Oracle9iAS Release 2 (9.0.2) Portal, or when the middle tier is upgraded before the Portal Repository is upgraded to Oracle9iAS Release 2 (9.0.2), you must set certain cacheability rules in Web Cache to prevent caching of Portal content. When it is cached, the content is no longer secure. This section explains why you must set the cacheability rules, and explains how to do it.
The default cacheability rules for Web Cache in Oracle9iAS Release 2 (9.0.2) include:
Portal version 3.0.9 uses standard HTTP headers to cache "Full Page", images and documents from the database and images from the middle tier in the browser for a predetermined length of time.
Caching Behavior Using a Release 2 Mid-Tier with Web Cache and Portal 3.0.9 Repository
When a Release 2 middle tier with Web Cache is used as a front end for a Portal 3.0.9 repository, Web Cache caching rules override Portal caching rules.
Two cacheability rules must be set in order to prevent caching of Portal content in Web Cache. These rules prevent caching of any request to:
/pls/DAD name/ identifies these requests. The default DAD name is portal30; it is used in the examples in this section.
/servlet/page/ identifies these requests.
Follow these steps to add these cacheability rules:
administrator for the user name, and the password given by the Web Cache administrator. (The default password is adminstrator.)
The Web Cache Administration page appears.
The Create Cacheability Rule window appears.
/pls/portal30 in the URL expression field. (If the DAD name is other than portal30, enter the DAD name.)
.*(dot asterisk) in the POST Body Expression field.
"This ensures that the Portal contents are not cached in Web Cache. Remove this comment as soon as the Portal Repository is upgraded to Release 2. " in the Comment field.
The window closes. The first row of the table contains the values you entered.
The Create Cacheability Rule window appears.
/servlet/page in the URL expression field.
"This ensures that the Portal contents are not cached in Web Cache. Remove this comment as soon as the Portal Repository is upgraded to Release 2. " in the Comment field.
The window closes. The second row of the table contains the values you entered.
pls/portal30_sso.
Migrating the SSL configuration is a manual process, consisting of configuring the SSL connections on the Portal page rendering route. Oracle9iAS Portal contains combinations of clients and servers, each of which is secured by an SSL connection. For example, Web Cache and the Parallel Page Engine act as both clients and servers, while the Application Server acts simply as a server.
Migrating (or re-configuring) the SSL connection in Oracle9iAS Release 2 (9.0.2) involves the steps listed below. The SSL certificate and wallet for the Oracle HTTP Server were prepared by the Oracle9iAS Migration Assistant (see "Migration of SSL Settings"). You can use the certificate from the previous release, unless it is a Global Site ID (which is not supported in Release 2).
Figure 4-1 shows the communication routes involved in any Portal page rendering. Each SSL connection point is described below:
Requests for Portal pages are served over this connection. It is secured with an SSL certificate on the Web Cache listener.
A request can bypass the Web Cache server if port numbers are suitably configured, so you must configure Oracle9iAS for SSL communication.
|
See Also:
Oracle9i Application Server Security Guide, Oracle9i Application Server Administrator's Guide |
This communication path is secure if Web Cache is secure; however, some configuration is necessary for the PPE to recognize the use of SSL.
With HTTPS, you use certificates for ports to increase security. To set this up, edit the ORACLE_HOME_2/j2ee/OC4J/applications/portal/portal/WEB_INF/web.xmlweb.xml file.
You must set up HTTPS such that it is used by all ports at all times. The Parallel Page Engine must be aware of which port(s) are operating under HTTPS.
Add the following to the web.xml file:
<init-param> <param-name>httpsports</param-name> <param-value>433:444</param-value> </init-param>
where the port numbers 433 and 444 are replaced by your HTTPS port configuration. Your server need only have one port, but two are shown here to show the syntax used for multiple entries. Each port in this list operates using the HTTPS protocol, and must have a certificate created on the Oracle HTTP Server on that port.
This section describes configuration settings and files that must be present in order for the migrated Portal to work correctly. If you have problems, ensure that the conditions described in this section have been met.
In order for Oracle9iAS Release 2 (9.0.2) to serve all the static Oracle Portal image files used in your Oracle9iAS Release 1 (1.0.2.2.x) install, you will need to make the following changes to ORACLE_HOME/Apache/Apache/conf/httpd.conf:
# Configuration information added for Oracle Portal 3.0.9 Alias /help/ "/physical/location/of/your/3.0.9/help/files" Alias /images/ "/physical/location/of/your/3.0.9/image/files " <Directory "/physical/location/of/your/3.0.9/image/files" > AllowOverride None Order allow,deny Allow from all ExpiresActive on ExpiresDefault A28800 <Files *> Header set Surrogate-Control 'max-age=2592000' </Files> </Directory> <Directory "/physical/location/of/your/3.0.9/help/files" > AllowOverride None Order allow,deny Allow from all ExpiresActive on ExpiresDefault A28800 <Files *> Header set Surrogate-Control 'max-age=2592000' </Files> </Directory>
Ensure that the portal.ear file exists under ORACLE_HOME_2/j2ee/OC4J_Portal/applications. If it does not, then an incorrect install type was selected to install Oracle9iAS. If you have access to this file, you can just move or copy it to this location; it is not necessary to re-install Oracle9iAS.
Ensure that the JNI cache library wwjni.jar exists in ORACLE_HOME_2/portal/jlib, and that OC4J is configured to use it. Specifically, verify that ORACLE_HOME_2/j2ee/home/config/application.xml has the line
"<library_path="../../../lib" />
where the path resolves to the path on which wwjni.jar resides. If it does not, then an incorrect install type was selected to install Oracle9iAS. If you have access to this file, you can just move or copy it to this location; it is not necessary to re-install Oracle9iAS.
To migrate from Oracle Ultra Search Release 9.0.1 to Oracle Ultra Search Release 9.0.2, you must run the migration script and perform some manual steps.
The Ultra Search migration script first verifies the version of the current system, then migrates user data. User data includes all dictionary and table data, such as metadata, data sources, mappings, crawler schedules, authentication, and query statistics.
All crawler schedules and jobs created in the 9.0.1 system are disabled before data and system migration. When migration is complete, you should re-activate the crawling schedule to re-index the document. You do not need to reconfigure the system or re-enter any data. Users can still query documents that were crawled and indexed by the previous version.
There are two approaches to migrate UltraSearch user data: the in-place approach and the ETL (extract-transform-load) approach.
To migrate using the in-place approach, perform the following steps:
/admin/wk0upgrade.sql. It takes the following input parameters:
SYSPW - password of the user SYS
WKSYSPW - password of the user WKSYS
HOST - database host machine
PORT - database port number
ORACLE_SID - database SID
WK_TABLESPACE - tablespace for Ultra Search
WK_TEMPTABLESPACE - temporary tablespace
CONN_STRING - database connect string
ORACLE_HOME - path of the Oracle home
JAVA_EXE_PATH - Java executable file path
PATH_SEPARATOR - Java classpath separator; use : (colon) for UNIX or ; (semicolon) for Windows.
The script performs the following functions:
To migrate using the ETL approach, perform the following steps:
/admin/wk0migrate.sql. It requires the following input parameters:
The script performs the following functions:
The wk0upgrade.sql and wk0migrate.sql migration scripts for in-place and ETL migration log the actions the migration script has taken. The scripts write the following actions to the log file:
The log file name for in-place migration is:
ULTRASEARCH_HOME/admin/wk0upgrade.log
The log file name for ETL migration is:
ULTRASEARCH_HOME/admin/wk0migrate.log
|
 Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
|