Oracle® Fusion Middleware SmartUpgrade User's Guide 11g Release 1 (11.1.1) E15878-01 |
|
![]() Previous |
In addition to generating an upgrade report, SmartUpgrade can generate artifacts, such as Web application deployment descriptor files and the mapping files and type classes required to run Web Services on a WebLogic server.
For the generated deployment descriptors, you can review the generated Oracle WebLogic Server elements and use them as a starting point for upgrading your application so you can deploy it successfully on Oracle WebLogic Server.
In the case of Web services, you can configure SmartUpgrade to create an archive of the generated Web services artifacts and the archive can be deployed directly to Oracle WebLogic Server.
The following sections describe how to use artifacts generated by SmartUpgrade to upgrade your applications so they can be deployed on Oracle WebLogic Server:
When SmartUpgrade generates artifacts, it saves them in a separate, predefined location. None of the source files of your original application are modified.
For more information, see the following:
By default, SmartUpgrade saves the generated artifacts to a series of directories relative to the project directory if you're using Oracle JDeveloper or relative to the directory where you are running the command-line interface:
If you are using Oracle JDeveloper, then the output directories are by default under the /gen_src/
directory inside your new project directory. However, you can define a different location from the OC4J Artifacts page of the Java EE Upgrade wizard. The location is relative to the project directory where SmartUpgrade saves the upgrade report.
If you are using the SmartUpgrade command-line interface, the output directories are created in the upgrade directory inside the directory where you invoked the command-line tool.
Figure 4-1 illustrates the organization of the output files on disk.
For information about the Web services artifact directories, including the exploded, intermediate, and final directories, and the location of the source and target upgrade plans, see Section 4.3.4, "About the Content of the Generated Web Services Output Directories" and Table 4-2.
If you are using Oracle JDeveloper, you can also access the generated artifacts by using the Application Navigator to expand the folders of the new SmartUpgrade project.
Figure 4-2 shows how you can expand the Application Sources folder of the SmartUpgrade project to view the generated weblogic.xml
file, as well as a pointer to the existing EAR file that was used to generated the Upgrade Report and the sample Oracle WebLogic Server deployment descriptor.
Figure 4-3 shows how you can expand the project to view the generated Web services output folders. For more information, see Section 4.3.4, "About the Content of the Generated Web Services Output Directories".
For information about using the deployment descriptor artifacts that are generated by SmartUpgrade, refer to the following sections:
Differences Between OC4J and Oracle WebLogic Server Deployment Descriptors
List of Deployment Descriptor Elements Generated by SmartUpgrade
Using Web Application Deployment Descriptor Artifacts Generated by SmartUpgrade
One of the key differences between OC4J and Oracle WebLogic Server is the fact that OC4J supports a set of OC4J-specific deployment descriptor elements (for example, orion-web.xml), and Oracle WebLogic Server supports a set of WebLogic-specific deployment descriptor elements, which are stored in its equivalent proprietary files (for example, weblogic.xml).
For more information, see "Comparison of OC4J and Oracle WebLogic Server Deployment Descriptors" in the Oracle Fusion Middleware Upgrade Guide for Java EE.
One of the important tasks you must perform when upgrading your applications from OC4J to Oracle WebLogic Server is creating a weblogic.xml
file that contains a set of elements equivalent to those previously defined in the orion-web.xml file.
To help you perform this task, Oracle provides the following resources:
The information available in the Oracle Fusion Middleware Upgrade Guide for Java EE
The advice provided in the SmartUpgrade report that is generated when you analyze your application with SmartUpgrade
Besides reviewing the upgrade documentation and reviewing the advice available in the upgrade report findings, you can also configure SmartUpgrade to generate a specific set of Oracle WebLogic Server Web application deployment descriptor elements for you.
Specifically, if you configure SmartUpgrade to generate artifacts, and the software identifies an orion-web.xml
file within the application, SmartUpgrade automatically generates the equivalent Oracle WebLogic Server deployment descriptor elements in a sample weblogic.xml file:
If your application contains a Web application, then SmartUpgrade can generate the deployment descriptor elements listed Section 4.2.2, "List of Deployment Descriptor Elements Generated by SmartUpgrade". The generated elements are saved in a sample weblogic.xml
file.
Figure 4-4 shows a flow chart of the steps you can take to generate and use the generated deployment descriptor elements. Figure 4-4 describes each of the steps in the flow chart in more detail.
To use the deployment descriptor artifacts generated SmartUpgrade:
Locate the generated weblogic.xml
file and review the elements that SmartUpgrade created in the file.
For more information, see Section 4.1, "Locating the Artifacts Generated by SmartUpgrade".
If you are unfamiliar with any of the elements, refer to the deployment descriptor information in the Oracle Fusion Middleware Upgrade Guide for Java EE.
Copy the elements from the generated weblogic.xml
file and paste them into the weblogic.xml
file you created in the project where you are modifying your application for redeployment on Oracle WebLogic Server.
Figure 4-4 Flow Chart of Upgrading a Java EE Application and Generating Web Application Deployment Descriptor Artifacts
Table 4-1 Description of the Steps Required to Generate and Use Deployment Descriptor Elements Generated by SmartUpgrade
Step | Description |
---|---|
Start the Java EE Upgrade Wizard; or run command-line utility |
From Oracle JDeveloper, start the Java EE Upgrade wizard, as described in Section 2.2, "Starting and Using the Java EE Upgrade Wizard" From the command-line interface, run the command-line arguments, as described in Chapter 3, "Using the SmartUpgrade Command Line". |
From Oracle JDeveloper, select Generate Artifacts on the OC4J Artifacts screen in the Java EE Upgrade wizard. From the command-line interface, use the |
|
Locate the sample |
For more information, see Section 4.1, "Locating the Artifacts Generated by SmartUpgrade". |
If you are unfamiliar with any of the generated elements, refer to theOracle WebLogic Server deployment descriptor information in the Oracle Fusion Middleware Upgrade Guide for Java EE |
|
Copy elements to |
The To upgrade your application, you should edit the files in a working project directory that is a copy of your original application project directory. As you follow the advice in the upgrade report findings, copy the appropriate elements in the generated sample into the working copy of your |
Follow report advice and make changes in separate working directory |
For each finding in the report, follow the advice and make the necessary modifications to the files in your working directory. Your working directory should be a separate project directory where you are upgrading your application. This directory is typically separate from the application and project created for the upgrade report findings and for the artifacts generated by SmartUpgrade. |
Compile and redeploy application on WebLogic Server |
After you make the changes identified in the upgrade report, you can then compile your application and check for compilation errors. If the compilation is successful, redeploy your application on Oracle WebLogic Server. For information on deploying applications to Oracle WebLogic Server, refer to the following resource:
|
For information about using the Web services artifacts that are generated by SmartUpgrade, refer to the following sections:
Differences Between OC4J and Oracle WebLogic Server Web Services
How Web Services Artifact Generation Differs From Deployment Descriptor Generation
About the Content of the Generated Web Services Output Directories
Using Artifacts Generated for a Dedicated Web Services Application
Using Artifacts Generated for an Application with Both Web Services and Other Java EE Elements
For general information about the differences between OC4J and Oracle WebLogic Server Web services, refer to the following resources:
"Task 6: Upgrade the Application Web Services" in the Oracle Fusion Middleware Upgrade Guide for Java EE
"Overview of WebLogic Web Services" in Oracle Fusion Middleware Introducing WebLogic Web Services for Oracle WebLogic Server
Unlike other features of OC4J, SmartUpgrade automates much of the upgrade process for Web services.
For example, for most of the other application features and technologies, you analyze the application or project with SmartUpgrade and then follow the advice in each finding within the SmartUpgrade upgrade report.
Alternatively, for Web services applications, you can let SmartUpgrade do most of the work. If you configure SmartUpgrade to generate artifacts, and the application contains Web services, then SmartUpgrade does not generate findings for the Web services in your application. Instead, it automatically generates a set of artifacts that in most cases are ready to be deployed on Oracle WebLogic Server.
In fact, if the application is a dedicated Web services application (with no other features to upgrade) you can configure SmartUpgrade to generate an archive of the generated Web services artifacts. The resulting archive can be deployed directly on Oracle WebLogic Server. For more information, see Section 2.2.3, "Setting Properties When Upgrading OC4J Web Services with SmartUpgrade".
When you generate Oracle WebLogic Server Web services artifacts, SmartUpgrade upgrades the following OC4J Web services to Oracle WebLogic Server 10.3 JAX-RPC Web services:
OC4J 10g Release 3 (10.1.3) Web services
OC4J 10g Release 2 (10.1.2) Web services
The upgraded Web services use the same contextpath
and the context URI as the OC4J 10g Web services. For example, suppose the URI for your OC4J 10g Release 3 (10.1.3) Web services were as follows:
http://locahost:8888/contextpath/soap11 http://locahost:8888/contextpath/soap12
After the upgrade, you should be able to access the same Web services via the following URI on the Oracle WebLogic Server domain:
http://locahost:7001/contextpath/soap11 http://locahost:7001/contextpath/soap12
During the upgrade process, SmartUpgrade automatically merges Web services related deployment descriptors (such as web.xml
and weblogic-webservices.xml
) and generates "glue code" that allows your upgraded Web services to communicate with your existing remote endpoints.
For more information about the Web services upgrade tasks that SmartUpgrade performs for you, see Section 1.4.2, "Generation of Web Services Artifacts".
You can optionally configure SmartUpgrade to analyze your application specifically to determine the performance impact of the generated glue code. For more information, see Section 4.4, "Analyzing the Performance Impact of the Web Services Glue Code Generated by SmartUpgrade".
By default, SmartUpgrade saves all generated artifacts, including the Web services artifacts, in the /gen_src/
directory inside your new project directory (if you are using Oracle JDeveloper) or in the upgrade folder (if you are using the command-line interface). For more information, see Section 4.1, "Locating the Artifacts Generated by SmartUpgrade".
The Web services artifacts are output to a subdirectory called web-services-artifacts
, which is created under the default application-specific output directory (Figure 4-1).
For example, if your application archive is called myWSapplication.ear
, then the Web services artifacts are created in the following directory structure:
project_directory/gen_src/myWSapplication.d/web-services-artifacts
/myWSapplication-output/
Within the output directory, you will find:
A set of log files with the extension .out
and .err
, which identify the output and error log files for each phase of the Web services upgrade.
The source upgrade plan (config.xml
) and target upgrade plan (outConfig.xml
).
The configuration files used to assemble the Web services.
The subdirectories described in Table 4-2.
Table 4-2 Summary of the Web Services Output Directories
If the application you are upgrading is a dedicated Web services application, then you can configure SmartUpgrade to package the contents of the output folder into a deployable archive.
Figure 4-5 shows a flow chart of the steps required to generate a deployable EAR file that contains the upgraded Web services artifacts. Table 4-3 describes each of the steps in the flow chart.
Table 4-3 Description of the Flow Chart Steps When Upgrading a Dedicated Web Services Application
Step | Description |
---|---|
Start the Java EE Upgrade Wizard; or run command-line utility |
From Oracle JDeveloper, start the Java EE Upgrade wizard, as described in Section 2.2, "Starting and Using the Java EE Upgrade Wizard" From the command-line interface, run the command-line arguments, as described in Chapter 3, "Using the SmartUpgrade Command Line". |
From Oracle JDeveloper, select Generate Artifacts on the OC4J Artifacts screen in the Java EE Upgrade wizard. From the command-line interface, use the |
|
From Oracle JDeveloper, select Package Upgraded Application from the OC4J Web Services Upgrade page in the Java EE Upgrade wizard. From the command-line interface, use the |
|
Warning or error in Log window? |
Check the SmartUpgrade log output to see if an error or warnding appears, such as the one shown in Example 2-1. |
Perform any manual tasks described in the Log window |
The warning or error in the Log window will include specific instructions for how to address any issues found with the Web services in your application. Follow the instructions in the warning or error. Some of these actions will involve manipulating files in the intermediate or exploded output directories. |
Rerun SmartUpgrade using options identified in Log window |
In Oracle JDeveloper, follow the instructions in Section 2.2.4, "Continuing with the Upgrade of Web Services Artifacts". If you are using the command-line interface, then run the SmartUpgrade command again, using the options indicated in the warning or error message. |
Locate generated EAR file in final output folder |
Refer to Section 4.1, "Locating the Artifacts Generated by SmartUpgrade" for more information about the SmartUpgrade output folders. |
Deploy generated EAR file on WebLogic Server |
For information on deploying applications to Oracle WebLogic Server, refer to the following resource:
|
If your application contains OC4J Web services and also contains other Java EE features that must be updated, then you can generate the Web services artifacts, update the application with your additional required changes, and then repackage the application.
Figure 4-6 shows a flow chart of the steps required to perform this task. XXX provides an explanation of each step.
Figure 4-6 Flow Chart of Upgrading an Application That Contains Web Services and Other Java EE Features That Require Upgrade
Table 4-4 Description of the Steps in the Web Services and Java EE Application Upgrade Flow Chart
Step | Description |
---|---|
Start the Java EE Upgrade Wizard; or run command-line utility |
From Oracle JDeveloper, start the Java EE Upgrade wizard, as described in Section 2.2, "Starting and Using the Java EE Upgrade Wizard" From the command-line interface, run the command-line arguments, as described in Chapter 3, "Using the SmartUpgrade Command Line". |
From Oracle JDeveloper, select Generate Artifacts on the OC4J Artifacts screen in the Java EE Upgrade wizard. From the command-line interface, use the |
|
From Oracle JDeveloper, clear the Package Upgraded Application check box on the OC4J Web Services Upgrade page in the Java EE Upgrade wizard. From the command-line interface, do not use the |
|
Warning or Error in Log Window? |
Check the SmartUpgrade log output to see if an error appears, such as the one shown in Example 2-1. |
Perform any manual tasks described in the Log window |
The warning or error in the Log window will include specific instructions for how to address any issues found with the Web services in your application. Follow the instructions in the warning or error. Some of these actions will involve manipulating files in the intermediate or exploded output directories. |
Rerun SmartUpgrade using optipns Identified in Log window |
In Oracle JDeveloper, follow the instructions in Section 2.2.4, "Continuing with the Upgrade of Web Services Artifacts". If you are using the command-line interface, then run the SmartUpgrade command again, using the options indicated in the warning message. |
Locate intermediate and exploded directories |
For more information, see Section 4.1, "Locating the Artifacts Generated by SmartUpgrade". |
Copy generated deployment descriptors to |
As you update the deployment descriptors in the exploded directory, copy any generated elements from the sample For more information, see Section 4.2.3, "Using the Generated Web Application Deployment Descriptor Elements". |
Follow report advice and make Java EE changes in exploded directory |
For each finding in the report, follow the advice and make the necessary modifications to the files in the exploded directory. Modifications you make to the files in this directory will be saved and can be packaged into the final EAR file later, as long as you do not run SmartUpgrade and generate a source upgrade plan. CAUTION: To be sure your changes to this directory are not overwritten, after you make changes to the directory, be sure to select Skip Glue Code Generation in Oracle JDeveloper or use the |
Start the Java EE Upgrade Wizard; or run command-line utility |
From Oracle JDeveloper, start the Java EE Upgrade wizard, as described in Section 2.2, "Starting and Using the Java EE Upgrade Wizard" From the command-line interface, run the command-line arguments, as described in Chapter 3, "Using the SmartUpgrade Command Line". |
From Oracle JDeveloper, select Generate Artifacts on the OC4J Artifacts screen in the Java EE Upgrade wizard. From the command-line interface, use the |
|
From Oracle JDeveloper, select Skip Glue Code Generation on the OC4J Artifacts page in the Java EE Upgrade wizard. From the command-line interface, use the CAUTION: If you made changes to the exploded directory, it is important that you select this option; otherwise your changes will be overwritten. |
|
From Oracle JDeveloper, select Package Upgraded Application from the OC4J Web Services Upgrade page in the Java EE Upgrade wizard. From the command-line interface, use the |
|
Locate generated EAR file in final output folder |
Refer to Section 4.1, "Locating the Artifacts Generated by SmartUpgrade" for more information about the SmartUpgrade output folders. |
Deploy generated EAR file on WebLogic Server |
For information on deploying applications to Oracle WebLogic Server, refer to the following resource:
|
To upgrade your OC4J Web services to Oracle WebLogic Server, SmartUpgrade generates Java programming code called "glue code," which allows your upgraded Web services to continue to communicate with your existing external partners and URIs.
To determine the performance impact of the generated glue code:
Select one of the following options when you use SmartUpgrade to upgrade your application and generate Web services artifacts:
If you are using Oracle JDeveloper, select Generate Instrumented Code for Performance Analysis on the OC4J Web Services Upgrade page of the Java EE Upgrade wizard.
If you are using the SmartUpgrade command-line interface, use the -evaluate
command-line option.
If you enable this option, then SmartUpgrade instruments the generated wrapper ("glue") code for performance analysis.
Note that this option is appropriate only for testing the application, and not for production environments.
Perform the upgrade of your application and deploy the application on Oracle WebLogic Server.
After the application is deployed and running successfully on Oracle WebLogic Server, locate the following HTML file in the Oracle WebLogic Server domain directory:
MW_HOME/user_projects/domains/domain_name/webservice_port_name.html
Open the HTML file in a browser.
The browser displays the Glue Code Performance Analysis page. By default, no data is displayed in each column of the table.
Exercise the Web service to generate some performance data.
You can test the Web service using the Oracle WebLogic Server Administration Console or the Oracle Enterprise Manager Fusion Middleware Control.
For more information, see "Testing Your Web Services" in the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.
Refresh the browser where the Glue Code Performance Analysis page is displayed.
Each time you test the Web service, an entry is added to the Glue Code Performance page. Use the data on this page to measure the impact of the glue code on the performance of the Web service.
Note: When you are finished analyzing the performance metrics, repackage the application for production environment, by running SmartUpgrade again with the following options:
|