ALDSP 3.0 applications are created in the Data Services Studio environment and deployed on WebLogic Server 9.2.
ALDSP 2.5 applications are created in the WebLogic Workshop 8.x environment and deployed on WebLogic Server 8.1.
ALDSP 3.2 applications are created within the WorkSpace Studio framework and are deployed on WebLogic Server 10.0 MP1.
While upgrading an ALDSP 2.5 application to ALDSP 3.2, the 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 WebLogic 10.0 MP1.
This chapter provides the steps to upgrade ALDSP 2.5 applications to ALDSP 3.2 dataspaces. It includes the following sections:
The upgrade path from ALDSP 3.0 to 3.2 is very simple:
Development environment. To upgrade to the ALDSP 3.2 development environment, uninstall ALDSP 3.0 and install ALDSP 3.2, as described in Preparing to Install ALDSP. You can then use an existing ALDSP workspace, or create a new one and import the contents of a 3.0-level workspace.
Deployment environment. From the ALDSP 3.2 Workspace Studio, you can build and deploy project created under ALDSP 3.0. Alternatively, you can deploy a JAR file created under ALDSP 3.0 to an ALDSP-enabled WebLogic 10.0 MP1 server.
Upgrading from ALDSP 2.5 Prerequisites
Before you start upgrading an ALDSP 2.5 data service application to ALDSP 3.2, make sure that you perform Build > Clean Application in Workshop 8.1 environment. This ensures that application upgrade is successful and does not require manual clean up of files later.
Upgrading ALDSP 2.5 Artifacts to ALDSP 3.2
ALDSP source upgrade allows you to upgrade ALDSP 2.5 data service projects and bring them into ALDSP 3.2 WorkSpace Studio 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 ALDSP 3.2:
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.
To upgrade using WorkSpace Studio, do the following:
Launch WorkSpace Studio.
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
Expand the Other option, select Workshop 8.1 Application, and click Next. The Workshop 8.1 Application Upgrade: Application Import dialog is displayed.
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 ALDSP 3.2. 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.
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.
Ensure that runtime environment is set to BEA WebLogic Server v10.0 for ALDSP 3.2.
Click Next. The Workshop 8.1 Application Upgrade: Source Upgrade dialog is displayed as shown in Figure 6-3.
Select the Message verbosity option from the list. The options include:
Include informational comments
Include warning comments
Include error comments
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.
Click Next. This displays the 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.
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.
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
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 Control from ALDSP 2.5 to 3.2
You need to upgrade an ALDSP 2.5 control created in Workshop for WebLogic 8.1 to use it in WorkSpace Studio 1.1. This section describes the steps to upgrade projects using an ALDSP 2.5 LD control (.jcx).
After the upgrade, all the old annotations are also upgraded to the new annotations. The upgraded ALDSP control is then available in WorkSpace Studio 1.1.
Before you begin the upgrade process, you need to install the control plug-in and the control upgrade plug-in:
Right-click in the Project Explorer, and choose Import > Import. This displays the Import dialog box, as shown in Figure 6-6.
Figure 6-6 Import Dialog
Expand the Other option, select Workshop 8.1 Application, and click Next. The Workshop 8.1 Application Upgrade: Application Import dialog is displayed.
The control, ElecDB.jcx, is listed and the actions to be performed by the upgrade utility on the associated files are mentioned.
Click Finish. This completes the upgrade process. The new control in WorkSpace Studio is displayed in the Project Explorer. After the upgrade, the control is converted to a .java file.
Note:
If the return type of the control is complex, then make sure that the upgraded control has the associated schema JAR or XMLBeans JAR in the WebContent\WEB-INF\lib folder. For details on XMLBeans JAR file for the control, refer to Key Differences for WebLogic Workshop 8.1 Users topic in the WebLogic Workshop documentation.
Importing ALDSP 2.5 Configuration to ALDSP 3.2
After you upgrade an ALDSP 2.5 application to 3.2, you may want to import your existing administration and project configuration to the new ALDSP environment. You can import the ALDSP 2.5 configuration file using the ALDSP Administration Console in ALDSP 3.2. The ALDSP 2.5 configuration file is located at:
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 ALDSP 3.2. For more information about setting default anonymous access in ALDSP 3.2, refer to “Allowing Anonymous Access” section in Securing ALDSP Resources.
ALDSP configuration import requires the ALDSP 2.5 data service projects to be upgraded to a ALDSP 3.2 dataspace project and deployed in a ALDSP 3.2 runtime environment.
To import the ALDSP 2.5 configurations:
Launch ALDSP Administration Console using the following URL and then log in:
http://localhost:7001/dspconsole
Select the upgraded dataspace project.
Select the System Administration category and then click the Import tab.
Click Lock & Edit to acquire the lock.
Click the Import 2.5 Configuration link as shown in Figure 6-10.
Figure 6-10 Import Tab
In the Import 2.5 Configuration section, browse and specify the path where the 2.5 configuration file is located, as shown in Figure 6-11.
Figure 6-11 Importing 2.5 Configuration
Click Save > Activate Changes to complete upgrading the configuration file.
Post-Upgrade Artifact Mapping in ALDSP 3.2
This section highlights the results after upgrading from ALDSP 2.5 to 3.2 and provides information about mapping artifacts between ALDSP 2.5 and ALDSP 3.2.
Note:
After upgrade, you can continue to use ALDSP 2.5 static clients to communicate with the ALDSP-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 ALDSP 3.2.
Table 6-1 provides details about the upgrade and the mappings of artifacts after upgrading to ALDSP 3.2.
Table 6-1 Upgrade Features and Artifact Mapping
ALDSP 2.5 Artifact
ALDSP 3.2 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 ALDSP 3.2, 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 ALDSP 3.2 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 3.2 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 ALDSP 3.2.
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:
Save the WSDL file for the JWS locally and remove the parameterOrder attribute from operations tag.
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');
where <WL_HOME> is root directory, which contains the WebLogic Server 10.0 MP1 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.
An ALDSP 2.5 Control will work if the SDO is exposed over JWS, however upgraded 2.5 applications will not support exposing SDO over JWS.
No workaround available.
The max thread per application property in ALDSP 2.5 is not imported into the ALDSP 3.2 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 WLS 10.0 Work Manager see:
