Note that you should also make sure that the Java bin directory is defined as part of the current PATH variable, so you can run the java command from any location on your system. Otherwise, you must include the path to the java command every time you run the SmartUpgrade software.

3.1.4.2 Identifying a SmartUpgrade Locator

A locator is a general term to identify the object or objects that you want SmartUpgrade to analyze. The locator can be one or more application archives (EAR, WAR, JAR, or RAR files). It can also be a directory path where archives are stored, or the configuration directory of an OC4J server.

Table 3-1 describes the values you can use for the LOCATOR_NAME command-line option.

Table 3-1 Supported Values for the SmartUpgrade LOCATOR_NAME Option

LOCATOR_NAME value

Description

Examples

--ears

Identifies one or more enterprise archive (EAR) files to analyze.

If you are a providing the path to more than one EAR file, then use a space-delimited list after the -ear option.

If you do not provide a value for this option, SmartUpgrade determines the archive type automatically, by analyzing the archive and assigning the value as follows:

WAR - If the archive contains a WEB-INF directory

EJBJAR - If the archive contains a META-INF directory with an ejb-jar.xml file.

EAR - If the archive contains a WAR or EJBJAR archive

-additionalClassPath

Additional Classpath

An additional classpath containing JAR files and class directories. This option is required when the input application does not contain all the libraries that a Web service depends on.

-autoPack

Package Upgraded Application

Enable this option by passing -autoPack (or -autoPack true) on command line or by selecting the check box on the OC4J Web Services Upgrade wizard page.

When enabled, SmartUpgrade packages the target upgraded application into a deployable archive.

The default value is true when you use the command-line interface and false when you use Oracle JDeveloper (the check box is clear by default).

Note: You can disable this option if the input archive has other JEE artifacts that need to be upgraded. After the wrapper code is generated, and you have upgraded other Java EE artifacts in the application, you can pack the application in a new command by specifying -skipGlueCode and -autoPack options.

The JDK home that SmartUpgrade uses to run the Web Service tools on the target server. The system automatically attempts to locate JDK installed with the target server.

You can override this behavior by specifying a JDK home as a value for this option.

If this option is not specified and if no JDK home is installed as part of the target server, the system will use the current JDK home used to run this upgrade tool.

-packLIBs

Packaging Includes

A list of JAR files, separated by a path separator.

On Windows, the separator is a semicolon (;); on UNIX systems, the separator is colon (:).

The identified JAR files are automatically packaged into the final generated archive, if the final archive is an EAR or WAR file.

This value is also added into the value of additionalClassPath option.

-processTimeout

Generate Tasks Timeout (seconds)

The number of seconds SmartUpgrade will continue trying to process WSDL documents and generate artifacts.

The tasks timeout default is 300 seconds. A different value may be set by using this command-line option, by providing a positive number on the wizard page in Oracle JDeveloper, or by setting the following environment variable prior to starting SmartUpgrade:

GENERATION_TASKS_TIMEOUT

-qos

Quality of Service Policies

This option indicates the types of policies (Quality Of Services) that need to be enabled in the target Web service that is generated.

The list of possible tokens is MTOM, WSS_UNT, or STATEFUL.

Multiple values can be passed with a comma(,) as the separator.

-sourceStack

N/A

The name and version of the server that hosted the original Web services application.

Possible values are:

OC4J1013

OC4J1012

By default, SmartUpgrade attempts to determine the server version from the application. When there is an ambiguity, this option is mandatory.

-targetStackHome

Target Server Home Directory

Mandatory property used to specify the target WebLogic Server home. For example:

C:\Oracle\Middleware\wlserver_10.3

If you are migrating a large number of applications, you can avoid repeatedly specifying this property by setting the environment variable WL_HOME prior to starting Oracle JDeveloper.

The value you set in WL_HOME environment variable will be applied to all applications during the upgrade process.

Important Note: The Target Server Home Directory must be for a WebLogic Server home that is installed separately from Oracle JDeveloper. Do not select the WebLogic Server home that is installed with the Oracle JDeveloper installer.

-wrapperNullAllowed

Wrapper Null Value Allowed

Enable this option by passing -wrapperNullAllowed (or -wrapperNullAllowed true) on the command line or by selecting the check box on the OC4J Web Services Upgrade wizard page.

When enabled, null values are allowed for wrapper types already present in the application before upgrade.

The default value is false. In this case, the null value of a wrapper type will be represented by an empty object.

Enable this option by passing -acceptDuplicates (or -acceptDuplicates true) on the command line or by selecting the check box on the OC4J Web Services Upgrade wizard page.

This option indicates whether the system should ignore the duplicate class error and continue the glue code generation.

You should enable this option only after ensuring that the duplicate classes are identical.

-debug

Pring Debug Info

Enable this option by passing -debug (or -debug true) on the command line or by selecting the check box on the OC4J Web Services Upgrade wizard page.

When enabled, indicates that debug level messages should be printed. The debug messages are more detailed than INFO level messages.

