Skip Headers
Oracle® Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1)

Part Number B31974-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

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

32 Deploying Fusion Web Applications

This chapter describes how to deploy Oracle ADF applications to a target application server. It describes how to create deployment profiles, deployment descriptors, and how to load ADF runtime libraries. It also contains information on deploying to Oracle WebLogic Server 10gR3.

This chapter includes the following sections:

32.1 Introduction to Deploying Fusion 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 applications directly to Oracle WebLogic Server 10gR3, 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 the Integrated WLS Server.

Oracle WebLogic Server 10gR3 Java EE applications are based on standardized, modular components. Oracle WebLogic Server 10gR3 provides a complete set of services for those modules and handles many details of application behavior automatically, without requiring programming.

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 use JDeveloper to:

If you are developing an application in JDeveloper and want to run the application in the Integrated WLS, 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 the Integrated WLS and does not require any deployment profiles or descriptors. The Integrated WLS also has access to the ADF libraries required to run an ADF application. You can run an application by selecting Run from the JDeveloper menu. You also debug the application using the features described in Chapter 29, "Testing and Debugging ADF Components".

In general (other than Integrated WLS), you use JDeveloper to prepare the application or project for deployment by:

You also must prepare Oracle WebLogic Server for ADF application deployment by:

After the application and Oracle WebLogic Server have been prepared, you can:

32.2 Creating a Connection to the Target Application Server

You can deploy applications to Oracle WebLogic Server via JDeveloper application server connections.

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 Name and Type page of the Create AppServer Connection dialog, enter a connection name.

  3. In the Connection Type dropdown list, choose WebLogic 10.3 to create a connection to Oracle WebLogic Server 10gR3.

  4. Click Next.

  5. On the Authentication page, enter a user name and password for the administrative user authorized to access the Oracle WebLogic Server.

  6. Select Deploy Password to include the password for this connection with the archives deployed for it. Deselect it to require the user to supply a password when connecting.

    Typically, you would select this option for development testing purposes only when using the Integrated WLS server in JDeveloper, because it enables you to connect more quickly. You should then deselect it again before you deploy your final application.

  7. Click Next.

  8. On the Configuration page, enter a Oracle WebLogic host name.

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

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

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

  10. In the SSL Port field, enter an SSL port number for the Oracle WebLogic Server 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.

  11. Select Always use SSL to connect to the Oracle WebLogic Server using the SSL port.

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

  13. Click Next.

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

  15. Click Finish.

32.3 Creating a Deployment Profile

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

You should create a WAR deployment profile for each web (ViewController) project that you want to deploy in your application. Then you create an application-level EAR deployment profile and select the projects you want to include from a list. When the application is deployed, the EAR file will include all the projects that were selected in the deployment profile.

32.3.1 How to Create Deployment Profiles

Before you create project and application deployment profiles, you must have already created a Fusion web application.

To create deployment profiles 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 and select Deployment Profiles.

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

  3. In the Items list, choose WAR File and click OK.

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

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

    Note:

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

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

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

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

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

  10. In the New Gallery, expand General and choose Deployment Profiles.

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

  11. In the Items list, choose EAR File and click OK.

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

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

    • Select Platform, select WebLogic 10.3 as the default platform and then select the target application connection from the Target Connection dropdown list.

    Note:

    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.
  14. Click OK to exit the Deployment Profile Properties dialog.

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

32.3.2 How to View and Change 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.

32.4 Creating and Editing Deployment Descriptors

Deployment descriptors are server configuration files that define the configuration of an application for deployment and 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 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 service.

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.

In the application EAR file, make sure it includes a weblogic-application.xml file and that the file contains a reference to adf.oracle.domain. It should have a <library-ref> entry as shown in Example 32-1.

Example 32-1 library-ref tag in weblogic-application.xml

<library-ref>
    <library-name>adf.oracle.domain</library-name>
</library-ref>

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

32.4.1 How to Create Deployment Descriptors

Before you create a deployment descriptor, you should check to see if JDeveloper has already generated it.

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 and choose Deployment Descriptors.

  3. In the Items list, choose a descriptor type, and click OK.

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

    JDeveloper starts the Create Deployment Descriptor wizard or opens the file in the 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.

32.4.2 How to View or Change Deployment Descriptor Properties

After you have created a deployment descriptor, you can change its properties 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, right-click the deployment descriptor and choose Properties.

    The Properties dialog that appears depends on the selected descriptor type.

    If the context menu does not have a Properties item, then the descriptor must be edited as a source file. Choose Open from the context menu to open the profile in the source editor.

  2. In the Properties dialog, choose items in the left pane to open dialog pages in the right pane. Configure the descriptor by setting property values in the pages of the dialog.

  3. Click OK.

32.4.3 How to Create or Configure 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 create the application.xml file:

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

  2. In the New Gallery, expand General, choose Deployment Descriptors, and in Items, choose Java EE Deployment Descriptor Wizard and click OK.

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

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

  5. In the Summary page, click Finish.

32.4.4 How to Create or Configure 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.

To create the web.xml file:

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

  2. In the New Gallery, expand General, choose Deployment Descriptors, and in Items, choose Java EE Deployment Descriptor Wizard and click OK.

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

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

  5. In the Summary page, click Finish.

32.4.5 How to Create Deployment Descriptors for Applications with ADF Faces Components

If your application uses ADF Faces components, ensure that the standard Java EE deployment descriptors contain entries for ADF Faces and that you include the ADF and JSF configuration files in your archive file (typically a WAR file). When you create ADF Faces components in your application, JDeveloper automatically creates and configures the files for you.

If you are using ADF databound UI components as described in Section 11.3, "Using the Data Controls Panel", ensure that you have the DataBindings.cpx file. For information about the file, see Section 11.4, "Working with the DataBindings.cpx File".

32.5 Installing the ADF Runtime to the WebLogic Installation

The Oracle WebLogic Server requires the ADF Runtime to run Oracle ADF applications.

Installing the ADF Runtime is not required if you are using JDeveloper to run applications in the Integrated WLS.

If you installed the Oracle WebLogic Server 10gR3 together with JDeveloper 11g using the Oracle Installer (or installed it with the Application Development Framework Runtime option selected), the ADF Runtime is installed as part of the Oracle WebLogic Server installation. You can proceed to Section 32.6, "Creating and Extending WebLogic Domains".

If you already have an existing Oracle WebLogic Server 10gR3 installation, you can add the ADF Runtime into that installation using the Oracle Installer

32.5.1 How to Install the ADF Runtime into an Existing WebLogic Server

Before you add the ADF Runtime into an existing Oracle WebLogic Server 10gR3 installation, you must have obtained the Oracle Installer. You can download the installer from the Oracle Technology Network (OTN) web site at http://www.oracle.com/technology/software/products/jdev/index.html.

Use the instructions in the Oracle JDeveloper 11g Installation Guide to start the installer and to complete the installation.

To install the ADF Runtime into an existing WebLogic Server:

  1. Start the Oracle Installer as described in the Oracle JDeveloper 11g Installation Guide.

  2. In the Choose Middleware Home directory page, select Use an existing Middleware Home, select the directory in which your Oracle WebLogic Server 10gR3 resides, and click Next.

  3. In the Choose Products and Components page, choose Application Development Framework Runtime, (deselect JDeveloper Studio if you do not want to install the JDeveloper IDE) and click Next.

    The Oracle WebLogic Server product and components should be gray and unselectable. If it is enabled and selected, you must check whether you have selected the correct Oracle WebLogic Server installation directory.

  4. Follow the instructions in the Oracle JDeveloper 11g Installation Guide to complete the installation

  5. When the installation is complete, click Done.

    Follow the instructions in Section 32.6, "Creating and Extending WebLogic Domains" to use the Oracle WebLogic Configuration Wizard to create or extend a WebLogic domain.

32.5.2 What You May Need to Know About ADF Libraries

A JAR file is an ADF Library if it contains JAR services registered for ADF components such as ADF task flows, pages, or application modules. If the JAR file contains these components, the ADF Library provides summary information that can be browsed in the Resource Palette. For more information, see Chapter 31, "Reusing Application Components".

