# Installation Guide

# Upgrading from ALDSP 3.0 or 2.5 to
Oracle Data Service Integrator 10gR3

This chapter describes the steps to upgrade ALDSP 2.5 and ALDSP 3.0/3.2 applications to Oracle Data Service Integrator 10gR3 dataspaces. It includes the following sections:

- Upgrading from ALDSP 3.0/3.2 to Oracle Data Service Integrator 10gR3
- Upgrading from ALDSP 2.5 to Oracle Data Service Integrator 10gR3
- ALDSP 2.5 Upgrade: Known Issues and Workarounds

Note the following:

- ALDSP 2.5 applications are created in the WebLogic Workshop 8.x environment and deployed on WebLogic Server 8.1.
- ALDSP 3.0 applications are created in the Data Services Studio environment and deployed on WebLogic Server 9.2.
- ALDSP 3.2 applications are created within the WorkSpace Studio framework and are deployed on WebLogic Server 10.0 MP1.
- Oracle Data Service Integrator 10gR3 applications are created using Oracle Workshop for WebLogic and are deployed on Oracle WebLogic Server 10gR3.

While upgrading an ALDSP 2.5 application to Oracle Data Service Integrator 10gR3, data service projects within the data service application are upgraded to single a dataspace project. The dataspace project contains all the data services along with the relevant artifacts which need to be deployed on Oracle WebLogic 10gR3.

## Upgrading from ALDSP 3.0/3.2 to Oracle Data Service Integrator 10gR3

Upgrading from ALDSP 3.0 or ALDSP 3.2 to Oracle Data Service Integrator 10gR3 is a very straightforward process, and involves the following:

- Development environment. To upgrade to the Oracle Data Service Integrator 10gR3 development environment, uninstall ALDSP 3.0 or ALDSP 3.2 and install Oracle Data Service Integrator 10gR3, as described in Chapter 1, “Preparing to Install Oracle Data Service Integrator.” You can then use an existing Oracle Data Service Integrator workspace, or create a new one and import the contents of an ALDSP 3.0/3.2-level workspace.
- Deployment environment. From Workshop for WebLogic, you can build and deploy projects created under ALDSP 3.0 or ALDSP 3.2. Alternatively, you can deploy a JAR file created under ALDSP 3.0/3.2 to an Oracle Data Service Integrator-enabled Oracle WebLogic 10gR3 server.

## Upgrading from ALDSP 2.5 to Oracle Data Service Integrator 10gR3

This section describes how to upgrade from ALDSP 2.5 to Oracle Data Service Integrator 10gR3, and covers the following topics:

- Upgrading from ALDSP 2.5 Prerequisites
- Upgrading ALDSP 2.5 Artifacts to Oracle Data Service Integrator 10gR3
- Upgrading an ALDSP 2.5 Application
- Upgrading an ALDSP 2.5 Control to Oracle Data Service Integrator 10gR3
- Importing ALDSP 2.5 Configuration to Oracle Data Service Integrator 10gR3
- Post-Upgrade Artifact Mapping in Oracle Data Service Integrator 10gR3
- Post-Upgrade Tasks for Java Web Service

### Upgrading from ALDSP 2.5 Prerequisites

Before you start upgrading an ALDSP 2.5 data service application to Oracle Data Service Integrator 10gR3, make sure that you perform Build > Clean Application in the Workshop 8.1 environment. This ensures that the application upgrade can be successful and does not require manual clean up of files later.

### Upgrading ALDSP 2.5 Artifacts to Oracle Data Service Integrator 10gR3

Oracle Data Service Integrator source upgrade allows you to upgrade ALDSP 2.5 data service projects and bring them into Workshop for WebLogic as a dataspace project. It also upgrades data service related artifacts such as schema, model diagram, .java files, and WSDL files.

Note: | To upgrade any ALDSP 2.5 data service applications developed in versions prior to 2.5, you need to first upgrade the application to ALDSP 2.5. For more information about upgrading to ALDSP 2.5, refer to Upgrading AquaLogic Data Services Platform Application To Version 2.5 in the ALDSP 2.5 Installation Guide.

This section describes the upgrade of the following artifacts from ALDSP 2.5 to Oracle Data Service Integrator 10gR3:

- Applications
- Projects
- Schemas
- Java Files within the ALDSP Project
- JAR Data Service Projects
- Shredder Based Artifacts
- Other Artifacts

Notes: |

- You cannot use Data Services Studio with Eclipse WTP to upgrade non-data service projects such as Portal and Java web services. To upgrade non-data service projects, refer to the Upgrading WebLogic Workshop 8.1 Applications chapter in the Workshop for WebLogic Platform Programmer's Guide.
- Java projects and Schema projects on which the data service project depends, can be upgraded along with data service projects.

For steps to upgrade an ALDSP Control to Oracle Data Service Integrator 10gR3, refer to Upgrading an ALDSP 2.5 Control to Oracle Data Service Integrator 10gR3.

### Upgrading an ALDSP 2.5 Application

To upgrade using Workshop for WebLogic, do the following:

1. Launch Workshop for WebLogic.
2. Right-click in the Project Explorer, and choose Import > Import. This displays the Import dialog box, as shown in Figure 6-1.
Figure 6-1 Import Dialog

3. Expand the Other option, select Workshop 8.1 Application, and click Next. The Workshop 8.1 Application Upgrade: Application Import dialog is displayed.
4. Browse and select the ALDSP 2.5 application to be upgraded, as shown in Figure 6-2.

Note: | All projects within an ALDSP 2.5 application, along with dependent schemas and Java projects, are upgraded to the same dataspace in Oracle Data Service Integrator 10gR3. Select all the Data Service project dependents such as Java projects and Schema projects, if any. If you do not want to upgrade all the projects within the application to the same dataspace, then select only the projects that you want to upgrade.

Figure 6-2 Workshop 8.1 Application Upgrade: Application Import Dialog

5. Select the Add this prefix to project names option if you want to specify a prefix for the project being upgraded.

Note: | All project files upgraded from ALDSP 2.5 will add the specified prefix, including Java and schema projects created from Data Service projects. The Deployment name property also includes the prefix. However, the ALDSP 2.5 Data Service project folder within the dataspace name will not carry the prefix and therefore, the LD namespace URI does not need to be changed.

1. Ensure that runtime environment is set to Oracle WebLogic Server v10.3.
2. Click Next. The Workshop 8.1 Application Upgrade: Source Upgrade dialog is displayed as shown in Figure 6-3.
Figure 6-3 Workshop 8.1 Application Upgrade: Source Upgrade Dialog

3. In the Source Upgrade dialog box:

1. Select the Error Handling option, which includes:

- Log errors and continue upgrade
- Log errors and abort upgrade
- Display dialog on error

1. Select the Message verbosity option from the list. The options include:

- Include informational comments
- Include warning comments
- Include error comments

1. Select the Change Dataspace Name suffix option to change the name of the dataspace suffix. By default, the dataspace project name will be <application_name>_DS. You can also select a checkbox to create a schema project with the name <Application_Name>_
   Schema from the selected Data Service projects. For example, you can use this option when the schema or the XMLBeans created are to be used outside of the project.

4. Click Next. This displays the Workshop 8.1 Application Upgrade:ODSI Dependency Selection dialog.
Figure 6-4 Workshop 8.1 Application Upgrade: DSP Dependency Selection Dialog

The dialog lists the data service project selected for upgrade along with project JARs including the catalog services project (if available). By default, the data service JAR projects are selected for upgrade. You need to review and deselect them if you do not want them to be upgraded. Because the data service projects are already selected, you cannot edit the selection here.

The dialog also lists the dataspace dependencies such as schemas, Java projects, and library JARs. You need to select the Java projects, schema projects or any library JARs if they are used by one or more data service projects that are bring upgraded. However, internal JAR files such as ldclient.jar and ld-server-app.jar are not listed.

