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

Part Number E12434-01
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

12 Deploying Your WebCenter Application

Deployment is the process through which application files are packaged as an archive file and transferred to the target Oracle Application Server. This chapter describes concepts related to WebCenter application deployment and explains the procedures you must perform to package, predeploy, deploy, and undeploy WebCenter applications.

Read the following sections to understand the WebCenter application deployment and learn step-by-step procedures:

12.1 Introduction to WebCenter Application Deployment

This section introduces you to the WebCenter application life cycle and WebCenter application deployment in the production and development environments. It includes the following sections:

12.1.1 Understanding the WebCenter Application Deployment Life Cycle

WebCenter applications differ from traditional J2EE applications in that they support run-time customization of the application's pages and of the portlets contained within these pages. Customizations are stored as follows:

  • WebCenter application customizations are stored in Oracle Metadata Services (MDS) on the file system.

  • Portlet producer customizations (or preferences) are stored in a Preference Store, which can be file-based or located in a database.

WebCenter applications typically consume portlets from various portlet producers and can connect to content repositories, such as Oracle Content Database (Oracle Content DB) and Oracle Application Server Portal (OracleAS Portal). The connection details are stored inside of the WebCenter application .ear file (connections.xml).

Therefore, it is common that when a WebCenter application is deployed on a stage or production server that some, or all, of the details for the external dependencies may have changed. For example, the following items may have changed:

  • Portlet producer end-points

  • Connection details for content repositories

  • Credentials for the connections

  • MDS location

  • Portlet producer preference store locations

  • Policy and identity information

Figure 12-1 describes external dependencies for WebCenter applications.

Figure 12-1 WebCenter Applications and External Dependencies

Description of Figure 12-1 follows
Description of "Figure 12-1 WebCenter Applications and External Dependencies"

To address the additional requirement, the Oracle WebCenter Framework provides the Predeployment tool. This tool can migrate customizations that are associated to a WebCenter application from one location to another and it enables you to reconfigure WebCenter application as well, simplifying the deployment process.

The complexity of the deployment process is largely determined by the following two factors:

  • Number of deployment stages

  • Number of stages during which customizations are enabled

Once portlets have been added to a page using Oracle JDeveloper, you have to decide in which stages of the life cycle customizations are enabled (development, stage, and production). While portlet customizations made within the development environment (for example, in Omniportlet and Webclipping portlets) are persisted, page customizations are not written to MDS. This enables each subsequent execution of the application to start with the initial page design so that developers can iteratively modify their page without a resultant clash occurring from previous customizations. It should be noted that page and portlet customizations made postdevelopment (for example, in stage and production), are persisted in MDS, as shown in Figure 12-2. These postdevelopment customizations are processed separately from the base application.

Figure 12-2 Development, Stage, and Production Environments

Description of Figure 12-2 follows
Description of "Figure 12-2 Development, Stage, and Production Environments"

WebCenter Application Scenarios

The following WebCenter application deployment phases can be distinguished:

  • Initial deployment: The application is deployed in the production system for the first time.

  • Subsequent deployment: A second version of the application is rolled out over a previously deployed version. In this case, it is likely that run-time modifications have occurred since the initial deployment.

  • Parallel deployment: The application is deployed across multiple production servers for use in highly available configuration. This is conceptually the same for each, but treated as a separate case. See Oracle Application Server High Availability Guide for more information about high availability.

The following sections discuss how initial and subsequent deployments are performed in different scenarios:

12.1.1.1 Scenario 1: Portlet Customization in the Development Environment

In this scenario, developers perform page customizations and portlet customizations when running the application using the embedded Oracle Containers for J2EE (OC4J) in Oracle JDeveloper. As page customizations are not persisted in the development environment, only portlet customizations are packaged as part of the generic EAR file. The following sections describe initial and subsequent deployment processes:

Initial Deployment

Figure 12-3 describes the cascade deployment of WebCenter applications.

Figure 12-3 Cascade Deployment of WebCenter Applications

Description of Figure 12-3 follows
Description of "Figure 12-3 Cascade Deployment of WebCenter Applications"

The following steps provide an overview of the initial deployment process:

  1. Create an application using WebCenter Application template, as described in Section 3.1.1, "Creating a WebCenter Application Using a Template".

  2. Run the application in the embedded OC4J and customize the portlets that are contained in the application, as required.

  3. Deploy the application to an EAR file, as described in Section 12.2.1.4, "Creating the Generic EAR File".

  4. Transfer the generic EAR file to the stage platform.

  5. Run the Predeployment tool on the stage platform to unpack the customizations to that server's local file system. Perform the following procedures, if they are applicable to your environment:

  6. Deploy the targeted EAR file created by the Predeployment tool to the OC4J instance (standalone or on Oracle Application Server) on the stage platform, as described in Section 12.2.6.2, "Deploying to Standalone OC4J".

  7. If your application uses encrypted attributes, such as, passwords in the credential store, then use the Credential Mbean to change them, as described in Section 12.5, "Updating Credentials in a Deployed Application".

  8. If the embedded OC4J and the deployment servers are not using the same identity store, then run the JAZN Migration tool against the app-jazn-data.xml file found within the META-INF directory of the deployed application. Merge policies into the local system-jazn-data.xml policy store or generate an equivalent LDIF file for incorporation into a central LDAP based policy store, as described in Section 12.2.4, "Migrating Security and Application Roles".

  9. After testing, repeat the steps on the production server.

Subsequent Deployment

In this case, all customizations are performed in the development environment with no subsequent customizations at run time. The subsequent deployment can be seen as overwriting of the initial deployment. Repeat the steps each time you update application.

12.1.1.2 Scenario 2: Customization Performed Only In the Production Environment

If customizations of the application only occur in the production environment, then the subsequent redeployment of the application requires only a single point of truth for customizations and therefore it can be performed by using a single export and import procedure during the upgrade. The steps described in this section assume that the testing phase will occur independently of this deployment.

Note:

It is recommended that the application be run in a non-customizable mode during the period of the upgrade to a subsequent version of the application. For information, see Chapter 10, "Securing Your WebCenter Application". If this is not possible, then a last minute export of customizations should occur prior to the predeployment of a subsequent version of the application.

Initial Deployment

Perform steps described in Initial Deployment of Section 12.1.1.1, "Scenario 1: Portlet Customization in the Development Environment".

Subsequent Deployment

The following steps provide an overview of the subsequent deployment process:

  1. Extract the page and portlet customizations made in the production environment into a separate customization-only archive file by running the Predeployment tool in the export mode (-export), as described in Section 12.4, "Transporting Customizations Between Environments".

  2. Transfer the generic EAR file created in the development environment to the production server once the stage process is complete.

  3. Predeploy the new generic EAR file from the development environment to the production platform and subsequently deploy the new version of the application to the production application server.

  4. Import the exported run-time customizations (made during the upgrade process), by running the Predeployment tool in the import mode, as described in Section 12.4, "Transporting Customizations Between Environments".

12.1.1.3 Scenario 3: Customization of Deployed Applications in Both the Stage and Production Environments

In this scenario, deployed applications are customized in the stage environment, before the applications are deployed to the production environment. The following sections describe initial and subsequent deployment processes.

Initial Deployment

The following steps provide an overview of the initial deployment process.

  1. Perform steps described in Initial Deployment of Section 12.1.1.1, "Scenario 1: Portlet Customization in the Development Environment".

  2. Perform run-time customizations after deployment to the stage environment.

  3. Extract the page and portlet customizations made in the stage environment into a separate customization-only archive file by running the Predeployment tool in the export mode (-export), as described in Section 12.4, "Transporting Customizations Between Environments".

  4. Once testing is complete in the stage environment, predeploy the original generic EAR file (the one that was produced in the development environment) to the production server and deploy the application accordingly.

  5. Import the run-time customizations that were made during the stage deployment into the application in the production environment, by running the Predeployment tool in the import mode (-import), as described in Section 12.4, "Transporting Customizations Between Environments".

Subsequent Deployment

As customizations are performed postdeployment, they are stored separately from the application. In this case, the customizations occur during the stage deployment. If further customization occurred on the production platform after deployment from the stage environment, then these customizations should also be exported prior to a subsequent deployment and used as the most recent customizations for that deployment.

The following steps provide an overview of the subsequent deployment process:

  1. Extract the production platform's page and portlet customizations into a separate customization-only archive file by running the Predeployment tool in the export mode (-export), as described in Section 12.4, "Transporting Customizations Between Environments".

    Note:

    It is recommended that further customizations of the production application be prevented during the application upgrade process, until the subsequent version of the application is deployed to the production server. For information, see Chapter 10, "Securing Your WebCenter Application". If this is not possible, then a subsequent export of the customizations will be required.
  2. Predeploy and deploy the new version of the application on the stage platform, as described in steps 5 to 8 in Initial Deployment of Section 12.1.1.1, "Scenario 1: Portlet Customization in the Development Environment".

  3. Once deployed to the stage platform, update the application to include the latest set of end user customizations from the production server using the appropriate customization archive as the input file. To do so, run the Predeployment tool in the import mode (-import), as described in Section 12.4, "Transporting Customizations Between Environments". Consider the following while updating your application:

    • If the production application was run in a non-customizable mode during the upgrade process, then use the customization archive created in step 1.

    • If customization of the production application was enabled during the upgrade process (for example, the upgrade was staged over a number of days or weeks to enable for load testing, and so on), then a new export of the customization from the production system should be taken prior to applying the changes to the stage system. Use this new export EAR file as the input file for the Predeployment tool.

    This will synchronize the stage environment with the customizations that are used by the application end users.

    Note:

    Any customizations performed by end users during production execution take precedence over seeded values that are deployed with the application. This is because customizations are defined by named attributes or value pairs, and if the new version of the application has defined a different value for the named attributes of customized objects, then the imported value will override the new deployed version. For all other attributes the new deployed version will be used.
  4. Once the application is ready to be deployed to the production server, any subsequent customizations performed on the stage server should be exported using the Predeployment tool, as described in Section 12.4, "Transporting Customizations Between Environments". Likewise, if the production system was not run in a non-customizable mode, then an export of the most up-to-date customization should be taken from the production system by running the Predeployment tool in the export mode.

  5. Predeploy the new generic EAR file from the development environment to the production platform and subsequently deploy the new version of the application to the production application server.

  6. Import the run-time customizations that were made during the stage deployment, to the application in the production environment, by running the Predeployment tool in the import mode, as described in Section 12.4, "Transporting Customizations Between Environments".

  7. Apply any subsequent customizations that may have been added to the production system during the application upgrade process, by running the Predeployment tool in the import mode, as described in Section 12.4, "Transporting Customizations Between Environments".

12.1.2 About WebCenter Application Deployment in the Production Environment

In the production environment, applications are deployed to OC4J in Oracle Application Server using Application Server Control Console.

Note:

An alternate way to deploy your WebCenter application is to use the command-line interface. However, Oracle recommends that you use only Application Server Control Console to deploy your applications, because it offers ease-of-use and enables quick deployment.

Figure 12-4 depicts the process flow to deploy a WebCenter application to an OC4J instance in Oracle Application Server in the production environment. This figure shows that a generic EAR file is created using Oracle JDeveloper in the development environment. Then, the targeted EAR file is created from the generic EAR file using the Predeployment tool. The configuration files in the targeted EAR file are configured to work with the target system. Finally, the targeted EAR file is deployed to OC4J in Oracle Application Server in the production environment using Application Server Control Console. This figure also shows that the JAZN Migration tool migrates security role and policy information from the development environment to the production environment for the XML or the LDAP providers.

Figure 12-4 Deployment of a WebCenter Application to an OC4J in Oracle Application Server

Description of Figure 12-4 follows
Description of "Figure 12-4 Deployment of a WebCenter Application to an OC4J in Oracle Application Server"

The procedure of creating the generic EAR file is called packaging. The procedure of creating the targeted EAR file is called predeployment, and the procedure of deploying the targeted EAR file to OC4J is called deployment. In the production environment, you can also use WebCenter Ant Tasks to deploy your WebCenter applications.

12.1.3 About WebCenter Application Deployment in the Development Environment

In the development environment, application deployment should be quick, because developers must test their applications frequently at run time. Oracle JDeveloper enables you to deploy your WebCenter application to the following:

  • A standalone OC4J instance that is either running on the same system as Oracle JDeveloper, or using a shared network drive for the MDS location, as shown in Figure 12-5.

  • An OC4J instance on Oracle Application Server running on the same computer as Oracle JDeveloper.

In this case, Oracle JDeveloper runs the Predeployment tool automatically as you deploy to OC4J. However, in this simplified deployment, you cannot change portlet producer end points and MDS must be accessible from the development environment. Additionally, you must run the JAZN Migration tool against the app-jazn-data.xml file that is part of the generic EAR file to update the system-jazn-data.xml file for the OC4J instance you are deploying your application on. For more information, see Section 12.2.6.2, "Deploying to Standalone OC4J".

Figure 12-5 Deployment of a WebCenter Application to Embedded and Standalone OC4J Instances

Description of Figure 12-5 follows
Description of "Figure 12-5 Deployment of a WebCenter Application to Embedded and Standalone OC4J Instances"

You can also use the embedded OC4J in Oracle JDeveloper to quickly test your application in a browser. For more information, see Section 12.2.6.1, "Deploying to Embedded OC4J".

12.1.4 About Transporting Customizations between Environments

The Predeployment tool available with Oracle WebCenter Suite lets you transport portlet customizations from a stage environment to a production environment. Common scenarios of portlet customizations is the change of a portlet title, defining an OmniPortlet, and so on.

The Predeployment tool enables you to export customizations made in a stage environment and import them into the production environment, as shown in Figure 12-6. Similarly, you can export customizations from the production environment and import those to the stage environment. To do this, you run the Predeployment tool in export and import mode, as described in Section 12.4, "Transporting Customizations Between Environments".

Figure 12-6 Customizations Export and Import

Description of Figure 12-6 follows
Description of "Figure 12-6 Customizations Export and Import"

12.2 Deploying Your WebCenter Application

You can deploy your WebCenter applications in a production environment using Application Server Control Console. In the process, you package your WebCenter application in a generic EAR or WAR file. After that, you run the Predeployment tool against this file to remap the WebCenter application's external dependencies, for example, portlet producer end points and the MDS location. The Predeployment tool generates a targeted EAR file that is ready to deploy on the remote system. Additionally, some tasks related to security, content integration, and external applications may need to be performed as part of the deployment process.

Read the following sections to understand how deployment-related tasks are performed:

12.2.1 Packaging Your WebCenter Application

To deploy a WebCenter application, all required files must be packaged in a standard J2EE format and directory structure, in an EAR file. All the packaging and deployment instructions for the WebCenter application are configured through a deployment profile. The deployment profile manages all the components necessary for the deployment of an application. It is basically a configuration file, which includes names of the pages, portlets, customizations, and metadata comprising the application, the type and name of the archive file to be created, dependency information, platform-specific instructions, and more.

This section includes the following topics:

12.2.1.1 What You Should Know About Packaging a WebCenter Application

This section describes in the following sections important factors that you must know before you package your WebCenter application:

What You Should Know About Packaging Security Information

The policy information for OC4J, which includes permissions, users, roles, and role memberships for your application, is typically stored in the system-jazn-data.xml file. WebCenter application-specific policy information is stored in the app-jazn-data.xml file and this file is updated when policy information changes. In the production environment, the app-jazn-data.xml file is used as an input file for the JAZN Migration tool that updates the Lightweight Directory Interchange Format (LDIF) file or the production system-jazn-data.xml file. The LDIF file is imported into Oracle Internet Directory for the administrator's use. For further information, see Section 12.2.4, "Migrating Security and Application Roles".

What You Should Know About Packaging an External Application

Consider the following points when you package an external application:

  • Before packaging an external application, ensure that values predefined in the external application, such as login URLs point to those required in the production environment. You must do this because these values cannot be modified at the predeployment stage. This is in contrast to producer URLs of WebCenter applications, which can be changed while generating the targeted EAR files.

  • If your external application is hosted on a different computer or instance, then you must update the external application login URL prior to creating an EAR file from the deployment profile. Change the first part of the login URL to reflect the new host name. For example, from http://m1.abc.com:7777/ to http://lbr.abc.com/.

12.2.1.2 Creating the WebCenter Application WAR Deployment Profile

To deploy your WebCenter application, you must use a WebCenter application WAR deployment profile, which is then included in a generic EAR file, as described in Section 12.2.1.4, "Creating the Generic EAR File".

Note:

If your WebCenter application contains portlets and producers, then register the first producer before creating the deployment profile. See Section 4.3.1, "Registering Portlet Producers" for information about registering producers. During the first producer registration, the MDS instance definition is created in the adf-config.xml file. To define the MDS file contributors, the deployment profile creation process uses this MDS instance definition.

To create the deployment profile, perform the following steps:

  1. From the Application Navigator, select the ViewController folder. Then, choose New from the File menu. The New Gallery window is displayed.

  2. From Filter By, select Project Technologies and under General, select Deployment Profiles. Then, under Items select WebCenter Application WAR (as shown in Figure 12-7) and click OK.

    Figure 12-7 WebCenter Application WAR File Item in the New Gallery Window

    Description of Figure 12-7 follows
    Description of "Figure 12-7 WebCenter Application WAR File Item in the New Gallery Window"

  3. The Create WebCenter Application Deployment Profile window is displayed. Enter a name for the deployment profile and click OK. Your deployment profile (.deploy) is created under the Resources folder.

  4. Go to the Application Navigator and expand the Resources folder. Then, right-click the deployment profile and select Properties. The WAR Deployment Properties dialog box is displayed.

  5. Under General, select Specify J2EE Web Context Root and enter the J2EE context root in the corresponding field.

  6. Select Platform and then select your connection from Target Connection. If you do not have a connection, then see Section 12.2.6.2.1, "Defining Standalone OC4J Connection Details". Use can use this option to specify a connection to an OC4J instance on Oracle Application Server.

    Note:

    If you select a connection from Target Connection, then the orion-application.xml will be updated automatically when you create the EAR file. If you cannot create a connection, you must manually add the orion-application.xml file, as described in Section 12.2.1.3, "Manually Creating and Editing the orion-application.xml File".

12.2.1.3 Manually Creating and Editing the orion-application.xml File

To manually create the orion-application.xml file, you must create a deployment descriptor and specify the ./adf library path, which is required to point to the adf-config.xml file that the Predeployment tool uses while predeploying an application, as described in Section 12.2.2, "Predeploying Your WebCenter Application".

To manually create and edit the orion-application.xml file, perform the following steps:

  1. In Oracle JDeveloper, select your project, then go to File and select New. The New Gallery window is displayed.

  2. Under General, select Deployment Descriptors and under Items select OC4J Deployment Descriptor Wizard, as shown in Figure 12-8.

    Figure 12-8 New Gallery - OC4J Deployment Descriptor Wizard

    Description of Figure 12-8 follows
    Description of "Figure 12-8 New Gallery - OC4J Deployment Descriptor Wizard"

  3. Click OK. The Create Deployment Descriptor - Welcome page is displayed.

  4. Click Next to display the Select Descriptor page.

  5. Select orion-application.xml, as shown in Figure 12-9, and click Next to display the Select Version page.

    Figure 12-9 Select Descriptor - orion-application.xml

    Description of Figure 12-9 follows
    Description of "Figure 12-9 Select Descriptor - orion-application.xml"

  6. Select 10.0, as shown in Figure 12-10, and then click Next.

    Figure 12-10 Select Version

    Description of Figure 12-10 follows
    Description of "Figure 12-10 Select Version"

  7. Click Finish to complete the creation of orion-application.xml.

  8. To view the orion-application.xml file, go to your project in the Application Navigator and expand the Application Sources and META-INF folders, as shown in Figure 12-11.

    Figure 12-11 Application Navigator - orion-application.xml

    Description of Figure 12-11 follows
    Description of "Figure 12-11 Application Navigator - orion-application.xml"

  9. Double-click the orion-application.xml file to open it.

  10. Open the Component Palette, if it is not already opened. Select the OC4J Application option and then select library, as shown in Figure 12-12.

    Figure 12-12 Library Option

    Description of Figure 12-12 follows
    Description of "Figure 12-12 Library Option"

  11. Drop the library node on to the orion-application.xml page. The <library> </library> element is added.

  12. In the Property Inspector, enter ./adf for the path.

  13. From OC4J Application, select jazn and drop it on to the page.

  14. In the Property Inspector, enter ./jazn-data.xml for location and select XML for Provider.

  15. Now, select data-sources and drop it on to the page.

  16. In the Property Inspector, enter ./data-sources.xml for the path. Example 12-1 shows the sample orion-application.xml file.

    Example 12-1 Sample Orion-Application.xml File

    <?xml version = '1.0'?>
    <orion-application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/orion-application-10_0.xsd">
    <library path="./adf" />
    <jazn location="./jazn-data.xml" provider="XML"/>
    <data-sources path="./data-sources.xml"/>
    </orion-application>
    

12.2.1.4 Creating the Generic EAR File

To create the generic EAR file, right-click the name.deploy file and select Deploy to EAR file. The deployment finished message appears in the Deployment - Log window.

On Windows, the default location of the EAR file is ORACLE_HOME\jdev\mywork\MyApplication\ViewController\deploy

On Linux, the default location of the EAR file is ORACLE_HOME/jdev/mywork/MyApplication/ViewController/deploy

You can change this location that Oracle JDeveloper uses and create your application in any preferred location. To do so, right-click your deployment profile (.deploy) in the Application Navigator and select Properties. In the General tab of the WAR Deployment Properties dialog box change the path to EAR and WAR files. You can also change your application name.

The generic EAR file is used by the Predeployment tool to create the targeted EAR file, which is deployed to OC4J in Oracle Application Server in the production environment, using Application Server Control Console.

12.2.2 Predeploying Your WebCenter Application

Before you deploy the WebCenter Application EAR file to OC4J in Oracle Application Server, the development references contained in the file must be modified to be specific to the target instance. You use the Predeployment tool to create a targeted EAR file. The targeted EAR file is typically created on the computer that has the Oracle Application Server installation, to which the application is going to be being deployed. This ensures that the MDS directory is created in the appropriate location on the target system, and the targeted EAR file contains the correct MDS path. The targeted EAR file is deployed to OC4J in Oracle Application Server using Application Server Control Console.

The Predeployment tool performs the following when the EAR file is run through the tool:

  • Creates the MDS store on the target system.

  • Updates the adf-config.xml file: The existing MDS directory in this file points to the development environment. MDS is the dedicated store in which metadata specific to WebCenter applications, such as page customizations, is stored. The Predeployment tool changes the MDS directory to the production environment, based on the location that you provide when prompted.

  • Updates the connections.xml file: The URL and proxy information of the producers contained in this file is updated based on the input that you provide when prompted by the Predeployment tool.

  • Imports the portlet customizations from the MDS Export data set to the production producers, that is, creates the MDS store on the target system. However, the credential store is not migrated during predeployment or export and import.

This section includes the following topics:

12.2.2.1 What You Should Know About Predeployment

Consider the following points when you predeploy your WebCenter application:

  • You can run the Predeployment tool at any time to reconfigure any of the connection details and other exposed settings. After predeploying your application, you must redeploy the application again.

  • The generic EAR file contains relative paths set up by Oracle JDeveloper and you can specify multiple paths specified by a comma separated list, for example, ../../mds/;../../. However, when deploying using the Predeployment tool to the targeted EAR file, only one MDS path can be specified in the profile.xml file and this must be an absolute path, for example, C:\MDS\deploy.

  • The predeployment tool accepts an MDS path without a terminating slash (/).

  • A shared MDS path, that is, a network mounted drive, is treated as a local drive. The stored MDS path should be the path of the mounted drive from the computer on which you plan to deploy the targeted EAR file. If you use a shared MDS, then you must only execute the Predeployment tool once to produce the targeted EAR file, and then you deploy the targeted EAR file on other OC4J instances. For information about how to select the MDS path using Oracle JDeveloper, see Section 12.2.6.2.2, "Deploying Your WebCenter Application to Standalone OC4J".

  • If multiple instances of OC4J in Oracle Application Server share an MDS location, then the adf-config.xml file should be updated manually on each location to specify the path of the shared MDS from that location. This must be done because the drive on which the MDS is mounted could be different in each instance. For example, if there are two OC4J instances, then in one instance the MDS may be mounted on drive F and in another instance, the MDS may be mounted on drive E, so the adf-config.xml file should be updated on both OC4J instances. However, to avoid updating the adf-config.xml file due to different mount points, it is recommended to keep the mount point same on all OC4J instances.

  • Before predeploying an external application, ensure that values predefined in the external application such as login URLs, point to those required in the production environment. You must do this because these values cannot be modified during predeployment or postdeployment. This is in contrast to producer URLs of WebCenter applications that can be changed using the Predeployment tool while generating the targeted EAR files.

  • If you are accessing an Secure Sockets layer (SSL) enabled producer, and if the producer's security certificate is not listed in the keystore, then before predeploying your application, you must register the security certificate with the keystore. To do this, follow the steps described in Section 10.8, "Registering Custom Certificates with the Keystore".

  • The Predeployment tool does not support signed EAR files.

  • The Predeployment tool does not support reconfiguration of secure connections in WebCenter applications that contain portlets.

  • The Predeployment tool does not support remapping of file system, OracleAS Portal, and Oracle Content Server adapter connections. Therefore, these connections must be manually reconfigured as described in Reconfiguring OracleAS Portal, Oracle Content Server, and File System Adapters.

12.2.2.2 Predeploying WebCenter Applications and JCR Adapter-based Applications

This section discusses predeployment procedures for WebCenter applications and content integration applications, as follows:

Predeploying Your WebCenter Application Using the Predeployment Tool

The Predeployment tool is used to create targeted EAR files from generic EAR files.

The Predeployment tool uses the -jar java command line, which calls portlet-client-deploy.jar that ensures the correct classpath and main class for the tool. By default, the Predeployment tool JARs and its dependencies are located in ORACLE_HOME/adfp/lib.

To predeploy your application, run the following command from ORACLE_HOME of the target system:

Tip:

You can run this command from any other directory if absolute paths are specified in the arguments to the Predeployment tool.
ORACLE_HOME/jdk/bin/java -jar ORACLE_HOME/adfp/lib/portlet-client-deploy.jar 
-predeploy -source <genericEAR> -target <targetedEAR> 
[ -configuration <config file> [-profile <profile name>] ] -backup <directory path>

where:

portlet-client-deploy.jar is the predeployment JAR file from which the Predeployment tool is run.

genericEAR is the generic EAR file created using Oracle JDeveloper.

targetedEAR is the targeted EAR file, which the Predeployment tool creates during predeployment.

config file is the XML mapping file, which contains information about one or more predeployment profiles, as shown in Example 12-2. A config file may contain multiple predeployment profiles. If it does, then you must specify which one you want to use when you run the Predeployment tool. If there is only one profile in the configuration file, you do not need to specify the profile name. Example 12-3 shows a sample config file with multiple profiles.

profile is the name used inside the XML mapping file to identify a particular predeployment profile. If you do not specify a profile name in the mapping file, then the tool checks that there is an entry. If there is only one entry, then the tool uses it. But if there are several entries, then it generates an error because it cannot discern which entry to use.

Note:

In WSRP portlets, when the XSD file for the portlets is located on an external site such as OASIS, then the Predeployment tool obtains validation information from the external site. To enable the Predeployment tool to obtain validation from Internet, specify the standard Java proxy configuration properties before the -jar flag, as shown in the following example:
ORACLE_HOME/jdk/bin/java -Dhttp.proxyHost=www-proxy.my.company.com -Dhttp.proxyPort=80 -jar adfp/lib/portlet-client-deploy.jar

-backup is optional. It accepts as its value the path to targeted EAR file in the application home of your Oracle Application Server, that is, ORACLE_HOME/j2ee/home/applications/YourApplication. The backup and recovery configuration of the specified ORACLE_HOME is updated so that the MDS path that the user enters during predeployment is included as part of a backup. The following example discusses the use of -backup option:

ORACLE_HOME\jdk\bin\java -jar portlet-client-deploy.jar -source c:\EAR\sample.ear 
-target c:\EAR\sampleTarget2.ear -predeploy -backup 
ORACLE_HOME\j2ee\home\applications\sampleTarget2

In this example, the MDS path provided while running the Predeployment tool is updated in <ORACLE_HOME>/backup_restore/config/config_misc_files.inp. The config_misc_files.inp file already exists and is appended with the MDS path. For more information, see section titled Backup Strategy and Procedures in Oracle Application Server Administrator's Guide.

Example 12-2 shows a sample config file with a single profile.

Example 12-2 Sample Config File with a Single Profile

<?xml version = '1.0' encoding = 'UTF-8'?>
<DeployConfig xmlns="http://xmlns.oracle.com/webcenter/lifecycle/deployconfig">
  <profile name="Production">
   <mds_metadata_path>
          /home/mydirectory/mdstest
   </mds_ metadata_path>
    <producers>   
   <producer name="MyWebProducerConnection" proxyHost="" proxyPort="0" 
    serviceURL="http://host_name:port/adapter/portal"/>
    </producers>
  </profile>
</DeployConfig>

Example 12-3 shows a sample config file with multiple profiles.

Example 12-3 Sample Config File with Multiple Profiles

<?xml version = '1.0' encoding = 'UTF-8'?>
<DeployConfig xmlns="http://xmlns.oracle.com/webcenter/lifecycle/deployconfig">
<profile name="Production">
   <mds_metadata_path>
   /WorkEnvLifecycle/Lifecycle/jpswork/components/Lifecycle/data/MDS
   </mds_metadata_path>
   <producers>
      <producer name="WSRPProducerConnection1" proxyHost="www-proxy.my.company.com" proxyPort="80"
serviceURL="http://host:port/adapter/portal/portletapp/portlets/WSRPBaseService?WSDL"/>
   </producers>
</profile>
<profile name="portletArchiveWSRP203760">
    <mds_metadata_path>
     /WorkEnvLifecycle/Lifecycle/jpswork/components/Lifecycle/data/MDS
      </mds_metadata_path>
    <producers>
        <producer name="WSRPProducerConnection1"   proxyHost="www-proxy.my.company.com" proxyPort="80" 
     serviceURL="http://host:port/adapter/portal/nonexist/portlets?ABCD"/>
     </producers>
</profile>
<profile name="portletArchiveWSRP203750">
     <mds_metadata_path>
    /WorkEnvLifecycle/Lifecycle/jpswork/components/Lifecycle/data/NoPermission
     </mds_metadata_path>
     <producers>
        <producer name="WSRPProducerConnection1"   proxyHost="www-proxy.my.company.com" proxyPort="80"
serviceURL="http://host:port/adapter/portal/portletapp/portlets/WSRPBaseService?WSDL"/>
     </producers>
</profile>
<profile name="portletArchiveWSRP197300">
    <mds_metadata_path>
      /WorkEnvLifecycle/Lifecycle/jpswork/components/Lifecycle/data/MDS/197300
      </mds_metadata_path>
     <producers>
       <producer name="WSRPProducerConnection1"  proxyHost="www-proxy.my.company.com" proxyPort="80"
serviceURL="http://host:port/adapter/portal/portletapp/portlets/WSRPBaseService?WSDL"/>
    </producers>
</profile>

Example 12-4 shows a sample of the output that the Predeployment tool generates while predeploying a WebCenter application. If you do not specify the config file, then the Predeployment tool prompts you for the information, which is in bold in the sample.

Example 12-4 Output of the Predeployment Tool for a WebCenter Application

http://host:port/jpdk/providers/sample$ java -jar portlet-client-deploy.jar -source
/Automation/PDKValid1.ear -target /Automation/PDKValid1Target1.ear -predeploy
Processing Arguments
Run Mode : 1
Source : /Automation/PDKValid1.ear
Target : /Automation/PDKValid1Target1.ear
...
Cleaning up /tmp/predeploy/
Processing source EAR file
Source EAR file processed
Processing adf-config.xml
...
Producer : PdkPortletProducer1_11605536060373662ab97-010e-1000-8001-984463fc1d8d
Current Service URL :
http://host:port/jpdk/providers/sample
Current Proxy URL   :
Current Proxy Port   : 0
Do you want to modify this connection? (Y/N [default=N]) :
Y
Enter new Service URL (or Enter to leave it as it is): http://newhost:newport/jpdk/providers/sample
Do you want to save this new Deployment Profile (Y/N [default=N]) :
Y
Enter a name for this Deployment Profile (e.g. 'Production') :
PDKValid1
Enter the path for the Deployment Profile XML file (e.g. 'C:\profile.xml'):
/JDEV/DepFiles/PDKValid1.cml
...
MDS extracted from source EAR file
Creating target EAR file
Processing source EAR file
...
source MDS Path (temp) : /tmp/predeploy/mds
Production MDS Path : /MDS/PDKValid1
Connections.xml Path : /tmp/predeploy/connections.xml.new
Export ID : /export
<Date> <Time> oracle.mds
...
Backing up existing target EAR to /Automation/PDKValid1Target1.ear.old
Moving /tmp/predeploy/PDKValid1Target1.ear to /Automation/PDKValid1Target1.ear
Target EAR /Automation/PDKValid1Target1.ear created
Cleaning up /tmp/predeploy/

Reconfiguring WSRP Portlet Producers

The Predeployment tool does not support reconfiguration of WSRP portlet producers. Therefore, if you want to deploy your WebCenter application to a production environment where WS-Security is implemented, then register the WSRP producer URLs in the development environment using Oracle JDeveloper. To learn how to register producer URLs, see Section 4.3.1.1, "Registering WSRP Portlet Producers".

Reconfiguring Parameters of Oracle Content DB-based Content Integration Applications

During the predeployment phase, the Predeployment tool lets you reconfigure parameters of Oracle Content DB based content integration applications. You can use the Predeployment tool to reconfigure parameters of both versions 10.1.3.2 and 10.2 of Oracle Content DB. For information about Oracle Content DB parameters, see Section 5.2.4, "Configuring a Content Data Control Based on the Oracle Content DB Adapter" and Section 5.2.5, "Configuring a Content Data Control Based on Oracle Content DB Version 10.2".

Note:

While reconfiguring the parameters of a content integration application that is based on Oracle Content DB, you cannot remap a nonsecure connection with a secure connection or a secure connection with a nonsecure connection. Therefore, the type of connections that you map must be of the same type.

When you run the Predeployment tool to reconfigure Oracle Content DB parameters, it prompts you as discussed in Table 12-1.

Table 12-1 Parameters Prompted by the Predeployment Tool

Parameters Values, if WS-Security is Implemented Values, if S2S is Implemented

Do you want to modify this connection? (Y/N [default=N]):

Y or N, as required.

Y or N, as required.

What is the value of 'Server URL' (or Enter to leave it as is):

Enter the server URL in format: http://host:port/content/ws

Enter the server URL in format: http://host:port/content/ws

What is the value of 'Server Version' (or Enter to leave it as is):

10.3.1.2

10.2

What is the value of 'Trusted Authentication Method' (or Enter to leave it as is):

WS-Security

S2S

What is the value of 'S2S Application Name' (or Enter to leave it as is):

Leave it blank.

Enter name of the application. This is configured in Oracle Internet Directory and must be set here together with the S2S application password.

What is the value of 'KeyStore File Location' (or Enter to leave it as is):

Enter the location where the keystore file should be located in the production environment.

Leave it blank.

What is the value of 'KeyStore Type' (or Enter to leave it as is):

Keystore type is usually JKS or PKCS12.

Leave it blank.

What is the value of 'Server Public Key Alias' (or Enter to leave it as is):

Enter the alias value that you specified while configuring the keystores.

Leave it blank.

What is the value of 'Private Key Alias' (or Enter to leave it as is):

Enter the private key alias that you specified while configuring the keystores.

Leave it blank.


Note:

If you do not have a security setup, then specify only the URL and press Enter to skip other parameters.

Example 12-5 shows remapping of Oracle Content DB version 10.1.3.2 parameters.

Example 12-5 Sample Output of the Predeployment Tool for an Oracle Content DB Version 10.1.3.2-based Application

Development MDS Repository Path : C:\adfsrdemojsf\mds;C:\adfsrdemojsf
...
What is the value of 'Server URL' (or Enter to leave it as is): http://yourhost:port/content/ws
What is the value of 'Server Version' (or Enter to leave it as is): 
10.3.1.2
What is the value of 'Trusted Authentication Method' (or Enter to leave it as is): WS-Security
What is the value of 'S2S Application Name' (or Enter to leave it as is):
<blank>
What is the value of 'KeyStore File Location' (or Enter to leave it as is):/private1/keystore/client-keystore.jks
What is the value of 'KeyStore Type' (or Enter to leave it as is): 
JKS
What is the value of 'Server Public Key Alias' (or Enter to leave it as is): server
What is the value of 'Private Key Alias' (or Enter to leave it as is): 
keyalias

Reconfiguring OracleAS Portal, Oracle Content Server, and File System Adapters

If you want to reconfigure your OracleAS Portal and File System repositories to point to different instances, then you must manually edit the connections.xml file. After deployment, the connections.xml file can be found at

ORACLE_HOME/j2ee/home/applications/Application name/adf/META-INF/

Example 12-6 shows the segment of the connections.xml file, which must be modified to reconfigure the File System adapter.

Example 12-6 Connections.xml for the File System Adapter

<StringRefAddr addrType="jcr_basePath">
            <Contents>/private/myfiles</Contents>
     </StringRefAddr>

Example 12-7 shows the segment of the connections.xml file, which must be modified to reconfigure the OracleAS Portal adapter.

Example 12-7 Connections.xml for the OracleAS Portal Adapter

<StringRefAddr addrType="jcr_dataSourceName">
            <Contents>jdbc/DBConnection1DS</Contents>
</StringRefAddr>

Note:

While reconfiguring the parameters of a content integration application that is based on OracleAS Portal, you cannot remap a nonsecure connection with a secure connection or a secure connection with a nonsecure connection. Therefore, the type of connections that you map must be of the same type.

Example 12-8 shows the segment of the connections.xml file, which must be modified to reconfigure a web type connection of the Oracle Content Server adapter.

Example 12-8 web Type Connection of the Oracle Content Server Adapter

<StringRefAddr addrType="jcr_oracle.stellent.jcr.configuration.server.web.url">
         <Contents>http://host:port/idc/idcplg</Contents>
</StringRefAddr>
<StringRefAddr addrType="jcr_oracle.stellent.jcr.configuration.cis.config.socket.type">
         <Contents>web</Contents>
</StringRefAddr>

Example 12-9 shows the segment of the connections.xml file, which must be modified to reconfigure a socket type connection of the Oracle Content Server adapter.

Example 12-9 socket Type Connection of the Oracle Content Server Adapter

<StringRefAddr addrType="jcr_oracle.stellent.jcr.configuration.server.host">
            <Contents>host</Contents>
</StringRefAddr>
         <StringRefAddr addrType="jcr_oracle.stellent.jcr.configuration.server.port">
            <Contents>port</Contents>
</StringRefAddr>
         <StringRefAddr addrType="jcr_oracle.stellent.jcr.configuration.cis.config.socket.type">
            <Contents>socket</Contents>
</StringRefAddr>

12.2.3 Deploying Your WebCenter Application Using Application Server Control Console

This section describes the procedures to deploy and test your WebCenter application using Application Server Control Console, as follows:

12.2.3.1 Deploying Your WebCenter Application

To deploy your application using Application Server Control Console, you need the targeted EAR file of your application. The targeted EAR file must be created on the system to which the application is being deployed. If you have not created the generic and targeted EAR files already, then see Section 12.2.1, "Packaging Your WebCenter Application" and Section 12.2.2, "Predeploying Your WebCenter Application" respectively.

Note:

For detailed information about deploying applications to OC4J, see Oracle Containers for J2EE Deployment Guide on the OracleAS Portal Documentation page on Oracle Technology Network (OTN).

To deploy your application using Application Server Control Console, perform the following steps:

  1. To access Application Server Control Console, navigate to the following URL: http://<host_name>.<domain>:<port>/em.

    For example, http://test.acme.com:8888/em.

    To find the exact URL for your Application Server Control Console, look at readme.txt. After installation, this text file is saved to the following Oracle Application Server location:

    On UNIX: ORACLE_HOME/install/readme.txt

    On Windows: ORACLE_HOME\install\readme.txt

  2. Log in to the Application Server Control Console. The Cluster Topology page is displayed.

  3. On the Cluster Topology page, click the link to your application server.

  4. Under System Components, click the Create OC4J Instance button. The Create OC4J Instance page is displayed.

  5. Specify a name for the OC4J instance, for example, myoc4j.

  6. Make sure the Start this OC4J instance after creation check box is not selected.

  7. Click Create.

  8. On Oracle Application Server, select the OC4J instance that you just created.

  9. Select the Applications tab (Figure 12-13) and click Deploy. The Deploy: Select Archive page is displayed.

    Figure 12-13 Applications Tab of Application Server Control Console

    Description of Figure 12-13 follows
    Description of "Figure 12-13 Applications Tab of Application Server Control Console "

  10. If the EAR file is located on the local computer, then select the Archive is present on local host option and browse to the location of the EAR file, as shown in Figure 12-14, or select the Archive is already present on the server where Application Server Control is running option. Then, click Next.

    Figure 12-14 Deploy: Select Archive in Application Server Control Console

    Description of Figure 12-14 follows
    Description of "Figure 12-14 Deploy: Select Archive in Application Server Control Console"

    Note:

    You can use the Redeploy button to redeploy the application. You can also stop and restart the application from here.
  11. In the Deploy: Application Attributes page (Figure 12-15), enter the context root of your Web application as the application name or what you configured while creating the deployment profile described in Section 12.2.1.2, "Creating the WebCenter Application WAR Deployment Profile".

    Figure 12-15 Application Attributes in Application Server Control Console

    Description of Figure 12-15 follows
    Description of "Figure 12-15 Application Attributes in Application Server Control Console"

  12. Deployment Settings page is displayed, as shown in Figure 12-16. If required, then make the changes in this page and click Deploy.

    Note:

    If you have not yet migrated the security policies by running the JAZN Migration tool, then you can defer the selection of the Security Provider.

    Figure 12-16 Deployment Settings in Application Server Control Console

    Description of Figure 12-16 follows
    Description of "Figure 12-16 Deployment Settings in Application Server Control Console"

  13. The deployment confirmation page is displayed, as shown in Figure 12-17.

    Figure 12-17 Confirmation Message in Application Server Control Console

    Description of Figure 12-17 follows
    Description of "Figure 12-17 Confirmation Message in Application Server Control Console "

  14. Migrate the security information, as described in Section 12.2.4, "Migrating Security and Application Roles".

12.2.3.2 Testing Your WebCenter Application

Open a browser window and navigate to the welcome page of your application. You must enter a URL that uses the context root defined in the deployment profile, followed by /faces/, and the page name itself. The URL format you require is http://<host>:<port>/<context-root>/faces/<page-name>

For example:

http://localhost:8888/SRApplication/faces/Welcome.jspx

where:

SRApplication is the context root specified in the deployment profile, as described in Section 12.2.1.2, "Creating the WebCenter Application WAR Deployment Profile".

12.2.4 Migrating Security and Application Roles

After you have deployed your WebCenter application, you must use the JAZN Migration tool to migrate your application's realm and policy information. To facilitate the deployment of this security information, Oracle JDeveloper packages the specific policies for the application in the app-jazn-data.xml file. In your development environment, the app-jazn-data.xml is located in your application's .adf\META-INF directory. Postdeployment, the file is unpacked to the directory ORACLE_HOME/j2ee/<oc4j_instance>/applications/<app-name>/adf/META-INF.

The app-jazn-data.xml file is created when a policy is defined in the application using the authorization editor of Oracle JDeveloper. Each time a developer updates the policy for a page or component (for example, an iterator or data control), Oracle JDeveloper's embedded OC4J's system-jazn-data.xml, located in JDEV_HOME\system\oracle.j2ee.10.1.3.xx.xx\embedded-oc4j\config, is updated. At the same time, these changes are also propagated to file app-jazn-data.xml. The elements and attributes contained in the app-jazn-data.xml file are a subset of OC4J's system-jazn-data.xml file.

When you migrate security information with the JAZN Migration tool, the destination for this information will either be a file-based provider (for example, system-jazn-data.xml) or an LDAP provider. In the latter case, the output from the migration tool is an LDIF file that must be subsequently loaded into the LDAP directory (for example, Oracle Internet Directory).

This section discusses the following:

12.2.4.1 About Modes of Migration

The JAZN Migration tool supports the following modes of operation:

  • Realm mode: This is used to migrate only users and roles. All users in the source realm are migrated when the migration mode is realm or all.

    When the output LDIF file is generated, passwords from jazn-data.xml are exposed in clear text. The administrator maintains and protects the generated LDIF file so that no one else can access the LDIF file.

  • Policy mode: This is used to migrate grantees and the permissions granted to these grantees.

  • All mode: This is used to migrate users, roles, grantees, and the permissions granted to these grantees. The grantees can be realm grantees or non-realm grantees.

12.2.4.2 Updating Policy Information (Optional)

If you have defined a list of temporary role names in the development environment that represent the ultimate production roles and have used these roles for policy definition, then at deployment time, these policies must be updated to reflect the actual production roles. Skip this section if you have used actual production role names in the development environment. See Section 10.2.1, "Defining Roles for Developing Secured WebCenter Applications" for more information.

To update policy information with actual production roles, replace the temporary development roles in the app-jazn-data.xml file with those you are going to use in the production environment, prior to running the JAZN Migration tool.

Example 12-10 shows the app-jazn-data.xml file with a managers role defined in the development environment.

Example 12-10 app-jazn-data.xml file with a managers Role

<roles>
     <role>
       <name>managers</name>
         <guid>58B213307F7811DBBF8F39184ABB7640</guid>
           <members>
           </members>
     </role>
</roles>
.
.
.
<grant>
  <grantee>
    <principals>
      <principal>
        <realm-name>jazn.com</realm-name>
          <type>role</type>
          <class>oracle.security.jazn.spi.xml.XMLRealmRole</class>
          <name>managers</name>
      </principal>
    </principals>
  </grantee>
  <permissions>
    <permission>
      <class>oracle.adf.share.security.authorization.RegionPermission</class>
      <name>view.pageDefs.testPageDef</name>
      <actions>customize,personalize,view</actions>
    </permission>
  </permissions>
</grant>

To map this role to the doc_managers role in the production environment, update the name element specified for the role and principal, as shown in Example 12-11.

Example 12-11 Updated app-jazn-data.xml File with the doc_managers Role

<roles>
     <role>
       <name>doc_managers</name>
         <guid>58B213307F7811DBBF8F39184ABB7640</guid>
           <members>
           </members>
     </role>
</roles>
.
.
.
<grant>
  <grantee>
    <principals>
      <principal>
        <realm-name>jazn.com</realm-name>
          <type>role</type>
          <class>oracle.security.jazn.spi.xml.XMLRealmRole</class>
          <name>doc_managers</name>
      </principal>
    </principals>
  </grantee>
  <permissions>
    <permission>
      <class>oracle.adf.share.security.authorization.RegionPermission</class>
      <name>view.pageDefs.testPageDef</name>
      <actions>customize,personalize,view</actions>
    </permission>
  </permissions>
</grant>

If the named role does not exist in the identity management solution at the time you run the JAZN Migration tool, it will be added. If it does exist, then the role that is defined in the app-jazn-data.xml file will not overwrite the existing role definition, but apply the policy to the existing role in the identity management solution.

12.2.4.3 Using the JAZN Migration Tool

The JAZN Migration tool is packaged as an executable utility, which runs from the command-line. Example 12-12 describes the syntax for the JAZN Migration tool and Table 12-2 describes the elements of the syntax. Before you run the JAZN Migration tool, you must set the CLASSPATH to ORACLE_HOME/j2ee/home/jazn.jar;ORACLE_HOME/BC4J/lib/adfshare.jar.

Note:

You must shutdown OC4J before running the JAZN Migration tool to migrate security policies from the app-jazn-data.xml file to the system-jazn-data.xml file. Once the policies are migrated, restart OC4J.

Example 12-12 Syntax for the JAZN Migration Tool

java oracle.security.jazn.tools.JAZNMigrationTool -help
java JAZNMigrationTool [-D binddn] [-w passwd] [-h ldaphost] [-p ldapport] 
                                [-sf filename] [-df LDIF_filename] 
                                [-sr source_realm] [-dr dest_realm]
                                [-st source_type] [-dt dest_type]
                                [-m policy|realm|all]
                                [-help]   

Table 12-2 Description of the JAZN Migration Tool Syntax

Element Description

-D

The Oracle Internet Directory user name.

-w

The Oracle Internet Directory user password.

-h

The Oracle Internet Directory host.

Default: location value in ORACLE_HOME/j2ee/home/config/jazn.xml

-p

The Oracle Internet Directory port.

Default: location value in ORACLE_HOME/j2ee/home/config/jazn.xml

-sf

Path to XML provider file.

Default: ORACLE_HOME/j2ee/home/config/system-jazn-data.xml

-df

Path to destination LDIF file.

Default: ORACLE_HOME/j2ee/home/config/system-jazn-data.xml, if -dt is XML.

-sr

Name of the realm to be migrated.

Default: The realm name when there is only one realm

-dr

Name of the destination subscriber realm in the Oracle Internet Directory.

Default: The realm name when there is only one realm, and if -dt is xml.

The default subscriber realm if -dt is ldap.

-st

Type of provider at the source.Default: xml

-dt

Type of provider at the destination. Available options are ldap and xml.Default: ldap

-m

The mode for running the tool. Available options are policy, realm, and all. Default: all

Use the policy mode if only the JAAS policies have to be migrated.

Use the realm mode, if only realm users and roles have to be migrated. Use the all mode, if user, roles, and JAAS policies have to be migrated.

-help

Display usage.


Example 12-13 describes the syntax to facilitate migration from XML to XML. Table 12-2 describes the elements of the syntax.

Example 12-13 Syntax for XML to XML Migration

java oracle.security.jazn.tools.JAZNMigrationTool
-sr sourcerealm -dr destrealm -st xml -dt xml -sf -<sourcefile> -df <destfile> -m policy|realm|all

Example 12-14 describes the syntax to facilitate migration from XML to LDAP. Table 12-2 describes the elements of the syntax.

Example 12-14 Syntax for XML to LDAP Migration

java oracle.security.jazn.tools.JAZNMigrationTool
-D binddn -w passwd -h ldaphost -p ldapport -sr sourcerealm -st xml -dt ldap -sf 
<source file> -df <dest file> -m policy|realm|all(default)

12.2.4.4 Using the ldapmodify Command-Line Tool

The ldapmodify command-line tool enables you to add, delete, or replace attributes for entries by supplying an LDIF file as input. Example 12-15 describes the syntax for ldapmodify and Table 12-3 discusses the arguments for ldapmodify.

Note:

The ldapmodify command is available in the OracleAS Infrastructure installation that you have associated with your application. Therefore, run the ldapmodify command from the OracleAS Infrastructure host.

Example 12-15 Syntax for ldapmodify

ldapmodify -h <oid_host_name> -p <oidport> -D <binddn> -w <password>  -f <ldiffile> -v -c -o <errors_ldiffile>

Table 12-3 Arguments for ldapmodify

Elements Description

-h

The host name or IP address of the Oracle Internet Directory server, for example, infrahost.company.com. Host name is mandatory.

-p

The port number used to connect to the Oracle Internet Directory server, for example, 389. Port number is optional.

-D

The DN of the Oracle Internet Directory user, for example, cn=orcladmin. It is needed to bind to the directory and is mandatory.

-w

The user password needed to bind to the directory, for example, welcome1. Password is mandatory.

-f

The full path and file name of the input file that contains the data you want to import, for example, entry.ldif. This is mandatory.

-v -c -o

The tool continues on errors and writes all the LDIF lines causing the errors into the specified error LDIF file so that they can be corrected and resubmitted.


12.2.5 Deploying Your WebCenter Application Using the Command Line

This section describes the procedure to deploy a WebCenter application using the command-line interface. The command-line tool deploys the targeted EAR file that the Predeployment tool generates from the generic EAR file. If you have not created the generic and targeted EAR files already, then see Section 12.2.1, "Packaging Your WebCenter Application" and Section 12.2.2, "Predeploying Your WebCenter Application" respectively.

In this section, you will use command-line syntax for the following:

12.2.5.1 Deploying the EAR File to OC4J in Oracle Application Server

To deploy the targeted EAR file to OC4J in Oracle Application Server, perform the following steps:

  1. Place the targeted EAR file in a directory in your Oracle Application Server. For example, ORACLE_HOME/j2ee/home/applications/

  2. Go to your J2EE home. The path should be like ORACLE_HOME/j2ee/home/

  3. To deploy the application, run the following command:

    java -jar admin.jar ormi://localhost/<ormi port> <admin_username> <admin_pwd> 
    deploy -file <full_path_of_ear_file> -deploymentName <deployment_name>
    

where:

admin.jar is available at ORACLE_HOME/j2ee/home/

ormi://localhost/<ormi port> is the Remote Method Invocation (RMI) port with default value 23791. Its value gets stored in the config file. This is stored in the rmi.xml file available at <ORACLE_HOME>/j2ee/home/config.

<admin_username> is the user name of the administrator of your OC4J in Oracle Application Server.

<admin_pwd> is the password of the administrator of your OC4J in Oracle Application Server.

<deployment_name> is the unique name provided for the deployment in progress.

Note:

You can deploy an application multiple times while providing a unique name for each deployment. If the deployment with a name already exists, then it is treated as a redeployment.

12.2.5.2 Testing the Deployment

In OC4J, verify the following:

  • In the applications directory, the EAR file appears expanded. The path of the applications directory should be like ORACLE_HOME\j2ee\home\applications.

  • The application-deployments directory contains files related to the deployed application.

  • The <deployment_name> directory is created in both applications and application-deployments directories.

12.2.5.3 Binding web_module to a Web Site

To bind the application to the port to which OC4J listens, perform the following steps:

  1. Run the following command:

    java -jar admin.jar ormi://host/<ormi_port>/ <admin_username> <admin_pwd> 
    0bindWebApp <deployment_name> <web_module_name> <webSiteName> <context_root> 
    

    where:

    ormi_port is the RMI port. Its value is stored in the config file.

    deployment_name is the name of the deployed application.

    web_module_name is the name of the module to bind. This is specified for the application.

    webSiteName is the host name of the site to which the application is deployed.

    context_root is the Web Application's Context Root stored in the deployment profile.

  2. Access your application with the appropriate URL, which should be in the following format:

    http://host:port/web_site_name/context_root/faces/page_name.jspx
    

Note:

If you have <webSiteName> as the default http-web-site, then you do not need to include it in the URL, so the format of your URL is http://host:port/context_root.

Your WebCenter application is now deployed and ready to use.

12.2.6 Deploying Your WebCenter Application Using Oracle JDeveloper

You can use Oracle JDeveloper to deploy your WebCenter application to a standalone OC4J by performing the following steps:

12.2.6.1 Deploying to Embedded OC4J

To deploy your content pages to the embedded OC4J, and test them in a browser, right-click your project and select Run, as shown in Figure 12-18.

Figure 12-18 Testing with Embedded OC4J

Description of Figure 12-18 follows
Description of "Figure 12-18 Testing with Embedded OC4J"

The page that you selected will display in the browser.

12.2.6.2 Deploying to Standalone OC4J

This section describes the following procedures:

12.2.6.2.1 Defining Standalone OC4J Connection Details

To create a direct connection to the standalone OC4J on which you will deploy your application, perform the following steps:

  1. In the Navigator, click the Connections tab.

  2. Right-click Application Server and choose New Application Server Connection. The Welcome page is displayed.

  3. Click Next to exit the Welcome page. The Step 1 of 4: Type window is displayed, as shown in Figure 12-19.

    Figure 12-19 Create Application Server Connection - Step 1 of 4 Window

    Description of Figure 12-19 follows
    Description of "Figure 12-19 Create Application Server Connection - Step 1 of 4 Window"

  4. On step 1, enter a name for your standalone OC4J connection in the Connection Name field.

  5. Then, choose the appropriate connection type from the list. For example, Standalone OC4J 10g 10.1.3 and click Next.

  6. On step 2, enter a valid user name and password, such as oc4jadmin and oracle1, and then click Next.

  7. On step 3, enter the host name of the standalone OC4J, for example, myhost.mycompany.com, its RMI Port, for example, 23795, and then click Next.

    The RMI information is stored in the rmi.xml file available under ORACLE_HOME/j2ee/home/config.

  8. Click Test Connection. The Success! message appears, as shown in Figure 12-20. Click Finish. If the test fails, you may need to revise your connection information.

    Figure 12-20 Server Connection Successful

    Description of Figure 12-20 follows
    Description of "Figure 12-20 Server Connection Successful"

Now include this connection in the deployment profile required to deploy your portlet, as described in Section 12.2.1.2, "Creating the WebCenter Application WAR Deployment Profile".

12.2.6.2.2 Deploying Your WebCenter Application to Standalone OC4J

In this section, you will use the connection details you defined in Section 12.2.6.2.1, "Defining Standalone OC4J Connection Details"to deploy your application to your standalone OC4J. To use this connection, you must configure your deployment profile, as discussed in Section 12.2.1, "Packaging Your WebCenter Application".

Note:

When deploying a WebCenter application to a standalone OC4J instance, the Predeployment tool runs under the cover. For information about the Predeployment tool, see Section 12.2.2, "Predeploying Your WebCenter Application".

To deploy your application to the standalone OC4J instance, the OC4J must be running on the same computer as Oracle JDeveloper as both Oracle JDeveloper and OC4J require access to the MDS directory that is specified at deployment time. If you choose to deploy your target EAR file from a shared MDS path, that is, a network mounted drive, then it is treated as a local drive to the file system. So, the stored MDS path includes the path of the mounted drive from the system at which you plan to deploy. Hence, to use it in other locations, the target EAR file should be deployed there. Similarly, if you change the location of the MDS, all instances must be redeployed. While deploying an application, the MDS path can be modified. However, producer URLs cannot be changed in this type of deployment.

When you deploy an external application to a standalone OC4J instance using Oracle JDeveloper, user credentials entered while testing the application are not deployed.

To deploy your application, perform the following steps:

  1. From the Applications Navigator, right-click name.deploy under the Resources folder and select the targeted connection. The Select Target MDS Path window is displayed, as shown in Figure 12-21.

    Figure 12-21 Select Target MDS Path Window

    Description of Figure 12-21 follows
    Description of "Figure 12-21 Select Target MDS Path Window"

  2. Click Browse to select the MDS directory and click OK.

    If the directory you specify does not exist, Oracle JDeveloper creates it for you.

    Caution:

    To avoid browser access to the MDS content, always specify the MDS path to be in a directory that is outside the Web content root. Additionally, always create the MDS repository for your deployment outside the working directory for your application. Keeping separate MDS directories for development and deployment will not only avoid confusion but will prevent content in your application's source MDS repository from being overwritten.

    EAR files are generated and uploaded to the standalone OC4J. EAR files contain a number of configuration (.xml files) and all the files and libraries used by the application.

  3. The Configure Application window is displayed, as shown in Figure 12-22. Click OK.

    Figure 12-22 Configure Application Window

    Description of Figure 12-22 follows
    Description of "Figure 12-22 Configure Application Window"

When the deployment is successful, the page displays in the browser.

Migrating Security Information

To migrate security information to a standalone OC4J, see the procedure in Section 12.2.4.3, "Using the JAZN Migration Tool". This section contains the syntax to migrate security-related data from XML to XML, as shown in Example 12-13.

12.3 Deploying Your WebCenter Application with WebCenter Ant Tasks

This section provides an overview of WebCenter Ant Tasks in Oracle WebCenter Framework and describes how to use Ant Tasks to automate deployment of WebCenter applications.

This section covers the following:

12.3.1 Overview of WebCenter Ant Tasks

This section describes the following Another neat tool (Ant) tasks to automate creation of a config file, migration of JAZN data, predeployment of an EAR file, and export and import of customizations:

The WebCenter Ant Tasks discussed here must be used with Apache Ant version 1.6.5, which is distributed for free. For information and most recent Apache Ant product documentation, see http://ant.apache.org/manual/

webcenter:generateConfigTemplate

This task generates a configuration file template and populates it with IDs of the producer connections that are used in your WebCenter application. The generated template can then include MDS path and provider remapping details. Example 12-16 describes syntax of the generateConfigTemplate task. You must create a configuration template before using the tasks described later in this section.

Example 12-16 webcenter:generateConfigTemplate

<webcenter:generateConfigTemplate ear="Source ear file" file="Name of the config file." />

Note:

This task generates a configuration file that contains the default MDS path. You must modify this path to specify preferred MDS location.

webcenter:preDeploy

This task is used to predeploy your WebCenter application. It creates a targeted EAR file, which can be deployed to a local application server or a standalone OC4J. The configuration file must contain MDS path and remapping of providers, if any. In addition, a profile name must be specified even if there is only one profile, because this Ant task does not create a default profile like the Predeployment tool does.Example 12-17 describes syntax of the webcenter:preDeploy task.

Example 12-17 webcenter:preDeploy

<webcenter:predeploy sourceEAR="Source ear file."
                  targetEAR="Targeted ear file."
                  config="Configuration file with MDS path and provider remapping
                  details."
                  profile="Profile name to use from the config file."
</webcenter:preDeploy>

See Also:

For more information, see Oracle Containers for J2EE Deployment Guide and Section 12.2.2.2, "Predeploying WebCenter Applications and JCR Adapter-based Applications"

webcenter:exportMdsData

This task enables export of MDS data from a deployed application into a customizations export archive file. Example 12-18 describes syntax of the webcenter:exportMdsData task.

Example 12-18 webcenter:exportMdsData

<webcenter:exportMdsData ear="Target ear file."
                  deployedApp="Deployed application from which to export data."
                  mdsPath="MDS path of the jdev application."
                  connectionPath="Path to connections.xml."/>

webcenter:importMdsData

This task enables import of customizations from a deployment application into your customizations archive file that was previously exported. Example 12-19 describes syntax of the webcenter:importMdsData task.

Example 12-19 webcenter:importMdsData

<webcenter:importMdsData ear="Source ear file" 
                deployedApp="Import from deployed application into your EAR."/>

webcenter:generateMdsExportSet

This task enables the export of design time customizations made to portlets in a WebCenter application to a specified file system path. Example 12-20 describes syntax of the webcenter:generateMdsExportSet task.

Example 12-20 webcenter:generateMdsExportSet

<webcenter:generateMdsExportSet applicationPath="Path to the WebCenter application root, 
for example, C:\JDeveloper\mywork\MyApplication." targetPath="File system location to store generated export set."/>

12.3.2 Preparing to Use Ant Tasks

The following sections describe prerequisites for Ant tasks and procedures to meet those prerequisites:

12.3.2.1 Incorporating Ant Tasks in Your Oracle WebCenter Framework

The WebCenter installation includes Ant 1.6.5 and the files for the WebCenter Ant tasks. Before you can use the Ant tasks, you must incorporate them into your environment. To do so, perform the following steps:

  1. Set ORACLE_HOME environment variable by running the following syntax:

    setenv ORACLE_HOME ORACLE_HOME/oc4j
    
  2. Update CLASSPATH environment variable to include ant/lib directory by running to following syntax:

    setenv CLASSPATH ${CLASSPATH}:ORACLE_HOME/oc4j/ant/lib
    
  3. Set ANT_HOME by running the following syntax:

    On UNIX:

    setenv ANT_HOME ORACLE_HOME/ant
    

    On Windows

    set ANT_HOME=ORACLE_HOME\ant
    

Note:

You must use the ant command located in ORACLE_HOME/ant/bin to ensure that the libraries in ORACLE_HOME/ant/lib are loaded. Keep this in mind when you define variables, such as ANT_HOME. Invoking the ant command from any other directory may not load the appropriate libraries successfully.

12.3.2.2 Installing Ant Tasks

Ant tasks in WebCenter Framework are available out-of-the-box in the OC4J instances that are installed as part of Oracle Application Server. To use these Ant tasks on a standalone OC4J instance, Oracle Application Server 10.1.3.1.0 or earlier, or a third-party application server, you must first run the Oracle ADF Runtime installer to add the following files:

  • <OC4J_HOME>/ant/lib/ant-oracle-adfp.jar

  • <OC4J_HOME>/adfp/utilities/ant-adfp-classes.jar

  • <OC4J_HOME>/adfp/utilities/ant-oracle-adfp.xml

Caution:

Do not run the ADF Runtime installer on an Oracle Application Server 10.1.3.2.0 instance as you may get errors and will not be able to restart the application server instance.

A visual check is recommended to ensure that the Oracle ADF Runtime installer has run properly and Ant jars exist in appropriate directories.

If you deploy from an OC4J_HOME instance using the same build file that you used in Oracle JDeveloper, then make sure that the following code excerpt is still valid:

<import file="ORACLE_HOME/adfp/utilities/ant-oracle-adfp.xml"/>

You can make it valid in the following ways:

  • If you are using environment variables, then set the ORACLE_HOME environment variable to point to OC4J_HOME.

  • If you are using hard coded path, then update it appropriately.

12.3.3 Deploying Your WebCenter Application with Ant Tasks

This section covers the following procedures:

12.3.3.1 Namespacing Class Definitions

To use Ant tasks, namespace class definitions in your build.xml file, as shown in the following example:

<project name="Project1" default="all" xmlns:webcenter="antlib:oracle.adfp">

xmlns attribute of project enables you to import WebCenter Ant Tasks.

The webcenter prefix is customizable and users can change it as required. If this prefix is changed, all the deployment tasks must start with new prefix, for example <prefix>:deploy, <prefix>:import, and so on.

12.3.3.2 Creating the build.xml File

To deploy your WebCenter application with Ant tasks, you must first create a build.xml file containing Ant tasks. This build.xml file contains a project and targets. Targets contain task elements and each task element of the build file can have an id attribute, which can later be referred to by the unique value supplied to this. For information about WebCenter Ant tasks, see Section 12.3.1, "Overview of WebCenter Ant Tasks".

To create the build.xml file, perform the following steps:

  1. In Oracle JDeveloper, go to the Application Navigator and select your project. Then, from the File menu select New. The New Gallery dialog box is displayed.

  2. Under General select Ant, and under Items select Empty Buildfile, as shown in Figure 12-23.

    Figure 12-23 New Gallery - Empty Buildfile

    Description of Figure 12-23 follows
    Description of "Figure 12-23 New Gallery - Empty Buildfile"

  3. Click OK. The Create Ant Buildfile dialog box is displayed, as shown in Figure 12-24.

    Figure 12-24 Create Ant Buildfile

    Description of Figure 12-24 follows
    Description of "Figure 12-24 Create Ant Buildfile"

  4. Click OK. The build.xml file is created under the Resources folder, as shown in Figure 12-25.

    Note:

    build.xml is a typical name given to any WebCenter Ant build file and it must remain unchanged.

    Figure 12-25 Application Navigator - build.xml

    Description of Figure 12-25 follows
    Description of "Figure 12-25 Application Navigator - build.xml"

  5. Under Resources, double-click the build.xml file to open it.

  6. In the Source mode, enter Ant tasks, as described in Example 12-21, with appropriate values.

    Example 12-21 Sample Build File

    <?xml version="1.0" encoding="US-ASCII" ?>
    <project name="Project1" default="deploy2server" xmlns:webcenter="antlib:oracle.adfp"
                                           xmlns:oracle="antlib:oracle">
      <property name="ORACLE_HOME" value="c:/jdev"/>
      <import file="${ORACLE_HOME}/adfp/utilities/ant-oracle-adfp.xml"/>
      <property name="proj" value="c:/jdev/jdev/mywork/Application1/Project1/deploy"/>
    
    <!-Config Task. This task generates a configuration file template. -->
    
      <target name="config">
        <webcenter:generateConfigTemplate ear="${proj}/webcenterArchive1.ear"
                        file="${proj}/config.xml"/>
      </target>
    
      <!--Predeploy Task. This tasks creates a targeted EAR from a generic EAR. -->
    
    <target name="predeploy">
        <webcenter:predeploy sourceEAR="${proj}/webcenterArchive1.ear"
                        targetEAR="${proj}/target.ear"
                        config="${proj}/config.xml"
                        profile="Template"/>
      </target>
    
    <!--Deploy to Server Task. This task deploys the targeted EAR to the specified server. -->
      <target name="deploy2server" depends="predeploy">
        <oracle:deploy deployerUri="deployer:oc4j:localhost:23791"
                       userid="oc4jadmin"
                       password="welcome1"
                       file="${proj}/target.ear"
                       deploymentName="webcenterArchive1"
                       bindAllWebApps="default-web-site"
                       logFile="${proj}/deploy.log"/>
    
    <!-- Export and Import tasks Note: Do not run export and import tasks from Oracle JDeveloper. 
    Run these tasks in stage/production environment instead-->
    
      </target>
      <target name="export">
        <webcenter:exportMdsData ear="${proj}/export.ear"
                        deployedApp="C:/jdev/j2ee/home/applications/webcenterArchive1"/>
      </target>
      <target name="import">
        <webcenter:importMdsData ear="${proj}/export.ear"
                        deployedApp="C:/jdev/j2ee/home/applications/webcenterArchive1"/>
    
    <!--FTP Task.-->
    
      </target>
      <target name="ftp_mds">
    <ftp server="localhost" remotedir="C:/tmp"
             userid="ftpuser" password="welcome1"
             binary="no" verbose="yes">
            <fileset dir="C:/tmp/MDS"/>
        </ftp>
      </target>
    
    <!-- Note: You can use an FTP Ant task together with the oracle:deploy task to 
    copy the MDS directory to a remote OC4J and deploy the application.-->
      
    <target name="ftp_and_deploy" depends="ftp_mds">
          <webcenter:deploy deployerUri="deployer:oc4j:localhost:23791"
                 userid="oc4jadmin"
                 password="welcome1"
                 file="${proj}/target.ear"
                 deploymentName="webcenterArchive1"
                 bindAllWebApps="default-web-site"
                 logFile="${proj}/deploy.log"/>
      </target>
    </project>
    
  7. Save the build.xml file.

12.3.3.3 Deploying with the build.xml File

To deploy your WebCenter application using the build.xml file, run the ant command from the directory that contains the build.xml file. For instance, if you run the ant predeploy command based on Example 12-21, it will call webcenter:predeploy, which will create the targeted EAR file from the generic EAR file. Then, webcenter:deploy will deploy the targeted EAR file to the OC4J instance specified in the build.xml file. oracle:deploy is the J2EE Ant task and it is available out-of-the-box.

12.4 Transporting Customizations Between Environments

You can export and import customizations made to pages and portlets (PDK-Java and WSRP version 2 producers) of an already deployed application by running the Predeployment tool in the Export and Import modes. The following sections describe the procedures to export customizations from the stage environment and import them into the production environment:

12.4.1 Exporting Customizations

The Predeployment tool exports customizations to a customizations export archive file. This customizations export archive file is later imported into the MDS directory in the production environment.

To export customizations from the stage environment to the production environment, run the following syntax:

ORACLE_HOME/jdk/bin/java -jar adfp/lib/portlet-client-deploy.jar -export -deployedapp <deployed_app_path> -target <targetedEAR>

where:

targetedEAR is the name of the customizations export archive file created by the export process. It contains all the customizations that can be imported into the same application deployed in another instance.

deployed_app_path is the location of the already deployed application from which you are exporting customizations, for example, ORACLE_HOME/j2ee/home/applications/YourApplication.

The Predeployment tool uses the customizations archive file that was exported during the export, to import customizations into the production environment.

12.4.2 Importing Customizations

You can import customizations that you exported to the customizations archive file, into your production environment. To import these customizations to your production environment, perform the following steps:

  1. In the command prompt, run the following syntax:

    ORACLE_HOME/jdk/bin/java -jar adfp/lib/portlet-client-deploy.jar -import -source <genericEAR> -deployedapp <deployed_app_path> 
    

    where:

    genericEAR is the customizations import archive file that was previously exported, which was created in the Export mode. It contains the customizations to be imported into the deployed application.

    deployed_app_path is the location of the already deployed application to which you want to import the customizations, for example, ORACLE_HOME/j2ee/home/applications/YourApplication.

  2. If your WebCenter application also includes WSRP version 2 producers, then you must restart OC4J to see the customizations.

Customizations are now imported into your application in the production environment.

12.5 Updating Credentials in a Deployed Application

WebCenter applications persist secure properties associated with connections (stored in connections.xml) in an encrypted format in the credential-store.xml file. In design time, you can update these secure properties in Oracle JDeveloper, but to update secure properties postdeployment on the target system, you must use the Credentials Java Management Extension (JMX) MBean. This MBean can be accessed by running Application Server Control Console. Changes made to the connections' secure properties are updated in the credential-store.xml file.

Including the Credentials MBean in Your Application

To use the Credentials MBean, you must first ensure that it is available in your application and that your application is running. The MBean is included in the ORACLE_HOME/BC4J/lib/oracle.extapp.runtime.jar file that is part of your Oracle JDeveloper installation. In an Oracle Application Server installation, this JAR file is available in the ORACLE_HOME/adfp/lib directory.

The Credentials MBean is only available to applications that include the Oracle ADF authentication servlet. The Oracle ADF authentication servlet is already added to your application if you implemented security by using the Oracle ADF Security Wizard in Oracle JDeveloper.

For applications that do not use Oracle ADF Security for user authentication, but include connections with secure properties, you can add the AuthenticationServlet to your application manually by including the following XML code excerpt in your web.xml file:

<servlet>
   <servlet-name>AuthenticationServlet</servlet-name>
   <servlet-class>
      oracle.adf.share.security.authentication.AuthenticationServlet
   </servlet-class>
   <load-on-startup>0</load-on-startup>
</servlet>

Restart your Oracle Application Server instance after updating the web.xml file.

To ensure that the AuthenticationServlet is loaded when your application is started, it is necessary to include the <load-on-startup> element even though the application may never use it.

Note:

The MBean is available only when your application is running.

Updating Secure Connections Properties

To update secure connections properties using the Credentials MBean, perform the following steps:

  1. Log in to the Application Server Control Console. The Home page is displayed.

  2. Select the OC4J instance to which your application is deployed.

  3. Click the Applications tab and navigate to the Application MBeans page as shown in Figure 12-26.

    Figure 12-26 Applications Tab

    Description of Figure 12-26 follows
    Description of "Figure 12-26 Applications Tab"

  4. From the list of MBean names in the left-hand frame, shown in Figure 12-27, select Credentials.

    The right-hand frame displays a description of this MBean and the Operations tab with the four operations that you can perform using this MBean.

    Figure 12-27 Credentials MBean Page

    Description of Figure 12-27 follows
    Description of "Figure 12-27 Credentials MBean Page"

  5. Select the listConnections operation to list all connections that have at least one secured property.

  6. On the Operation: listConnections page, click Invoke Operation to obtain a list of such connections. Write down the connection names, because you will need them to perform operations later.

  7. Click Return.

  8. Select the listCredentials operation on the MBean: Connections: Credentials page to list the credentials for any of the connections you wrote down in the previous step. The Operation: listCredentials page is displayed, as shown in Figure 12-28.

    Figure 12-28 listCredentials Operation Page

    Description of Figure 12-28 follows
    Description of "Figure 12-28 listCredentials Operation Page"

  9. Specify the connection name and click Invoke Operation to view the secured properties for that connection. All secure properties for the selected connection are listed as shown in Figure 12-29. Write down the credential names, because you will need them to perform the operations later.

    Note:

    To ensure a high level of security, the MBean does not expose the existing credential values.

    Figure 12-29 listCredentials Operation Page with Secure Properties Listed

    Description of Figure 12-29 follows
    Description of "Figure 12-29 listCredentials Operation Page with Secure Properties Listed"

  10. Click Return.

  11. Select the setCredential operation on the MBean: Connections: Credentials page to update the secure properties of a connection. The Operation: setCredentials page is displayed, as shown in Figure 12-30.

    Figure 12-30 setCredential Operation Page Used for Setting a Secured Property Value

    Description of Figure 12-30 follows
    Description of "Figure 12-30 setCredential Operation Page Used for Setting a Secured Property Value"

  12. Specify the connection name, secure property name, and new property value, and click Invoke Operation to change the value of a secured property. The resulting page shows that the secured property was updated successfully, as shown in Figure 12-31.

    Figure 12-31 setCredentials Operation Results Page

    Description of Figure 12-31 follows
    Description of "Figure 12-31 setCredentials Operation Results Page"

    Note:

    Ensure that you specify the connection and property name correctly. The property names and values are case-sensitive.
  13. Click Return.

  14. Select the resetCredential operation on the MBean: Connections: Credentials page to reset any of the secure properties of a connection.

  15. Specify the connection name, secure property name and click Invoke Operation to reset the value of a secure property.

  16. Repeat steps 4 to 15 as required. Changes you make to secure properties are committed immediately.

    Note:

    You can perform the four operations in any order. There is no sequence to be followed.

Copying the credential-store.xml File back to the Development Environment

When you update secure credentials in the deployed application, internally the credential-store.xml file is updated with this information. However, these credentials are lost when the application is redeployed from the development environment. This is because the credential-store.xml file in the deployed application is overwritten when the application is redeployed. To ensure that the credentials you updated earlier are available in the redeployed application, you must copy the credential-store.xml file back to the development environment so that it can be repackaged with the application to be redeployed. However, credentials entered or modified after copying the file to the development environment and before redeploying the application will be lost.

In the development environment, you may have to update some credentials using appropriate wizards, as those credentials can be specific to stage and production environments. In other words, you must update credentials that you updated using the MBean in the stage and production environments, to original values so that they work in the development environment. Additionally, you must update the same credentials again after deployment, using the MBean.

12.6 Cloning WebCenter Applications

Cloning is the process of copying an existing installation to a different location while preserving its configuration. This section describes the following scenarios for cloning WebCenter applications:

12.6.1 Expanding an Oracle Application Server Cluster

In this scenario, you create a new or another node in a cluster or a cluster-ready setup. All settings such as MDS, producer preferences, connections, and load balancing router (LBR) configuration remain unchanged.

The following are the perquisites for expanding an Oracle Application Server cluster:

  • The Oracle home must be set up for clustering.

  • The MDS location must be shared.

  • The portlet producer preference stores (file or database) must be shared.

To use cloning to expand an Oracle Application Server cluster, follow the steps in section 9.7 Example: Using Cloning to Expand an Oracle Application Server Cluster of chapter titled Cloning Application Server Middle-Tier Instances" in Oracle Application Server Administrator's Guide. As you are going to deploy the cloned target instance in exactly the same environment as the cloned source instance, it is assumed that none of the external dependencies shown in Figure 12-1, such as portlet producer end-points, have changed. Following the cloning steps outlined in the chapter titled Cloning Application Server Middle-Tier Instances" in Oracle Application Server Administrator's Guide will therefore be enough.

12.6.2 Using Cloning to Move from Stage to Production

As you can see in Figure 12-1, WebCenter applications typically have a number of external dependencies, such as, portlet producers and content repositories. When you move from stage to production, the configuration details for these external dependencies may change. For example, the database connection details for Oracle Content Database (Oracle Content DB) may be different in the production environment.

To use cloning for moving from stage to production, perform the following procedures:

  1. Clone the Oracle home as described in chapter titled Cloning Application Server Middle-Tier Instances" in Oracle Application Server Administrator's Guide.

  2. Perform the following procedures, if they are applicable to your environment:

  3. Export portlet and page customizations from stage to production, as described in Section 12.4, "Transporting Customizations Between Environments". These customizations are first exported to a customizations export archive file in the stage environment. Then, this customizations archive file is imported into the MDS directory in the production environment.

  4. Test your cloned application to see if it is working as expected.

12.7 Configuring Your WebCenter Application to Run in a Distributed Environment

For information about configuring your WebCenter application to run in a distributed environment, see Oracle Application Server Enterprise Deployment Guide and chapter titled "Active-Active Topologies" in Oracle Application Server High Availability Guide.

12.8 Undeploying Your WebCenter Application

You can undeploy your application either using Application Server Control Console or the command-line interface. It is recommended that you use Application Server Control Console; however, for your better understanding, this sections also describes the syntax to undeploy your WebCenter application using the command-line interface.

Read the following sections to learn the procedures to undeploy your WebCenter application:

12.8.1 Undeploying Your WebCenter Application Using Application Server Control Console

To undeploy your application, perform the following steps:

  1. Log in to the Application Server Control Console. The Home page is displayed.

  2. Click the Applications tab. The Applications page is displayed, as shown in Figure 12-32.

    Figure 12-32 Applications Page in Application Server Control Console

    Description of Figure 12-32 follows
    Description of "Figure 12-32 Applications Page in Application Server Control Console "

  3. Click Undeploy. The Undeploy Application warning page is displayed, as shown in Figure 12-33.

    Figure 12-33 Undeploy Page in Oracle Enterprise Manager

    Description of Figure 12-33 follows
    Description of "Figure 12-33 Undeploy Page in Oracle Enterprise Manager "

  4. Click Yes to undeploy your application. The undeployment Confirmation page is displayed, as shown in Figure 12-34.

    Figure 12-34 Undeploy Confirmation Page in Application Server Control Console

    Description of Figure 12-34 follows
    Description of "Figure 12-34 Undeploy Confirmation Page in Application Server Control Console "

    Your application is undeployed now. It is no longer displayed under the Applications tab. However, the MDS directory of your application is still available.

12.8.2 Undeploying Your WebCenter Application Using the Command Line

To undeploy your application using the command line, run the following:

ORACLE_HOME/jdk/bin/java -jar admin.jar ormi://localhost/<ormi port> <admin_username> <admin_pwd> -undeploy 
-deploymentName <deployment_name> <true|false>