Installation Guide

Migrating Legacy DSP Applications

The basic migration path for BEA AquaLogic Data Services Platform 2.0.n application and projects is straightforward. This section provides instructions for such upgrades including:

Platform Installation and Configuration

Prior to installing Data Services Platform, WebLogic Platform 8.1 SP4 or SP5 must be installed and configured properly.

Data Services Platform 2.1 Installation and Deployment

In order to migrate an application DSP 2.0x you must first install DSP 2.1. In a production environment, that installation must be completed for each WebLogic Platform 8.1 domain that you are using with DSP.

Data Services Platform 2.1 Installation

Follow the appropriate preparation, installation, and post-installation steps described in other sections of this document starting with Installation Prerequisites.

Data Services Platform Upgrade Options

There are a several of steps to take when upgrading to the latest version of Data Services Platform.

Upgrading Earlier (2.0) Applications to DSP 2.1

Applications can be migrated through WebLogic Workshop or using the DSP 2.1 Convert utility.

Using Workshop to Upgrade 2.0 DSP Applications

After you have installed DSP 2.1 you need to upgrade several JAR files in your existing DSP applications in order to deploy those applications under DSP 2.1. In WebLogic Workshop the update process is semi-automatic. When you open your application in WebLogic Workshop you will get a message indicated that some DSP JAR files are out-of-date and asking if you want to update your application.

Choose Yes to update the files. This will automatically cause your application to be built or rebuilt.

Note: If you choose No, your 2.0 application will not be updated and you will not be able to deploy it under DSP 2.1.

Using the Convert Utility to Upgrade Legacy DSP Applications

If your Data Services Platform 2.0 application is already packaged in an EAR file you can use a command-line utility to upgrade the EAR to DSP 2.1. The utility inspects the EAR file for out-of-date copies of the following:

ld-server.app.jar

LiquidDataControl.jar

If pre-DSP 2.1 versions of these files are found, they are replaced with 2.1 versions.

Upgrading EAR Files on Windows

To upgrade a Windows-based DSP 2.0 EAR file to DSP 2.1 using the Convert migration utility following these steps:

Back up your EAR file.

Open a command window using Window's Run command.

Set the WebLogic Server environment, if it is not already set on your system:

<WL_HOME>\server\bin\setWLSEnv.cmd

Run the Convert command-line utility on your EAR file. For example:

<WL_HOME>\liquiddata\bin\convert.cmd myEAR.ear

Upgrading EAR Files on UNIX Systems

To upgrade a UNIX-based DSP 2.0 EAR file to DSP 2.1 using the Convert migration utility following these steps:

Back up your EAR file.

Set the WebLogic Server environment, if it is not already set on your system:

<WL_HOME>/server/bin/setWLSEnv.sh

Run the Convert command-line utility on your EAR file. For example:

<WL_HOME>/liquiddata/bin/convert.sh myEAR.ear

Migrating Earlier (2.0) Projects to DSP 2.1

Earlier versions of Data Services Platform managed functions returning sequences by generating additional "arrayOf" types (.xsd schema files) in schema projects. For example, when a data service was created around an XMLtype of customer (customer.xsd) an XML type arrayOfcustomer (arrayOfCustomer.xsd) was created automatically. Applications calling functions returning sequences could then utilize the arrayOf type.

This approach to handling functions returning sequences has been deprecated. Instead, functions returning sequences of records are handled by converting each item in the sequence into a standard data object (SDO). With DSP 2.1 Java arrarys of SDO are supported. (For details on SDO and handling of sequence SDOs see the Application Developer's Guide.)

If your Data Services Platform project was created using an earlier version of DSP you have a choice:

By default your legacy project will utilize the original arrayOf technique for returning sequences through functions.
Or you can migrate your project to the improved means of handling sequences on a project-by-project basis. This is done through the Migrate Data Services Project menu option.

You can access the Migrate Data Services Project option by right-clicking on your legacy project (see Figure 5-1).

After migrating projects existing Java mediator client code that relied upon the ArrayOf types will need to be updated.

Figure 5-1 Upgrade Data Services Project Option

Upgrade Data Services Project Option

Note: Migration of projects to DSP 2.1 are not reversible.