5. Click Next. This completes the upgrade process and a summary of the upgraded files is displayed in the Upgrade Preview, as shown in Figure 6-5.
Figure 6-5 Application Upgrade: Upgrade Preview Dialog

The Upgrade Preview provides the following details:

- List of the actions performed during the upgrade
- List of files added and deleted
- List of files that do not require an upgrade

6. Click Finish. The imported dataspace shows up in the Project Explorer.

Note: | After completing upgrade, an empty EAR project folder is also created. This EAR project is not relevant to the upgraded dataspace and can be deleted if you are not planning to use it at a later stage.

### Upgrading an ALDSP 2.5 Control to Oracle Data Service Integrator 10gR3

Oracle Data Service Integrator 10gR3 does not automatically upgrade ALDSP 2.x Controls. This is because ALDSP 2.x Controls use certain deprecated API methods that preclude a seamless migration path for these controls.

This means that ALDSP 2.x Controls within a project are not considered for upgrade. During upgrade, the preview screen displays the message “If you have Data Service controls, those classes will need to be upgraded manually” to remind you of this condition.

After the upgrade process is complete, you can delete the control file and recreate it as an Oracle Data Service Integrator control.

### Importing ALDSP 2.5 Configuration to Oracle Data Service Integrator 10gR3

After you upgrade an ALDSP 2.5 application to Oracle Data Service Integrator 10gR3, you may want to import your existing administration and project configuration to the new environment. You can import the ALDSP 2.5 configuration file using the ALDSP Administration Console in Oracle Data Service Integrator 10gR3. The ALDSP 2.5 configuration file is located at:

<domain_dir>\liquiddata\<applicationname>config.xml

where <domain_dir> is usually located at `<bea_home>`\weblogic81\samples\domains\

Note: | The Allow Default Anonymous Access option from ALDSP 2.5 is not imported into Oracle Data Service Integrator 10gR3. For more information about setting default anonymous access in Oracle Data Service Integrator 10gR3, refer to “Allowing Anonymous Access” section in Securing Oracle Data Service Integrator Resources.

Oracle Data Service Integrator configuration import requires the ALDSP 2.5 data service projects to be upgraded to a Oracle Data Service Integrator 10gR3 dataspace project and deployed in an Oracle Data Service Integrator 10gR3 runtime environment.

To import the ALDSP 2.5 configurations:

1. Launch ALDSP Administration Console using the following URL and then log in:

http://localhost:7001/odsiconsole

2. Select the upgraded dataspace project.
3. Select the System Administration category and then click the Import tab.
4. Click Lock & Edit to acquire the lock.
5. Click the Import 2.5 Configuration link as shown in Figure 6-6.
Figure 6-6 Import Tab

6. In the Import 2.5 Configuration section, browse and specify the path where the ALDSP 2.5 configuration file is located, as shown in Figure 6-7.
Figure 6-7 Import 2.5 Configuration

7. Click Save > Activate Changes to complete upgrading the configuration file.

### Post-Upgrade Artifact Mapping in Oracle Data Service Integrator 10gR3

This section highlights the results after upgrading from ALDSP 2.5 to Oracle Data Service Integrator 10gR3 and provides information about mapping artifacts between ALDSP 2.5 and Oracle Data Service Integrator 10gR3.

Note: | After upgrade, you can continue to use ALDSP 2.5 static clients to communicate with the Oracle Data Service Integrator-enabled server. If you want to change the upgraded dataspace to use ALDSP 2.5 clients, then you need to apply the changes to the original ALDSP 2.5 application, generate the 2.5 static clients, and use the clients in Oracle Data Service Integrator 10gR3.

Table 6-1 provides details about the upgrade and the mappings of artifacts after upgrading to Oracle Data Service Integrator 10gR3.

Table 6-1 Upgrade Features and Artifact Mapping
ALDSP 2.5 Artifact | Oracle Data Service Integrator 10gR3 Mapping | Features
--- | --- | ---
Application | Dataspace | The dataspace name is the 2.5 application name with the _DS suffix. For example, RTLApp_DS. You can change the suffix during the upgrade process. For more information, refer to Upgrading an ALDSP 2.5 Application.
Projects | Dataspace projects under the upgraded dataspace. | Multiple data service projects are upgraded to a single dataspace. The data service project becomes a folder under the dataspace. The project retains the URI for data service and schemas. To allow ALDSP 2.5 mediator APIs access to the upgraded application, the dataspace project uses the application name (EAR project name) for deployment.
Project Dependencies | JAR files, schema projects, and Java projects | Schema projects that you mark as dependent projects are copied under the dataspace project. For information about marking or selecting project dependencies, refer to step 9 in Upgrading an ALDSP 2.5 Application. Library files marked as dependent are copied to the dataspace project’s DSP-INF\lib folder. Dataspace project depends on the created Java projects and dependant Java projects. All the created Java projects and dependant Java projects depends on the schema project, if created.
Other Project Files | index.xml | Individual index.xml files are removed from projects within the upgraded dataspace. Instead, a single index.xml file is created for the entire dataspace when you build the project. For different projects within a dataspace, the sdo.xsdconfig.xml file is removed at the root level. The xquery-types.xsd file is removed for individual projects and one file is created for the dataspace. The SQL index file from each of the projects in a dataspace are merged and placed under DSP-INF/sql/sql-index.xml for the dataspace.
Java Files | <dataservice_ project_name>_ java | In Oracle Data Service Integrator 10gR3, dataspace projects cannot store Java files. Therefore, during upgrade of ALDSP 2.5 data service projects, they are moved under a new Java project for each data service project. This project has the name: <dataservice_project_name>_java. For the Java projects that are created from the data service project, the dependency is set at the dataspace level. While building the dataspace project, the dependent JAR or binary files, are copied to the DSP-INF/lib folder.
Schema Files | Same as 2.5 | The folder structure and name of the schema remains the same after upgrade. The schema files from ALDSP 2.5 applications must be recompiled with XMLBeans v2to run them inside the Oracle Data Service Integrator 10gR3 server environment. You can do this using the XMLBeans Builder facet. If you choose to create a separate schema project, then all the schema files from different selected data service projects are placed in a separate schema project with name <dataspace_name>_Schema. For information about selecting separate schema project, refer to step c in Upgrading an ALDSP 2.5 Application.
Catalog Data Service Projects | Exploded as _catalogservices folder under dataspace project | Catalog services JAR under APP-INF/lib in ALDSP 2.5 are upgraded in the exploded form under the dataspace. All catalog services are upgraded like other data services. All class files are filtered out and deleted after upgraded and a new catalogservicelib.jar is added under DSP-INF/lib folder.

There are other artifacts such as data services, xfl and Java files, schemas, and WSDL files, which are outlined in Table 6-2.

Table 6-2 Mapping and Features of Other Artifacts Post-Upgrade
Other Files | Features
--- | ---
.ds | The .ds files are upgraded as entity data services with the .ds extension. Data service namespaces are not changed. Pragma information that contains the version number changes to include the 10gR3 stamp. All read functions are upgraded with visibility=public, kind=retrieve All navigation functions are retained with visibility=public, kind=navigate All procedures (side effecting functions) have visibility=public, kind=library. In addition: Function declarations use the following declaration for external functions: procedure declare procedure for external functions Function declarations use the following declaration if the function is not external and has a body: function (declare function)
Note: | After the upgrade, mark the kind for side-effecting functions as CUD if they are from the libraryProcedure.
All functions are marked as primary = false with the new validation rules. A key schema file is created and added, if key element is present in the data service pragma. This key schema is TargetTypeSchemaName_KEY. It shares the same namespace as the target type schema such as XML or other return type schemas.
.xfl | These files are changed to library data service files and have no return type pragma. The namespace prefix are changed from lib to ld and all its references are also modified. The name of the xfl is retained if there are no DS files with the name in the same folder. If another data service with the same name exists, then it is resolved with numbered suffixes. All functions are set to visibility=protected during upgrade and in case of private functions, are retained as private. All functions are set to kind=library and function declaration is function(declare function)
.java files | These files are moved to separate Java projects.
WSDL files | WSDL files are upgraded as is. However, in some cases, you may need to upgrade the WSDL manually.
XML, CSV | No change occurs to these files after upgrade.
Model Diagram | Model diagrams are upgraded as is.

Note: | If you have configured the max thread per application property in ALDSP 2.5 using the ALDSP Administration Console, then this configuration is not upgraded to Oracle Data Service Integrator 10gR3.

### Post-Upgrade Tasks for Java Web Service

After completing the upgrade of Java Web Service (JWS), you need to perform the following steps to retrieve values from a dynamic JWS client:

1. Save the WSDL file for the JWS locally and remove the parameterOrder attribute from operations tag.
2. Modify the client code to use the saved WSDL to create the service. Examples of the ALDSP 2.5 configuration and the modified version are shown in Listing 6-1 and Listing 6-2.
Listing 6-1 ALDSP 2.5 Client

    QName serviceName = new QName(targetNamespace, 'testSimplePhyCtrlTest');

    URL wsdlLocation = new

    URL('http://localhost:7001/testWSProj/controls/testSimplePhyCtrlTest.jws?WSDL');

    Service service = factory.createService(wsdlLocation, serviceName);

Listing 6-2 Modified ALDSP 2.5 Client

    QName serviceName = new QName(targetNamespace, 'testSimplePhyCtrlTest');

    URL wsdlLocation = new

    URL('file:///D:/dynwsclient/testSimplePhyCtrlTest.wsdl');

    Service service = factory.createService(wsdlLocation, serviceName);

Note: | While modifying the client, ensure that the port name matches the port name of the migrated JWS.

3. Recompile and run the client with the ALDSP 2.5 classpath. This allows you to run the JWS successfully.

## ALDSP 2.5 Upgrade: Known Issues and Workarounds

Table 6-3 are some of the known issues after you upgrade various components from ALDSP 2.5 environment to Oracle Data Service Integrator 10gR3:

Table 6-3 Known Issues and Workarounds
Known Issues | Workaround
--- | ---
An XQueryTypeException occurs when a read function, which is shredded from a custom Java function, is invoked. | The schema (.xsd) file needs to be recompiled using XMLBeans v2, using the following command: java -classpath ${WL_HOME}/common/lib/javax.xml.stream_1.0.0.0.jar;${WL_HOME}/server/lib/xbean.jar com.bea.xbean.tool.SchemaCompiler *.xsd -d testbin -src testsrc -out <jarfilename>.jar where <WL_HOME> is root directory, which contains the Oracle WebLogic Server 10gR3 installation and <jarfilename> is the name of the schema JAR file.
ALDSP 2.5 update properties are not displayed in the Properties view in WorkSpace Studio. For example, DS pragma elements are not displayed. | No workaround available.
The max thread per application property in ALDSP 2.5 is not imported into the Oracle Data Service Integrator 10gR3 configuration. | You can obtain similar results by configuring the dataspace Work Manager. However, the value is not the same because the pool of thread is shared across async/timeout spawned threads and the top-level EJB threads. In addition, because the Work Manager is self-tuning, it is advised that you do not specify a maximum- or minimum-threads constraint unless you have a specific need to do so. For additional information on the Oracle WebLogic 10gR3 Work Manager see: http://download.oracle.com/docs/cd/E12840_01/wls/docs103/config_wls/self_tuned.html
Schema projects that only exist in JAR format in the Libraries folder are not upgraded to create schemas in the dataspace project. | Obtain the original expanded schema project and include it in the application before starting upgrade.