4 Using SmartUpgrade Generated Artifacts

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:

Locating the Artifacts Generated by SmartUpgrade
Using Web Application Deployment Descriptor Artifacts Generated by SmartUpgrade
Using Web Services Artifacts Generated by SmartUpgrade

4.1 Locating the Artifacts Generated by SmartUpgrade

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:

Locating the Generated Artifacts and Output Folders
Locating the Generated Artifacts in Oracle JDeveloper

4.1.1 Locating the Generated Artifacts and Output Folders

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.

Figure 4-1 Output Directories for Generated Artifacts

4.1.2 Locating the Generated Artifacts in Oracle JDeveloper

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

Figure 4-2 Locating Generated Deployment Descriptor Artifacts in Oracle JDeveloper

Figure 4-3 Locating the Web Services Output Folders in Oracle JDeveloper

4.2 Using Web Application Deployment Descriptor Artifacts Generated by SmartUpgrade

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

4.2.1 Differences Between OC4J and Oracle WebLogic Server Deployment Descriptors

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

4.2.2 List of Deployment Descriptor Elements Generated by 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:

virtual-directory
resource-eve-ref-mapping
ejb-ref-mapping
default-char-set
jsp-print-nulls
default-mime-type
directory-browsing
persistence-path

4.2.3 Using the Generated Web Application Deployment Descriptor Elements

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".
Select Generate Artifacts	From Oracle JDeveloper, select Generate Artifacts on the OC4J Artifacts screen in the Java EE Upgrade wizard. From the command-line interface, use the `-generate` command-line option.
Locate the sample `weblogic.xml` file generated by SmartUpgrade	For more information, see Section 4.1, "Locating the Artifacts Generated by SmartUpgrade".
Review generated elements in sample `weblogic.xml`	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 `weblogic.xml` in working directory	The `weblogic.xml` generated by SmartUpgrade upgrade is a sample file. 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 `weblogic.xml` file.
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: Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server "Deploying Applications" in the Oracle Fusion Middleware Administrator's Guide

4.3 Using Web Services Artifacts Generated by SmartUpgrade

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
Capabilities of the SmartUpgrade Web Services Upgrade
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

4.3.1 Differences Between OC4J and Oracle WebLogic Server Web Services

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

4.3.2 How Web Services Artifact Generation Differs From Deployment Descriptor Generation

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

4.3.3 Capabilities of the SmartUpgrade Web Services Upgrade

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 3 (10.1.3) EJB 2.1 Web services
OC4J 10g Release 3 (10.1.3) EJB 3.0 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".

4.3.4 About the Content of the Generated Web Services Output Directories

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

Directory Description When is it created or overwritten?

Directory	Description	When is it created or overwritten?
final	If you configured SmartUpgrade to package the upgraded application into an archive, then this folder contains the final, upgraded, and deployable Web services application. The application is expanded on disk, as well as in the form of a packaged enterprise archive file.	This directory gets overwritten and recreated each time you run SmartUpgrade with the options for generating Web services artifacts and packaging the upgrade results in an EAR file. Specifically, the directory is overwritten when you select Package Upgraded Application on the OC4J Web Service Upgrade wizard page or use the `-autoPack` command-line option. The directory is recreated by merging the content of the exploded and intermediate directories.
intermediate	This directory contains the upgraded Web services artifacts and glue code that are not yet packaged in the final deployable application archive. It contains intermediate information only for Web service artifacts.	This directory gets overwritten and recreated each time you run SmartUpgrade when it is configured to generate Web services glue code. You can prevent SmartUpgrade from overwriting this directory by enabling the option to skip the generation of glue code.
exploded	This directory contains the original, input application archive, as-is, exploded on disk, with no changes. You can perform manual changes in this directory to manually upgrade non-Web services components. However, note that if you run SmartUpgrade again, you must enable the option to skip upgrade plan generation; otherwise, the directory and your changes are overwritten.	This directory gets overwritten and is recreated each time you run SmartUpgrade when it is configured to generate a source upgrade plan. You can prevent SmartUpgrade from overwriting this directory by selecting Skip Source Upgrade Plan Generation on the OC4J Web Services Upgrade wizard page or by using the `-skipSourcePlan` command-line option. Note: If you select Skip Glude Code Generation (or use the -`skipGlueCode` command-line option), then SmartUpgrade also enables the `-skipTargetPlan` option, which in turn enables the `-skipSourcePlan` option.

final

If you configured SmartUpgrade to package the upgraded application into an archive, then this folder contains the final, upgraded, and deployable Web services application.

The application is expanded on disk, as well as in the form of a packaged enterprise archive file.

This directory gets overwritten and recreated each time you run SmartUpgrade with the options for generating Web services artifacts and packaging the upgrade results in an EAR file.

Specifically, the directory is overwritten when you select Package Upgraded Application on the OC4J Web Service Upgrade wizard page or use the -autoPack command-line option.

The directory is recreated by merging the content of the exploded and intermediate directories.

intermediate

This directory contains the upgraded Web services artifacts and glue code that are not yet packaged in the final deployable application archive.

It contains intermediate information only for Web service artifacts.

This directory gets overwritten and recreated each time you run SmartUpgrade when it is configured to generate Web services glue code.

You can prevent SmartUpgrade from overwriting this directory by enabling the option to skip the generation of glue code.

exploded

This directory contains the original, input application archive, as-is, exploded on disk, with no changes.

You can perform manual changes in this directory to manually upgrade non-Web services components.

However, note that if you run SmartUpgrade again, you must enable the option to skip upgrade plan generation; otherwise, the directory and your changes are overwritten.

This directory gets overwritten and is recreated each time you run SmartUpgrade when it is configured to generate a source upgrade plan.

You can prevent SmartUpgrade from overwriting this directory by selecting Skip Source Upgrade Plan Generation on the OC4J Web Services Upgrade wizard page or by using the -skipSourcePlan command-line option.

Note: If you select Skip Glude Code Generation (or use the -skipGlueCode command-line option), then SmartUpgrade also enables the -skipTargetPlan option, which in turn enables the -skipSourcePlan option.

4.3.5 Using Artifacts Generated for a Dedicated Web Services Application

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.

Figure 4-5 Flow Chart of Upgrading a Dedicated Web Services Application

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".
Select Generate Artifacts	From Oracle JDeveloper, select Generate Artifacts on the OC4J Artifacts screen in the Java EE Upgrade wizard. From the command-line interface, use the `-generate` command-line option.
Select Package Upgraded Application	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 `-autoPack` command-line option.
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: Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server "Deploying Applications" in the Oracle Fusion Middleware Administrator's Guide

4.3.6 Using Artifacts Generated for an Application with Both Web Services and Other Java EE Elements

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".
Select Generate Artifacts	From Oracle JDeveloper, select Generate Artifacts on the OC4J Artifacts screen in the Java EE Upgrade wizard. From the command-line interface, use the `-generate` command-line option.
Do NOT select Package Upgraded Application	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 `-autoPack` command-line option.
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 `weblogic.xml` in exploded directory	As you update the deployment descriptors in the exploded directory, copy any generated elements from the sample `weblogic.xml` file in the new SmartUpgrade project to a `weblogic.xml` deployment descriptor structure in the exploded directory. 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 `-skipGlueCode` option when running the SmartUpgrade command-line interface; otherwise, your changes will overwritten by SmartUpgrade.
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".
Select Generate Artifacts	From Oracle JDeveloper, select Generate Artifacts on the OC4J Artifacts screen in the Java EE Upgrade wizard. From the command-line interface, use the `-generate` command-line option.
Select Skip Glue Code Generation	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 `-skipGlueCode` option. CAUTION: If you made changes to the exploded directory, it is important that you select this option; otherwise your changes will be overwritten.
Select Package Upgraded Application	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 `-autoPack` command-line option.
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: Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server "Deploying Applications" in the Oracle Fusion Middleware Administrator's Guide

4.4 Analyzing the Performance Impact of the Web Services Glue Code Generated by SmartUpgrade

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:

If you are using Oracle JDeveloper, then do not select Generate Instrumented Code for Performance Analysis and select Skip Target Upgrade Plan Generation.
If you are using the command-line interface, then use the -evaluate false and -skipTargetPlan true options when you run SmartUpgrade.

Figure 4-7 SmartUpgrade Web Services Upgrade - Glue Code Performance Analysis Page