32.6 Creating and Extending WebLogic Domains

You need to create or configure a WebLogic domain to accept ADF applications. If you do not already have a domain, you need to create a new domain. If you already have a domain, you must extend the domain before it can run ADF applications.

If you are using WebLogic Managed servers to run your applications, you may need to configure your Managed server. For more information about configuring a WebLogic Managed server on Oracle WebLogic Server, see the "Customizing the Environment" chapter in the Creating WebLogic Domains Using the Configuration Wizard guide on the Oracle Technology Network website at http://download.oracle.com/docs/cd/E12839_01/common/docs103/confgwiz/custom.html.

32.6.1 How to Create a WebLogic Domain for Oracle ADF

You must create a WebLogic domain if it does not already exist.

To create a new WebLogic domain:

  1. Start the configuration by choosing Oracle Fusion Middleware 11.1.1.0.1 > WebLogic Server 10.3 > Tools > Configuration Wizard from the Windows Start menu.

    Or, change to the ORACLE_HOME/wlserver_10.3/common/bin directory and run config.cmd or config.sh (depending on your platform) from the command line.

  2. In the Welcome page, select Create a New WebLogic Domain and click Next.

  3. In the Select Domain Source page, select Generate a domain configured automatically to support the following products, then select Application Development Framework and click Next.

    The option WebLogic Server (Required) is already selected.

  4. In the Configure Administrator Username and Password page, enter the user name and password and click Next.

  5. In the Configure Server Start Mode and JDK page, select whether the domain is for a development or a production system, choose the JDK to use, and click Next.

  6. In the Customize Environment and Services Setting page, select No when asked to customize further domain options and click Next.

  7. In the Create WebLogic Domain page, enter the name and location of the new domain, the location of applications, and click Create.

  8. Click Done when the creation process has finished.

32.6.2 How to Extend a WebLogic Domain for Oracle ADF

If you have an existing WebLogic domain that has not been updated to run Oracle ADF applications, you can extend it for Oracle ADF. You must already have the ADF Runtime installed in the WebLogic Server installation.

To extend a WebLogic Domain for Oracle ADF:

  1. Start the configuration by choosing Oracle Fusion Middleware 11.1.1.0.1 > WebLogic Server 10.3 > Tools > Configuration Wizard from the Windows Start menu.

    Or, change to the ORACLE_HOME/wlserver_10.3/common/bin directory and run config.cmd or config.sh (depending on your platform) from the command line.

  2. In the Welcome page, select Extend an existing WebLogic domain and click Next.

  3. In the Select a WebLogic Domain Directory page, select the location of the domain you want to configure for ADF, and click Next.

  4. In the Select Extension Source page, select Extend my domain automatically to support the following added products, then select Application Development Framework and click Next.

  5. In the Customize JDBC and JMS File Store Settings page, leave No selected to update the domain as specified in the template and click Next.

  6. In the Extend WebLogic Domain page, enter the application location and then click Extend.

  7. Click Done when the configuration has finished.

  8. After you have extended the domain, check the POST_CLASSPATH entry to make sure that setDomainEnv is set to the correct location.

    The correct location should be ORACLE_HOME\jdeveloper\modules\features\adf.share_11.1.1.jar.

    This configures the rest of the runtime .jar files using the manifest file.

    Note:

    Your application's EAR file must have a weblogic-application.xml file containing a reference to the adf.oracle.domain shared library.

You can now start the Oracle WebLogic Server by running the command line script ORACLE_HOME\user_projects\domains\domain_name\bin\startWebLogic.cmd and stop the server using the stopWebLogic.cmd script in the same directory.

Access the Oracle WebLogic Server Administration Console using the URL http://localhost:7001/console.

32.7 Creating a JDBC Data Source for a WebLogic Domain Server

Oracle ADF applications can use either a data source or JDBC URL for database connections. You use the Oracle WebLogic Server Administration Console to configure a JDBC data source

