Oracle® Fusion Middleware Upgrade Guide for Oracle SOA Suite, WebCenter, and ADF 11g Release 1 (11.1.1) E10127-02 |
|
![]() Previous |
![]() Next |
This chapter provides important supplementary information upgrading Oracle SOA applications to Oracle Fusion Middleware 11g.
Use Chapter 8, "Overview of Upgrading Oracle SOA Suite, WebCenter, and ADF Applications" for the tasks required to upgrade any Oracle SOA Suite, WebCenter, and ADF application.
Use the following sections to understand tasks specific to upgrading Oracle SOA applications:
Section 9.2, "Upgrade Tasks Associated with All Java Applications"
Section 9.3, "Upgrade Tasks Associated with All Oracle SOA Suite Applications"
When you open an Oracle Application Server 10g Oracle SOA Suite application in Oracle JDeveloper 11g, the Oracle JDeveloper Migration Wizard attempts to upgrade your application automatically to Oracle Fusion Middleware 11g.
However, there are some limitations to what the Oracle JDeveloper Migration Wizard can perform automatically. Refer to specific sections of this chapter for information about the types of manual tasks you might have to perform on your Oracle SOA Suite applications before or after using the Migration Wizard.
Applying the Latest Patch Sets
For best results, Oracle recommends that you apply the most recent patch sets to your Oracle SOA Suite environment and that you use the latest 10g Release 3 (10.1.3) Oracle JDeveloper before upgrading to 11g.
Keeping Oracle JDeveloper and Oracle SOA Suite at the Same Version Level
As a general rule, you should always update your Oracle SOA Suite and Oracle JDeveloper installations at the same time and run the same version of both these Oracle products.
Verifying That You Have the Required SOA Composite Editor Oracle JDeveloper Extension
To upgrade your Oracle SOA Suite applications to 11g, you must have the Oracle SOA Composite Editor extension for Oracle JDeveloper 11g.
To verify that the extension is installed, select About from the Oracle JDeveloper Help menu, and click the Version tab. You should see an entry in the list of components called SOA Composite Editor
.
If this component does not appear on the Version tab of the About dialog box, close the About dialog and select Check for Updates from the Help menu. Use the Check for Updates wizard to locate and install the latest version of the SOA Composite Editor extension.
Before you begin upgrading your Oracle SOA Suite applications, be sure to review the Oracle Fusion Middleware Upgrade Guide for Java EE, which contains information about upgrading standard Java EE applications to Oracle WebLogic Server.
If your applications contain any custom Java code, you should review the Java code against the procedures and recommendations available in the Oracle Fusion Middleware Upgrade Guide for Java EE.
The following information should reviewed when you are upgrading any Oracle SOA Suite application to Oracle Fusion Middleware 11g:
Understanding Oracle SOA Suite API Changes for Oracle Fusion Middleware 11g
Upgrading Applications That Require Proxy Settings for Web Services
Recreating build.xml and build.properties Files Not Upgraded by the Migration Wizard
Table 9-1 describes the APIs you can use in an Oracle SOA Suite application. For each Oracle Application Server 10g API, it provides a summary of the changes for Oracle Fusion Middleware 11g and where you can get more information about upgrading your applications that use the API.
Table 9-1 Summary of Oracle SOA Suite API Changes for Oracle Fusion Middleware 11g
10g API | Action for 11g | 11g JavaDoc |
---|---|---|
Updated for Oracle Fusion Middleware 11g, but the new 11g version is backward compatible with 10g. |
Oracle Fusion Middleware Callout Java API Reference |
|
Oracle Application Server Integration B2B Instance Message Java API |
Updated for Oracle Fusion Middleware 11g, but the new 11g version is backward compatible with 10g. |
Oracle Fusion Middleware Instance Data Access Java API Reference |
Updated for Oracle Fusion Middleware 11g, but the new 11g version is backward compatible with 10g. |
Oracle Fusion Middleware Workflow Services Java API Reference for Oracle BPEL Process Manager |
|
See Section 9.3.1.1, "Upgrading to the Oracle Fusion Middleware Java API for Oracle Business Rules" |
Oracle Fusion Middleware Java API Reference for Oracle Business Rules |
|
See Section 9.3.1.2, "Upgrading to the Oracle Fusion Middleware Infrastructure Management Java API for Oracle SOA Suite" |
See Section 9.3.1.2, "Upgrading to the Oracle Fusion Middleware Infrastructure Management Java API for Oracle SOA Suite" |
|
Updated for Oracle Fusion Middleware 11g, but the new 11g version is backward compatible with 10g and part of the new Infrastructure Management Java API. |
"Using Oracle BPEL Process Manager Sensors" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite |
The following sections introduce the Oracle Business Rules 11g SDK and API and provide instructions for upgrading to the Oracle Business Rules API:
In Oracle Fusion Middleware11g, the Oracle Business Rules SDK and API has been significantly improved.
In Oracle Application Server 10g, developers were required to manually manage accessing the repository and creating and using RuleSession
instances. In Oracle Fusion Middleware 11g, the Decision Point API and decision function features provide an interface and implementation that simplifies the definition and execution of rules.
When upgrading to Oracle Business Rules 11g, look first at how you can use these new features, as documented in the Oracle Fusion Middleware User's Guide for Oracle Business Rules.
However, if you want to continue to use the Oracle Business Rules SDK in the same way as you did for 11g, then the following sections describe how to directly translate the Oracle Business Rules 10g SDK to the 11g SDK.
All of the classes discussed in this section are in the rulesdk2.jar
file and under the oracle.rules.sdk2
package.
In Oracle Business Rules 10g, it was common for an application developer to use a file-based repository while developing the application, and then switch to using a WebDAV repository for production.
In Oracle Business Rules 11g, you can instead access the rule dictionary file directly before it is packaged into a format which can be deployed to MDS.
In the following examples, compare the code required to access a dictionary in development mode in 10g (Example 9-1) with the code required in 11g (Example 9-2).
Note that in general, you should use the Decision Point API rather than continuing to access the RuleRepository directly.
Example 9-1 Accessing a Dictionary with Oracle Business Rules 10g in a Development Environment
String path; // the path to the file repository Locale locale; // the desired Locale // The following code assumes that the path and locale have been set appropriately RepositoryType rt = RepositoryManager.getRegisteredRepositoryType("oracle.rules.sdk.store.jar"); RuleRepository repos = RepositoryManager.createRuleRepositoryInstance(rt); RepositoryContext rc = new RepositoryContext(); rc.setLocale(locale); rc.setProperty("oracle.rules.sdk.store.jar.path", path); repos.init(rc);
Example 9-2 Accessing a Dictionary with Oracle Business Rules 11g in a Development Environment
protected static final String DICT_LOCATION ="C:\\scratch\\CarRental.rules"; ... RuleDictionary dict = null; Reader reader = null; try { reader = new FileReader(new File(DICT_LOCATION)); dict = RuleDictionary.readDictionary(reader, new DecisionPointDictionaryFinder(null)); List<SDKWarning> warnings = new ArrayList<SDKWarning>(); dict.update(warnings); if (warnings.size() > 0 ) { System.err.println("Validation warnings: " + warnings); } } catch (SDKException e){ System.err.println(e); } catch (FileNotFoundException e){ System.err.println(e); } catch (IOException e){ System.err.println(e); } finally { if (reader != null) { try { reader.close(); } catch (IOException ioe) {ioe.printStackTrace();} } }
In Oracle Business Rules 10g, WebDAV was the recommended production repository.
In Oracle Business Rules 11g, WebDAV is no longer supported and Metadata Services (MDS) is the recommended repository. Also, the dictionary "name" and "version" have been replaced with a "package" and "name" (similarly to the Java class naming scheme).
In Oracle Business Rules 10g, the version did not provide true versioning. In Oracle Business Rules 11g, the equivalent to specifying a version is to simply change the name. For example, a 10g dictionary with the name foo.bar.MyDict
and version 2
would in 11g be packaged as foo.bar
and name MyDict2
.
In the following examples, compare the code required to access a dictionary in production mode in 10g (Example 9-3) with the code required in 11g (Example 9-4).
Example 9-3 Accessing a Dictionary with Oracle Business Rules 10g in a Production Environment
String url; // the URL for the WebDAV repository Locale locale; // the desired Locale // The following code assumes that the url and locale have been set appropriately RepositoryType rt = RepositoryManager.getRegisteredRepositoryType("oracle.rules.sdk.store.webdav"); RuleRepository repos = RepositoryManager.createRuleRepositoryInstance(rt); RepositoryContext rc = new RepositoryContext(); rc.setLocale(locale); rc.setProperty("oracle.rules.sdk.store.webdav.url", url); repos.init(rc); RuleDictionary dictionaryWithInitialVersion = repos.loadDictionary(dictionaryName); RuleDictionary dictionarySpecificVersion = repos.loadDictionary(dictionaryName, dictionaryVersion);
Example 9-4 Accessing a Dictionary with Oracle Business Rules 11g in a Production Environment
import static oracle.rules.sdk2.repository.RepositoryManager.createRuleRepositoryInstance; import static oracle.rules.sdk2.repository.RepositoryManager.getRegisteredRepositoryType; import static oracle.rules.sdk2.store.mds.Keys.CONNECTION; ... private static final String DICT_PKG = "oracle.middleware.rules.demo"; private static final String DICT_NAME = "CarRental"; private static final DictionaryFQN DICT_FQN = new DictionaryFQN(DICT_PKG, DICT_NAME); ... RuleRepository repo = createRuleRepositoryInstance(getRegisteredRepositoryType(CONNECTION)); repo.init(new RepositoryContext() {{ setDictionaryFinder(new DecisionPointDictionaryFinder(null)); }}); RuleDictionary dict = repo.load(DICT_FQN);
Oracle SOA Suite 11g introduces a new infrastructure management API that replaces several other APIs previously available in Oracle SOA Suite 10g.
For more information about the new API, refer to the Oracle Fusion Middleware Release Notes, which are available as part of the Oracle Fusion Middleware 11g documentation library.
If you are upgrading an Oracle SOA Suite application that depends upon references to custom JAR file libraries. note that these references may not get upgraded automatically when you open and upgrade your application in Oracle JDeveloper 11g.
As a result, you should review your projects for these types of dependencies and, after the upgrade, make sure that you add any missing references, by selecting the Libraries and Classpath link in the Oracle JDeveloper 11g Project Properties dialog.
If you are upgrading an application that uses Web services resources outside your company firewall, you must modify a configuration file that will enable the upgrade to accesses proxy settings and adjust them accordingly during the upgrade of the application.
To configure Oracle JDeveloper 11g to use the proxies during the upgrade process:
Locate the following file in the JDEV_HOME
/bin
directory:
ant-sca-upgrade.xml
Edit the file and modify the following settings to identify the proxy server and port required to resolve the Web services addresses for the applications you are upgrading.
<jvmarg value="-Dhttp.proxySet=true"/> <jvmarg value="-Dhttp.proxyHost=PROXY_SERVER"/> <jvmarg value="-Dhttp.proxyPort=PROXY_PORT"/>
Note that there are two locations in the file to modify these settings. One location is used to set the proxy when you are upgrading an ESB project to Oracle Mediator 11g; the other is used when you are upgrading Oracle BPEL Process Manager projects.
Stop and start Oracle JDeveloper 11g so your changes can take effect and then open and upgrade your application in Oracle JDeveloper 11g.
When you open and upgrade an application in Oracle JDeveloper 11g, the build.xml
and build.properties
files associated with your application projects are not upgraded.
Instead, you must recreate these files in Oracle JDeveloper 11g after the upgrade.
The following information is important if any of your Oracle BPEL Process Manager or Oracle Enterprise Service Bus 10g projects use remote resources that are registered in a UDDI (Universal Description, Discover and Integration) registry, such as Oracle Service Registry (OSR).
Refer to the following for more information:
If you have a 10g Release 3 (10.1.3) project that references an endpoint URL that uses a serviceKey from OSR, then you must be sure that the endpoint URL is up and available when you upgrade the application. Otherwise, the upgrade of the application will fail. To prevent such a failure, verify that the endpoint URLs are available, and if necessary, modify the endpoint URLs in bpel.xml
or the routing service to point to new URL which is accessible.
In Oracle Application Server 10g Release 3 (10.1.3), Oracle BPEL Process Manager and Oracle Enterprise Service Bus projects used the uddi
protocol to obtain resource references from OSR. In Oracle Fusion Middleware 11g, Oracle BPEL Process Manager and Oracle Mediator projects use the orauddi
protocol.
As a result, prior to upgrading your Oracle BPEL Process Manager or Oracle Enterprise Service Bus projects, you must do the following:
Use the service registry to modify the registered service so it uses the new bindings supported by Oracle Fusion Middleware 11g.
For example, in OSR, do the following:
Log in to your Oracle Service Registry.
On the Search tab, click Businesses.
Click Add Name to search for a business by name.
From the search results, click the name of the business you want to modify.
In the left pane of the View Business page, right-click the service you want to modify and select Add Binding from the context menu.
From the Type drop-down menu on the Add Binding page, select wsdlDeployment.In the Access Point field, enter the URL.
For example:
http://machine:port/Proj_ep?WSDL/
Click Add Binding.
Click Save Changes.
Open and upgrade the application in Oracle JDeveloper 11g.
In Oracle JDeveloper, edit the composite.xml
file for the upgraded project and configure the endpoint URL using the UDDI Registry option on the Resource Palette.
For more information about the UDDI registry, visit the following URL:
http://www.oracle.com/technology/tech/soa/uddi/index.html
The following sections describe how to use the Oracle SOA Suite command-line upgrade tool:
Benefits of Using the Oracle SOA Suite Command-Line Upgrade Tool
Using the Oracle SOA Suite Command-Line Upgrade Tool with Oracle JDeveloper 11g
Upgrading BPEL Projects with the Oracle SOA Suite Command-Line Upgrade Tool
The Oracle SOA Suite Command-Line Upgrade Tool has the following benefits:
You can use the command-line tool to automate your application upgrade work, using scripts or other command-line automation tools.
The command-line tool upgrades both Oracle BPEL Process Manager projects, and upgrades Oracle Enterprise Service Bus 10g projects to Oracle Mediator 11g.
With the command-line tool, you can merge BPEL projects together and create a single composite out of multiple BPEL projects. This is not possible when you use the Oracle JDeveloper Migration Wizard.
The functionality is exactly the same as the JDeveloper mode when it comes to dealing with SOA project contents because the same codebase is used.
The Oracle SOA Suite Command-Line Upgrade Tool is compatible (with restrictions) with the Oracle JDeveloper Migration Wizard. In other words, you can choose to remain in command-line mode all the way through the upgrade process (upgrade, compile, package, and deploy), or you can choose to move to Oracle JDeveloper, or you use both tools, with no functionality loss.
However, it is important to note that the command-line tool upgrades SOA project artifacts only. Other Oracle JDeveloper artifacts (for example, the .jpr
and .jws
files) are ignored.
To work around this restriction, note the following:
The Oracle SOA Suite Command-Line Upgrade Tool copies files from the BPEL suitcase directory (the BPEL subdirectory or the directory hosting the BPEL files) to the specified target directory, specified on the command line.
The above copying action does not copy the .jpr
or .jws
files. After the upgrade, the target directory contains only the upgraded SOA project contents.
To remedy this problem in Oracle JDeveloper, you can create a new application or new project, and then define the project directory to be the newly upgraded composite directory.
If you attempt to use the Oracle SOA Suite Command-Line Upgrade Tool to upgrade an application that contains Oracle Human Workflow projects, note that the tool will create a separate project for each upgraded task form.
This resulting project is an Oracle ADF project and Oracle ADF does not support command line deployment. As a result, after using the Oracle SOA Suite Command-Line Upgrade Tool, you must open the upgraded projects in Oracle JDeveloper 11g deploy it from JDeveloper.
For information about how to open the upgraded project in Oracle JDeveloper, see Chapter 9, "Using the Oracle SOA Suite Command-Line Upgrade Tool with Oracle JDeveloper 11g".
The files required to run the Oracle SOA Suite Command-Line Upgrade Tool are installed automatically when you install Oracle JDeveloper 11g and when you install Oracle SOA Suite 11g:
When you install the Oracle SOA Suite 11g, the required XML files are installed in the bin directory of the Oracle SOA Suite Oracle home.
When you install Oracle JDeveloper 11g, the required XML files are installed in the bin directory of the Oracle JDeveloper home.
You can use this files in this directory, together with Apache Ant, to migrate your 10g Release 3 (10.1.3) SOA projects to 11g.
Note: For the purposes of this procedure, it is assumed you are running the Oracle SOA Suite Command-Line Upgrade Tool from the Oracle home of an Oracle SOA Suite installation.If you are running it from a Oracle JDeveloper home, replace ORACLE_HOME with JDEV_HOME in the following procedures. |
To use the ANT project:
Set the ORACLE_HOME environment variable so it is defined as the path to the Oracle SOA Suite Oracle home.
Set the other environment variables that are required by the command-line tool, by running the following script:
On UNIX systems:
. ORACLE_HOME/bin/soaversion.sh
On Windows systems:
ORACLE_HOME\bin\soaversion.cmd
Run the Ant project, as follows:
ant -f ORACLE_HOME/bin/ant-sca-upgrade.xml -Dsource sourceDir -Dtarget targetDir -DappName app_name
When you run the Ant command, note the following:
Your BPEL files from the source directory are migrated to the target directory you specified on the command line. The migration tool creates an application subdirectory using the value you entered as the appName value on the command line.
The sourceDir you specified on the command line can be the bpel
folder, the parent directory that hosts the bpel
folder, or the Oracle Enterprise Service Bus project folder.
The sourceDir and targetDir parameters must be fully-qualified path names.
Note that if the sourceDir and the targetDir directories are the same directory, then the command-line upgrade tool will automatically create a backup of the directory before migration; if you must re-run the upgrade, you can restore the source files using the backup directory. You can identify the backup directory by the ".backup" suffix in its name.
If the sourceDir and targetDir directories are different, a backup directory is not created and is not necessary, because the files in the sourceDir are not modified during the migration.
After upgrade, the logs can be found in the following output directory:
ORACLE_HOME/upgrade/logs
After upgrade, you must run the SCA-Compiler (ant-sca-compile.xml
) which will verify the migrated sources. Because the SCA-Upgrade will not generate complete artifacts in all cases, you will see some errors or warnings from SCA-Compiler with pointers on how to fix them. Check the SCA Compiler for reference.
After getting a clean pass from the SCA-Compiler you can use the ant-sca-package.xml
tool to package your application. You can then deploy the application using ant-sca-deploy.xml
. After deployment, your project will be available to the server for testing.
Note, however, that in most cases, you will likely want to open the upgraded project in Oracle JDeveloper 11g. From there, you can easily review, verify, and make any necessary updates to the application projects.
For more information, see Section 9.3.6.2, "Using the Oracle SOA Suite Command-Line Upgrade Tool with Oracle JDeveloper 11g".
Using the Oracle SOA Suite Command-Line Upgrade Tool, you can merge BPEL projects together and create a single composite. This is not possible when you use the Migration Wizard in Oracle JDeveloper.
To combine multiple BPEL projects into a single composite, provide multiple source directories as part of the -Dsource
property on the command line.
Path separators can be a colon (:) or a semicolon (;). Ant will convert the separator to platform's local conventions. As a guideline, also use double quotes to identity the multiple source directories to prevent Ant from parsing the input in an unexpected manner.
The first source directory specified will be considered as the root of the 11g project and will determine the composite name.
For example:
ant -f ORACLE_HOME/bin/ant-sca-upgrade.xml -Dsource "sourceDir1:sourceDir2" -Dtarget targetDir -DappName app_name
The first project in the source list is considered the root project and only those services are exposed as Composite Services. Anytime you use the merge feature, it is recommended that the projects be related.
Merging of projects is supported for BPEL projects only. ESB projects cannot be merged with other BPEL or other ESB projects.
The Oracle SOA Suite Command-Line Upgrade Tool can also be used to upgrade ESB projects to Oracle Mediator 11g.
To upgrade an ESB project, use the instructions in Section 9.3.6.4, "Upgrading BPEL Projects with the Oracle SOA Suite Command-Line Upgrade Tool", but replace the Ant command with the following:
ant -f $ORACLE_HOME/bin/ant-sca-upgrade.xml -Dsource sourceDir -Dtarget targetDir -DappName app_name mediator
If you use domain value maps (DVMs) or Cross References in your Oracle BPEL Process Manager 10g or Oracle Enterprise Service Bus 10g projects, then note the following:
The xPath functions you use to access the domain value maps or cross references are upgraded automatically to Oracle BPEL Process Manager and Oracle Mediator 10g when you open and upgrade your applications in Oracle JDeveloper 11g.
However, you must perform a manual upgrade task to upgrade the domain value maps and cross references that are saved in the Oracle Enterprise Service Bus repository. The upgrade process moves the domain value maps from the ESB repository to the Oracle Fusion Middleware 11g Metadata Services (MDS) repository.
For more information, see "Managing the MDS Repository" in the Oracle Fusion Middleware Administrator's Guide.
To upgrade your 10g domain value maps in the ESB repository perform the following tasks.
Change directory to the Oracle Enterprise Service Bus Oracle home.
Use the export script to export the metadata to a ZIP file.
For example, on UNIX systems:
ORACLE_HOME/export.sh metadata10g.zip
Use Apache Ant and the upgrade-xrefdvm
target in the sca-upgrade.xml
file to use the metadata ZIP file to generate an Oracle SOA Suite archive JAR file:
Change directory to the Oracle SOA Suite 11g Oracle home.
Use the following command to generate a SOA archive file, which will automatically be called sca_XrefDvmFiles10g_rev1.0.jar
:
ant -f ant-sca-upgrade.xml upgrade-xrefdvm -Dsource=location_of_the_zip_file -Dtarget=location_of_the_soa_archive
For example:
ant -f ant-sca-upgrade.xml upgrade-xrefdvm -Dsource=$ORACLE_HOME/temp/upgrade/metadata10g.zip -Dtarget=$ORACLE_HOME/temp/upgrade
Start Oracle JDeveloper 11g and create a new application.
Import the Oracle SOA Suite archive into a new SOA project:
From the Oracle JDeveloper 11g File menu, select Import, then SOA Archive into SOA Project.
In the Create SOA Project from SOA Archive Dialog Box, select JAR Options in the navigation tree on the left, and then click Browse to locate the sca_XrefDvmFiles10g_rev1.0.jar
file that you created previously in this procedure.
Select File Groups > Project Output from the navigational tree on the left, and enter XrefDvmFiles10g
in the Target Directory in Archive field.
Click OK to create the new SOA project, which is called XrefDvmFiles10g
.
The new project consists of an empty composite, along with the upgraded XRef and DVM files.
Create a JAR file for the XRef and DVM metadata, and then deploy the JAR file to the Oracle SOA Infrastructure.
For more information, see "Deploying and Using Shared Metadata Across SOA Composite Applications," in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
After you upgrade the DVM and cross reference metadata to 11g, you can then use Oracle JDeveloper 11g to modify the entries in the XrefDvmFiles10g
project as needed. Each time you make changes, you must then transfer them to the proper MDS repository using the same deployment process.