Installation Guide

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Upgrading from ALDSP 2.5 to ALDSP 3.0

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 within the Eclipse framework and are deployed on WebLogic Server 9.2. While upgrading an ALDSP 2.5 application to 3.0, 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 Server 9.2.

This chapter provides the steps to upgrade ALDSP 2.5 applications to ALDSP 3.0 dataspaces. It includes the following sections:


Upgrading from ALDSP 3.0 to 3.01

The upgrade path from ALDSP 3.0 to 3.01 is very simple: uninstall ALDSP 3.0 and install ALDSP 3.01, as described in Preparing to Install ALDSP. You can thes use an existing ALDSP workspace, or create a new one and import the contents of a 3.0-level workspace.


Upgrading from ALDSP 2.5 Prerequisites

Before you start upgrading an ALDSP 2.5 data service application to 3.0, 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.0

ALDSP source upgrade allows you to upgrade ALDSP 2.5 data service projects and brings them under 3.0 eclipse workspace 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.0:

Note: For steps to upgrade an ALDSP Control to 3.0, refer to Upgrading an ALDSP Control from ALDSP 2.5 to 3.0.

Upgrading an ALDSP 2.5 Application

To upgrade using the Eclipse IDE:

  1. Open the Eclipse IDE.
  2. Right-click in the Project Explorer.
  3. Select Import. This displays the Import dialog box as shown in Figure 6-1.
  4. Figure 6-1 Import Dialog Box

    Import Dialog Box

  5. Expand the Other option and select Workshop 8.1 Application.
  6. Click Next. The Workshop 8.1 Application Upgrade: Application Import dialog box is displayed.
  7. Browse and select the 2.5 application to be upgraded as shown in Figure 6-2.
  8. Note: All projects within a 2.5 application along with dependent schemas and Java projects are upgraded to the same dataspace in 3.0. Select all the Data Service projects 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 Dialog Box

    Workshop 8.1 Application Upgrade Dialog Box

  9. 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 include the prefix including java and schema projects created from data service projects. 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 BEA WebLogic Server v9.2.
  2. Click Next. The Workshop 8.1 Application Upgrade: Source Upgrade dialog box is displayed as shown in Figure 6-3.
  3. Figure 6-3 Workshop 8.1 Application Upgrade: Source Upgrade Dialog Box

    Workshop 8.1 Application Upgrade: Source Upgrade Dialog Box

  4. In the Source Upgrade dialog box:
    1. Select the Error Handling option, which include:
    • 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 and can be changed. You can create a schema project by selecting create a schema project from the schemas of Dataspace. This option creates a schema project with all the schemas within the dataspace project with the name <Application_Name>_Schema. When the schema or the Xmlbeans created from these schema is used outside the project then use this option to create a separate schema project.
  5. Click Next. This displays the Workshop 8.1 Application Upgrade: DSP Dependency Selection dialog box.
  6. Figure 6-4 Workshop 8.1 Application Upgrade: DSP Dependency Selection Dialog Box

    Workshop 8.1 Application Upgrade: DSP Dependency Selection Dialog Box

    This dialog box lists the data service project selected for upgrade along with project JARs including 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 the user will not be able to edit the selection here.

    It also lists the dataspace dependencies such 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 getting upgraded. However, internal jar files, ldclient.jar and ld-server-app.jar are not listed.

  7. 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.
  8. Figure 6-5 Upgrade Preview

    Upgrade Preview

    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
  9. Click Finish. The imported dataspace shows up in the Project Explorer as shown in Figure 6-6.
  10. Figure 6-6 Imported Dataspace in the Eclipse IDE

    Imported Dataspace in the Eclipse IDE

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.0

An ALDSP 2.5 control in Workshop for WebLogic 8.x needs to be upgraded to Workshop for WebLogic 9.2. This section describes the steps to upgrade projects with 2.5 LD control (.jcx).

After the upgrade, all the old annotations are also upgraded to the new annotations. The upgraded ALDSP control is available in Workshop for WebLogic 9.2.

Before you begin the upgrade process, the control plug-in and the control upgrade plug-in needs to be installed:

  1. Copy the file from the following location:
  2. <bea_home>\weblogic92\aldsp_3.0\eclipse-plugins\workshop9

    where <bea_home> is the home directory for BEA product installations. For example, c:\bea.

  3. Paste this file to the following location:
  4. <bea_home>\workshop92\eclipse\links

To upgrade the control:

  1. Launch Workshop for WebLogic 9.2.
  2. Right-click the Package Explorer and select Import.
  3. From the Import dialog box, select Workshop 8.1 Application option as shown in Figure 6-7.
  4. Figure 6-7 Import Dialog Box: Selecting Workshop 8.1 Application Option

    Import Dialog Box: Selecting Workshop 8.1 Application Option

  5. Click Next. The Workshop 8.1 Application Upgrade: Application Import dialog box is displayed as shown in Figure 6-8.
  6. Figure 6-8 Workshop 8.1 Application Upgrade: Application Import Dialog Box

    Workshop 8.1 Application Upgrade: Application Import Dialog Box

  7. In the Application Import box:
    1. Browse and enter the application that needs to upgraded.
    2. If you want to enter a prefix for projects, select the Add this prefix to project names option and enter the prefix.
    3. Click Next. The Workshop 8.1 Application Upgrade: Source Upgrade dialog box is displayed as shown in Figure 6-9.
    4. Figure 6-9 Workshop 8.1 Application Upgrade: Source Upgrade Dialog Box

      Workshop 8.1 Application Upgrade: Source Upgrade Dialog Box

  8. In the Source Upgrade dialog box:
    1. Select the Error Handling option. The options are same as mentioned in step a of Upgrading an ALDSP 2.5 Application.
    2. Select the Message verbosity option. The options are same as mentioned in step b of Upgrading an ALDSP 2.5 Application.
    3. Select the Use WebLogic J2EE Shared Libraries option to avoid duplicating runtime JAR files among projects.
    4. Select the option: Delete copied resource bundle files from the web content folder, to delete the .properties files that are not required by the JSP pages.
    5. Select the Upgrade XQ2002 to XQ2004 option from the JPD Document Upgrader options section to upgrade XQuery from XQ2002 to XQ2004.
    6. Select the Replace BEA NetUI tag with Apache Beehive tags option to upgrade the NetUI compatibility tags, which are compatible with 9.2 server runtime, with the Apache Beehive project tags.
    7. Click Next. This starts the process of importing configuration for the project folders and report generation of the files being upgraded.
    8. After the report is generated, the Upgrade Preview dialog box is displayed as shown in Figure 6-10.

      Figure 6-10 Upgrade Preview

      Upgrade Preview

      The control customer.jcx is listed and the actions to be performed by the upgrade utility on the associated files are mentioned.

  9. Click Finish. This completes the upgrade process. The new control in Workshop for WebLogic 9.2 is displayed in the Project Explorer, as shown in Figure 6-11. After the upgrade, the control is converted to a .java file.
  10. Figure 6-11 Upgraded ALDSP Control and Associated Schema in Project Explorer

    Upgraded ALDSP Control and Associated Schema in Project Explorer

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 9.2 documentation.


Importing ALDSP 2.5 Configuration to 3.0

After you upgrade an ALDSP 2.5 application to 3.0, you may need to import the old administration configuration to the new ALDSP environment. If you want to use the ALDSP 2.5 project configurations, then you can import the 2.5 configuration file using the ALDSP Administration Console in ALDSP 3.0. 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 3.0. For more information about setting default anonymous access in ALDSP 3.0, refer to “Allowing Anonymous Access” section in Securing ALDSP Resources.

ALDSP configuration import requires the 2.5 data service projects to be upgraded to a 3.0 dataspace project and this needs to be deployed in the ALDSP 3.0 runtime environment.

To import the 2.5 configurations:

  1. Launch ALDSP Administration Console using the following URL and then log in:
  2. http://localhost:7001/dspconsole

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

    Import Tab

  8. 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-13.
  9. Figure 6-13 Importing 2.5 Configuration

    Importing 2.5 Configuration

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


Post-Upgrade Artifact Mapping in ALDSP 3.0

This section highlights the end results after upgrading from ALDSP 2.5 to 3.0 and provides information about mapping artifacts between 2.5 to 3.0.

Note: After upgrade, you can continue to use the 2.5 static clients to communicate with the 3.0 server. If you want to change the upgraded dataspace to use the 2.5 clients, then you need to apply the changes to the original 2.5 application, generate the 2.5 static clients and use the clients in ALDSP 3.0.

Table 6-1 provides details about the upgrade and the mappings of artifacts after upgrading to ALDSP 3.0.

Table 6-1 Upgrade Features and Artifact Mapping
2.5 Artifact
3.0 Mapping
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 step c in Upgrading an ALDSP 2.5 Application.
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 11 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
  • 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
_java Suffix
  • In 3.0, dataspace projects cannot store Java files. Therefore, during upgrade of 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.
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 mentioned in Table 6-2.

Table 6-2 Mapping and Features of Other Artifacts Post-Upgrade
Other Files
  • 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.0 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 declaration 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.
  • 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.
  • 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.
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 ALDSP2.5 using the ALDSP Administration Console, then this configuration is not upgraded to 3.0.

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.
  3. Listing 6-1 ALDSP 2.5 Client
    QName serviceName = new QName(targetNamespace, 'testSimplePhyCtrlTest');
    URL wsdlLocation = new 
    Service service = factory.createService(wsdlLocation, serviceName);
    Listing 6-2 Modified ALDSP 2.5 Client
    QName serviceName = new QName(targetNamespace, 'testSimplePhyCtrlTest');
    URL wsdlLocation = new 
    Service service = factory.createService(wsdlLocation, serviceName);
    Note: While modifying the client, ensure that the port name matches the port name of the migrated JWS.
  4. 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 3.0:

Table 6-3 Known Issues and Workarounds
Known Issues
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
com.bea.xbean.tool.SchemaCompiler *.xsd -d testbin -src testsrc -out <jarfilename>.jar
where <WL_HOME> is root directory, which contains the WebLogic Platform 9.2 installation and is usually located at:
<jarfilename> is the name of the schema JAR file.
ALDSP 2.5 update properties are not displayed in the Properties view in Data Service Studio. For example, DS pragma elements are not displayed.
No workaround available.
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 3.0 configuration.
You can obtain similar results by configuring the dataspace WorkManager. 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 WorkManager 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 9.2 WrokManager see:
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.

  Back to Top       Previous  Next