To configure a WebLogic domain server for both data source and JDBC URL:

  1. Start the Oracle WebLogic Server (if not already started) by choosing Oracle Fusion Middleware 11.1.1.0.1 > User Projects > Domain > Start Admin Server for WebLogic Server Domain from the Windows Start menu.

  2. Start the Oracle WebLogic Server Administration Console by choosing Oracle Fusion Middleware 11.1.1.0.1 > User Projects > Domain > Admin Server Console from the Windows Start menu.

  3. Log in to the Oracle WebLogic Server Administration Console.

  4. In the WebLogic Server Administration Console page, select JDBC > Data Sources.

  5. Click New.

  6. In the JDBC Data Source Properties page:

    • In the Name field, enter the name of the JDBC data source.

    • In the JNDI field, enter the name of the connection in the form jdbc/connection DS.

    • For the Database Type, choose Oracle.

    • For the Database Driver, choose Oracle Driver (thin), and click Next.

  7. In the Transactions Options page, accept the default options and click Next.

  8. In the Connection Properties page:

    • For Database Name, enter the Oracle SID. For example, orcl.

    • For Host Name, enter the machine name of the database.

    • Enter the port number used to access the database.

    • Enter the user name and password for the database and click Next.

  9. In the Test Database Connection page, click Test Configuration to test the connection.

  10. In the Select Targets page, select the server for which the JDBC data source is to be deployed.

  11. Click Finish.

Once the data source has been created on the domain server, it can be used by an application module.

32.8 Deploying the Application

Before you can deploy the application to your target application server, you may need to perform some vendor-specific configuration. See your application server documentation for instructions.

You can deploy directly to Oracle WebLogic Server if you have set up a connection in JDeveloper to your Oracle WebLogic Server.

Note:

When you are deploying to Oracle WebLogic Server 10gR3 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 your Oracle WebLogic Server.

Table 32-1 shows the supported version of Oracle WebLogic Server.

Table 32-1 Support for Oracle WebLogic Server

WebLogic version JDK version Java EE version

10.3

1.6

Java EE 1.5


Before deploying applications that use Oracle ADF to Oracle WebLogic Server, you need to install the ADF Runtime on the server. For more information, see Section 32.5, "Installing the ADF Runtime to the WebLogic Installation".

Table 32-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 using scripting tools.

Table 32-2 Deployment Techniques

Deployment Technique When to Use

Run directly from Oracle JDeveloper

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

Oracle JDeveloper contains Integrated WLS, on which you can run and test your application. You should also deploy your application to an external application server to test it.

Deploy to EAR file, then use the target application server's tools for deployment

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 OracleAS Single Sign-On Server) 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 a script to deploy applications

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


Instead of deploying applications directly from JDeveloper, you can use JDeveloper to create the archive file, and then deploy the archive file using the Oracle WebLogic Server Administration Console.

If your application has security credential data, including database credentials, you must migrate your application-level policy data to a domain-level policy store. For more information, see "Migrating the Security Repository to a Production Environment" in the "Developing Secure Applications" section of the JDeveloper online help

32.8.1 How to Deploy to a WebLogic Server from JDeveloper

Before you deploy an application or project, you should have already created an application-level deployment profile that deploys to an EAR file.

To deploy to the target application server from JDeveloper:

  • To deploy an application, in the Application Navigator, right-click the application and choose Deploy > deployment profile > to > application server connection.

    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 32.2, "Creating a Connection to the Target Application Server".

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.

32.8.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 the Oracle WebLogic Server Administration Console.

To create an archive file:

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

For Java EE applications, create an EAR deployment profile from the application context menu and assemble the projects, which typically represent Java EE modules, into your application archive.

Tip:

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

32.8.3 How to Deploy an Application Using Ant

You can deploy to most application servers from JDeveloper, or you can use tools provided by the application server vendor. You can also use Ant to package and deploy applications. The build.xml file, which contains the deployment commands for Ant, may vary depending on the target application server.

For deployment to other application servers, see the application server's documentation. If your application server does not provide specific Ant tasks, you may be able to use generic Ant tasks. For example, the generic ear task creates an EAR file for you.

For information about Ant, see http://ant.apache.org.

32.9 Testing the Application and Verifying Deployment

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

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 the /faces part in the URL, then forwards 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.