Skip Headers
Oracle® WebCenter Framework Developer's Guide
10g (10.1.3.2.0)

Part Number B31074-05
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

B Additional Portlet Configuration

This appendix discusses configuration information for some of the portlet technologies available with Oracle WebCenter Suite. This chapter includes the following sections:

B.1 Java Portlet Configuration Tips

This section contains configuration information for Java portlets.

Disabling a WSRP Test Page

To disable your WSRP test page, perform the following steps:

  1. In Oracle JDeveloper, go to the Application Navigator and expand the Web Content and WEB-INF folders.

  2. Double-click the web.xml file to open it.

  3. In the Source mode, look for the following element and delete it:

    <servlet-mapping>
          <servlet-name>WSRPTestPage</servlet-name>
          <url-pattern>/info</url-pattern>
       </servlet-mapping>
    

    Note:

    If you do not want to delete the element as you may need it later, then put the element in comment tag, as shown in the following example:
    <servlet-mapping>
          <!--Added by WSRP install tool-->
          <servlet-name>WSRPTestPage</servlet-name>
          <url-pattern>/info</url-pattern>
       </servlet-mapping>
    
  4. Save the web.xml file.

  5. Run your test page in a browser, an error occurs.

B.2 OmniPortlet Configuration Tips

This section contains configuration information for OmniPortlet. To learn more about the OmniPortlet wizard, see Chapter 16, "Creating Portlets with OmniPortlet". This section contains configuration information for the following areas:

B.2.1 Configuring the OmniPortlet Producer to Access Data Outside a Firewall

If the OmniPortlet producer is inside your firewall, then you must configure OmniPortlet to access URLs of data (such as CSV, XML, or Web Services) located outside the firewall. You configure the proxy information in the provider.xml file. Table B-1 provides a list of parameters and their descriptions.

Table B-1 Provider.xml Tags

Parameter Description

httpProxyHost

Enter the host name of a proxy server if one is required to make a URL connection from the OmniPortlet producer to its data sources.

httpProxyPort

Enter the port number for the HTTP Proxy Host.

dontProxyFor

Enter the name of any domain or hosts to which you can directly connect, bypassing a proxy server. Domain names are the part of a URL that contain the names of a business, or organization, or government agency, for example:

*.company.com, *.us.company.com

Hosts can be fully qualified host names or can be IP addresses.

proxyUseAuth

Acceptable values: true | false

Enter true if your proxy server requires authentication. The authentication parameters will be specified by the following tags: proxyType, proxyRealm, proxyUseGlobal, proxyUserName, and proxyPassword.

proxyType

Acceptable values: Basic | Digest

Choose the type of proxy server this provider.

Note: For more information about basic or digest authentication, see http://www.faqs.org/rfcs/rfc2617.html.

proxyRealm

Enter the name of the realm of the proxy server that is accessed by the user according to the login information described later in the table. If you do not know the name of the realm, then contact the administrator of the proxy server.

proxyUseGlobal

Acceptable values: true | false

If true, then the <proxyUser> and <proxyPassword> values are used for all users. Users do not see the Proxy Authentication section on the Source tab and Personalize screen. If false, then page designer must log in using the Proxy Authentication section on the Source tab when they define the portlet. The end user must log in using the Proxy Authentication section on the Personalize screen. If <proxyUsername> and <proxyPassword> are given, then they are only used for public users.

proxyUserName

Enter the username to log in to the proxy server.

ProxyPassword

Enter the password for the specified username. You must prefix ! before your plain password text. It will then be encrypted in the provider.xml file for protection once the producer starts.


The following is a basic example of using a proxy to access data outside a firewall:

<proxyInfo class="mycompany.portal.provider.v2.ProxyInformation">
<httpProxyHost>www-proxy.mycompany.com</httpProxyHost>
<httpProxyPort>80</httpProxyPort>
<proxyUseAuth>false</proxyUseAuth>
</proxyInfo>
 

The following example requires a login and basic authentication for all users for the proxy server:

<proxyInfo class="mycompany.portal.provider.v2.ProxyInformation">
<httpProxyHost>stport823.mycompany.com</httpProxyHost>
<httpProxyPort>8080</httpProxyPort>
<proxyUseAuth>true</proxyUseAuth>
<proxyType>Basic</proxyType>
<proxyRealm>stport823</proxyRealm>
<proxyUseGlobal>false</proxyUseGlobal>
</proxyInfo>

B.2.2 Configuring the OmniPortlet Producer to Access Other Relational Databases

Perform this step if you want to access other relational databases with OmniPortlet. The OmniPortlet SQL data source is preconfigured to access Oracle Databases using the Oracle JDBC driver, and ODBC data sources using the JDBC-ODBC driver from Sun Microsystems.

See Also:

For a list of supported databases, Certification Matrix for Oracle Application Server and DataDirect JDBC available at

http://www.oracle.com/technology/tech/java/oc4j/htdocs/datadirect-jdbc-certification.html

You can configure the OmniPortlet SQL data source to access other relational databases by using DataDirect JDBC drivers. To do this, perform the following steps:

B.2.2.1 Installing DataDirect JDBC Drivers

DataDirect JDBC drivers are packaged in a single ZIP file containing the different drivers used to access supported databases. Download the ZIP file from the following location:

http://www.oracle.com/technology/software/products/ias/htdocs/utilsoft.html

To install DataDirect JDBC drivers, perform the following steps:

  1. Unzip the contents of the ZIP file into a temporary directory, for example /temp/datadirect.

  2. Create the ORACLE_HOME/j2ee/<OC4J_INSTANCE_HOME>/applib directory if it does not already exist.

  3. From the /temp/datadirect/lib directory, copy the DataDirect JDBC drivers to the ORACLE_HOME/j2ee/<OC4J_INSTANCE_HOME>/applib directory.

  4. Check the configuration of the OC4J_Portal instance to ensure that the DataDirect libraries are loaded. To do this, perform the following steps:

    1. Open the ORACLE_HOME/j2ee/<OC4J_INSTANCE_HOME>/config/server.xml file.

    2. Add the Extensible Markup Language (XML) entry, <code-source path="../applib"/>, to the oracle.portal shared-library tag:

      <shared-library name="oracle.portal" version="10.1.3.2.0" library
      compatible="true">
        <code-source path="../applib"/> 
      
    3. Save and close the file.

B.2.2.2 Registering DataDirect Drivers in OmniPortlet

OmniPortlet is implemented as a Web producer and all the configuration properties are stored in the provider.xml file. To use DataDirect JDBC drivers with OmniPortlet, you must register these drivers in the provider.xml file.

To register the new DataDirect JDBC drivers, perform the following steps:

  1. Back up the file, ORACLE_HOME/j2ee/<OC4J_INSTANCE_HOME>/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml, and then open the file.

  2. Add the drivers that you want to use for the SQL data source configuration entry. To do this, perform the following:

    1. Search for the XML tag, driverInfo.

    2. Add a new entry after the last driverInfo tag.

    Following is an example showing a Microsoft SQL Server entry:

    • For OmniPortlet version 9.0.4.1 or later:

      <!-- registration of DataDirect Connect for JDBC SQL Server driver -->
      <driverInfo class="oracle.webdb.reformlet.data.jdbc.JDBCDriverInfo">
        <name>Microsoft SQL Server</name>
        <sourceDataBase>other</sourceDataBase>
        <subProtocol>sqlserver</subProtocol>
        <connectString>mainProtocol:subProtocol://databaseName</connectString>
        <driverClassName>com.oracle.ias.jdbc.sqlserver.SQLServerDriver
        </driverClassName>
        <dataSourceClassName>com.oracle.ias.jdbcx.sqlserver.SQLServerDataSource
        </dataSourceClassName>
        <connHandlerClass>oracle.webdb.reformlet.data.jdbc.JDBCConnectionHandler
        </connHandlerClass>
        <connPoolSize>5</connPoolSize>
        <loginTimeOut>30</loginTimeOut>
      </driverInfo>
      
    • For OmniPortlet versions before 9.0.4.1:

      <!-- registration of DataDirect Connect for JDBC SQL Server driver -->
      <driverInfo class="oracle.webdb.reformlet.data.jdbc.JDBCDriverInfo">
        <name>Microsoft SQL Server</name>
        <sourceDataBase>other</sourceDataBase>
        <subProtocol>sqlserver</subProtocol>
        <connectString>mainProtocol:subProtocol://databaseName</connectString>
        <driverClassName>com.oracle.ias.jdbc.sqlserver.SQLServerDriver
        </driverClassName>
        <connHandlerClass>
        oracle.webdb.reformlet.data.jdbc.JDBCODBCConnectionHandler
        </connHandlerClass>
        <connPoolSize>5</connPoolSize>
        <loginTimeOut>30</loginTimeOut>
      </driverInfo>
      

    Table B-2 describes the parameters in the driverInfo property.

    Table B-2 Parameters in the driverInfo Property

    Parameter Description

    name

    Name of the database you want to use. This name will be used on the Source tab of the OmniPortlet wizard.

    sourceDataBase

    Internal value. Set the value to other.

    subProtocol

    JDBC subprotocol name used by OmniPortlet to create the connection string, for example sqlserver, sybase, or db2.To get the list of subprotocol names, see the DataDirect JDBC driver documentation using the links provided at the end of this section.

    connectString

    Description of the connect string format. For DataDirect drivers, the format is: mainProtocol:subProtocol://databaseName

    driverClassName

    Name of the driver class. To get the different values, see the DataDirect JDBC driver documentation using the links provided at the end of this section.

    dataSourceClassName

    Name of the data source class that implements connection pooling. This parameter is only available in OmniPortlet version 9.0.4.1 or later. See Table B-3 for the right data source class name for your driver.

    connHandlerClass

    Class used by OmniPortlet to manage the driver and connection pooling. The value is either of the following:

    • For OmniPortlet version 9.0.4.1 or later:

      oracle.webdb.reformlet.data.jdbc.JDBCConnectionHandler

    • For OmniPortlet versions before 9.0.4.1:

      oracle.webdb.reformlet.data.jdbc.JDBCODBCConnectionHandler

    connPoolSize

    Minimum number of connections that are opened by the connection pool.

    loginTimeOut

    Maximum time, in seconds, that this data source will wait while attempting to connect to a database.


    Table B-3 lists the values for the driverClassName and dataSourceClassName properties for specific DataDirect JDBC drivers.

    Table B-3 Parameters and Values for driverClassName and dataSourceClassName

    DataDirect Drivers Supported Properties

    Microsoft SQL Server

    • Parameter: driverClassName

      Value: com.oracle.ias.jdbc.sqlserver.SQLServerDriver

    • Parameter: dataSourceClassName

      Value: com.oracle.ias.jdbcx.sqlserver.SQLServerDataSource

    Sybase

    • Parameter: driverClassName

      Value: com.oracle.ias.jdbc.sybase.SybaseDriver

    • Parameter: dataSourceClassName

      Value: com.oracle.ias.jdbcx.sybase.SybaseDataSource

    DB2

    • Parameter: driverClassName

      Value: com.oracle.ias.jdbc.db2.DB2Driver

    • Parameter: dataSourceClassName

      Value: com.oracle.ias.jdbcx.db2.DB2DataSource

    Informix

    • Parameter: driverClassName

      Value: com.oracle.ias.jdbc.informix.InformixDriver

    • Parameter: dataSourceClassName

      Value: com.oracle.ias.jdbcx.informix.InformixDataSource


  3. Save the provider.xml file.

  4. Stop and start the Oracle Application Server instance. To do so, navigate to your ORACLE_HOME, then to the subdirectory opmn/bin.

  5. Type the following command:

    opmnctl restartproc process-type=<OC4J_Instance_Name>
    

Note:

If you are using OmniPortlet in a multiple nodes configuration, for example, in a clustering or load-balancing environment, then you must manually copy the provider.xml file on each node.

See Also:

For more information about DataDirect JDBC drivers, see the following documentation:

Troubleshooting Information

If you encounter errors or problems when configuring or using the OmniPortlet producer, then see Appendix G, "Troubleshooting WebCenter Applications" for troubleshooting information.

B.2.3 Configure Portal Tools and Web Producers (Optional)

To ensure that the Portal Tools (OmniPortlet and OracleAS Web Clipping) producers, locally built, and custom built Web producers work properly, in the middle-tier environment, some additional configuration is required. If OmniPortlet or any other Web producers already have customization in the file system, then PDK-Java provides a Preference Store Migration/Upgrade Utility that can be used to migrate the existing customizations to the database and upgrade customizations from earlier releases. See Section B.4, "Portlet Preference Store Migration Utilities" for more information about the PDK Preference Store Migration Utility.

Configuring Portal Tools Producers in the Multiple Middle-Tier Environment

By default, the OmniPortlet producer uses the file-based Preference Store. In a multiple middle-tier environment, you must configure the File Preference Store to a shared file system, or use the database Preference Store (DBPreferenceStore).

To configure OmniPortlet's File Preference Store to use a shared file system, set the <rootDirectory> tag in OmniPortlet's provider.xml file to the shared file system path:

<preferenceStore class="oracle.webdb.reformlet.ReformletFilePreferenceStore">
      <name>omniPortletprefStore</name>
      <useHashing>true</useHashing>
      <rootDirectory>shared-file-system-path</rootDirectory>
   </preferenceStore>

To configure OmniPortlet producer to use DBPreferenceStore, perform the following steps:

    1. Navigate to the directory ORACLE_HOME/j2ee/OC4J_Portal/applications/jpdk/jpdk/doc/dbPreferenceStore. For example:

      cd ORACLE_HOME/j2ee/OC4J_Portal/applications/jpdk/jpdk/doc/dbPreferenceStore
      
    2. Create a user on the database containing the PORTAL schema, and grant create resource and connect privileges, using the create user and grant connect commands in SQL*Plus. Substitute the actual password in the following command. Do not use the default password of welcome, as this poses a security risk. For example:

      create user prefstore identified by password;
      grant connect, resource to prefstore;
      
    3. Connect as user prefstore and run the jpdk_preference_store2.sql script as follows in SQL*Plus:

      @jpdk_preference_store2
      
    4. Add the following entry to the file data-sources.xml, located in the directory ORACLE_HOME/j2ee/OC4J_Portal/config:

      <connection-pool name="ConPool_1">
      <connection-factory factory-class="oracle.jdbc.pool.OracleDataSource"
      username="prefstore"
      password="password"
      url="jdbc:oracle:thin:@infra.host.com:1521:orcl">
      </connection-factory>
      </connection-pool>
       
      <managed-data-source name="PooledConnection"
      connection-pool-name="ConPool_1"
      jndi-name="jdbc/PooledConnection"/> 
      

      Note:

      Embedding passwords in deployment and configuration files poses a security risk. If you do not want to use a clear text password in the data-sources.xml file, then you can create an indirect password by performing the following steps:
      1. Edit the ORACLE_HOME/j2ee/OC4J_Portal/config/jazn-data.xml file to add the prefstore user in the jazn.com realm as shown in the following example (You can create a new realm for this instead of using the jazn.com realm):

        <realm>
            <name>jazn.com</name>
            <users>
              <user>
                 <name>prefstore</name>
                 <display-name>OmniPortletprefstore</display-name>
                 <description>OmniPortlet prefstore</description>
                 <credentials>!welcome</credentials>
              </user>
              <user>
                 ... 
        

        Note that the password is included in the <credentials> element and is prefixed with an exclamation (!) mark. The next time Oracle Containers for J2EE (OC4J) reads the jazn-data.xml, it will rewrite the file with this password obfuscated.

      2. Edit the ORACLE_HOME/j2ee/OC4J_Portal/config/data-sources.xml file again to use the indirect password that you created in the previous step by replacing the password attribute as follows:

        password="->jazn.com/prefstore"
        

        For more information about creating an indirect password, see Oracle Containers for J2EE Security Guide.

    5. Edit the file provider.xml located in the directory ORACLE_HOME/j2ee/OC4J_Portal/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet. Edit the preferenceStore tag as shown in bold:

      <provider class="oracle.webdb.reformlet.ReformletProvider"> 
         <vaultId>0</vaultId> 
         <session>true</session> 
         <preferenceStore class="oracle.portal.provider.v2.preference.DBPreferenceStore"> 
            <name>omniPortletprefStore</name> 
            <connection>jdbc/PooledConnection</connection> 
         </preferenceStore> 
      
    6. Restart OC4J_Portal.

    You can find more information about configuring the database Preference Store in the PDK article titled "Installing the DBPreferenceStore Sample (V2)", (with the filename installing.db.preference.store.v2.html) located in the pdksoftware10132.zip file located on the Oracle Technology Network (http://www.oracle.com/technology/products/webcenter/index.html).

    If you have already created an OmniPortlet instance with customizations in the file system, then you must migrate these customizations to the database using the Preference Store Migration Utility. To run the migration utility, perform the following steps:

    1. Navigate to the middle-tier Oracle home directory using the following command:

      cd ORACLE_HOME
      
    2. Run the following command to migrate OmniPortlet data from a file-based Preference Store (FilePreferenceStore) to the database Preference Store (DBPreferenceStore):

      java -classpath lib/dms.jar:jdbc/lib/ojdbc14dms.jar:portal/jlib/pdkjava.jar:portal/jlib/
      ptlshare.jar oracle.portal.provider.v2.preference.MigrationTool -mode 
      filetodb -pref1UseHashing true -pref1RootDirectory portal/portletdata/tools/omniPortlet 
      -pref2User <User_Name> -pref2Password <User_Password> -pref2URL 
      jdbc:oracle:thin:@infra.host.com:1521:orcl
      

    See Section B.4, "Portlet Preference Store Migration Utilities" for more information about the PDK Preference Store Migration Utility.

  1. Typically, you perform the HTTP Proxy configuration for OmniPortlet and Web Clipping before you configure the LBR. To do it after the LBR is configured, perform the following steps:

    1. The Portal Tools configuration information is stored in the provider.xml file on the middle-tier server. You must update the configuration directly on one middle tier (for example, M1) and then propagate it across all middle tiers front-ended by the LBR. Before you do this, you must shut down all middle tiers except M1.

    2. You can change the HTTP Proxy settings in the provider.xml file. For more information, see Section B.2.1, "Configuring the OmniPortlet Producer to Access Data Outside a Firewall".

    3. Propagate the changes made to the provider.xml file to middle tier M2:

      • Copy ORACLE_HOME/j2ee/OC4J_Portal/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml from M1 to M2.

      • Copy ORACLE_HOME/j2ee/OC4J_Portal/applications/portalTools/webClipping/WEB-INF/providers/webClipping/provider.xml from M1 to M2.

  2. Copy the ORACLE_HOME/j2ee/OC4J_Portal/config/data-sources.xml file from M1 to M2.

  3. Copy the ORACLE_HOME/j2ee/OC4J_Portal/config/jazn-data.xml file file from M1 to M2.

  4. Restart middle tier M2.

  5. Update portlet producer registration in your WebCenter application. Change the first part of the producer registration URL from http://m1.abc.com:7777/ to http://lbr.abc.com/.

  6. Verify that OmniPortlet and the Web Clipping producers work properly through the LBR, by going to the test pages at the following URLs.

    • OmniPortlet Producer: http://lbr.abc.com/portalTools/omniPortlet/producers/omniPortlet

      If you see the "No Portlets Available" message under the Portlet Information section in the OmniPortlet Producer test page, then you may not have configured OmniPortlet correctly in Step 1. If OmniPortlet is configured correctly, then the OmniPortlet and Simple Parameter Form portlets are available on the test page.

    • Web Clipping Producer: http://lbr.abc.com/portalTools/webClipping/producers/webClipping

    Note:

    If you want to use the OracleAS Web Clipping portlet, or the Web Page Data Source for OmniPortlet, then you must also enable session binding in Oracle Web Cache.

B.3 Web Clipping Portlet Configuration Tips

Before you use Web Clipping, you must perform some administrative tasks, including the following:

B.3.1 Configuring the Web Clipping Repository

Web clippings have definitions that must be stored persistently in the Oracle Metadata Services store. Alternatively, the Web Clipping repository can also be hosted by an Oracle Database.

You can view the Web Clipping repository configuration by accessing the Web Clipping Producer Test Page at:

http://<host>:<port>/portalTools/webClipping/providers/webClipping

The Web Clipping Test page automatically detects whether or not the Web Clipping producer is configured with a valid repository. If it is not, then the Status column for the Web Clipping Repository displays Not Configured. Figure B-1 shows the Web Clipping Test page.

Figure B-1 Web Clipping - Producer Test Page

Description of Figure B-1 follows
Description of "Figure B-1 Web Clipping - Producer Test Page"

You cannot change the Web Clipping configuration information using the Producer Test Page. As WebCenter Framework administrator, you can configure the Web Clipping repository by setting appropriate values in the provider.xml file located in the <ORACLE_HOME>\j2ee\home\applications\portalTools\webClipping\WEB-INF\providers\webClipping directory.

By default, the Web Clipping producer is configured to use Oracle Metadata Services as the Web Clipping Repository. You can select either of the following as the Web Clipping repository:

  • Oracle Metadata Services

  • Other Oracle Databases of versions 9i or later

To change the repository settings, perform the following tasks:

  1. Open the file, <ORACLE_HOME>\j2ee\home\applications\portalTools\webClipping\WEB-INF\providers\webClipping\provider.xml in a text editor.

  2. Specify one of the following to be your Web Clipping repository:

    • Oracle Metadata Services (default): If you select Oracle Metadata Services as your Web Clipping repository, then the Web Clipping definition is saved in the file system. You can use Web Clipping even without a database.

      This is the default Web Clipping repository option. To use Oracle Metadata Services as the repository, specify the path to the mds-config.xml file in the mdsConfigLocation entry in the provider.xml file (by following the guidelines under this entry) as shown in Example B-1.

      Example B-1 Setting Oracle Metadata Services as Web Clipping Repository

      - <repositoryInfo class="oracle.portal.wcs.provider.info.MdsInformation">
      - <!--        
          Specify the location of the MDS configuration file here. It can be 
          absolute or relative. The definition of absolute pathname is system
          dependent. On UNIX systems, a pathname is absolute if it begins with a
          single forward slash "/". On Microsoft Windows systems, a pathname is
          absolute if it begins with a drive specifier followed by single
          backslash "\", or if begins with a double backslash "\\".
          
          When a relative path is specified, it is assumed to be relative to the
          base directory identified by
          OH/j2ee/home/applications/portalTools/webClipping/WEB-INF or
          OH/j2ee/OC4J_Portal/applications/portalTools/webClipping/WEB-INF
          depending on where the portalTools EAR file is deployed.
        --> 
        <mdsConfigLocation>mds-config.xml</mdsConfigLocation> 
        </repositoryInfo>
      

      Note:

      The mds-config.xml file contains the metadata store configuration information, including the path to the metadata store. You can change the path to the metadata store by editing the metadata-path property in <ORACLE_HOME>\j2ee\home\applications\portalTools\webClipping\WEB-INF\mds-config.xml as shown in the following example:
      <property name="metadata-path" value="portletdata/tools/webClipping"/>
      

      For a multiple middle tier deployment, change the metadata path to a shared file system.

    • Other Oracle9i or later Database: If you select this option, then the Web Clipping repository is stored in a user defined schema in Oracle Database. In this case, you must specify the connection parameters of Oracle Database. You can also specify this option if you want to use the OracleAS Infrastructure database as the Web Clipping repository.

      To use Oracle Database as the Web Clipping repository, comment out the default repository setting (shown in Example B-1) in the provider.xml file and uncomment the entry shown in Example B-2.

      Example B-2 Setting Oracle Database 9i or Later as Web Clipping Repository

      - <!--
       Uncomment the following and set the connection information to use database as the repository
          <repositoryInfo class="oracle.portal.wcs.provider.info.DatabaseInformation">
             <useRAA>false</useRAA>
             <databaseHost>mycompany.dbhost.com</databaseHost>
             <databasePort>1521</databasePort>
             <databaseSid>iasdb</databaseSid>
             <databaseUsername>scott</databaseUsername>
             <databasePassword>!tiger</databasePassword>
             <useASO>false</useASO>
          </repositoryInfo>
       -->
      

      In this entry, you must set the database connection parameters, which can be described as follows:

      • databaseHost: Host name of the computer running the database.

      • databasePort: Port number of the database listener.

      • databaseSid: The SID of the database. Use this format when the connect string is in the format, host:port:sid. For example: myhost.company.com:1521:mydb.

      • databaseUsername: The database account user name.

      • databasePassword: The database account password. To ensure security, you must enter plain text passwords prefixed with the ! character as shown in Example B-2, to allow the Web Clipping Producer to encrypt the password in the producer.

      If you require a secure database connection, then enable the Advanced Security Option (ASO) by setting the useASO entry to true.

      See Section B.3.3, "Securing the Web Clipping Producer" for more information about configuring the Advanced Security Option.

  3. Save the provider.xml file.

  4. Restart the OC4J instance.

B.3.2 Configuring HTTP or HTTPS Proxy Settings

Your HTTP or HTTPS proxy settings must be set to enable the Web Clipping Studio to connect to Web sites outside of your firewall. You can specify the settings by manually editing the provider.xml file.

As the WebCenter Application administrator, you can set proxy settings manually according to your HTTP or HTTPS configuration. Edit the appropriate entries in the provider.xml file located in the <ORACLE_HOME>\j2ee\home\applications\portalTools\webClipping\WEB-INF\providers\webClipping directory.

Example shows the relevant portion of provider.xml.

- <!-- 
 proxy information: Fill the following up if you have a proxy
 server between the provider and external sites.
   <proxyInfo class="oracle.portal.provider.v2.ProxyInformation">
      <httpProxyHost>yourproxy.yourdomain.com</httpProxyHost>
      <httpProxyPort>80</httpProxyPort>
      <dontProxyFor>.yourdomain.com</dontProxyFor>
   </proxyInfo>
   
  --> 

Table B-1, available earlier in this appendix, describes the proxy settings you must make in the provider.xml file. The descriptions in the table are applicable for Web Clipping producers also.

Note:

For environments that use a proxy server to reach external Web sites, you can use the dontProxyFor entry to specify the proxy exception list. Web Clipping uses the proxy exception list to restrict users from clipping content from unauthorized external Web sites.

Users attempting to reach a Web site in one of the listed domains, from the Web Clipping Studio, will then receive an HTTP timeout error.

B.3.3 Securing the Web Clipping Producer

The preceding sections described the administrative tasks that must be performed before you are able to use the Web Clipping producer. The following sections describe some security configuration options that you should implement to enable the Web Clipping producer to access trusted sites and encrypt the channel between itself and the database:

B.3.3.1 Adding Certificates for Trusted Sites

When a user navigates to a secure site, the Web site typically returns a certificate, identifying itself to the user when asking for secure information. If the user accepts the certificate, then the certificate is placed into the list of trusted certificates of the browser so that a secure channel can be opened between the browser and that server. Like a Web browser, the Web Clipping producer acts as an HTTP client to external Web sites. In order for the Web Clipping producer to keep track of trusted sites, it makes use of a file that stores the certificates of those sites, namely the ca-bundle.crt file, located in the ORACLE_HOME/portal/conf directory.

The shipped ca-bundle.crt is an exported version of the trusted server certificate file from Oracle Wallet Manager. The default trusted server certificate in Oracle Wallet Manager does not cover all possible server certificates that exist on the Web. For this reason, when a user navigates to a secure server using HTTPS, the user can get an Secure Sockets Layer (SSL) Hand-shake failed exception in the Web Clipping Studio. To solve this problem, the ca-bundle.crt file must be augmented with new trusted sites that are visited. As a WebCenter Application administrator, you must do the following to extend the shipped ca-bundle.crt file:

  1. Use a browser (preferably Internet Explorer) to download the root server certificate from each external HTTPS Web site in BASE64 format that is visited, and is missing from the trusted certificate file.

  2. Use Oracle Wallet Manager to import each certificate.

  3. Export the trusted server certificates into a file and copy its content into the ca-bundle.crt file.

More on OTN

For more information about Oracle Wallet Manager, see the Oracle Database Advanced Security Administrator's Guide in the Oracle Database documentation on OTN, http://www.oracle.com/technology/.

B.3.3.2 Configuring Oracle Advanced Security for the Web Clipping Producer

The Web Clipping producer can use Oracle Advanced Security Option (ASO) to secure and encrypt the channel between itself and the database that hosts the Web Clipping repository. This feature is available only if you have selected any Oracle Database as the Web Clipping repository. This feature is disabled by default as Oracle Metadata Services is the default Web Clipping repository. To enable it, perform the following steps:

  1. Open the file, <ORACLE_HOME>\j2ee\home\applications\portalTools\webClipping\WEB-INF\providers\webClipping\provider.xml in a text editor.

  2. Under the repository settings section in the file (shown in Example B–2), set the useASO entry to true.

  3. Save the provider.xml file.

In addition, you must set the following ASO configuration parameters in the sqlnet.ora file to ensure that the database connections created between the Web Clipping producer and the database hosting the Web Clipping Repository are using ASO. See the Oracle Advanced Security Administrator's Guide for the list of values to use as all possible combinations of parameters are described in detail.

  • SQLNET.AUTHENTICATION_SERVICES -- This parameter is used to select a supported authentication method in making database connections with ASO. See the Oracle Advanced Security Administrator's Guide for more information about setting this parameter.

  • SQLNET.CRYPTO_SEED -- This parameter denotes the cryptographic seed value (FIPS 140-1 setting), used in making database connections with ASO.

    See the Oracle Advanced Security Administrator's Guide for more information about setting this parameter.

    Note:

    When setting these parameters after the initial configuration (where the database parameters are already set up), the database connections are assumed to be open already. Because enabling ASO affects all connections made to the database, it is advisable to restart the OC4J instance containing the Web Clipping producer to reset all the current connections to now use ASO. You would also must do this when disabling ASO.

B.4 Portlet Preference Store Migration Utilities

A preference store is a mechanism for storing information like user preference data, portlet and producer settings, or even portlet data. Preferences can be stored in a database, which is recommended for high availability configurations, or a file system. You can migrate the following stores for your WebCenter applications:

B.4.1 JPS Portlet Preference Store

A WSRP container preference store is a mechanism used for persisting consumer registration and portlet preference data. Currently, there are two preference store implementations, database preference store and file preference store. A database preference store persists data using a relational database. A file preference store persists data using the file system. For WSRP Release 2, the default is to use the file preference store at ORACLE_HOME/portal/portletdata. For the 10.1.2 version of the portlet container, the default (and only) preference store is the database preference store.

With the introduction of the file preference store, you can remove the dependency on the database. The file preference store is used as the default preference store. Therefore, you may want to migrate from an existing database preference store to a file preference store. Note, however, that the database preference store is recommended for high availability configurations.

B.4.1.1 PersistenceMigrationTool

The WSRP container preference store migration utility, PersistenceMigrationTool, enables you to migrate existing data between different preference stores (for example, from a database preference store to a file preference store). This utility also enables upgrading users to ensure that their existing locale-specific portlet preference data uses a naming format compatible with the latest JPS release. You can also use this utility to migrate between source and destination stores of the same type. This enables data to be moved from one database store to another.

The syntax of the PersistenceMigrationTool is:

Note:

You can also obtain this syntax from the command line by entering the following command:
java -classpath
ORACLE_HOME/j2ee/wsrp/shared-lib/oracle.wsrp/1.0/
  wsrp-container.jar:
ORACLE_HOME/javacache/lib/cache.jar:
ORACLE_HOME/webservices/lib/saaj-api.jar:
ORACLE_HOME/webservices/lib/orasaaj.jar:
ORACLE_HOME/jdbc/lib/ojdbc14.jar
oracle.portlet.server.containerimpl.PersistenceMigrationTool
java oracle.portlet.server.containerimpl.PersistenceMigrationTool
-sourceType file | db 
-destType file | db 
{-sourcePath dir | 
 -sourceUsername username -sourcePassword password -sourceDatabase db}
{-destPath dir | destUsername username -destPassword password -destDatabase db}
[-debug]

where

sourceType indicates whether the source store is in a file or database. You can have source and destination stores of the same type. Hence, you can migrate from one database to another or one file system to another.

destType indicates whether the destination store is in a file or database. You can have source and destination stores of the same type. Hence, you can migrate from one database to another or one file system to another.

sourcePath is the location of a file-based preference store. This argument is required when sourceType is file.

sourceUsername is the database user name for a preference store database. This argument is required when sourceType is db.

sourcePassword is the database password for a preference store database. This argument is required when sourceType is db.

sourceDatabase is the name of a preference store database. This argument is required when sourceType is db.

destPath is the location of a file-based preference store. This argument is required when destType is file.

destUsername is the database user name for a preference store database. This argument is required when destType is db.

destPassword is the database password for a preference store database. This argument is required when destType is db.

destDatabase is the name of a preference store database. This argument is required when destType is db.

debug turns on full logging through standard output to enable users to diagnose issues that arise when the tool runs.

Example B-3 demonstrates running the PersistenceMigrationTool utility. In this example, preferences from a database store are copied to a file store.

Example B-3 Running the PersistenceMigrationTool Utility

java oracle.portlet.server.containerimpl.PersistenceMigrationTool -sourceType 
db -sourceUsername scott -sourcePassword tiger -sourceDatabase 
abc.mycompany.com:1521:e10gdev3 -destType file -destRoot /data/prefs

B.4.1.2 How to Determine and Set Your Preference Store

To determine which data store is used to persist data, you must add the persistentStore JNDI environment variable to the web.xml file (ORACLE_HOME\j2ee\OC4J_Portal\applications\portletapp\wsrp-samples\WEB-INF\web.xml). The default value for this variable is File. If you keep the default value, then you must also add the fileStoreRoot variable to specify the file system location for the file store. The default value for this variable is portletdata, and this value is relative to the ORACLE_HOME/portal directory, which means the default location for the file store is ORACLE_HOME/portal/portletdata.

If you deployed the sample WSRP producer or if your application is based on this sample producer, then these JNDI environment variables may already be present in the web.xml file. Add the code excerpt shown in Example B-4 to the web.xml file (the environment variables and their default values are shown in bold):

Example B-4 persistentStore and fileStoreRoot Variables in the web.xml File

<env-entry>
    <env-entry-name>oracle/portal/wsrp/server/persistentStore</env-entry-name>
    <env-entry-type>java.lang.String</env-entry-type>
    <env-entry-value>File</env-entry-value>
</env-entry>
<env-entry>
    <env-entry-name>oracle/portal/wsrp/server/fileStoreRoot</env-entry-name>
    <env-entry-type>java.lang.String</env-entry/type>
    <env-entry-value>portletdata</env-entry-value>
</env-entry>

Note:

You can leave the default values in the file if you do not want to explicitly select the type of preference store or location for the store.

B.4.2 PDK-Java Portlet Preference Store

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.

MigrationTool

If you have already installed OracleAS PDK, then 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. Note that you must run this tool from ORACLE_HOME. The syntax of the migration utility is:

Note:

You can also obtain this syntax from the command line by entering the following command:
java -classpath lib/dms.jar:jdbc/lib/ojdbc14dms.jar:
  portal/jlib/pdkjava.jar:portal/jlib/ptlshare.jar
  oracle.portal.provider.v2.preference.MigrationTool
java -classpath lib/dms.jar:jdbc/lib/ojdbc14dms.jar:portal/jlib/pdkjava.jar:
                portal/jlib/ptlshare.jar
 oracle.portal.provider.v2.preference.MigrationTool
  -mode [file | db | filetodb | filetofile | dbtofile | dbtodb]
  [-remap language | locale]
  [-countries iso_country_code]
  [-pref1UseHashing true | false]
  {-pref1RootDirectory directory |
   -pref1User username -pref1Password password -pref1URL url}
  [-pref1UseHashing true | false]
  {-pref2RootDirectory directory |
   -pref2User username -pref2Password password -pref2URL url}
  [-upfixwpi filename]

where:

-mode is the mode in which you want to run the Preference Store Migration and Upgrade Utility.

  • file or db indicates that you want to run in upgrade mode. See Upgrade Mode for more information about this mode.

  • filetodb, filetofile, dbtofile, or dbtodb indicates that you want to run in migration mode. See Migration Mode for more information about this mode.

-remap is the localePersonalizationLevel (language or locale). Note that you only must use this option if you want to change localePersonalizationLevel as part of your upgrade/migration.

-countries specifies a prioritized list of ISO country codes, indicating your order of preference in a collision between remapped preferences for different countries. -countries is only meaningful if you also specified the -remap option.

-pref1UseHashing is whether you want to employ hashing on the source for this operation.

-pref1RootDirectory is the path of a source file system, for example, j2ee/home/applications/jpdk/jpdk/WEB-INF/providers/sample.

-pref1User is the user name for a source database.

-pref1Password is the password for a source database.

-pref1URL is the URL to a source database, for example, jdbc:oracle:thin:@myserver.mydomain.com:1521:mysid.

-pref2UseHashing is whether you want to employ hashing on the destination for this operation.

-pref2RootDirectory is the path of a destination file system, for example, j2ee/home/applications/jpdk/jpdk/WEB-INF/providers/sample.

-pref2User is the user name for a destination database.

-pref2Password is the password for a destination database.

-pref2URL is the URL to a destination database, for example, jdbc:oracle:thin:@myserver.mydomain.com:1521:mysid.

- upfixwpi indicates a log file for the operation.

Note:

After running the utility, it is recommended that you restart the OC4J instance with the portlet container 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 B-4 describes the upgrade modes in which you can run the utility.

Table B-4 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:

  • You have upgraded from OracleAS PDK 9.0.4.0.0 or earlier and want to use existing portlets with the default localePersonalizationLevel setting of language (In earlier releases, the default setting was locale).

  • You have upgraded from OracleAS Portal 9.0.2.0.0 or earlier and want to use existing portlets with a localePersonalizationLevel setting of locale (OracleAS Portal now uses different names for some locales and therefore some existing data must be remapped).

  • You want to change the localePersonalizationLevel for an existing portlet from locale to language or vice-versa.

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 a collision between remapped preferences for different countries. For example, if you specify -remap language -countries GB,US in the command, then 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 B-5 describes the migration modes in which you can run the utility.

Table B-5 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.


If the destination for the operation is a database, then you must ensure that the destination database has the appropriate tables before running the migration utility. You create these tables by running the jpdk_preference_store2.sql which is found in ORACLE_HOME/j2ee/OC4J_WebCenter/applications/jpdk/jpdk/doc/dbPreferenceStore.

When using a migration mode, you can also 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, see the PDK-Java XML Provider Definition Tag Reference document on Portal Studio:

http://www.oracle.com/technology/products/ias/portal/html/javadoc/apidoc/oracle/portal/provider/v2/ProviderDefinition.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 OracleAS PDK on a standalone 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.

Example B-5 and Example B-6 illustrate the usage of the utility.

Example B-5 PDK-Java Migration Utility Command Line, Upgrade

java -classpath lib/dms.jar:jdbc/lib/ojdbc14dms.jar:
      portal/jlib/pdkjava.jar:portal/jlib/ptlshare.jarjava
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

Example B-6 PDK-Java Migration Utility Command Line, Migration

java -classpath lib/dms.jar:jdbc/lib/ojdbc14dms.jar:
      portal/jlib/pdkjava.jar:portal/jlib/ptlshare.jarjava
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

B.4.3 Web Clipping Repository

Web Clipping does not have a preference store as such, but it stores Web Clipping definitions and associated metadata. By default, it uses Oracle Metadata Services (MDS), which is file-based, for this purpose, but you can also configure Web Clipping to use a database. To migrate this repository for WebCenter applications, you can use the Predeployment tool in export and import mode to go from MDS to a database, or vice versa. This procedure must be done for each application as follows:

  1. Run the Predeployment tool in export mode on all WebCenter applications that use the Web Clipping producer. For more information, see Section 12.4.1, "Exporting Customizations".

  2. Update the producer to use a different repository. For example, a database, as described in Section 18.4.3.1, "Configuring a Web Clipping Portlet Producer to Use a Database Repository".

  3. Run the Predeployment tool in import mode on all WebCenter applications that use the Web Clipping producer. For more information, see Section 12.4.2, "Importing Customizations".

Note:

If Oracle Application Server Portal (OracleAS Portal) is consuming the Web Clipping producer, then you must use OracleAS Portal's export and import utilities to migrate the repository.