Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle WebCenter Portal
11g Release 1 (11.1.1.6.0)

Part Number E10148-19
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

E Additional Portlet Configuration

This appendix discusses configuration information for the portlet technologies available with Oracle WebCenter Portal.

This chapter includes the following sections:

For more information about using the portlet technologies at design time, see their respective chapters throughout this guide:

For more information about using these technologies at runtime, see their respective chapters in Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces.

E.1 OmniPortlet Configuration Tips

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

E.1.1 Configuring the OmniPortlet Producer to Access Data Outside a Firewall

If the OmniPortlet producer is inside your firewall, then you must configure the proxy information so that OmniPortlet can access URLs of data (such as CSV, XML, or web services) located outside the firewall. To do so, you can either set the proxy information in the command line when you start your WebLogic server. Or, you can set up the proxy information in OmniPortlet's provider.xml file, located here: OmniPortlet_WAR_DIR/WEB-INF/providers/omniPortlet/provider.xml.

Note:

For the Web Service data source, you must set the proxy information in both the provider.xml file and using the command line parameters.

  • To set the proxy information in the command line when starting the WebLogic server, set the parameters as described in Table E-1, if you are using an HTTP Proxy Host, or Table E-2, if you are using an HTTPS Proxy Host.

    Table E-1 HTTP Proxy Information Command Line Parameters

    Parameter Description

    http.proxyHost

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

    http.proxyPort

    The port number for the HTTP Proxy Host.

    http.nonProxyHosts

    The name of any domain or hosts to which you can directly connect, bypassing a proxy server, such as your local machine:

    localhost|localhost.localdomain

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

    http.proxyUser

    The user to log in to the proxy server if the proxy server requires authentication.

    http.proxyPassword

    The password to log in to the proxy server if the proxy server requires authentication.

    http.proxyAuthType

    The authentication type of the proxy server. Acceptable values: Basic | Digest.

    http.proxyAuthRealm

    The name of the realm of the proxy server. If you do not know the name of the realm, contact the proxy server administrator.


    Table E-2 HTTPS Proxy Information Command Line Parameters

    Parameter Description

    https.proxyHost

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

    https.proxyPort

    The port number for the HTTPS Proxy Host.

    https.nonProxyHosts

    The name of any domain or hosts to which you can directly connect, bypassing a proxy server, such as your local machine:

    localhost|localhost.localdomain

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

    https.proxyUser

    The user to log in to the proxy server if the proxy server requires authentication.

    https.proxyPassword

    The password to log in to the proxy server if the proxy server requires authentication.

    https.proxyAuthType

    The authentication type of the proxy server. Acceptable values: Basic | Digest.

    https.proxyAuthRealm

    The name of the realm of the proxy server. If you do not know the name of the realm, contact the proxy server administrator.


    The following are examples of three parameters and their values:

    -Dhttps.proxyHost=myProxyServer.mycompany.com
    -Dhttps.proxyPort=80
    -Dhttps.nonProxyHosts=localhost|localhost.localdomain|127.0.0.1|
    
  • To configure the proxy information in the provider.xml file, see Table E-3 for a list of parameters and their descriptions.

    Table E-3 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 are specified by the following tags: proxyType, proxyRealm, proxyUseGlobal, proxyUserName, and proxyPassword.

    proxyType

    Acceptable values: Basic | Digest

    Choose the type of proxy server this provider.

    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 page. 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 user name to log in to the proxy server.

    ProxyPassword

    Enter the password for the specified user name. You must prefix ! before your plain password text. It is then encrypted in the provider.xml file for protection when the producer starts.


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

    <proxyInfo class="oracle.portal.provider.v2.ProxyInformation">
    <httpProxyHost>www-proxy.example.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>myport.example.com</httpProxyHost>
    <httpProxyPort>8080</httpProxyPort>
    <proxyUseAuth>true</proxyUseAuth>
    <proxyType>Basic</proxyType>
    <proxyRealm>myport</proxyRealm>
    <proxyUseGlobal>false</proxyUseGlobal>
    </proxyInfo>
    

E.1.2 Configuring the OmniPortlet Producer to Access Other Relational Databases

The OmniPortlet SQL data source is preconfigured to access Oracle databases using the Oracle JDBC drivers, and ODBC data sources using Sun Microsystem's JDBC-ODBC driver. Oracle allows developers to access other relational databases using DataDirect JDBC drivers.

See Also:

For a list of supported databases, Certification Matrix for Oracle Application Server and DataDirect JDBC available on the Oracle Technology Network (http://www.oracle.com/technetwork/index.html).

This section contains the following steps:

E.1.2.1 Installing DataDirect JDBC Drivers

The following DataDirect JDBC drivers are included with the WebLogic Server installation:

  • wlinformix.jar

  • wlsqlserver.jar

  • wlutil.jar

  • wldb2.jar

  • wlresource.jar

  • wlspy.jar

  • wlbase.jar

If you do not plan to use these DataDirect drivers, you can instead download DataDirect JDBC drivers to access the desired database. These drivers are packaged in a single ZIP, which you can download from the following location:

http://www.oracle.com/technetwork/topics/datadirect-index-091847.html

To install DataDirect JDBC drivers:

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

  2. Copy the DataDirect JDBC drivers from the temporary directory to your WebLogic Server directory: WLS_DOMAIN_DIRECTORY/lib.

E.1.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:

  1. Back up the file, OmniPortlet_WAR_DIRECTORY/WEB-INF/providers/omniPortlet/provider.xml, and then open the file.

  2. Add the drivers to use for the SQL data source configuration entry:

    1. Search for the XML tag, driverInfo.

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

    The following are examples of the driverInfo for WebLogic DataDirect drivers:

    • Microsoft SQL Server:

      <driverInfo class="oracle.webdb.reformlet.data.jdbc.JDBCDriverInfo">
        <name>Microsoft SQL Server</name>
        <sourceDataBase>other</sourceDataBase>
        <subProtocol>weblogic:sqlserver</subProtocol>
        <connectString>mainProtocol:subProtocol://databaseName</connectString>
        <driverClassName>weblogic.jdbc.sqlserver.SQLServerDriver
        </driverClassName>
        <dataSourceClassName>weblogic.jdbcx.sqlserver.SQLServerDataSource
        </dataSourceClassName>
        <connHandlerClass>oracle.webdb.reformlet.data.jdbc.JDBCConnectionHandler
        </connHandlerClass>
        <connPoolSize>5</connPoolSize>
        <loginTimeOut>30</loginTimeOut>
      </driverInfo>
      
    • Sybase:

      <driverInfo class="oracle.webdb.reformlet.data.jdbc.JDBCDriverInfo">
        <name>Sybase</name>
        <sourceDataBase>other</sourceDataBase>
        <subProtocol>weblogic:sybase</subProtocol>
        <connectString>mainProtocol:subProtocol://databaseName</connectString>
        <driverClassName>weblogic.jdbc.sybase.SybaseDriver
        </driverClassName>
        <connHandlerClass>
        oracle.webdb.reformlet.data.jdbc.JDBCODBCConnectionHandler
        </connHandlerClass>
        <connPoolSize>5</connPoolSize>
        <loginTimeOut>30</loginTimeOut>
      </driverInfo>
      
    • DB2:

      <driverInfo class="oracle.webdb.reformlet.data.jdbc.JDBCDriverInfo">
        <name>DB2</name>
        <sourceDataBase>other</sourceDataBase>
        <subProtocol>weblogic:db2</subProtocol>
        <connectString>mainProtocol:subProtocol://databaseName</connectString>
        <driverClassName>weblogic.jdbc.db2.DB2Driver
        </driverClassName>
        <connHandlerClass>
        oracle.webdb.reformlet.data.jdbc.JDBCODBCConnectionHandler
        </connHandlerClass>
        <connPoolSize>5</connPoolSize>
        <loginTimeOut>30</loginTimeOut>
      </driverInfo>
      
    • Informix:

      <driverInfo class="oracle.webdb.reformlet.data.jdbc.JDBCDriverInfo">
        <name>Informix</name>
        <sourceDataBase>other</sourceDataBase>
        <subProtocol>weblogic:informix</subProtocol>
        <connectString>mainProtocol:subProtocol://databaseName</connectString>
        <driverClassName>weblogic.jdbc.informix.InformixDriver
        </driverClassName>
        <connHandlerClass>
        oracle.webdb.reformlet.data.jdbc.JDBCODBCConnectionHandler
        </connHandlerClass>
        <connPoolSize>5</connPoolSize>
        <loginTimeOut>30</loginTimeOut>
      </driverInfo>
      

    Table E-4 describes the parameters in the driverInfo property.

    Table E-4 Parameters in the driverInfo Property

    Parameter Description

    name

    Name of the database you want to use. This name is 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 E-5 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 waits while attempting to connect to a database.


    Table E-5 lists the values for the driverClassName and dataSourceClassName properties for specific DataDirect JDBC drivers.

    Table E-5 Parameters and Values for driverClassName and dataSourceClassName

    DataDirect Drivers Supported Properties

    Microsoft SQL Server

    Parameter: driverClassName

    Value: weblogic.jdbc.sqlserver.SQLServerDriver

    Sybase

    Parameter: driverClassName

    Value: weblogic.jdbc.sybase.SybaseDriver

    DB2

    Parameter: driverClassName

    Value: weblogic.jdbc.db2.DB2Driver

    Informix

    Parameter: driverClassName

    Value: weblogic.jdbc.informix.InformixDriver


  3. Save the provider.xml file.

  4. Stop and start the Oracle WebLogic Managed Server instance where your portlet producer was deployed. To do so, navigate to your WL_HOME, then to the subdirectory opmn/bin.

    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 how to use DataDirect JDBC drivers, see Chapter 65, "Creating Portlets with OmniPortlet."

E.1.3 Configuring Portal Tools and Web Producers (Optional)

To ensure that the OmniPortlet and Web Clipping producers, locally built, and custom built Web producers work properly in the middle-tier environment, some additional configuration may be needed. If OmniPortlet or any other Web producers have customizations in the file system, then PDK-Java provides a Preference Store Migration/Upgrade Utility that you can use to migrate the existing customizations to the database and upgrade customizations from earlier releases. See Section E.5, "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 Database Preference Store. It can work in a multiple middle-tier environment without additional configuration.

You can find more information about configuring the database Preference Store in Section E.5, "Portlet Preference Store Migration Utilities."

  1. If you have 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:

    1. Navigate to the WebCenter Portal Oracle home directory using the following command:

      cd WC_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 E.5, "Portlet Preference Store Migration Utilities" for more information about the PDK Preference Store Migration Utility.

  2. Typically, you perform the HTTP Proxy configuration for OmniPortlet and Web Clipping before you configure the Load Balancing Router (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. You must first 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 E.1.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 OmniPortlet_WAR_DIR/WEB-INF/providers/omniPortlet/provider.xml from M1 to M2.

      • Copy WebClipping_WAR_DIR/WEB-INF/providers/webClipping/provider.xml from M1 to M2.

  3. Restart middle tier M2.

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

  5. 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:

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

E.2 Web Clipping Portlet Configuration Tips

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

E.2.1 Web Clipping Repository Configuration

Web clippings have definitions that must be stored persistently in an Oracle Metadata Services (MDS) store or an Oracle database.

Note:

You cannot use a Microsoft SQL Server or IBM DB2 database as the Web Clipping repository.

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

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

Where, host is the server to which your Web Clipping producer has been deployed and port is the port to which the server is listening for HTTP requests.

Note:

Integrated WLS and the WLS_Portlet managed server are deployed to different ports even if they may be available on the same system. By default, Integrated WLS is deployed to port 7101 and WLS_Portlet is deployed to port 8889.

The Provider Test Page automatically detects whether 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 E-1 shows the Provider Test Page of Web Clipping.

Figure E-1 Web Clipping - Provider Test Page

Description of Figure E-1 follows
Description of "Figure E-1 Web Clipping - Provider Test Page"

You cannot change the Web Clipping configuration information by using the Provider Test Page. You can configure the Web Clipping repository by setting appropriate values in the provider.xml file. In this file, you use the repositoryInfo tag to specify the Web Clipping repository settings.

Note:

To determine the path of provider.xml, search for webClipping/provider.xml in the file system. For example, run the following command in UNIX:

> find DOMAIN_DIR -name "provider.xml" | grep -i webClipping

In Oracle JDeveloper's Integrated WLS, Web Clipping's provider.xml is located here:

JDEV_SYSTEM_DIRECTORY/DefaultDomain/servers/DefaultServer/tmp/_WL_user/portalTools_11.1.1.2.0/RANDOMLY_GENERATED_DIRECTORY/war/WEB-INF/providers/webClipping/provider.xml

Note that, on a Windows platform, pages in Framework applications are not rendered if there is a space in the path to the system directory in JDeveloper. Therefore, ensure that the JDEV_SYSTEM_DIRECTORY path does not contain spaces.

In the Fusion Middleware 11g installation, Web Clipping's provider.xml is located here:

FMW_HOME/user_projects/domains/wc_domain/servers/WLS_Portlet/tmp/_WL_user/portalTools_11.1.1.2.0/RANDOMLY_GENERATED_DIRECTORY/war/WEB-INF/providers/webClipping/provider.xml

This section includes the following subsections:

E.2.1.1 Using Oracle Metadata Services (MDS) as the Web Clipping Repository

By default, in Oracle JDeveloper, the Web Clipping producer hosted on Integrated WLS, the default server, is configured to use MDS, which is file-based, as the Web Clipping repository.

Note:

In a full Oracle Fusion Middleware installation, the Web Clipping portlet producer is also included within the WLS_Portlets managed server in the default domain. By default, this Web Clipping portlet producer is configured to use the Oracle database, which is installed as part of Oracle WebLogic Server, as the Web Clipping repository.

Example E-1 shows MDS as the default repository in provider.xml.

Example E-1 MDS as the Default Web Clipping Repository in provider.xml

<repositoryInfo class="oracle.portal.wcs.provider.info.MdsInformation">
    <mdsConfigLocation>mds-config.xml</mdsConfigLocation> 
  </repositoryInfo>

For an MDS repository, the repositoryInfo tag is set to the MdsInformation class. The mdsConfigLocation entry specifies the path to the mds-config.xml file, which contains the metadata store configuration information, including the path to the actual metadata store. In Oracle JDeveloper, the mds-config.xml file is located at the following path:

JDEV_SYSTEM_DIRECTORY/DefaultDomain/servers/DefaultServer/tmp/_WL_user/portalTools_11.1.1.2.0/RANDOMLY_GENERATED_DIRECTORY/war/WEB-INF

Note:

On a Windows platform, pages in Framework applications are not rendered if there is a space in the path to the system directory in JDeveloper. Therefore, ensure that the JDEV_SYSTEM_DIRECTORY path does not contain spaces.

The mds-config.xml file specifies the location of the repository in a property tag:

<property name="metadata-path" value="portletdata/tools/webClipping"/>

The location specified for value is relative to JDEV_HOME/portal. Any relative path specified is interpreted to be relative to JDEV_HOME/portal. To use another location, for example, a location outside the Oracle JDeveloper home, then specify an absolute path, such as c:\mds.

Note:

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

E.2.1.2 Using an Oracle Database as the Web Clipping Repository

Although MDS is the default repository in Oracle JDeveloper, you can alternatively select to use a database schema for your Web Clipping repository.

Note:

If you use a database as your Web Clipping repository, any customizations are retained even if the Web Clipping producer or the consuming application is redeployed.

You can use either of the following database schemas for Web Clipping:

  • The default PORTLET database schema created by RCU for Oracle WebLogic Server

  • A user-defined database schema for Oracle 9i or later

Note:

You cannot use a Microsoft SQL Server or IBM DB2 database as the Web Clipping repository.

This section includes the following subsections:

E.2.1.2.1 Using the Database Schema Created by RCU

For Web Clipping repository, you can use the Oracle database installed as part of Oracle WebLogic Server, through a JNDI data source named jdbc/portletPrefs. To access the database, the schema named PORTLET is used.

Note:

The PORTLET schema must be created in the Oracle database configured for WebCenter Portal. For more information, see the "Installing WebCenter Portal" chapter in the Oracle Fusion Middleware Installation Guide for Oracle WebCenter Portal.

E.2.1.2.2 Creating a Database Schema

You can use any user-defined schema for an Oracle 9i or later database as the Web Clipping repository. To create a database schema for Web Clipping definitions and clippings, run the Java command described in Example E-2.

Example E-2 Java Command for Creating a Schema for Web Clipping Portlet Definitions and Clippings

java -classpath WC_ORACLE_HOME/lib/xmlparserv2.jar:
WC_ORACLE_HOME/jdbc/lib/ojdbc14.jar:WC_ORACLE_HOME/portal/jlib/wce.jar
oracle.portal.wcs.Installer -installSchema -username dbuser -password
dbpassword -dburl jdbc:oracle:thin:@//host:port/dbid

Where:

  • WC_ORACLE_HOME is the path to your WebCenter Portal Oracle home directory

  • dbuser is the database user for the schema

    Consider using the same database user you use to create the WSRP and PDK-Java preference store database schema. If you do not use the same user, then you must create a new user and grant it connect and resource privileges.

  • dbpassword is the specified user's password

  • dburl is the URL for the database

    This is the database that contains the schema that you create for Web Clipping portlet definitions and clippings by using the following syntax:

    jdbc:oracle:thin:@//dbhost:dbport/service_name
    

    For example:

    jdbc:oracle:thin:@//shobeen:1521/sales_us
    

Note:

The classpath in Example E-2 uses different separators for UNIX and Windows. On UNIX systems, the classpath uses a colon (:) separator. On Windows systems, the classpath uses a semicolon (;) separator.

E.2.1.3 Configuring Web Clipping Repository in provider.xml

To change the repository configuration for the Web Clipping producer deployed to Integrated WLS:

  1. Open the provider.xml file in a text editor.

  2. Specify the setting for your Web Clipping repository:

    • Use the PORTLET schema referred by the JNDI data source created by RCU. Specify the entries shown in Example E-3.

      Example E-3 Oracle Database as the Web Clipping Repository

      <repositoryInfo class="oracle.portal.wcs.provider.info.JdbcDbInformation">
           <connectionName>jdbc/portletPrefs</connectionName>
           <useRAA>false</useRAA>
           <useASO>false</useASO>
        </repositoryInfo>
      

      For information about tag parameters, see Section E.2.1.4, "Attributes and Child Tags of the repositoryInfo Tag."

    • Use the database schema, created for an Oracle database 9i or later, where you can manually specify connection information.

      To specify Oracle 9i or later database as the Web Clipping repository, specify database connection parameters in the entry shown in Example E-4.

      Example E-4 Setting Oracle Database 9i or Later as Web Clipping Repository

      <repositoryInfo class="oracle.portal.wcs.provider.info.DatabaseInformation">
             <useRAA>false</useRAA>
             <databaseHost>dbhost.mycompany.com</databaseHost>
             <databasePort>1521</databasePort>
             <databaseSid>iasdb</databaseSid>
             <databaseUsername>scott</databaseUsername>
             <databasePassword>!tiger</databasePassword>
             <useASO>false</useASO>
          </repositoryInfo>
       
      

      For information about tag parameters, see Section E.2.1.4, "Attributes and Child Tags of the repositoryInfo Tag."

      If you require a secure database connection, then enable the Advanced Security Option (ASO) by setting the useASO entry to true. For more information about configuring ASO, see Section E.2.3, "Web Clipping Producer Security."

      Note:

      Only one entry of <repositoryInfo> can exist in provider.xml. Depending on the Web Clipping repository you choose, you must uncomment only that entry.

  3. Save the provider.xml file.

  4. Restart Integrated WLS.

E.2.1.4 Attributes and Child Tags of the repositoryInfo Tag

Table E-6 lists and describes the attributes and child tags of the repositoryInfo tag.

Note:

The attributes and child tags of the repositoryInfo tag are also described in the comments in the Web Clipping provider.xml file.

In the comments in the provider.xml file, the example provided for Oracle9i Database or later using Oracle infrastructure database is specific to Oracle Portal and its infrastructure database and application programming interfaces. That example must not be used for Framework application implementations.

Table E-6 Attributes and Child Tags of the repositoryInfo Tag

Attributes/Parameter MDS/Database Description

class

Both

The class attribute specifies the type of repository used to store Web Clipping definitions. The possible values for this attribute are:

  • oracle.portal.wcs.provider.info.MdsInformation

    This value signifies that MDS is used to store Web Clipping definitions and that MDS configuration is pushed to the mds-config.xml file.

  • oracle.portal.wcs.provider.info.DatabaseInformation

    This value signifies that an Oracle9i Database or later is used to store Web Clipping definitions and that the database connection details are included as children in the repositoryInfo tag.

  • oracle.portal.wcs.provider.info.JdbcDbInformation

    This value signifies that Oracle database installed as part of Oracle WebLogic Server is used to store Web Clipping definitions.

mdsConfigLocation

MDS

Use the mdsConfigLocation tag when the value for the class attribute indicates an MDS repository. It points to the MDS configuration file mds-config.xml, which specifies the actual MDS location. The mds-config.xml file is located at:

MW_HOME/wlserver_10.3/wc_domain/servers/WLS_Portlet/tmp/_WL_user/portalTools_11.1.1.2.0/yyggl7/war/WEB-INF

connectionName

Database

Specifies the JNDI name of the data source where the Web Clipping repository has been installed using the RCU. By default, the connection name is jdbc/portletPrefs, which points to the PORTLET schema in Oracle WebLogic Server.

In an interoperability scenario where an Oracle WebLogic Server 11g Middle Tier is paired with an Oracle Application Server 10g repository, the connection points to the PORTAL schema in the Oracle Application Server 10g repository.

useASO

Database

Set to true or false:

  • Specify true to use Oracle Advanced Security Option (ASO) to encrypt the communication channel between the Web Clipping producer and the database. This is provided for introducing added security if case-sensitive data is contained in the clipped content.

  • Specify false to omit this option.

useRAA

Database

Set to true or false:

  • Specify true if Repository Access APIs are used to access the database connection parameters. Specifying true is equivalent to making the Web Clipping producer use the default Oracle infrastructure database as the repository.

    Specifying true removes the need for other repositoryInfo child tags.

  • Specify false to omit this option.

databaseHost

Database

Specify the host name of the Oracle database. Use only version 9i or later. For example:

mycompany.dbhost.com

databasePort

Database

Specify the port number of the Oracle database listener. This is usually 1521.

databaseSid

Database

Specify the Oracle SID of the database that hosts the Web Clipping repository.

databaseUsername

Database

Enter the user name used to log in to the database.

databasePassword

Database

Enter a plain text password for the specified database user name. Prefix the password with an exclamation point (!) to allow the Web Clipping producer to encrypt the password when the producer starts.

For example:

!AX3tR

E.2.2 HTTP or HTTPS Proxy Configuration

Your HTTP or HTTPS proxy settings must be set to allow 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.

Framework application administrators can set proxy settings manually according to the HTTP or HTTPS configuration. Edit the appropriate entries in the provider.xml file.

Example E-5 shows the relevant portion of provider.xml.

Example E-5 Proxy Settings

- <!-- 
 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>proxy.mycompany.com</httpProxyHost>
      <httpProxyPort>80</httpProxyPort>
      <dontProxyFor>*.mycompany.com</dontProxyFor>
      <proxyUseAuth>true</proxyUseAuth>
      <proxyType>Basic</proxyType>
      <proxyRealm>realm1</proxyRealm>
      <proxyUseGlobal>false</proxyUseGlobal>
      <proxyUser>scott</proxyUser>
      <proxyPassword>!tiger</proxyPassword>
   </proxyInfo>
   
  --> 

It is optional to specify values for the following tags: <proxyUseAuth>, <proxyType>, <proxyRealm>, <proxyUseGlobal>, <proxyUser>, and <proxyPassword>.

Table E-3, available earlier in this appendix, describes the proxy settings you specify 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 a listed domain, from the Web Clipping Studio, receive an HTTP timeout error.

E.2.3 Web Clipping Producer Security

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 must implement to enable the Web Clipping producer to access Secure Sockets Layer (SSL)-enabled web sites and encrypt the channel between itself and the database:

E.2.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. To keep track of trusted sites, the Web Clipping producer uses the cacerts file, which is the Java keystore to store trusted certificates.

By default, the cacerts file stores various certificates including the Equifax, VeriSign, and Cybertrust certificates. However, it does not include 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 SSL handshake failed exception in the Web Clipping Studio. To solve this problem, you must add the certificate of that site to the cacerts file.

To add a certificate to the cacerts file:

  1. Download the certificate of the HTTPS web site and save the certificate in the PEM format.

    Tip:

    Mozilla Firefox 3.0 or later enable you to save a certificate file in the PEM format.

  2. Locate the path to the cacerts file:

    1. Log in to the Oracle WebLogic Server Administration Console by using the following URL format:

      http://host:port/console

    2. Open the Keystore tab for the WLS_Portlets managed server.

    3. Note down the location of the cacerts file given in the Java Standard Trust Keystore field.

      Figure E-2 Locating the cacerts file

      Description of Figure E-2 follows
      Description of "Figure E-2 Locating the cacerts file"

  3. At the command prompt, navigate to the location of the cacerts file and run the following command to add the certificate:

    keytool -importcert -alias certi_alias -file certifi_name -keystore cacerts -storepass password

    Where, certi_alias refers to the alias used for the certificate, certifi_name refers to the certificate file name, and password refers to the password of the cacerts file. The default password is changeit.

    For example,

    keytool -importcert -alias stamf05 -file stamf05.crt -keystore cacerts -storepass changeit

    Tip:

    It is advisable to import trusted certificate into the cacerts file by using an alias. It makes it easier for you to delete or list the entries in the keystore.

E.2.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 in Oracle JDeveloper.

To enable ASO:

  1. Open provider.xml in a text editor.

  2. Under the repository settings section in the file (shown in Example E-3), 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.

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

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

    For more information about setting parameters and about the values to use for various possible combinations of parameters, see the Oracle Database Advanced Security Administrator's Guide.

    Note:

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

E.3 Hiding or Removing the WSRP Test Page

If you do not want all users to be able to see the WSRP test page, you can protect it so that only administrators can see it. To do this, add the code shown in Example E-6 to the web.xml file.

Example E-6 Hiding the WSRP Test Page

<security-role>
  <description>AdministratorRole</description>
  <role-name>Admin</role-name>
</security-role>
<security-constraint>
  <display-name>TestPageInfo</display-name>
  <web-resource-collection>
    <web-resource-name>TestPageInfo</web-resource-name>
    <description>Protect the test page servlet.</description>
    <url-pattern>/info/*</url-pattern>
  </web-resource-collection>
  <auth-constraint>
    <description>Administrators</description>
    <role-name>Admin</role-name>
  </auth-constraint>
  <user-data-constraint>
    <transport-guarantee>NONE</transport-guarantee>
  </user-data-constraint>
</security-constraint>

If you want to remove the WSRP test page completely, you must modify the web.xml file to comment out the element shown in Example E-7.

Note:

This element is injected into web.xml at packaging time, so you must edit the web.ml file in the resulting EAR file.

Example E-7 Removing the WSRP Test Page

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

E.4 Setting Up a Preference Store

The portlet preference store is used for persisting consumer registration handles and portlet preference data. Portlet producers can use one of three types of preference store: File, Database and Consumer.

Using a consumer preference store ensures that the preference store data is always stored with the consumer application. Whatever happens to the producer over time, the consumer application's registrations and portlets continue to be valid while the producer connections point to functionally compatible producers (that is, the producer should be able to decode the portlet name from the portlet handle and be able to resolve this to the portlet that the consumer application developer expects). When this mechanism is used, the producer itself stores no persistent state whatsoever, meaning that a producer can be switched for another compatible one at any time, with no requirement to perform a preference store migration or export/import cycle.

In a clustered environment, Oracle recommends the use of a database or consumer preference store. If you prefer to use a file-based preference store, then you must also use a shared file system.

If you configure the WebLogic Server to run Portlet Producer applications, then the database preference store is configured for you. For more information, see the Oracle Fusion Middleware Installation Guide for Oracle WebCenter Portal.

This section contains configuration information for the following areas:

E.4.1 WSRP Producers

WSRP producers have a JNDI preference value that determines which preference store is used, and is set in the web.xml file of the Portlet Producer application. Table E-7 lists and describes the JNDI variables used to specify the preference store for WSRP producers.

Table E-7 WSRP Producer Database Preference Store-Related JNDI Variable

Variable Name Variable Value Description

oracle/portal/wsrp/server/persistentStore

Database

File

Consumer

Determines which data store (File, Database, or Consumer) is used for persisting a Portlet Producer application's consumer registration handles and portlet preferences.

oracle/portal/wsrp/server/fileStoreRoot

portletdata

Defines the path to the root directory to be used by the file preference store. Absolute paths are interpreted relative to the file system root. Relative paths are interpreted relative to the WC_ORACLE_HOME/portal directory.

Note that all producers running within the same WebLogic Server must use the same path for this variable. Otherwise, you get a Portlet unavailable error for some portlets.


The following examples show the entries in a producer's web.xml file.

Example E-8 Configuring web.xml to Use a Database Preference Store

<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>Database</env-entry-value>
</env-entry>

Example E-9 Configuring web.xml to Use a File-Based Preference Store

<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>myPrefStore</env-entry-value>
</env-entry>

Example E-10 Configuring web.xml to Use a Consumer Preference Store

<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>Consumer</env-entry-value>
</env-entry>

When you have updated the relevant web.xml files, restart your WebLogic Server.

E.4.2 PDK-Java Producers

The type of preference store used for PDK-Java producers is determined by the preferenceStore tag in the provider.xml file. Table E-8 lists and describes the attributes and parameters used with the preferenceStore tag when a database preference store is specified.

Table E-8 Attributes and Parameters of the preferenceStore Tag

Attribute/Parameter Description

class

This required attribute specifies the Java class that defines the location and other details of portlet preferences. For example, a file-based preference store might use:

<preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">

A database preference store might use:

<preferenceStore class="oracle.portal.provider.v2.preference.DBPreferenceStore">

OmniPortlet uses its own class, for example:

<preferenceStore class="oracle.webdb.reformlet.ReformletFilePreferenceStore">

name

This required parameter provides a name for the preference store. Use any value you choose. For example:

<preferenceStore class="oracle.portal.provider.v2.preference.DBPreferenceStore">
  <name>MyPDKProducerPreferenceStore</name>
</preferenceStore>

connection

This required parameter for a database preference store points to a JNDI connection that connects with a schema containing the portlet preference store. For example:

<preferenceStore class="oracle.portal.provider.v2.preference.FCFDBPreferenceStore">
  <name>MyPDKProducerPreferenceStore</name>
  <connection>java:comp/env/jdbc/portletPrefs</connection>
</preferenceStore>

rootDirectory

This optional parameter specifies the location where the file-based preference store preferences are stored.When this parameter is not included with the preferenceStore tag, the default file-based preference store location is used. This is the same folder where the producer's provider definition file is stored.

useHashing

This optional parameter is used when specifying a file based preference store, and accepts the value true or false. When it is set to true, each preference data file is stored in an extra subdirectory with a name determined by hashing the data file name. Using this parameter can improve file system performance by limiting the number of preference data files stored in a single directory.

For example:

<preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
  <name>PDKProducerPreferenceStore</name>
  <useHashing>true</useHashing>
</preferenceStore>

E.5 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, a file system, or with the consuming application. You can migrate the following stores for your Framework applications:

E.5.1 JPS Portlet Preference Store - PersistenceMigrationTool

A WSRP container preference store is a mechanism used for persisting consumer registration and portlet preference data. Currently, there are three preference store implementations, database preference store, file-based preference store, and consumer preference store. A database preference store persists data using a relational database. A file-based preference store persists data using the file system. A consumer preference store ties the producer metadata to the consumer application. A file-based or consumer preference store may be used for testing, since it removes the dependency on a database. But, for highly available configurations, Oracle recommends that you use a database or consumer preference store.

The WSRP container preference store migration utility, PersistenceMigrationTool, enables you to migrate existing data between database and file-based 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, enabling data to be moved from one database store to another.

Note:

You cannot use the preference store migration utility to migrate to or from a consumer preference store. To migrate to or from a consumer preference store, you must export the data from one producer from the consumer and import into another.

  1. Export the producer metadata from your consumer application to an EAR file, using JDeveloper or WLST. This contacts the remote producer to get customization data, and so on.

  2. Either remap the producer connection to another producer, which can be using any preference store type, or change the preference store configuration of the current producer, and restart it.

  3. Import from the exported EAR file back to your consumer application. This pushes the relevant metadata back to the producers, which then store it in their configured preference store.

For information about exporting and importing producers using JDeveloper, see Section E.6, "Exporting and Importing Portlet Producers at Design Time." For information about exporting and importing producers using WLST, see the section "Exporting and Importing Custom WebCenter Applications for Data Migration" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

The syntax of the PersistenceMigrationTool is:

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.

Note:

There are several libraries that must be referenced in the classpath when running the PersistenceMigrationTool utility:

  • wcs-producer-spi.jar

  • portlet-utils.jar

  • portlet-producer-container-common.jar

  • portlet-producer-container-persistence.jar

  • oracle-portlet-api.jar

  • wsrp-container.jar

  • oracle-portlet-tags.jar

  • ojdbc6.jar

The ojdbc6.jar library referenced in the classpath must be the same as the one used by your database.

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

Example E-11 Running the PersistenceMigrationTool Utility

./java  -classpath
ORACLE_COMMON_HOME/webcenter/modules/com.bea.wsrp_10.3.2.0/system/wcs-producer-spi.jar:
ORACLE_COMMON_HOME/webcenter/modules/oracle.portlet.server_11.1.1/portlet-utils.jar:
ORACLE_COMMON_HOME/webcenter/modules/oracle.webcenter.framework_11.1.1/portlet-producer-container-common.jar:
ORACLE_COMMON_HOME/webcenter/modules/oracle.webcenter.framework_11.1.1/portlet-producer-container-persistence.jar:
WC_ORACLE_HOME/webcenter/modules/oracle.portlet.server_11.1.1/oracle-portlet-api.jar:
WC_ORACLE_HOME/webcenter/modules/oracle.portlet.server_11.1.1/wsrp-container.jar:
WC_ORACLE_HOME/webcenter/modules/oracle.portlet.server_11.1.1/oracle-portlet-tags.jar:
DB_ORACLE_HOME/jdbc/lib/ojdbc6.jar
oracle.portlet.server.containerimpl.PersistenceMigrationTool
-sourceType db \
-sourceUsername scott \
-sourcePassword tiger \
-sourceDatabase abc.mycompany.com:1521:yourdatabase \
-destType file \
-destRoot /data/prefs

where:

  • ORACLE_COMMON_HOME is your Oracle Common home

  • WC_ORACLE_HOME is your WebCenter Portal Oracle home

  • DB_ORACLE_HOME is your database Oracle home if it is on the same machine as the WebCenter Portal Oracle home. If the database Oracle home is on a separate machine, then you must copy the DB_ORACLE_HOME/jdbc/lib directory into a temporary directory on the WebCenter Portal Oracle home and reference the ojdbc6.jar library from this temporary directory in the classpath.

E.5.2 PDK-Java Portlet Preference Store - Migration and Upgrade Utilities

PDK-Java has two PreferenceStore implementations, DBPreferenceStore and FilePreferenceStore. DBPreferenceStore persists data using a JDBC-compatible relational database and FilePreferenceStore persists data using the file system.

If you have installed Oracle 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 WC_ORACLE_HOME. The syntax of the migration utility is:

Note:

You must set the classpath when running this tool to include pdkjava.jar, ptlshare.jar, and ojdbc6.jar. For example:

java -classpath WC_ORACLE_HOME\jdeveloper\modules\oracle.dms_11.1.1\dms.jar;
WC_ORACLE_HOME\wlserver_10.3\server\lib\ojdbc6.jar;WC_ORACLE_HOME\jdeveloper\webcenter\modules\oracle.portlet.server_11.1.1\pdkjava.jar;
WC_ORACLE_HOME\jdeveloper\webcenter\modules\oracle.portlet.server_11.1.1\ptlshare.jar
oracle.portal.provider.v2.preference.MigrationTool
java oracle.portal.provider.v2.preference.MigrationTool
  -mode [file | db | filetodb | filetofile | dbtofile | dbtodb]
  [-remap language | locale]
  [-countries iso_country_code]
  [-pref1UseHashing true | false]
  [-pref1Driver driver]
  {-pref1RootDirectory directory |
   -pref1User username -pref1Password password -pref1URL url}
  [-pref2UseHashing true | false]
  [-pref2Driver driver]
  {-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

    filetodb, filetofile, dbtofile, or dbtodb indicates to run in migration mode. See Section E.5.2.1, "Migration Mode" for more information about this mode.

    file or db indicates to run in upgrade mode. See Section E.5.2.2, "Upgrade Mode" for more information about this mode.

  • -remap is the localePersonalizationLevel (language or locale). Note that you only must use this option to change localePersonalizationLevel as part of your upgrade or 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 specifies whether you want to employ hashing on the source for this operation.

  • -pref1Driver is the driver for the source database. If you do not specify this parameter, the nearest matched driver is used.

  • -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 specifies whether you want to employ hashing on the destination for this operation.

  • -pref2Driver is the driver for the destination database. If you do not specify this parameter, the nearest matched driver is used.

  • -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.

This section includes the following subsections:

E.5.2.1 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 E-9 describes the migration modes in which you can run the utility.

Table E-9 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, you must ensure that the destination WebLogic Server is created using the WebCenter Portal portlet template and the appropriate schemas have been created using the RCU. For more information, see Oracle Fusion Middleware Installation Guide for Oracle WebCenter Portal.

When using a migration mode, you can also use the -remap and -countries options to specify that the data must be upgraded while being migrated. Specifically, you use these options to ensure that the locale-specific preferences are appropriately remapped.

You can use the other options accepted by the utility 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.

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 sets the useHashing and rootDirectory properties of a source FilePreferenceStore.

When a migration basic mode 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 sets the database connection details on a target DBPreferenceStore.

Example E-12 PDK-Java Migration Utility Command Line, Migration

java -classpath WC_ORACLE_HOME/webcenter/modules/oracle.portlet.server_11.1.1/pdkjava.jar:
WC_ORACLE_HOME/webcenter/modules/oracle.portlet.server_11.1.1/ptlshare.jar:WC_ORACLE_HOME/ucm/shared/classes/ojdbc14.jar \
oracle.portal.provider.v2.preference.MigrationTool \
-mode dbtofile \
-pref1User portlet_prefs \
-pref1Password portlet_prefs \
-pref1URL jdbc:oracle:thin:@myserver.mydomain.com:1521:mysid \
-pref2RootDirectory /mydirectory/preferences

E.5.2.2 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 Oracle Portal and a given localePersonalizationLevel setting.

Table E-10 describes the upgrade modes in which you can run the utility.

Table E-10 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 Oracle 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 Oracle Portal 9.0.2.0.0 or earlier and want to use existing portlets with a localePersonalizationLevel setting of locale (Oracle 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 remaps the British English preference to become the English-wide preference (en).

Example E-13 PDK-Java Migration Utility Command Line, Upgrade

java -classpath WC_ORACLE_HOME/webcenter/modules/oracle.portlet.server_11.1.1/pdkjava.jar:
WC_ORACLE_HOME/webcenter/modules/oracle.portlet.server_11.1.1/ptlshare.jar:WC_ORACLE_HOME/ucm/shared/classes/ojdbc14.jar \
  oracle.portal.provider.v2.preference.MigrationTool \
 -mode file -remap language
 -countries GB,US -pref1UseHashing true 
 -pref1RootDirectory j2ee/home/applications/jpdk/jpdk/WEB-INF/providers/sample

E.5.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 MDS, which is file-based, for this purpose. But you can configure Web Clipping to use a database. To migrate this repository for Framework 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 Framework applications that use the Web Clipping producer. For more information, see Section 61.2.10, "How to Implement Export of Customizations (WSRP 2.0)."

  2. Update the producer to use a different repository. For information, see Section E.2.1.3, "Configuring Web Clipping Repository in provider.xml."

  3. Run the Predeployment tool in import mode on all Framework applications that use the Web Clipping producer. For more information, see Section 61.2.10, "How to Implement Export of Customizations (WSRP 2.0)."

E.5.4 Moving a Producer

In some situations, you may want to move a portlet producer. To do so, you must:

  1. Install the new producer.

  2. Make the preference store of the original producer available to the new producer by performing one of the following tasks:

    • Migrate the preference store using the Preference Store Migration and Upgrade Utilities (see Section E.5.2, "PDK-Java Portlet Preference Store - Migration and Upgrade Utilities" for more information), or

    • Configure the new producer to use the same preference store as the original producer. If the database preference store is being used, then you must point the WebLogic Server data source to the same database as the original producer.

  3. Update the URL of the producer registration by using Enterprise Manager Fusion Middleware Control or the WLST commands: setWSRPProducerRegistration or setPDKJavaProducerRegistration.

E.6 Exporting and Importing Portlet Producers at Design Time

You can export and import portlet producers at design time.

This section includes the following subsections:

E.6.1 Exporting Portlet Producers at Design Time

When you package an application for deployment, any portlet producers referenced by the application are contacted so that the producer data can be included in the MAR file. If any of the producers are not running, they cannot be contacted and the data cannot be included.

By creating an export archive of the producer data at design time instead, you can ensure that the producers are running, therefore all the producer data, including remote customizations and client-side metadata, can be retrieved. WebCenter Portal: Framework can then use the export archive at deployment, instead of having to contact the remote producers.

To export portlet producers at design time:

  1. Edit the WC_ORACLE_HOME/jdeveloper/jdev/bin/jdev.conf file and set the following JVM flag:

    AddVMOption  -Doracle.webcenter.portlet.dt.disableRemoteExport=true
    

    Setting this flag ensures that, when the application is packaged for deployment, the export archive you create in the following steps is included in the MAR file, rather than the remote producers being contacted to retrieve producer data.

  2. Restart JDeveloper to apply the new setting.

  3. Open the application that consumes the producers to export.

  4. From the menu, choose Application and then Export Portlet Producers.

    This menu option appears only if the current application contains producers.

  5. In the Export Portlet Producers dialog, in the Export Archive File Name (.ear) field, enter the absolute path and file name to use for the export set.

  6. Click OK.

    When the application is packaged for deployment, because you set the disableRemoteExport flag to true, WebCenter Portal: Framework checks for the presence of the export archive at the location specified in the dialog. If the export archive exists, the contents of the archive are included in the MAR file instead of contacting the remote producers to retrieve producer data.

    Note:

    If the disableRemoteExport flag is set and there is no export archive, a default export archive, without the remote producer data, is created and included in the MAR file.

E.6.2 Importing Portlet Producers at Design Time

You can import producer data, including customizations made at runtime, from a deployed application into your application at design time.

Note:

The producers in the export archive (EAR file) must be the same as those in the application into which they are being imported.

For information about how to create an export archive of producer metadata from a deployed application, see the section "Exporting Portlet Client Metadata (WebCenter Portal: Framework Application)" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

To import portlet producers at design time:

  1. Edit the WC_ORACLE_HOME/jdeveloper/jdev/bin/jdev.conf file and set the following JVM flag:

    AddVMOption  -Doracle.webcenter.portlet.dt.enableImport=true
    
  2. Restart JDeveloper to apply the new setting. This ensures that the Import Portlet Producers menu option is available.

  3. Open the application into which you want to import the producers.

  4. From the menu, choose Application and then Import Portlet Producers.

  5. In the Import Portlet Producers dialog, in the Import Archive File Name (.ear) field, enter the absolute path and file name of the export archive to import.

  6. Click OK.

Note:

If the application into which you import producers is currently running in Integrated WLS, you must re-run the application to see the updated producers. Simply refreshing the page may result in errors caused by the different MDS instances used at design time and runtime.

E.7 Migrating WebLogic Portal Portlets to WebCenter Portal

This section discusses migrating WebLogic Portal portlets developed with the WebLogic Portal's Eclipse IDE to WebCenter Portal's JDeveloper environment.

Note:

There is no direct support or tooling available for migrating WLP portlets to a WebCenter Portal project. In many cases, significant refactoring and recoding is required. This section highlights some of the migration issues and offers recommendations as appropriate.

E.7.1 Migrating Java Portlets from WebLogic Portal to WebCenter Portal

In general, JSR 286 standard portlets (Java portlets) that were developed in WebLogic Portal can be moved directly to a WebCenter Portal/JDeveloper environment. Simply copy all of the portlet artifacts (portlet.xml, .java files, .jsp files, and so on) into a JDeveloper Portlet Producer application project.

Note:

Any WebLogic Portal specific APIs used by the portlet must be rewritten to use WebCenter Portal APIs. WebLogic Portal specific APIs will not work in a WebCenter environment.

Tip:

You can use the WebLogic Portal Export feature to export your Java portlets to an archive file and then import the archive file into your JDeveloper project. This technique may be simpler than manually copying all the portlet artifacts from one environment to another. See "Exporting Java Portlets for Use on Other Systems" in the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.

E.7.2 Problems With Migrating WLP Portlets to a WebCenter Portal Application

Moving portlets from a WLP development environment to a WebCenter Portal development environment is not directly supported. In general, this process can involve substantial rewriting or refactoring of the migrated portlet code and related files.

Note:

If a portlet (regardless of type) was capable of running over WSRP in WebLogic Portal, the portlet can be consumed directly from the WebLogic Portal's portlet producer in a WebCenter Portal consumer. See "WSRP Interoperability with WebCenter Framework" in the Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal.

Problems inherent in moving WebLogic Portal portlets directly to a WebCenter Portal project in JDeveloper can include the following:

  • URL Generation – Some URL types supported by WebLogic Portal do not work in WebCenter Portal, including DesktopURL, CustomEventURL, PageURL, WindowURL, StandalonePortletURL, and possibly others.

  • Events – The WebCenter Portal consumer does not generate all of the events that the WebLogic Portal framework generates. These unsupported events include Init, LookAndFeelReinit, Notification, Refresh, WindowActivation, WindowDeactivation, and possibly others.

  • Render Dependencies – WLP render dependencies do not work in WebCenter.

  • WLP Framework APIs – Many WLP APIs are not supported in WebCenter Portal.

E.7.3 General Tips for Migrating WLP Portlets to a WebCenter Portal Portlet Producer Application

This section provides general guidance on moving WLP portlets into WebCenter Portal's portlet producer environment. Although portlet migration is not directly supported, this section lists tips that might help you with the manual migration process of the various WLP portlet types.

Caution:

This section provides general guidance only. As discussed in Section E.7, "Migrating WebLogic Portal Portlets to WebCenter Portal," direct migration of WLP portlet types to WebCenter Portal application or portlet producer application is not directly supported. In almost all cases, rewriting and refactoring of existing portlet code is required when moving portlets from WLP to WebCenter Portal.

As noted previously, any WebLogic Portal specific APIs used by the portlet must be rewritten to use WebCenter Portal APIs. WebLogic Portal specific APIs will not work in a WebCenter environment.

  • JSP portlets – Moving JSP portlets directly into a WebCenter Portal project is not supported. You can consider refactoring the JSP portlet into a JSR286 portlet and then migrate it as explained in Section E.7.1, "Migrating Java Portlets from WebLogic Portal to WebCenter Portal."

  • JSR 168/286 portlets – Most Java (JSR 168 / 286) portlets can be directly imported to a WebCenter Portal portlet producer and run as JSR286 portlets. Some JSR168 portlets that take advantage of specific error conditions guaranteed by the JSR168 specification may need to be run in a JSR168 compatibility mode. See "JSR-286/JSR-168 Portlet Compatibility" in the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal. JSR168 portlets using WLP's proprietary eventing (event subscriptions declared in a .portlet file) must be re-written to use JSR286 events.

  • Java Page Flow portlets – JPF portlets are not supported by WebCenter Portal's portlet producer and must be either consumed from a WebLogic Portal WSRP producer or refactored to become JSR286 or JSF portlets.

  • JSF portlets – If the portlet is written to the JSR329 JSF Portlet bridge in WLP, it should run on a WebCenter producer with no changes. For portlets using the WLP "native" JSF portlet bridge, the portlet must be consumed from a WebLogic Portal producer or upgraded to a JSF 1.2 portlet using the JSR329 bridge. See also "Working With JSF-Java Portlets" in the Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal.

  • Clipper portlets – Clipper portlets are not supported in WebCenter portal, but the web clipping features in WebCenter Portal's pagelet producer provide equivalent functionality.

  • Struts portlets – Moving Struts portlets directly into a WebCenter Portal project is not supported. You can consider refactoring the JSP portlet into a JSR286 portlet and then migrate it as explained in Section E.7.1, "Migrating Java Portlets from WebLogic Portal to WebCenter Portal."

  • Content Presenter portlets – WLP Content Presenter portlets will not work over WSRP and will not work with WebCenter. Portal However, equivalent functionality is available in WebCenter Portal's content presenter. See "Publishing Content Using Content Presenter" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces.

  • Remote (WSRP) portlets – Remote (WSRP) portlets consumed in WLP can be consumed in a WebCenter Portal's consumer instead. Remote portlets taking advantage of WLP-specific WSRP features may need modification. For example the custom data transfer feature must be replaced by using events or shared parameters to convey data. See "WSRP Interoperability With WebCenter Framework" and "Configuring WSRP Security Between WLP and WebCenter Framework" in the Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal.