36 Deploying Fusion Web Applications

This chapter describes how to deploy ADF 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.

36.1 Introduction to Deploying Fusion Web Applications

Deployment is the process of packaging application files as an archive file and transferring this file to a target application server. You can use JDeveloper to deploy ADF 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.

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

Deploying a Fusion web application is slightly different from deploying a standard Java EE application. JSF applications that contain ADF Faces components have a few additional deployment requirements:

You can run and debug applications using Integrated WebLogic Server and then deploy to a standalone WebLogic Server or to WebSphere.

Integrated IBM WebSphere Application Server is not supported for this release.

Deploy directly to the standalone application server

You can deploy applications directly to the standalone application server by creating a connection to the server and choosing the name of that server as the deployment target.

Deploy to an archive file

You can deploy applications indirectly by choosing an EAR file as the deployment target. The archive file can subsequently be installed on a target application server.

The StoreFront module of the Fusion Order Demo application demonstrates the use of the Fusion web application technology stack to create transaction-based web applications. You can run the StoreFront module of the Fusion Order Demo application in JDeveloper using Integrated WebLogic Server. You cannot run the Fusion Order Demo module in JDeveloper. You must deploy the Fusion Order Demo application to a SOA-enabled Oracle WebLogic Server. For more information about the StoreFront module and the Fusion Order Demo application, see Section 2.3, "Running the Fusion Order Demo Application StoreFront Module."

36.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, both of these are required to run ADF applications. You can run an application by choosing Run from the JDeveloper main menu.

Typically, for deployment to standalone application servers, you test and develop your application by running it in Integrated WebLogic Server. You can then test the application further by deploying it to testing Oracle WebLogic Server (in development mode) or to IBM WebSphere Application Server 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, and that are specific to the application server)

Updating application.xml and web.xml to be compatible with the application (if required)

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.

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.

36.2 Running an ADF 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.

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:

Detects the type of Java EE module to deploy based on the artifacts in the project and application

Creates a deployment profile in memory

Copies project and application files into a working directory with a file structure that would simulate the "exploded EAR" file of the application.

Performs the deployment tasks to register and deploy the simulated EAR into Integrated WebLogic Server

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 the default domain to run and test your applications. Open the Application Server Navigator, right-click IntegratedWebLogicServer and choose Create Default Domain.

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

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

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

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

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 this directory 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.

Before you begin:

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:

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

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

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.

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

Click Next.

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. Note that you should not use the wsadmin files from the ORACLE_HOME/oracle_common/common/bin directory, which are not the correct version. The default location is websphere-home/bin/wsadmin.sh for Unix/Linux and websphere-home/bin/wsadmin.bat for Windows.

Click Next.

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.

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.

Click Next.

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

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.

Click Finish.

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

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 Chapter 34, "Customizing Applications with MDS." 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. 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 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.

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

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.

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

Click OK again to exit the Project Properties dialog.

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.

36.3.2.2 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 model projects it requires.

Before you begin:

Create web-based projects. If you used the Fusion Web Application (ADF) template, you should already have a default WAR deployment profile.

To create WAR deployment profiles for an application:

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.

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 Technologies tab.

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

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 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 view controller project.

If you created your customization classes in the 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 view controller 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.

Click OK to exit the Deployment Profile Properties dialog.

Click OK again to exit the Project Properties dialog.

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

36.3.2.3 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 forms 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 36-1 shows the contents of a sample adf-settings.xml file.

In this example, the adf-settings.xml file has a web-app-root element that defines the rootName as order.If your enterprise application has only one web application project then there is no need to define a web-app-root element. If your enterprise application has multiple web application projects, then you should supply a web-app-root for all the web applications except one, without which the deployment would 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.

Before you begin:

Create an MDS repository for your customization requirements to deploy metadata using the MAR deployment profile. If you used the Fusion Web Application (ADF) template, you should already have a default MAR deployment profile.

To create a MAR deployment profile:

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

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

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 Technologies tab.

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

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

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

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 and Business Components content is added to User Metadata.

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.

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

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.

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 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 model project of the consuming application, deselect any customization classes on the File Groups > WEB-INF/classes > Filters page for the WAR.

Click OK to exit the Deployment Profile Properties dialog.

Click OK again to exit the Application Properties dialog.

Note:

To verify that your customization classes are put correctly in the EAR class path, you can deploy the EAR profile to file system. Then you can examine the EAR to make sure that the customization class JAR is available in the EAR class path (the EAR/lib directory) and not available in the WAR class path (the WEB-INF/lib and WEB-INF/classes directories).

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:

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

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

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.

Open the application you want to customize in JDeveloper in the Default role.

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

In the overview editor, click the Libraries tab.

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

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.

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

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

In the Project Properties dialog, click Deployment.

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

In the list, select a deployment profile.

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

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

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.

For WebLogic Server, 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 36-2 shows a sample weblogic-application.xml file.

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

For IBM WebSphere, the deployment descriptors are created at runtime and cannot be edited. Some of the relevant descriptors are shown in Table 36-1.

Table 36-1 IBM WebSphere Deployment Descriptors

WebSphere

Action

ibm-application-bnd.xml

This references the security role just mapped in application.xml and maps it to the well-known name "AllAuthenticatedUsers". Similar to weblogic.xml for WebLogic Server. Maps the "valid-users" JEE security role to the well-known name "Users".

application.xml

A standard Java EE deployment description, but it is also used to populate a security mapping for the "valid-users" role (which is defined in web.xml when using ADF Security).

<EAR_ROOT>/META-INF/manifest.mf

References application-shared libraries such as adf.oracle.domain.

<EAR_ROOT>/META-INF/deployment.xml

References WAR-shared libraries such as adf.oracle.domain.webapp.

36.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 use JDeveloper to create them.

Before you begin:

Check to see whether JDeveloper has already generated deployment descriptors.

To create a deployment descriptor:

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

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 Technologies 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 file of the same type per application or workspace. These files can be 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, -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.

Application-level descriptors created in the project will be ignored by the runtime. Only the application resources descriptors or descriptors generated at the EAR level will be used by the runtime.

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

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

In the overview editor, 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.

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

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

Example 36-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>

36.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. You can change the default behavior in the Application Properties dialog, as described in Section 30.8.1, "How to Configure, Deploy, and Run a Secure Application in JDeveloper."

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

Before you can deploy and run the web application with ADF Security enabled on the application 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. You can also use this command for configuring WebSphere for OAM. 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 SSO cookie 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:

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.

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.

36.3.4.2 Configuring Security for WebLogic Server

In a development environment, JDeveloper will automatically migrate application-level credentials, identities, and policies to the standalone 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 standalone 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 OVERWRITE or MERGE is set in weblogic-application.xml. 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 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%

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

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.

36.3.4.2.1 Applications with JDBC URL for WebLogic

If your application has components that use JDBC URL connections, the connection user names and passwords are also stored in the application-level credential and policy stores. For the deployed application to be able to connect to the database using the JDBC URL, these credentials and policies must be migrated. That is, if WebLogic Server is in production mode, system administrators must migrate this security information. If WebLogic Server is in development mode, it must have domain-level credential and policy stores set to OVERWRITE to allow the migration of security information.

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

36.3.4.3.1 Applications with JDBC URL for WebSphere

If your application has components that use JDBC URL connections, the connection user names and passwords are also stored in the application-level credential and policy stores. For the deployed application to be able to connect to the database using the JDBC URL, OPSS migration must be enabled.

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

36.3.4.3.3 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:

36.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).

36.3.6 How to Enable the Application for ADF MBeans

An ADF application uses many XML files for setting configuration information. Three 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 36-4 shows a web.xml file with listener entries for connections, configuration, and business components.

Additionally, ADF connection MBeans require the application to be configured with an MDS repository. ADF Business Components MBeans do not require MDS, but business components configuration is limited to updating the underlying bc4j.xcfg file in the exploded EAR location. MDS configuration entries in the adf-config.xml file for a file-based MDS are shown in Example 36-5. For more information about configuring MDS, see the Oracle Fusion Middleware Administrator's Guide.

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

Additionally, if several applications are sharing the same MDS configuration, each application can achieve 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 36-6.

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.

The ADF application module in the data model project can be configured to use a JDBC URL connection type, a JDBC data source connection type, or a combination of both types. By default, ADF application modules use a JDBC URL connection. A component that uses a JDBC URL will attempt to connect directly to the database using the JDBC URL, and it will ignore any JDBC data sources (global or application-level) that are available in WebLogic Server. For more information about migrating JDBC URL security information (user names and passwords) from the application to WebLogic Server, see Section 36.3.4, "How to Deploy Applications with ADF Security Enabled."

An ADF application can use a JDBC data source to connect to the database. 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.

Once the data source has been created in Oracle WebLogic Server, it can be used by an application module. 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.

36.4 Deploying the Application

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

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.

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

Table 36-2 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 Fusion Middleware Control or scripts.

Table 36-2 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 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 script 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 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 Fusion Middleware 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).

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

36.4.1 How to Deploy to the Application 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:

For WebLogic Server, 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 Fusion Middleware Administrator's Guide.

To deploy to the target application server from JDeveloper:

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

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

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.

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 36-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, the 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 Fusion Middleware Administrator's Guide.

Figure 36-6 MDS Configuration and Customization for Deployment

Note:

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

36.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/wsadmin scripts, Oracle WebLogic Server Administration Console, or WebSphere Administrative Console, respectively.

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:

Choose View >Log to see messages generated during creation of the archive file.

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

When you package an 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.

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

You can also use the application server commands for deployment. For WebLogic Server, you can use WLST commands and for IBM WebSphere Application Server, you can use wsadmin commands.

36.4.5 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 standalone 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 standalone 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 36.3.2.3, "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 standalone 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.

36.4.5.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 standalone application server.

Before you begin:

Create new customizations to the ADF Library using the cutomization developer role in JDeveloper.

To export the customizations directly into the application server:

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

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

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

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

36.5 Postdeployment Configuration

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

36.5.1 How to Migrate an Application

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

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

For non-Faces pages: http://<host>:port/<context root>/<page>

For Faces pages: http://<host>:port/<context root>/faces/<view_id>

where <view_id> is the view ID of the ADF task flow view activity.

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.

Scripting on this page enhances content navigation, but does not change the content in any way.