Skip Headers
Oracle® Fusion Middleware Java EE Developer's Guide for Oracle Application Development Framework
11g Release 2 (11.1.2.2.0)

Part Number E17272-03
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
PDF · Mobi · ePub

9 Deploying an ADF Java EE Application

This chapter describes how to deploy Oracle ADF Java EE applications to a target application server. It describes how to create deployment profiles, how to create deployment descriptors, and how to load ADF runtime libraries. It includes instructions for running an application in the Integrated WebLogic Server as well as deploying to a standalone Oracle WebLogic Server or IBM WebSphere Application Server.

This chapter includes the following sections:

9.1 Introduction to Deploying ADF Java EE Web Applications

Deployment is the process of packaging application files as an archive file and transferring it to a target application server. You can use JDeveloper to deploy Oracle ADF Java EE web applications directly to the application server (such as Oracle WebLogic Server or IBM WebSphere Application Server), or indirectly to an archive file as the deployment target, and then install this archive file to the target server. For application development, you can also use JDeveloper to run an application in Integrated WebLogic Server. JDeveloper supports deploying to server clusters. You cannot use JDeveloper to deploy to individual Managed Servers within a cluster.

Figure 9-1 shows the flow diagram that describes the overall deployment process. Note that preparing the target application server for deployment by installing the ADF runtime is described in the Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework

The following diagram contains clickable links.

Figure 9-1 Deployment Overview Flow Diagram

Deployment overview flow diagram Run and test using Integrated WebLogic Server Prepare the Application Deploy the Application Postdeployment tasks
Description of "Figure 9-1 Deployment Overview Flow Diagram"

Note:

Normally, you use JDeveloper to deploy applications for development and testing purposes. If you are deploying Oracle ADF Java EE web applications for production purposes, you can use Enterprise Manager or scripts to deploy to production-level application servers.

For more information about deployment to later-stage testing or production environments, see the Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework.

ADF Java EE applications are based on standardized, modular components and can be deployed to the following application servers:

JSF applications that contain ADF Faces components have a few additional deployment requirements:

You can use JDeveloper to:

9.1.1 Developing Applications with Integrated WebLogic Server

If you are developing an application in JDeveloper and you want to run the application in Integrated WebLogic Server, you do not need to perform the tasks required for deploying directly to Oracle WebLogic Server or to an archive file. JDeveloper has a default connection to Integrated WebLogic Server and does not require any deployment profiles or descriptors. Integrated WebLogic Server has a preconfigured domain that includes the ADF libraries, as well as the -Djps.app.credential.overwrite.allowed=true setting, that are required to run Oracle ADF applications. You can run an application by choosing Run from the JDeveloper main menu.

9.1.2 Developing Applications for Standalone Application Server

Typically, you test and develop your application by running it in Integrated WebLogic Server. You can then test the application further by deploying it to standalone Oracle WebLogic Server in development mode to more closely simulate the production environment.

In general, you use JDeveloper to prepare the application or project for deployment by:

  • Creating a connection to the target application server

  • Creating deployment profiles (if necessary)

  • Creating deployment descriptors (if necessary)

  • Updating application.xml and web.xml to be compatible with Oracle WebLogic Server (if required)

  • Enabling the application for Real User Experience Insight (RUEI) in web.xml (if desired)

  • Migrating application-level security policy data to a domain-level security policy store

  • Configuring the Oracle Single Sign-On (Oracle SSO) service and properties in the domain jps-config.xml file when you intend the web application to run using Oracle SSO

You must already have an installed application server. For Oracle WebLogic Server, you can use the Oracle 11g Installer or the Oracle Fusion Middleware 11g Application Developer Installer to install one. For other applications servers, follow the instructions in the applications server documentation to obtain and install the server.

You also must prepare the application server for ADF application deployment. For more information, see the "Preparing the Standalone Application Server for Deployment" section of the Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework.

  • Installing the ADF runtime into the application server installation:

    • For WebLogic Server

      • If you installed Oracle WebLogic Server together with JDeveloper using the Oracle 11g Installer for JDeveloper, the ADF runtime should already be installed.

      • If the ADF runtime is not installed and you want to use Oracle Enterprise Manager to manage standalone ADF applications (which are applications without Oracle SOA Suite or Oracle WebCenter components), use the Oracle Fusion Middleware 11g Application Developer Installer. This installer will install the necessary Oracle Enterprise Manager components into the Oracle WebLogic installation.

      • If the ADF runtime is not installed and you do not need to install Enterprise Manager, use the Oracle 11g Installer for JDeveloper.

    • For WebSphere

  • Extending Oracle WebLogic Server domains or WebSphere Cells to be ADF-compatible using the ADF runtime

  • For WebLogic, setting the Oracle WebLogic Server credential store overwrite setting as required (-Djps.app.credential.overwrite.allowed=true setting)

  • Creating a global JDBC data source for applications that require a connection to a data source

After the application and the application server have been prepared, you can:

  • Use JDeveloper to:

    • Directly deploy to the application server using the deployment profile and the application server connection.

    • Deploy to an EAR file using the deployment profile. For ADF applications, WAR and MAR files can be deployed only as part of an EAR file.

  • Use Enterprise Manager, scripts, or the application's administration tool to deploy the EAR file created in JDeveloper. For more information, see the Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework.

9.2 Running a Java EE Application in Integrated WebLogic Server

JDeveloper is installed with Integrated WebLogic Server, which you can use to test and develop your application. For most development purposes, Integrated WebLogic Server will suffice. When your application is ready to be tested, you can select the run target and then choose the Run command from the main menu.

Note:

The first time you run an application in Integrated WebLogic Server, the Configure Default Domain dialog appears for you to define an administrative password for the new domain.

When you run the application target, JDeveloper detects the type of Java EE module to deploy based on artifacts in the projects and workspace. JDeveloper then creates an in-memory deployment profile for deploying the application to Integrated WebLogic Server. JDeveloper copies project and application workspace files to an "exploded EAR" directory structure. This file structure closely resembles the EAR file structure that you would have if you were to deploy the application to an EAR file. JDeveloper then follows the standard deployment procedures to register and deploy the "exploded EAR" files into Integrated WebLogic Server. The "exploded EAR" strategy reduces the performance overhead of packaging and unpackaging an actual EAR file.

In summary, when you select the run target and run the application in Integrated WebLogic Server, JDeveloper:

Note:

JDeveloper ignores the deployment profiles that were created for the application when you run the application in Integrated WebLogic Server.

The application will run in the base domain in Integrated WebLogic Server. This base domain has the same configuration as a base domain in a standalone WebLogic Server instance. In other words, this base domain will be the same as if you had used the Oracle Fusion Middleware Configuration Wizard to create a base domain with the default options in a standalone WebLogic Server instance.

JDeveloper will extend this base domain with the necessary domain extension templates, based on the JDeveloper technology extensions. For example, if you have installed JDeveloper Studio, JDeveloper will automatically configure the Integrated WebLogic Server environment with the ADF runtime template (JRF Fusion Middleware runtime domain extension template).

You can explicitly create a default domain for Integrated WebLogic Server. You can use these domains to run and test your applications. Open the Application Server Navigator, right-click IntegratedWebLogicServer and choose Create Default Domain.

JDeveloper has a default connection to Integrated WebLogic Server. You do not need to create a connection to run an application. If you do want to manually create an application server connection to Integrated WebLogic Server, use the instructions in Section 9.3.1, "How to Create a Connection to the Target Application Server," to create the connection, selecting Integrated Server instead of Standalone Server in Step 2.

9.2.1 How to Run an Application in Integrated WebLogic Server

You can test an application by running it in Integrated WebLogic Server. You can also set breakpoints and then run the application within the ADF Declarative Debugger.

To run an application in Integrated WebLogic Server:

  1. In the Application Navigator, select the project, unbounded task flow, JSF page, or file as the run target.

  2. Right-click the run target and choose Run or Debug.

  3. The Configure Default Domain dialog displays the first time your run your application and start a new domain in Integrated WebLogic Server. Use the dialog to define an administrator password for the new domain. Passwords you enter can be eight characters or more and must have a numeric character.

9.2.2 How to Run an Application with Metadata in Integrated WebLogic Server

When an application is running in Integrated WebLogic Server, the metadata archive (MAR) profile itself will not be deployed to a repository, but a simulated Oracle Metadata Services (MDS) repository will be configured for the application that reflects the metadata information contained in the MAR. This metadata information is simulated, and the application runs based on this location in source control.

By default, only the customizations in ADF view and ADF Model are included in the MAR. If the Java EE application has customizations in other directories, you must create a custom MAR profile that includes these directories.

Any customizations or documents created by the application that are not configured to be stored in other MDS repositories are written to this simulated MDS repository directory. For example, if you customize an object, the customization is written to the simulated MDS repository. If you execute code that creates a new metadata object, then this new metadata object is also written to the same location in the simulated MDS repository. You can keep the default location for this directory (ORACLE_HOME\jdeveloper\systemXX.XX\o.mds.dt\adrs\Application\AutoGeneratedMar\mds_adrs_writedir), or you can set it to a different directory. You also have the option to preserve this directory across different application runs, or to delete it before each application run.

If your workspace has different working sets, only the metadata from the projects defined in the working set and their dependent projects will be included in the MAR. You can view and change a project's dependencies by right-clicking the project in the Application Navigator, choosing Project Properties, and then selecting Dependencies. For instance, an application may have several projects but workingsetA is defined to be viewcontroller2 and viewcontroller5; and viewcontroller5 has a dependency on modelproject1. When you run or debug workingsetA, only the metadata for viewcontroller2, viewcontroller5, and modelproject1 will be included in the MAR for deployment.

There should already be a MAR profile, either generated automatically by JDeveloper, or manually generated by a user.

To deploy the MAR profile to Integrated WebLogic Server:

  1. In the Application Navigator, right-click the application and choose Application Properties.

  2. In the Application Properties dialog, expand Run and choose MDS.

  3. In the Run MDS page:

    • Select the MAR profile from the MAR Profile dropdown list

    • Enter a directory path in Override Location if you want to customize the location of the simulated MDS repository.

    • Select the Directory Content option. You can chose to preserve the customizations across application runs or delete customizations before each run.

    Select the MAR profile from the MAR Profile dropdown list. Figure 9-2 shows Demometadata1 selected as the MAR profile.

    Figure 9-2 Setting the Run MDS options

    Application roperties Run MDS options

9.3 Preparing the Application

Before you deploy an ADF application to a standalone Oracle WebLogic Server instance, you must perform prerequisite tasks within JDeveloper to prepare the application for deployment.

Figure 9-3 show the process flow to prepare the application for deployment. After the application has been prepared and the application server has been prepared as described in the Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework, you can proceed to deploy the application as described in Section 9.4, "Deploying the Application."

The following diagram contains clickable links.

Figure 9-3 Preparing the Application for Deployment Flow Diagram

Preparing the Application for Deployment Flow Diagram Create application server connection Create deployment profiles Create deployment descriptors Enable RUEI monitoring (optional) Enable ADF MBeans (optional) Enable ADF Security
Description of "Figure 9-3 Preparing the Application for Deployment Flow Diagram"

9.3.1 How to Create a Connection to the Target Application Server

You can deploy applications to Oracle WebLogic Server via JDeveloper application server connections. If your application involves customization using MDS, you should register your MDS repository with the Oracle WebLogic Server domain.

For more information about registering MDS, see the Oracle Application Server Administrator's Guide.

To create a connection to an application server:

  1. Launch the Application Server Connection wizard.

    You can:

    • In the Application Server Navigator, right-click Application Servers and choose New Application Server Connection.

    • In the New Gallery, expand General, select Connections and then Application Server Connection, and click OK.

    • In the Resource Palette, choose New > New Connections > Application Server.

  2. In the Create AppServer Connection dialog Usage page, select Standalone Server.

  3. In the Name and Type page, enter a connection name.

  4. In the Connection Type dropdown list, choose:

    • WebLogic 10.3 to create a connection to Oracle WebLogic Server

    • WebSphere Server 7.x to create a connection to IBM WebSphere Server

  5. Click Next.

  6. On the Authentication page, enter a user name and password for the administrative user authorized to access the application server.

  7. Click Next.

  8. On the Configuration page, enter the information for your server:

    For WebLogic:

    • The Oracle WebLogic host name is the name of the WebLogic Server instance containing the TCP/IP DNS where your application (.jar,.war,.ear) will be deployed.

    • In the Port field, enter a port number for the Oracle WebLogic Server instance on which your application (.jar,.war,.ear) will be deployed.

      If you don't specify a port, the port number defaults to 7001.

    • In the SSL Port field, enter an SSL port number for the Oracle WebLogic Server instance on which your application (.jar,.war,.ear) will be deployed.

      Specifying an SSL port is optional. It is required only if you want to ensure a secure connection for deployment.

      If you don't specify an SSL port, the port number defaults to 7002.

    • Select Always Use SSL to connect to the Oracle WebLogic Server instance using the SSL port.

    • Optionally enter a WebLogic Domain only if Oracle WebLogic Server is configured to distinguish nonadministrative server nodes by name.

    For WebSphere:

    • In the Host Name field, enter the name of the WebSphere server containing the TCP/IP DNS where your Java EE applications (.jar, .war, .ear) are deployed. If no name is entered, the name defaults to localhost.

    • In the SOAP Connector Port field, enter the port number. The host name and port are used to connect to the server for deployment. The default SOAP connector port is 8879.

    • In the Server Name field, enter the name assigned to the target application server for this connection.

    • In the Target Node field, enter the name of the target node for this connection. A node is a grouping of Managed Servers. The default is machineNode01, where machine is the name of the machine the node resides on

    • In the Target Cell field, enter the name of the target cell for this connection. A cell is a group of processes that host runtime components. The default is machineNode01Cell, where machine is the name of the machine the node resides on.

    • In the Wsadmin script location field, enter, or browse to, the location of the wsadmin script file to be used to define the system login configuration for your IBM WebSphere application server connection. The default location is websphere-home/bin/wsadmin.sh for Unix/Linux and websphere-home/bin/wsadmin.bat for Windows.

  9. Click Next.

  10. If you have chosen WebSphere, the JMX page appears. On the JMX page, enter the JMX information (optional):

    Note:

    JMX configuration is optional and is not required for connecting to the WebSphere Application Server. JMX is only needed for deploying SOA applications.

    • Select Enable JMX for this connection to enable JMX.

    • In the RMI Port field, enter the port number of WebSphere's RMI connector port. The default is 2809.

    • In the WebSphere Runtime Jars Location field, enter or browse to the location of the WebSphere runtime JARs.

    • In the WebSphere Properties Location (for secure MBEAN access) field, enter or browse to the location of the file that contains the properties for the security configuration and the mbeans that are enabled. This field is optional.

  11. Click Next.

  12. If the SSl Signer Exchange Prompt dialog appears, click Y.

  13. On the Test page, click Test Connection to test the connection.

    JDeveloper performs several types of connections tests. The JSR-88 test must pass for the application to be deployable. If the test fails, return to the previous pages of the wizard to fix the configuration.

  14. Click Finish.

9.3.2 How to Create Deployment Profiles

A deployment profile defines the way the application is packaged into the archive that will be deployed to the target environment. The deployment profile:

  • Specifies the format and contents of the archive file that will be created

  • Lists the source files, deployment descriptors, and other auxiliary files that will be packaged

  • Describes the type and name of the archive file to be created

  • Highlights dependency information, platform-specific instructions, and other information

You need a WAR deployment profile for each web view-controller project that you want to deploy in your application. If you want to package seeded customizations or place base metadata in the MDS repository, you need an application-level metadata archive (MAR) deployment profile as well. For more information about seeded customizations, see the "Customizing Applications with MDS" section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework. If the application has customization classes, you need a JAR file for those classes and you need to add that JAR when you create the EAR file. If you are using EJB, you need an EJB JAR profile. Finally, you need an application-level EAR deployment profile and you must select the projects you want to include from a list, such as WAR and MAR profiles and customization classes JAR files. When the application is deployed, the EAR file will include all the projects that were selected in the deployment profile.

For Oracle ADF applications, you can deploy the application only as an EAR file. The WAR and MAR files that are part of the application should be included in the EAR file when you create the deployment profile.

9.3.2.1 Creating a WAR Deployment Profile

You will need to create a WAR deployment profile for each web-based project you want to package into the application. Typically, the WAR profile will include the dependent data model projects it requires.

To create WAR deployment profiles for an application:

  1. In the Application Navigator, right-click the web project that you want to deploy and choose New.

    You will create a WAR profile for each web project.

  2. In the New Gallery, expand General, select Deployment Profiles and then WAR File, and click OK.

    If you don't see Deployment Profiles in the Categories tree, click the All Features tab.

  3. In the Create Deployment Profile -- WAR File dialog, enter a name for the project deployment profile and click OK.

  4. In the Edit WAR Deployment Profile Properties dialog, choose items in the left pane to open dialog pages in the right pane. Configure the profile by setting property values in the pages of the dialog.

    • If you have customization classes in your application, they must be loaded from the EAR-level application class loader and not from the WAR. You will later add these customization classes to the EAR.

      By default, customization classes are added to the data model project's WAR class path. So for each WAR, you must exclude the customization classes.

      If you created your customization classes in an extension project of the application, be sure to deselect any customization class archive on the Library Dependencies page of the WAR deployment profile for each user interface project.

      If you created your customization classes in the data model project of the application, deselect any customization classes on the File Groups > WEB-INF/classes > Filters page of the WAR deployment profile for each user interface project. If you are using a customization.properties file, it should also be deselected.

    • You might also want to change the Java EE web context root setting (choose General in the left pane).

      By default, when Use Project's Java EE Web Context Root is selected, the associated value is set to the project name, for example, Application1-Project1-context-root. You need to change this if you want users to use a different name to access the application.

      If you are using custom JAAS LoginModule for authentication with JAZN, the context root name also defines the application name that is used to look up the JAAS LoginModule.

  5. Click OK to exit the Edit WAR Deployment Profile Properties dialog.

  6. Click OK again to exit the Project Properties dialog.

  7. Repeat Steps 1 through 7 for all web projects that you want to deploy.

9.3.2.2 Creating a MAR Deployment Profile

If you have seeded customizations or base metadata that you want to place in the MDS repository, you need to create a MAR deployment profile.

The namespace configuration under <mds-config> for MAR content in the adf-config.xml file is generated based on your selections in the MAR Deployment Profile Properties dialog.

Although uncommon, an enterprise application (packaged in an EAR) can contain multiple web application projects (packaged in multiple WARs), but the metadata for all these web applications will be packaged into a single metadata archive (MAR). The metadata contributed by each of these individual web applications can be global (available for all the web applications) or local to that particular web application.To avoid name conflicts for metadata with global scope, make sure that all metadata objects and elements have unique names across all the web application projects that form part of the enterprise application.To avoid name conflicts and to ensure that the metadata for a particular web application remains local to that application, you can define a web-app-root for that web application project.The web-app-root is an element in the adf-settings.xml file for a web application project. The adf-settings.xml file should be kept in the META-INF directory under the public_html directory for the web project. Example 9-1 shows the contents of a sample adf-settings.xml file.

Example 9-1 web-app-root Element in the adf-settings.xml File

<?xml version="1.0" encoding="UTF-8" ?>
 <adf-settings xmlns="http://xmlns.oracle.com/adf/settings"
 xmlns:wap="http://xmlns.oracle.com/adf/share/http/config">
    <wap:adf-web-config xmlns="http://xmlns.oracle.com/adf/share/http/config">
        <web-app-root rootName="order"/>
    </wap:adf-web-config>
</adf-settings>

In this example, the adf-settings.xml file has a web-app-root element that defines rootName as order.If your enterprise application has only one web application project, there is no need to define a web-app-root element. If your enterprise application has multiple web application projects, you should supply a web-app-root for all the web applications except one, without which the deployment will fail. For example, if you have web-application1, web-application2, and web-application3, two of these web application projects must define a web-app-root to preclude any name conflicts.

JDeveloper creates an auto-generated MAR when the Enable User Customizations and Across Sessions using MDS options are selected in the ADF View page of the Project Properties dialog or when you explicitly specify the deployment target directory in the adf-config.xml file.

By default, only the customizations in ADF view and ADF Model are included in the MAR. If the Java EE application has customizations in other directories, you must create a custom MAR profile that includes those directories.

Before you begin:

Create an MDS repository for your customization requirements to deploy metadata using the MAR deployment profile.

To create a MAR deployment profile:

  1. In the Application Navigator, right-click the application and choose New.

    You will create a MAR profile if you want to include customizations.

  2. In the New Gallery, expand General, select Deployment Profiles and then MAR File, and click OK.

    If you don't see Deployment Profiles in the Categories tree, click the All Features tab.

  3. In the Create Deployment Profile -- MAR File dialog, enter a name for the MAR deployment profile and click OK.

  4. In the Edit MAR Deployment Profile Properties dialog, choose items in the left pane to open dialog pages in the right pane.

    Figure 9-4 shows a sample User Metadata directory tree.

    Figure 9-4 Selecting Items for the MAR Deployment Profiles

    MAR deployment profile dialog

    Note the following important points:

    • To include all customizations, you need only create a file group with the desired directories.

    • To include files from other than ADF Model and ADF view, create a new file group under User Metadata with the desired directories and explicitly select the required content in the Directories page.

    • ADF Model and ADF view directories are added by default. No further action is required to package the ADF Model and ADF view customizations into the MAR. ADF view content is added to HTML Root dir, while ADF Model content is added to User Metadata. If your application has other customization directories, such as from an EJB project, you must add those directories.

    • To include the base metadata in the MDS repository, you need to explicitly select these directories in the dialog.

      When you select the base document to be included in the MAR, you also select specific packages. When you select one package, all the documents (including subpackages) under that package will be used. When you select a package, you cannot deselect individual items under that package.

    • If a dependent ADF library JAR for the project contains seeded customizations, they will automatically be added to the MAR during MAR packaging. They will not appear in the MAR profile.

    • If ADF Library customizations were created in the context of the consuming project, those customizations would appear in the MAR profile dialog by default.

  5. Click OK to exit the Edit MAR Deployment Profile Properties dialog.

  6. Click OK again to exit the Application Properties dialog.

9.3.2.3 Creating an EJB JAR Deployment Profile

If you are using an EJB module in the data model project, you need to create an EJB JAR deployment profile.

Before you begin:

Create a data model project that has an EJB module.

To create an EJB JAR deployment profile for an application:

  1. In the Application Navigator, right-click the web project that you want to deploy and choose New.

  2. In the New Gallery, expand General, select Deployment Profiles and then EJB JAR File, and click OK.

    If you don't see Deployment Profiles in the Categories tree, click the All Features tab.

  3. In the Create Deployment Profile -- EJB JAR File dialog, enter a name for the deployment profile and click OK.

  4. In the Edit EJB JAR Deployment Profile Properties dialog, choose items in the left pane to open dialog pages in the right pane. Configure the profile by setting property values in the pages of the dialog.

  5. Click OK to exit the Edit EJB JAR Deployment Profile Properties dialog.

  6. Click OK again to exit the Project Properties dialog.

9.3.2.4 Creating an Application-Level EAR Deployment Profile

The EAR file contains all the necessary application artifacts for the application to run in the application server. For more information about the EAR file, see Section 9.4.6, "What You May Need to Know About EAR Files and Packaging."

Before you begin:

To create an EAR deployment profile for an application:

  1. In the Application Navigator, right-click the application and choose New.

    You will create an EAR profile for the application.

  2. In the New Gallery, expand General, select Deployment Profiles and then EAR File, and click OK.

    If you don't see Deployment Profiles in the Categories tree, click the All Features tab.

  3. In the Create Deployment Profile -- EAR File dialog, enter a name for the application deployment profile and click OK.

  4. In the Edit EAR Deployment Profile Properties dialog, choose items in the left pane to open dialog pages in the right pane. Configure the profile by setting property values in the pages of the dialog.

    Be sure that you:

    • Select Application Assembly and then in the Java EE Modules list, select all the project profiles that you want to include in the deployment, including any WAR or MAR profiles.

    • Select Platform, and select the application server you are deploying to, and then select the target application connection from the Target Connection dropdown list.

    Note:

    If you are using a custom JAAS LoginModule for authentication with JAZN, the context root name also defines the application name that is used to look up the JAAS LoginModule.

  5. If you have customization classes in your application, configure these classes so that they load from the EAR-level application class loader.

    1. In the Edit EAR Deployment Profile Properties dialog, select Application Assembly.

    2. Select the JAR deployment profile that contains the customization classes, and enter lib in the Path in EAR field at the bottom of the dialog.

      Note:

      You should have created this JAR as described in Section 9.3.2.7, "Adding Customization Classes into a JAR."

    The JAR file containing the customization classes is added to the EAR file's lib directory.

    Note:

    If you have customization classes in your application, you must also make sure they are not loaded from the WAR. By default, customization classes that are added to the data model project's Libraries & Classpath are packaged to the WAR class path.

    To make sure customization classes from an extension project are not duplicated in the WAR, be sure to deselect any customization class archive on the Library Dependencies page for the WAR.

    If you created your customization classes in the data model project of the consuming application, deselect any customization classes on the File Groups > WEB-INF/classes > Filters page for the WAR.

  6. Click OK to exit the Deployment Profile Properties dialog.

  7. Click OK again to exit the Application Properties dialog.

9.3.2.5 Delivering Customization Classes as a Shared Library

As an alternative to adding your customization classes to the EAR, as described in Section 9.3.2.4, "Creating an Application-Level EAR Deployment Profile," you can also include the customization classes in the consuming application as a shared library.

Before you begin:

With the application containing the customization classes open in JDeveloper in the Studio Developer role, use the procedure described in Section 9.3.2.7, "Adding Customization Classes into a JAR," making sure that you select Shared Library JAR File as the type of archive to create.

Note:

This procedure describes how to create and use a shared library if you are deploying to Oracle Weblogic Server.

To create and use a shared library for your customization classes:

  1. In the Application Navigator, right-click the customization classes project, and choose Deploy > deployment-profile.

  2. In the Deploy wizard, select Deploy to a Weblogic Application Server and click Next.

  3. Select the appropriate application server, and click Finish.

    This makes the shared library available on the application server. You must now add a reference to the shared library from the consuming application.

  4. Open the application you want to customize in JDeveloper in the Studio Developer role.

  5. In the Application Resources panel of the Application Navigator, double-click the weblogic-application.xml file to open it.

  6. In the overview editor, click the Libraries tab.

  7. In the Shared Library References section, click the add icon.

  8. In the Library Name field of the newly created row in the Shared Library References table, enter the name of the customization classes shared library you deployed, and save your changes.

9.3.2.6 Viewing and Changing Deployment Profile Properties

After you have created a deployment profile, you can view and change its properties.

To view, edit, or delete a project's deployment profile:

  1. In the Application Navigator, right-click the project and choose Project Properties.

  2. In the Project Properties dialog, click Deployment.

    The Deployment Profiles list displays all profiles currently defined for the project.

  3. In the list, select a deployment profile.

  4. To edit or delete a deployment profile, click Edit or Delete.

9.3.2.7 Adding Customization Classes into a JAR

If your application has customization classes, create a JAR that contains only these customization classes. When you create your EAR, you can add the JAR to the EAR assembly. And when you create WAR profiles for your web projects, you must make sure they don't include the customization classes JAR.

Before you begin:

Make sure that your project has customization classes. You do not need to perform this procedure if the application does not have customization classes. For more information about customization classes, see the "How to Create Customization Classes" section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

To add customization classes into a JAR:

  1. In the Application Navigator, right-click the data model project that contains the customization classes you want to create a JAR for, and choose New.

  2. In the New Gallery, expand General, select Deployment Profiles and then JAR File, and click OK.

    Alternatively, if you want to create a shared library, select Shared Library JAR File from the list of profile types, and click OK.

    Note:

    If you don't see Deployment Profiles in the Categories tree, click the All Features tab.

  3. In the Create Deployment Profile -- JAR File dialog, enter a name for the project deployment profile (for example, CCArchive) and click OK.

  4. In the Edit JAR Deployment Profile Properties dialog, select JAR Options.

  5. Enter the location for the JAR file.

  6. Expand Files Groups > Project Output > Filters.

  7. In the Files tab, select the customization classes you want to add to the JAR file. If you are using a customization.properties file, it needs to be in the same class loader as the JAR file. You can select the customization.properties file to package it along with the customization classes in the same JAR.

  8. Click OK to exit the Edit JAR Deployment Profile Properties dialog.

  9. Click OK again to exit the Project Properties dialog.

  10. In the Application Navigator, right-click the project containing the JAR deployment profile, and choose Deploy > deployment profile > to JAR file.

    Note:

    If this is the first time you deploy to a JAR from this deployment profile, you choose Deploy > deployment profile and select Deploy to JAR in the wizard.

9.3.3 How to Create and Edit Deployment Descriptors

Deployment descriptors are server configuration files that define the configuration of an application for deployment and that are deployed with the Java EE application as needed. The deployment descriptors that a project requires depend on the technologies the project uses and on the type of the target application server. Deployment descriptors are XML files that can be created and edited as source files, but for most descriptor types, JDeveloper provides dialogs or an overview editor that you can use to view and set properties. If you cannot edit these files declaratively, JDeveloper opens the XML file in the source editor for you to edit its contents.

You can specify deployment descriptors that are specific to your target Oracle WebLogic application server instance.

In addition to the standard Java EE deployment descriptors (for example, application.xml and web.xml), you can also have deployment descriptors that are specific to your target application server. For example, if you are deploying to Oracle WebLogic Server, you can also have weblogic.xml, weblogic-application.xml, and weblogic-ejb-jar.xml.

Make sure that the application EAR file includes a weblogic-application.xml file that contains a reference to adf.oracle.domain, and that it includes an ADFApplicationLifecycleListener to clean up application resources between deployment and undeployment actions. Example 9-2 shows a sample weblogic-application.xml file.

Example 9-2 Sample weblogic-application.xml

<weblogic-application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-application.xsd"
 xmlns="http://www.bea.com/ns/weblogic/weblogic-application">
  <listener>
    <listener-class>oracle.adf.share.weblogic.listeners.
          ADFApplicationLifecycleListener</listener-class>
  </listener>
  <listener>
    <listener-class>oracle.mds.lcm.weblogic.WLLifecycleListener</listener-class>
  </listener>
  <library-ref>
    <library-name>adf.oracle.domain</library-name>
       <implementation-version>
       </implementation-version>
    </library-ref>
</weblogic-application>

If you are deploying web services, you may need to modify your weblogic-application.xml and web.xml files as described in the "How to Deploy Web Services to Oracle WebLogic Server" section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

If you want to enable the application for Real User Experience Insight (RUEI) monitoring, you must add a parameter to the web.xml file, as described in Section 9.3.3.5, "Enabling the Application for Real User Experience Insight."

During deployment, the application's security properties are written to the weblogic-application.xml file to be deployed with the application in the EAR file.

Because Oracle WebLogic Server runs on Java EE 1.5, you may need to modify the application.xml and web.xml files to be compatible with the server.

9.3.3.1 Creating Deployment Descriptors

JDeveloper automatically creates many of the required deployment descriptors for you. If they are not present, or if you need to create additional descriptors, you can explicitly create them.

Before you begin:

Check to see whether JDeveloper has already generated deployment descriptors.

To create a deployment descriptor:

  1. In the Application Navigator, right-click the project for which you want to create a descriptor and choose New.

  2. In the New Gallery, expand General, select Deployment Descriptors and then a descriptor type, and click OK.

    If you can't find the item you want, make sure that you chose the correct project, and then choose the All Features tab or use the Search field to find the descriptor. If the item is not enabled, check to make sure that the project does not already have a descriptor of that type. A project is allowed only one instance of a descriptor.

    JDeveloper starts the Create Deployment Descriptor wizard and then opens the file in the overview or source editor, depending on the type of deployment descriptor you choose.

Note:

For EAR files, do not create more than one deployment descriptor per application or workspace. These files are assigned to projects, but have application workspace scope. If multiple projects in an application have the same deployment descriptor, the one belonging to the launched project will supersede the others. This restriction applies to application.xml, weblogic-jdbc.xml, jazn-data.xml, and weblogic.xml.

The best place to create an application-level descriptor is in the Descriptors node of the Application Resources panel in the Application Navigator. This ensures that the application is created with the correct descriptors.

9.3.3.2 Viewing or Modifying Deployment Descriptor Properties

After you have created a deployment descriptor, you can change its properties by using JDeveloper dialogs or by editing the file in the source editor. The deployment descriptor is an XML file (for example, application.xml) typically located under the Application Sources node.

To view or change deployment descriptor properties:

  1. In the Application Navigator or in the Application Resources panel, double-click the deployment descriptor.

  2. In the editor window, select either the Overview tab or the Source tab, and configure the descriptor by setting property values.

    If the overview editor is not available, JDeveloper opens the file in the source editor.

9.3.3.3 Configuring the application.xml File for WebLogic Compatibility

You may need to configure your application.xml file to be compliant with Java EE 1.5.

Note:

Typically, your project has an application.xml file that is compatible and you would not need to perform this procedure.

To configure the application.xml file:

  1. In the Application Navigator, right-click the project and choose New.

  2. In the New Gallery, expand General, select Deployment Descriptors and then Java EE Deployment Descriptor Wizard, and click OK.

  3. In the Select Descriptor page of the Create Java EE Deployment Descriptor dialog, select application.xml and click Next.

  4. In the Select Version page, select 5.0 and click Next.

  5. In the Summary page, click Finish.

  6. Edit the application.xml file with the appropriate values.

9.3.3.4 Configuring the web.xml File for WebLogic Compatibility

You may need to configure your web.xml file to be compliant with Java EE 1.5 (which corresponds to servlet 2.5 and JSP 1.2).

Note:

Typically, your project has a web.xml file that is compatible and you would not need to perform this procedure. JDeveloper creates a starter web.xml file when you create a project.

To configure the web.xml file:

  1. In the Application Navigator, right-click the project and choose New.

  2. In the New Gallery, expand General, select Deployment Descriptors and then Java EE Deployment Descriptor Wizard, and click OK.

  3. In the Select Descriptor page of the Create Java EE Deployment Descriptor dialog, select web.xml and click Next.

  4. In the Select Version page, select 2.5 and click Next.

  5. In the Summary page, click Finish.

9.3.3.5 Enabling the Application for Real User Experience Insight

Real User Experience Insight (RUEI) is a web-based utility to report on real-user traffic requested by, and generated from, your network. It measures the response times of pages and transactions at the most critical points in the network infrastructure. Session diagnostics allow you to perform root-cause analysis.

RUEI enables you to view server and network times based on the real-user experience, to monitor your Key Performance Indicators (KPIs) and Service Level Agreements (SLAs), and to trigger alert notifications on incidents that violate their defined targets. You can implement checks on page content, site errors, and the functional requirements of transactions. Using this information, you can verify your business and technical operations. You can also set custom alerts on the availability, throughput, and traffic of all items identified in RUEI.

For more information about RUEI, see the Oracle Real User Experience Insight User's Guide at http://download.oracle.com/docs/cd/E16339_01/doc.60/e16359/toc.htm.

You must enable an application for RUEI by adding the context-param tag to the web.xml file shown in Example 9-3.

Example 9-3 Enabling RUEI Monitoring for an Application in web.xml

<context-param>
  <description>This parameter notifies ADF Faces that the 
               ExecutionContextProvider service provider is enabled.
               When enabled, this will start monitoring and aggregating
               user activity information for the client initiated
               requests. By default this param is not set or is false.
  </description>
  <param-name>
         oracle.adf.view.faces.context.ENABLE_ADF_EXECUTION_CONTEXT_PROVIDER
  </param-name>
  <param-value>true</param-value>
</context-param>

9.3.4 How to Deploy Applications with ADF Security Enabled

If you are developing an application in JDeveloper using Integrated WebLogic Server, application security deployment properties are configured by default, which means that the application and security credentials and policies will be overwritten each time you redeploy for development purposes. However, the application security deployment properties are the same for Integrated WebLogic Server and the standalone WebLogic Server.

9.3.4.1 Applications That Will Run Using Oracle Single Sign-On (SSO)

Before you can deploy and run the web application with Oracle ADF Security enabled on Oracle WebLogic Server, the administrator of the target server must configure the domain-level jps-config.xml file for the Oracle Access Manager (OAM) security provider. To assist with this configuration task, an Oracle WebLogic Scripting Tool (WLST) script has been provided with the JDeveloper install. For details about running this configuration script (with command addOAMSSOProvider(loginuri, logouturi, autologinuri)), see the procedure for configuring Oracle WebLogic Server for a web application using ADF Security, OAM SSO, and OPSS SSO in the Oracle Fusion Middleware Security Guide.

Running the configuration script ensures that the ADF Security framework defers to the OAM service provider to clear the ObSSOCookie token. OAM uses this token to save the identity of authenticated users and, unless it is cleared during logout, the user will be unable to log out.

After the system administrator runs the script on the target server, the domain jps-config.xml file will contain the following security provider definition that is specific for ADF Security:

<propertySet name="props.auth.uri">
    <property name="login.url.FORM" value="/${app.context}/adfAuthentication"/>
    <property name="logout.url" value=""/>
</propertySet>

Additionally, the authentication type required by SSO is CLIENT-CERT. The web.xml authentication configuration for the deployed application must specify the <auth-method> element as one of the following CLIENT-CERT types.

WebLogic supports two types of authentication methods:

  • For FORM-type authentication method, specify the elements like this:

    <login-config>
      <auth-method>CLIENT-CERT,FORM</auth-method>
      <realm-name>myrealm</realm-name>
      <form-login-config>
         <form-login-page>/login.html</form-login-page>
         <form-error-page>/error.html</form-error-page>
      </form-login-config>
    </login-config>
    
  • For BASIC-type authentication method, specify the elements like this:

    <login-config>
       <auth-method>CLIENT-CERT,BASIC</auth-method>
       <realm-name>myrealm</realm-name>
    </login-config>
    

WebSphere supports a single authentication method. Specify the elements like this:

<login-config>
  <auth-method>CLIENT-CERT</auth-method>
  <realm-name>myrealm</realm-name>
  <form-login-config>
     <form-login-page>/login.html</form-login-page>
     <form-error-page>/error.html</form-error-page>
  </form-login-config>
</login-config>

You can configure the web.xml file either before or after deploying the web application. For further details about setting up the authentication method for Single Sign-On, see the Oracle Fusion Middleware Security Guide.

9.3.4.2 Configuring Security for WebLogic Server

In a development environment, JDeveloper will automatically migrate application-level credentials, identities, and policies to the remote WebLogic Server instance only if the server is set up to be in development mode. Integrated WebLogic Server is set up in development mode by default. You can set up a remote WebLogic Server to be in development mode during Oracle WebLogic Server domain creation using the Oracle Fusion Middleware Configuration Wizard. For more information about configuring Oracle WebLogic Server domains, see Oracle Fusion Middleware Creating Domains Using the Configuration Wizard.

JDeveloper will not migrate application-level security credentials to WebLogic Server setup in production mode. Typically, in a production environment, administrators will use Enterprise Manager or WLST scripts to deploy an application, including its security requirements.

When you deploy an application to WebLogic Server, credentials (in the cwallet.sso and jazn-data.xml files) will either overwrite or merge with the WebLogic Server domain-level credential store, depending on whether a property in weblogic-application.xml is set to OVERWRITE or MERGE. In production-mode WebLogic Server, to avoid security risks, only MERGE is allowed. For development-mode WebLogic Server, you can set to OVERWRITE to test user names and passwords. You can also set the property by running setDomainEnv.cmd or setDomainEnv.sh with the following option added to the command (usually located in ORACLE_HOME/user_projects/domains/MyDomain/bin).

For setDomainEnv.cmd:

set EXTRA_JAVA_PROPERTIES=-Djps.app.credential.overwrite.allowed=true 
    %EXTRA_JAVA_PROPERTIES%

For setDomainEnv.sh:

EXTRA_JAVA_PROPERTIES="-Djps.app.credential.overwrite.allowed=true
     ${EXTRA_JAVA_PROPERTIES}"
export EXTRA_JAVA_PROPERTIES

If the Administration Server is already running, you must restart it for this setting to take effect.

You can check to see whether WebLogic Server is in production mode by using the Oracle WebLogic Server Administration Console or by verifying the following line in the WebLogic Server config.xml file:

<production-mode-enabled>true</production-mode-enabled>

By default, JDeveloper sets the application's credentials, identities, and policies to OVERWRITE mode. That is, the Application Policies, Credentials, and Users and Groups options are selected by default in the Application Properties dialog Deployment page. However, an application's credentials will be migrated only if the target WebLogic Server instance is set to development mode with -Djps.app.credential.overwrite.allowed=true.

Policy migration only works in development-mode. Identity migration only works when using JDeveloper to directly deploy to WebLogic Server regardless of whether it is in development or production-mode.

When your application is ready for deployment to a production environment, you should remove the identities from the jazn-data.xml file or disable the migration of identities by deselecting Users and Groups from the Application Properties dialog. Application credentials must be manually migrated outside of JDeveloper.

Note:

Before you migrate the jazn-data.xml file to a production environment, check that the policy store does not contain duplicate permissions for a grant. If a duplicate permission (one that has the same name and class) appears in the file, the administrator migrating the policy store will receive an error and the migration of the policies will be halted. You should manually edit the jazn-data.xml file to remove any duplicate permissions from a grant definition.

For more information about migrating application credentials and other jazn-data user credentials, see the Oracle Containers for J2EE Security Guide.

9.3.4.2.1 Applications with JDBC Data Source for WebLogic

If your application uses application-level JDBC data sources with password indirection for database connections, you may need to create credential maps in WebLogic Server to enable the database connection. For more information, see Section 9.3.7, "What You May Need to Know About JDBC Data Source for Oracle WebLogic Server."

9.3.4.3 Configuring Security for WebSphere Server

Applications with credentials and policies in the jazn-data.xml and cwallet.sso files can be migrated to WebSphere. You will need to perform additional tasks in WebSphere Be aware that the opss-application.xml file is not included in the application EAR file if it is intended for WebSphere.

Note:

Before you migrate the jazn-data.xml file to a production environment, check that the policy store does not contain duplicate permissions for a grant. If a duplicate permission (one that has the same name and class) appears in the file, the administrator migrating the policy store will receive an error and the migration of the policies will be halted. You should manually edit the jazn-data.xml file to remove any duplicate permissions from a grant definition.

For more information about setting up WebSphere to accept credentials and policies, see the Oracle Fusion Middleware Third-Party Application Server Guide.

9.3.4.3.1 Applications with JDBC Data Source for WebSphere

If your application uses application-level JDBC data sources with password indirection for database connections, you will need to create a JDBC data source in WebSphere. For more information, see the IBM WebSphere documentation.

9.3.4.3.2 Editing the web.xml File to Protect the Application Root for WebSphere

When you enable ADF Security for your web application, the web.xml file includes the Java EE security constraint allPages to protect the Java EE application root. By default, to support deploying to Oracle WebLogic Server, JDeveloper specifies the URL pattern for the security constraint as / (backslash). If you intend to deploy the application to IBM WebSphere, the correct URL pattern is /* (backslash-asterisk). Before you deploy the application to WebSphere, manually edit the web.xml file for your application to change the allPages security constraint as follows:

<security-constraint>
   <web-resource-collection>
      <web-resource-name>allPages</web-resource-name>
       <url-pattern>/*</url-pattern>
   </web-resource-collection>
   . . .
</security-constraint>

9.3.5 How to Replicate Memory Scopes in a Clustered Environment

If you are deploying an application that is intended to run in a clustered environment, you need to ensure that all managed beans with a lifespan longer than one request are serializable, and that the ADF framework is aware of changes to managed beans stored in ADF scopes (view scope and page flow scope).

For more information, see the "How to Set Managed Bean Memory Scopes in a Server-Cluster Environment" section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

9.3.6 How to Enable the Application for ADF MBeans

An ADF application uses many XML files for setting configuration information. Some of these configuration files have ADF MBean counterparts that are deployed with the application. After the application has been deployed, you can change configuration properties by accessing the ADF MBeans using the Enterprise Manager Fusion Middleware Control MBean browser.

To enable ADF MBeans, you must register them in the web.xml file. Example 9-4 shows a web.xml file with listener entries for connections and configuration.

Example 9-4 Enabling ADF MBeans in the web.xml File

<listener>
   <listener-class>
        oracle.adf.mbean.share.connection.ADFConnectionLifeCycleCallBack
   </listener-class>
</listener>
<listener>
   <listener-class>
        oracle.adf.mbean.share.config.ADFConfigLifeCycleCallBack</listener-class>
</listener>

Additionally, the ADFConnection and ADFConfig MBeans require the application to be configured with an MDS repository. MDS configuration entries in the adf-config.xml file for a file-based MDS are shown in Example 9-5. For more information about configuring MDS, see the Oracle Application Server Administrator's Guide.

Example 9-5 MDS Configuration Entries in the adf-config.xml File

<adf-mds-config xmlns="http://xmlns.oracle.com/adf/mds/config">
   <mds-config xmlns="http://xmlns.oracle.com/mds/config" version="11.1.1.000">
      <persistence-config>
         <metadata-store-usages>
            <metadata-store-usage 
                default-cust-store="true" deploy-target="true" id="myFileStore">
                  <metadata-store name="myReposName"
                       class-name=
                          "oracle.mds.persistence.stores.file.FileMetadataStore">
                       <property name="metadata-path" value="C:\Temp\"/>
                       <property name="partition-name" value="myAppName"/>
                  </metadata-store>
            </metadata-store-usage>
         </metadata-store-usages>
      </persistence-config>
   </mds-config>
</adf-mds-config>

In a production environment, an MDS repository that uses a database is required. You can use JDeveloper, Enterprise Manager Fusion Middleware Control, or WLST commands to switch from a file-based repository to a database MDS repository.

Additionally, if several applications are sharing the same MDS configuration, you can ensure that each application has distinct customization layers by defining a adf:adf-properties-child property in the adf-config.xml file. JDeveloper automatically generates this entry when creating applications. If your adf-config.xml file does not have this entry, add it to the file with code similar to that of Example 9-6.

Example 9-6 Adding MDS Partition Code to the adf-config.xml File

<adf:adf-properties-child xmlns="http://xmlns.oracle.com/adf/config/properties">
     <adf-property name="adfAppUID" value="Application3-4434"/>
     <adf-property name="partition_customizations_by_application_id"
            value="true"/>
</adf:adf-properties-child> 

The value attribute is either generated by JDeveloper or you can set it to any unique identifier within the server farm where the application is deployed. This value can be set to the value attribute of the adfAppUID property.

When adf-property name is set to adfAppUid, then the corresponding value property should be set to the name of the application. By default, JDeveloper generates the value property using the application's package name. If the package name is not specified, JDeveloper generates the value property by using the workspace name and a four-digit random number.

For more information about configuring Oracle ADF applications using ADF MBeans, see the Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework.

9.3.7 What You May Need to Know About JDBC Data Source for Oracle WebLogic Server

An Oracle ADF Java EE application can use a JDBC data source to connect to the database. You use the Oracle WebLogic Server Administration Console to configure a JDBC data source. A JDBC data source has three types: global, application level, and application level with password indirection. You generally set up a global JDBC data source in WebLogic Server. Any application that requires access to that database can use that JDBC data source. An application can also include application-level JDBC data sources. When the application is packaged for deployment, if the Auto Generate and Synchronize weblogic-jdbc.xml Descriptor During Deployment option is selected, JDeveloper creates a connection_name-jdbc.xml file for each connection that was defined. Each connection's information is written to the corresponding connection_name-jdbc.xml file (entries are also changed in weblogic-application.xml and web.xml). When the application is deployed to WebLogic Server, the server looks for application-level data source information before it looks for the global data source.

If the application is deployed with password indirection set to true, WebLogic Server will look for the connection_name-jdbc.xml file for user name information and it will then attempt to locate application-level credential maps for these user names to obtain the password. If you are using JDeveloper to directly deploy the application to WebLogic Server, JDeveloper automatically creates the credential map and populates the map to the server using an MBean call.

However, if you are deploying to an EAR file, JDeveloper will not be able to make the MBean call to WebLogic Server. You must set up the credential maps using the Oracle WebLogic Administration Console. Even if you have a global JDBC data source set up, if you do not also have credential mapping set up, WebLogic Server will not be able to map the credentials with passwords and the connection will fail. For more information about JDBC data sources, password indirection, and how to set up application credential mappings, see "JDBC Data Sources" in the "Deploying Applications" section of the JDeveloper online help.

For more information, see the "Preparing the Standalone Application Server for Deployment" section of the Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework.

9.4 Deploying the Application

You can use JDeveloper to deploy applications directly to the standalone application server or create an archive file and use other tools to deploy to the application server.

Figure 9-5 show the process flow for deploying an application and also for deploying customizations to the target standalone application server.

The following diagram contains clickable links.

Figure 9-5 Application Deployment Flow Diagram

Application Deployment Flow Diagram Deploy from JDeveloper Package the application into an archive Deploy customizations as a JAR Deploy using commands Testing and verifying deployment
Description of "Figure 9-5 Application Deployment Flow Diagram"

Note:

Before you begin to deploy applications that use Oracle ADF to the standalone application server, you need to prepare the application server environment by performing tasks such as installing the ADF runtime and creating and extending domains or cells. For more information, see the "Preparing the Standalone Application Server for Deployment" section of the Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework.

Table 9-1 describes some common deployment techniques that you can use during the application development and deployment cycle. The deployment techniques are listed in order from deploying on development environments to deploying on production environments. It is likely that in the production environment, the system administrators deploy applications by using Enterprise Manager or the WLST scripting tool.

Table 9-1 Deployment Techniques for Development or Production Environments

Deployment Technique Environment When to Use

Run directly from JDeveloper

Test or Development

When you are developing your application. You want deployment to be quick because you will be repeating the editing and deploying process many times.

JDeveloper contains Integrated WebLogic Server, on which you can run and test your application.

Use JDeveloper to directly deploy to the target application server

Test or Development

When you are ready to deploy and test your application on an application server in a test environment.

On the test server, you can test features (such as LDAP and Oracle Single Sign-On) that are not available on the development server.

You can also use the test environment to develop your deployment scripts, for example, using Ant.

Use JDeveloper to deploy to an EAR file, then use the target application server's tools for deployment

Test or Development

When you are ready to deploy and test your application on an application server in a test environment. As an alternative to deploying directly from JDeveloper, you can deploy to an EAR file and then use other tools to deploy to the application server.

On the test server, you can test features (such as LDAP and Oracle Single Sign-On) that are not available on the development server.

You can also use the test environment to develop your deployment scripts, for example, using Ant.

Use Enterprise Manager or WLST scripts to deploy applications

Production

When your application is in a test and production environment. In production environments, system administrators usually use Enterprise Manager or run WLST scripts to deploy applications.


Any necessary MDS repositories must be registered with the application server. If the MDS repository is a database, the repository maps to a data source with MDS-specific requirements.

If you are deploying the application to Oracle WebLogic Server, make sure to target this data source to the WebLogic Administration Server and to all Managed Servers to which you are deploying the application. For more information about registering MDS, see the Oracle Application Server Administrator's Guide.

If you are using the application server's administrative consoles or scripts to deploy an application packaged as an EAR file that requires MDS repository configuration in adf-config.xml, you must run the getMDSArchiveConfig command to configure MDS before deploying the EAR file. MDS configuration is required if the EAR file contains a MAR file or if the application is enabled for DT@RT (Design Time At Run Time).

For more information about WLST commands, see the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference. For more information about wsadmin commands, see the Oracle Fusion Middleware Third-Party Application Server Guide and the Oracle Fusion Middleware Configuration Guide for WebSphere.

If you plan to configure ADF connection information or adf-config.xml using ADF MBeans after the application has been deployed, make sure that the application is configured with MDS and that you have the MBean listeners enabled in the web.xml file. For more information, see Section 9.3.6, "How to Enable the Application for ADF MBeans."

9.4.1 How to Deploy to WebLogic Server from JDeveloper

Before you begin:

Create an application-level deployment profile that deploys to an EAR file.

Note:

When you are deploying to Oracle WebLogic Server from JDeveloper, ensure that the HTTP Tunneling property is enabled in the Oracle WebLogic Server Administration Console. This property is located under Servers > ServerName > Protocols. ServerName refers to the name of Oracle WebLogic Server.

Note:

JDeveloper does not support deploying applications to individual Managed Servers that are members of a cluster. You may be able to target one or more Managed Servers within a cluster using the Oracle WebLogic Server Administration Console or other Oracle WebLogic tools; however, the cluster can be negatively affected. For more information about deploying to Oracle WebLogic Server clusters, see the Oracle Application Server Administrator's Guide.

To deploy to the target application server from JDeveloper:

  1. In the Application Navigator, right-click the application and choose Deploy > deployment profile.

  2. In the Deploy wizard Deployment Action page, select Deploy to Application Server and click Next.

  3. In the Select Server page, select the application server connection.

  4. If you are deploying to a WebLogic Server instance, the WebLogic Options page appears. Select a deploy option and click Next.

    Note:

    If you are deploying an ADF application, do not use the Deploy to all instances in the domain option.

  5. Click Finish.

    During deployment, you can see the process steps displayed in the deployment Log window. You can inspect the contents of the modules (archives or exploded EAR) being created by clicking on the links that are provided in the log window. The archive or exploded EAR file will open in the appropriate editor or directory window for inspection.

    If the adf-config.xml file in the EAR file requires MDS repository configuration, the Deployment Configuration dialog appears for you to choose the target metadata repository or shared metadata repositories, as shown in Figure 9-6. The Repository Name dropdown list allows you to choose a target metadata repository from a list of metadata repositories registered with the Administration Server. The Partition Name dropdown list allows you to choose the metadata repository partition to which the application's metadata will be imported during deployment. You can use WLST/wsadmin scripts, Oracle WebLogic Server Administration Tool, or WebSphere Administrative Tool, respectively, to configure and register MDS. For more information about managing the MDS repository, see the Oracle Application Server Administrator's Guide.

    Figure 9-6 MDS Configuration and Customization for Deployment

    MDS configuration

    Note:

    If you are deploying a Java EE application, click the application menu next to the Java EE application in the Application Navigator.

    For more information on creating application server connections, see Section 9.3.1, "How to Create a Connection to the Target Application Server."

    Tip:

    You may get an exception in JDeveloper when trying to deploy large EAR files. The workaround is to deploy the application using the Oracle WebLogic Server Administration Console.

9.4.2 How to Create an EAR File for Deployment

You can also use the deployment profile to create an archive file (EAR file). You can then deploy the archive file using Enterprise Manager, WLST scripts, or Oracle WebLogic Server Administration Console.

Although an Oracle ADF Java EE application is encapsulated in an EAR file (which usually includes WAR, MAR, and JAR components), it may have parts that are not deployed with the EAR.

To create an EAR archive file:

  • In the Application Navigator, right-click the application containing the deployment profile, and choose Deploy > deployment profile > to EAR file.

    If an EAR file is deployed at the application level, and it has dependencies on a JAR file in the data model project and dependencies on a WAR file in the view-controller project, then the files will be located in the following directories by default:

    • ApplicationDirectory/deploy/EARdeploymentprofile.EAR

    • ApplicationDirectory/ModelProject/deploy/JARdeploymentprofile.JAR

    • ApplicationDirectory/ViewControllerProject/deploy/WARdeploymentprofile.WAR

Tip:

Choose View >Log and select the Deployment tab to see messages generated during the creation of the archive file.

9.4.3 What You May Need to Know About ADF Libraries

An ADF Library is a JAR file that contains JAR services registered for ADF components such as ADF task flows, pages, or application modules. If you want the ADF components in a project to be reusable, you create an ADF Library deployment profile for the project and then create an ADF Library JAR based on that profile.

An application or project can consume the ADF Library JAR when you add it using the Resource Palette or manually by adding it to the library classpath. When the ADF Library JAR is added to a project, it will be included in the project's WAR file if the Deployed by Default option is selected.

For more information, see the "Reusing Application Components" section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

9.4.4 How to Deploy New Customizations Applied to ADF LIbrary

If you have created new customizations for an ADF Library, you can use the MAR profile to deploy these customizations to any deployed application that consumes that ADF Library. For instance, applicationA, which consumes ADFLibraryB, was deployed to a remote application server. Later on, when new customizations are added to ADFLibraryB, you only need to deploy the updated customizations into applicationA. You do not need to repackage and redeploy the whole application, nor do you need to manually patch the MDS repository.

Note:

This procedure is for applying ADF Library customization changes to an application that has already been deployed to a remote application server. It is not for the initial packaging of customizations into a MAR that will eventually be a part of an EAR. For information about the initial packaging of the customization using a MAR, see Section 9.3.2.2, "Creating a MAR Deployment Profile."

To deploy ADF Library customizations, create a new MAR profile that includes only the customizations to be deployed and then use JDeveloper to:

  • Deploy the customizations directly into the MDS repository in the remote application server.

  • Deploy the customizations to a JAR. And then import the JAR into the MDS repository using tools such as the Fusion Middleware Control.

9.4.4.1 Exporting Customization to a Deployed Application

You can export the customizations directly from JDeveloper into the MDS repository for the deployed application on the remote application server.

Before you begin:

Create new customizations to the ADF Library using JDeveloper.

To export the customizations directly into the application server:

  1. In the Application Navigator, right-click the application and choose Deploy > metadata.

  2. In the Deploy Metadata dialog Deployment Action page, select Export to a Deployed Application and click Next.

    If the MAR profile is included in any of the application's EAR profiles, Export to a Deployed Application will be dimmed and disabled.

  3. In the Application Server page, select the application server connection and click Next.

  4. For WebLogic Server, the Server Instance page appears. In this page, select the server instance where the deployed application is located and click Next.

  5. In the Deployed Application page, select the application you want to apply the customizations to and click Next.

  6. In the Sandbox Instance page, if you want to deploy to a sandbox, select Deploy to an associated sandbox, choose the sandbox instance and click Next.

  7. In the Summary page, verify the information and click Finish.

9.4.4.2 Deploying Customizations to a JAR

When you deploy the ADF Library customizations to a JAR, you are packaging the contents as defined by the MAR profile.

Before you begin:

Create new customizations to the ADF Library using JDeveloper.

To deploy the customizations as a JAR

  1. In the Application Navigator, right-click the application and choose Deploy > metadata.

  2. In the Deploy Metadata dialog Deployment Action page, select Deploy to MAR.

  3. In the Summary page, click Finish.

  4. Use Enterprise Manager Fusion Middleware Control or the application server's administration tool to import the JAR into the MDS repository.

9.4.5 What You May Need to Know About ADF Libraries

An ADF Library is a JAR file that contains JAR services registered for ADF components such as ADF task flows or pages. If you want the ADF components in a project to be reusable, you create an ADF Library deployment profile for the project and then create an ADF Library JAR based on that profile.

An application or project can consume the ADF Library JAR when you add it using the Resource Palette or manually by adding it to the library classpath. When the ADF Library JAR is added to a project, it will be included in the project's WAR file if the Deployed by Default option is selected.

For more information, see the "Reusing Application Components" section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

9.4.6 What You May Need to Know About EAR Files and Packaging

When you package an Oracle ADF application into an EAR file, it can contain the following:

  • WAR files: Each web-based view-controller project should be packaged into a WAR file.

  • MAR file: If the application has customizations that are deployed with the application, it should be packaged into a MAR.

  • ADF Library JAR files: If the application consumes ADF Library JARs, these JAR files may be packaged within the EAR.

  • Other JAR files: The application may have other dependent JAR files that are required. They can be packaged within the EAR.

9.4.7 How to Deploy the Application Using Scripts and Ant

You can deploy the application using commands and automate the process by putting those commands in scripts. The ojdeploy command can be used to deploy an application without JDeveloper. You can also use Ant scripts to deploy the application. JDeveloper has a feature to help you build Ant scripts. Depending on your requirements, you may be able to integrate regular scripts with Ant scripts.

For more information about commands, scripts, and Ant, see the Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework.

9.4.8 What You May Need to Know About JDeveloper Runtime Libraries

When an application is deployed, it includes some of its required libraries with the application. The application may also require shared libraries that have already been loaded to WebLogic Server as JDeveloper runtime libraries. It may be useful to know which JDeveloper libraries are packaged within which WebLogic Server shared library. For a listing of the contents of the JDeveloper runtime libraries, see the Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework.

9.5 Postdeployment Configuration

After you have deployed your application to WebLogic Server, you can perform configuration tasks.

9.5.1 How to Migrate an Application

If you want to migrate an Oracle ADF Java EE application from one WebLogic Server to another WebLogic Server, you may need to perform some of the same steps you did for a first time deployment.

In general, to migrate an application, you would:

9.5.2 How to Configure the Application Using ADF MBeans

If ADF MBeans were enabled and packaged with the deployed application, you can configure ADF properties using the Enterprise Manager Fusion Middleware Control MBean Browser. For instructions to enable an application for MBeans, see Section 9.3.6, "How to Enable the Application for ADF MBeans."

For information on how to configure ADF applications using ADF MBeans, see the Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework.

9.5.3 How to Configure WebSphere for Result Sets Reuse

ADF applications deployed to WebSphere Application Server use shared database connections. You need to set the non-transactional datasource and DisableMultiThreadedServletConnectionMgmt properties in WebSphere to allow the application to reuse result sets across requests.

If you do not set these properties, WebSphere will close the result sets between requests.

For more information, see the "Configuring WebSphere Application Server" section in the Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework

9.6 Testing the Application and Verifying Deployment

After you deploy the application, you can test it from Oracle WebLogic Server. To test-run your ADF application, open a browser window and enter a URL:

Tip:

The context root for an application is specified in the view-controller project settings by default as ApplicationName/ProjectName/context-root. You can shorten this name by specifying a name that is unique across the target application server. Right-click the view-controller project, and choose Project Properties. In the Project Properties dialog, select Java EE Application and enter a unique name for the context root.

Note:

/faces has to be in the URL for Faces pages. This is because JDeveloper configures your web.xml file to use the URL pattern of /faces in order to be associated with the Faces Servlet. The Faces Servlet does its per-request processing, strips out /faces part in the URL, then forwards the URL to the JSP. If you do not include the /faces in the URL, then the Faces Servlet is not engaged (since the URL pattern doesn't match). Your JSP is run without the necessary JSF per-request processing.