The default value is false.

-debugControl

Logging Level

Use this option to set the level of logging output.

The value is one of the following:

FINE|DEBUG|INFO|WARNING|ERROR|TRACE

The default value is INFO.

Note: This option is not validated; any invalid value will be ignored.

-debugWrap

Margins in Log Output

Enable this option by passing -debugWrap (or -debugWrap true) on the command line or by selecting the check box on the OC4J Web Services Upgrade wizard page.

When enabled, this option causes SmartUpgrade to align the diagnostic output for easy reading.

The default value is true. You can adjust column width using the debugWrapLength option.

-debugWrapLength

Log Line Width

Use this option to set the maximum length of the text that is logged without breaking the text into multiple lines. Use this option to preserve alignment.

This is applicable only when debugWrap option is set to true. The default value is 80.

-plansOnly

Generate Upgrade Plans Only

Enable this option by setting the value to true or selecting the check box in the OC4J Web Services Upgrade wizard page.

When this option is enabled, SmartUpgrade does not generate Web services glue code.

The default value is false (glue code generation should be done).

When this option is enabled, SmartUpgrade exits immediately after the target upgrade plan is generated.

You can use this option when you want to edit the target upgrade plan and then generate glue code in a separate step. This option takes priority over options such as autoPack, which are functional only after the glue code is generated. Such options will be ignored when this option is enabled.

-resolveMapAmbiguity

Resolve Mapping Ambiguity

Enable this option by setting the value to true or selecting the check box in the OC4J Web Services Upgrade wizard page.

Enable this option to allow the system to resolve mapping ambiguities automatically.

This option is applicable only when SmartUpgrade does not find mapping information either in mapping file or from annotations.

The default value is false.

If you want to rely on SmartUpgrade to resolve ambiguity, then enable this option.

-skipGlueCode

Skip Glue Code Generation

Enable this option by setting the value to true or selecting the check box in the OC4J Web Services Upgrade wizard page.

When enabled, this option indicates that glue code generation needs to be skipped. When enabled, the target plan generation is also skipped. Use this option when the you have modified the generated glue code and you need to compile and package the application.

-skipSourcePlan

Skip Source Upgrade Plan Generation

Enable this option by setting the value to true or selecting the check box in the OC4J Web Services Upgrade wizard page.

When enabled, SmartUpgrade does not generate a source migration plan generation and uses an existing plan.

-skipTargetPlan

Skip Target Upgrade Plan Generation

Enable this option by setting the value to true or selecting the check box in the OC4J Web Services Upgrade wizard page.

When enabled, SmartUpgrade does not generate a target upgrade plan generation and instead uses an existing plan.

When this option is enabled, the source upgrade plan generation is also skipped.

3.1.6 Examples of Using the SmartUpgrade Command-Line Interface

The following sections provide some examples of how you can use the SmartUpgrade command-line options to help you upgrade your applications to Oracle WebLogic Server:

3.1.6.1 Using the SmartUpgrade Command-Line Interface to analyze an Enterprise Archive (EAR) File

To generate a SmartUpgrade report for a specific enterprise archive (EAR) file, use the following command syntax:

java -jar smartupgrade.jar --ears path_of_ear_file.ear

For example, if you have an EAR file called myApp.ear and it resides in a directory called my C:\MyApps, then use the following command:

java -jar smartupgrade.jar --ears C:\MyApps\myApp.ear

SmartUpgrade generates a report that is written to the terminal window. To save the report findings, redirect the output to a file. For example, the following examples show how to redirect the output to a file called report.txt.

In addition to generating a report, SmartUpgrade can also generate a limited number of artifacts that can make it easier to update your applications so they can be deployed successfully on Oracle WebLogic Server.

At a minimum, you must:

Use the -generate option to generate artifacts

Specify the mandatory -targetStackHome option that identifies the target server home directory

For example, to generate artifacts in addition to a SmartUpgrade report for an archive called myApp.ear, use the following command:

3.1.6.3 Using the SmartUpgrade Command-Line Interface to Generate an HTML Report

By default, the SmartUpgrade command-line interface generates a report in text format and the report is written to the standard output of the current machine. In most cases, this means the output is written to the terminal window.

You can optionally generate a report in HTML format, which includes headings and lists that can make the output easier to read. Further, you can use your operating system commands to redirect the output to a file. The resulting HTML file can be read by any Web browser or other tool that can read HTML.

For example, if you have an EAR file called account_mgmt.ear and it resides in a directory called my C:\MyApps, then use the following command to generate an HTML file called account_mgmt_report.html:

After you define the taskdef, as shown in Example 3-2, then you can execute SmartUpgrade from within an Ant script.

Example 3-3 shows a typical example, which recursively locates all EAR files in the demo directory and executes SmartUpgrade to examine each file. The valid values used for the upgrade locator element in Example 3-3 are identical to those used for the LOCATOR_NAME on the Java command line.