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:
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:
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.
Upgrading an ALDSP 2.5 Application
To upgrade using the Eclipse IDE:
Open the Eclipse IDE.
Right-click in the Project Explorer.
Select Import. This displays the Import dialog box as shown in Figure 6-1.
Figure 6-1 Import Dialog Box
Expand the Other option and select Workshop 8.1 Application.
Click Next. The Workshop 8.1 Application Upgrade: Application Import dialog box is displayed.
Browse and select the 2.5 application to be upgraded as shown in Figure 6-2.
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.
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.
Ensure that runtime environment is set to BEA WebLogic Server v9.2.
Click Next. The Workshop 8.1 Application Upgrade: Source Upgrade dialog box 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 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.
Click Next. This displays the 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.
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 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
Click Finish. The imported dataspace shows up in the Project Explorer as shown in Figure 6-6.
Figure 6-6 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:
Copy the com.bea.dsp.ide.control.feature.link file from the following location:
Select the Use WebLogic J2EE Shared Libraries option to avoid duplicating runtime JAR files among projects.
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.
Select the Upgrade XQ2002 to XQ2004 option from the JPD Document Upgrader options section to upgrade XQuery from XQ2002 to XQ2004.
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.
Click Next. This starts the process of importing configuration for the project folders and report generation of the files being upgraded.
After the report is generated, the Upgrade Preview dialog box is displayed as shown in Figure 6-10.
Figure 6-10 Upgrade Preview
The control customer.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 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.
Figure 6-11 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:
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-12.
Figure 6-12 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-13.
Figure 6-13 Importing 2.5 Configuration
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
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 step c in 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 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
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
_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
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.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.
.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.
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 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:
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 Platform 9.2 installation and is usually located at:
<bea_home>\weblogic92
<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:
