Examples of Using the SmartUpgrade Command-Line Interface

3-12 Oracle Fusion Middleware SmartUpgrade Users Guide

3.1.7 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: ■ Identifying the Oracle WebLogic Server Home Directory ■ Using the SmartUpgrade Command-Line Interface to analyze an Enterprise Archive EAR File ■ Using the SmartUpgrade Command-Line Interface to Generate Oracle WebLogic Server Artifacts ■ Using the SmartUpgrade Command-Line Interface to Generate an HTML Report ■ Limiting the Findings to Specific Rule Categories from the SmartUpgrade Command-Line Interface ■ Using the SmartUpgrade Command-Line Interface to Analyze 10g Release 2 10.1.2 Applications

3.1.7.1 Identifying the Oracle WebLogic Server Home Directory

For many of its operations, SmartUpgrade requires specific libraries and resources that are provided by Oracle WebLogic Server. When running SmartUpgrade as an extension to Oracle JDeveloper, SmartUpgrade locates these files automatically using the Oracle WebLogic Server software that you install with the Oracle JDeveloper installer. For more information, see Section 2.1, Installing and Configuring Oracle JDeveloper . However, on the command line, you must either define the environment variable WL_ HOME or use the -targetStackHome option to specify the location of an Oracle WebLogic Server home directory to use for this purpose. For example, to define the WL_HOME variable: set WL_HOME=c:\middleware\wlserver_10.3 To use the -targetStackHome option, refer to the following example: -wrapperNullAllowed Wrapper Null Value Allowed This option applies specifically to artifact generation of Web Services. It should be used in conjunction with the -generate argument when the web-services category is enabled. 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. Note that WebLogic Server JAX-RPC Web Services do not allow null values for wrapper types. Table 3–3 Cont. Summary of the Command-Line Options Specific to Generating Artifacts Command-Line Option Equivalent Option in the Java EE Upgrade Wizard Description Using the SmartUpgrade Command Line 3-13 java -jar smartupgrade.jar --ears myApp.ear -generate -category web-services -targetStackHome c:\middleware\wlserver_10.3

3.1.7.2 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. ■ On the Windows operating system: java -jar smartupgrade.jar --ears C:\MyApps\myApp.ear account_report.txt ■ On the UNIX operating system: java -jar smartupgrade.jar --ears homeMyAppsmyApp.ear account_report.txt

3.1.7.3 Using the SmartUpgrade Command-Line Interface to Generate Oracle WebLogic Server Artifacts

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: java -jar smartupgrade.jar --ears archive_name -generate -targetStackHome c:\middleware\wlserver_10.3 For another example, suppose you want to do the following: ■ Specify the Oracle WebLogic Server home ■ Restrict generation of artifacts for upgrade to Web Services artifacts only ■ Specify the classpath to additional libraries not contained in the application archive but required for the loading of classes ■ Indicate that you want SmartUpgrade to generate code instrumented for performance analysis 3-14 Oracle Fusion Middleware SmartUpgrade Users Guide In that case, you would enter the following command: java -jar smartupgrade.jar --ears archive_name -generate -category web-services -targetStackHome c:\middleware\wlserver_10.3 -additionalClassPath path_to_libraries -evaluate For information on the results of this analysis, see Chapter 4, Using SmartUpgrade Generated Artifacts .

3.1.7.4 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: java -jar smartupgrade.jar --ears myApp.ear -html account_mgmt_report.html For related information, see Section 3.1.8, Controlling the Output of SmartUpgrade Findings Information and Error Reporting . 3.1.7.5 Limiting the Findings to Specific Rule Categories from the SmartUpgrade Command-Line Interface By default, SmartUpgrade generates a report and optionally generates artifacts by applying all rule categories to the selected archive or OC4J server configuration. However, if you want to limit the size of the report, or if you want to focus on a particular aspect of your application, you can limit the analysis to a specific set of SmartUpgrade rule categories. For example, to analyze only the data-source configuration of the myApp.ear application: java -jar smartupgrade.jar --ears myApp.ear -category data-sources To apply multiple categories, separate the list of categories with a space. For example: java -jar smartupgrade.jar --ears myApp.ear -category data-sources web-app Table 3–4 describes the SmartUpgrade rule categories you can apply when generating your reports and, optionally, your application artifacts. Note: If you are generating artifacts, use caution when specifying the -category option. If you use both the -category and -generate options, SmartUpgrade generates only the artifacts of the specified categories. Using the SmartUpgrade Command Line 3-15

3.1.7.6 Using the SmartUpgrade Command-Line Interface to Analyze 10g Release 2 10.1.2 Applications

By default, SmartUpgrade assumes the applications you are upgrading were previously deployed on Oracle Application Server 10g Release 3 10.1.3. However, you can use the -target option to specify that SmartUpgrade analyze your application for any features, configuration settings, or artifacts that are specific to 10g Release 2 10.1.2. If you are upgrading an application that was previously deployed on OC4J as part of an Oracle Application Server 10g Release 2 10.1.2 installation, use the -target option as follows: java -jar smartupgrade.jar --LOCATOR_NAME -target 10.1.2 For example: java -jar smartupgrade.jar --ears C:\myApps\my1012App.ear -target 10.1.2 Table 3–4 List of SmartUpgrade Rule Categories Rule Category Use this category to analyze... adf Artifacts specific to the Oracle Application Development Framework Oracle ADF. api Standard application programming interfaces APIs used in the application. This category of rules checks for OC4J and third-party APIs that may not be supported in Oracle WebLogic Server. app-client Client interfaces within the application. classloading Classloading configurations and shared libraries used by the application. cluster Cluster-specific configuration settings in the application. data-sources OC4J-specific data source configuration settings. ejb Enterprise Java Beans being used by the application. jca J2EE Connector Architecture JCA configuration settings and artifacts. jms Java Messaging Server configuration settings and artifacts, including the use of Oracle Enterprise Messaging Service OEMS. jmx Java Management Extensions JMX used by the application. jndi Java Naming and Directory Interface JNDI configuration settings and artifacts. jta Java Transaction API JTA configuration settings and artifacts. rmi Remote Method Invocation RMI configuration settings and artifacts. security Security configuration settings and artifacts. soa Service-Oriented Architecture SOA configuration settings and artifacts. web-app Web application configuration settings and artifacts. web-services Web services configuration settings and artifacts. webcache Oracle Web Cache configuration settings. 3-16 Oracle Fusion Middleware SmartUpgrade Users Guide

3.1.8 Controlling the Output of SmartUpgrade Findings Information and Error Reporting