Client Application Developer’s Guide

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

Accessing Data Services Through a WebLogic Workshop Control

This chapter describes how you can use ALDSP Controls in applications generated by BEA Workshop for WebLogic Platform. The following topics are included:


Introduction to Data Service Controls

An ALDSP Control enables Workshop for WebLogic Platform applications to easily access data services. When you use an ALDSP Control to invoke data service functions, you get information back as a data object. A data object is a unit of information as defined by the Service Data Objects (SDO) specification. For more information on SDO, see Data Programming Model and Update Framework.

In addition to the functionality discussed in this chapter, ALDSP Controls provide many of the same features available through the SDO Mediator API, including:

For more information on these features, see Advanced Topics.

Data Service Controls Defined

An ALDSP Control provides access to ALDSP dataspaces within Workshop for WebLogic Platform. It is a wizard-generated Java file that can be used to access data service operations. These operations can be added to an ALDSP Control from data services deployed on any accessible WebLogic Server, both local or remote. The ALDSP Control wizard retrieves all available data service operations on the server. It then lets you choose the ones to include in your control.

Note: All client APIs, including ALDSP Control, support calling data service functions without parameters. Data service functions with optional parameters can be called within other data service functions or from an ad hoc query, but such functions cannot be invoked using a Data Service control itself.

Like Java controls, you can use an ALDSP Control in Workshop for WebLogic Platform applications such as Web services, page flows, and WebLogic integration business processes. After applying the control to a client application, you can use the data returned from query functions in the control in your application.

This chapter describes how to use an ALDSP Control in a web service project application. The steps for using it in other Workshop for WebLogic Platform projects are similar.

Description of the Data Service Control File

In the 3.0 release, ALDSP Control is available with both Workshop for WebLogic Platform 9.2 and Workshop Studio 10.1. However, ALDSP Control cannot be used in the Eclipse WTP environment packaged with ALDSP 3.0.

When you create an ALDSP Control, Workshop for WebLogic Platform generates a Java Control file (.java) that contains methods based on the data services functions, and a commented method that can be uncommented and used to pass any XQuery statements (called ad hoc queries) to the server.

Design View

The Design View tab of the Java web services displays a graphical view of the data service methods that were selected for inclusion in the control.

Figure 7-1 Design View of a Web Service with ALDSP Control Methods

Design View of a Web Service with ALDSP Control Methods

Source View

The Source View tab shows the source code of the ALDSP Control. It includes annotations defining the data service function names associated with each method. For update functions, the data service bound to the update is the data service specified by the locator attribute. For example:

locator = "1{ld:ADDRESS}updateADDRESS", functionKind = "procedure")

The signature for the method shows its return type. The return type for a read method is an SDO object corresponding to the schema type of the data service that contains the referenced function. The SDO classes corresponding to the data services used in an ALDSP Control reside in the Libraries folder of the project. An interface is generated for each data service.

The only time you should need to manually edit the source code is if you want to add a method to run an ad hoc query, as described in Using ALDSP Control for Ad Hoc Queries.

Listing 7-1 shows portions of a generated ALDSP Control file. It shows the package declaration, import statements, and data service URI used with the queries.

Listing 7-1 ALDSP Control File Sample
package xyzpackage;

import org.apache.beehive.controls.api.bean.ControlExtension;
import com.bea.dsp.control.core.DSPControl;
import com.bea.dsp.control.core.annotation.DSPControlInterfaceAnnotation;
import com.bea.dsp.control.core.annotation.ALDSPControlMethodAnnotation;
import com.bea.dsp.RequestConfig;
import commonj.sdo.DataObject;

@DSPControlInterfaceAnnotation(version = "3.0" , application = "DS2", urlKey = "DS2.xyzpackage.xyz_DSPControlFile", url = "t3://localhost:7001", username = "weblogic")
public interface xyz_DSPControlFile extends DSPControl {

@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="ADDRESS", schemaURI = "ld:ADDRESS", schemaRootElement = "ADDRESS", locator = "0{ld:ADDRESS}ADDRESS", functionKind = "function")
public address.ADDRESS[] ADDRESS() ;

@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="createADDRESS", schemaURI = "ld:ADDRESS", schemaRootElement = "ADDRESS_KEY", locator = "1{ld:ADDRESS}createADDRESS", functionKind = "procedure")
public address.ADDRESS_KEY[] createADDRESS(address.ADDRESS[] p) ;

@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="updateADDRESS", schemaURI = "", schemaRootElement = "", locator = "1{ld:ADDRESS}updateADDRESS", functionKind = "procedure")
public void updateADDRESS(address.ADDRESS[] p) ;

@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="deleteADDRESS", schemaURI = "", schemaRootElement = "", locator = "1{ld:ADDRESS}deleteADDRESS", functionKind = "procedure")
public void deleteADDRESS(address.ADDRESS[] p) ;

@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="getCREDIT_CARD", schemaURI = "ld:CREDIT_CARD", schemaRootElement = "CREDIT_CARD", locator = "1{ld:ADDRESS}getCREDIT_CARD", functionKind = "function")
public credit_card.CREDIT_CARD[] getCREDIT_CARD(address.ADDRESS pk) ;

@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="getCUSTOMER", schemaURI = "ld:CUSTOMER", schemaRootElement = "CUSTOMER", locator = "1{ld:ADDRESS}getCUSTOMER", functionKind = "function")
public customer.CUSTOMER[] getCUSTOMER(address.ADDRESS fk) ;

* Using RequestConfig:
* In order to use a RequestConfig parameter with functions,
* procedures and submit methods
* please edit a method signature as follows:
* From:
* Customer getCustomer(java.lang.String p0);
* To:
* Customer getCustomer(java.lang.String p0, RequestConfig
* config);
* The RequestConfig parameter allows you to send FilterXQuery and
* QueryAttributes
* to the server and receive Audit Event. **/
Note: In the ALDSP 3.0 release, the read operations do not contain the control level flag for txRequired and txSupported. This flag is available in RequestConfig and is applied on a per-call basis.


Creating Data Service Controls

You can create an ALDSP Control in Workshop Studio 10.1 or in Workshop for WebLogic Platform 9.2 environment. The steps to create the control in either of these environments are almost the same. However, some of the options that you select while creating the control may differ based on your environment.

This section describes the steps involved in creating an ALDSP Control using the Workshop for WebLogic Platform 9.2 and using it in a Web Service project. In addition, it provides information about the options that you need to configure differently if you create the control in Workshop Studio 10.1.

The general steps to create an ALDSP Control are:

The following sections describe each of these steps in detail.


Ensure that your Workshop for WebLogic Platform 9.2 is using JDK 1.5.0_07 or higher.

Note: For ALDSP 3.0 and, in some cases, ALDSP 3.2, it is necessary to copy an ALDSP Control configuration file to the Workshop installation. Details can be see in the Client Configuration Section (" Configuration Instructions for WebLogic Workshop in Conjunction with ALDSP Control") of Release Notes.
Note: If you want to use ALDSP Control with WLI, also see the Client Configuration section of ALDSP 3.0/3.2 Release Notes.

Step 1: Create a Project

Before you can create an ALDSP Control in Workshop for WebLogic Platform, you must create a web-enabled project such as portal or Web Service Project. A Web Service Project allows you to create Java web service projects while you can use a dynamic web project to create portal components like Java page flows and JSPs.

Step 2: Start WebLogic Server

Make sure that the WebLogic Server that hosts the ALDSP dataspace project is running. WebLogic Server can be running locally (on the same domain as Workshop for WebLogic Platform) or remotely (on a different domain from Workshop for WebLogic Platform).

Step 3: Create a Package under src Folder

In the web-enabled project or Web Service Project, an src folder is created. Create a package under this folder as follows:

  1. Right-click the src folder and select New > Package.
  2. Enter the package name in the New Java Package dialog box.
  3. Click Finish.

Step 4: Create the Data Service Control

To create an ALDSP Control:

  1. Right-click the package you created previously, and select New > Other > Controls > ALDSP Control.
  2. Click Next. This starts the ALDSP Control creation wizard.
  3. In the New DSP Control dialog box, select the project and package under which you need to create the control, as shown in Figure 7-2.
  4. Figure 7-2 New DSP Control Dialog Box

    New DSP Control Dialog Box

    Note: An ALDSP Control can be created only in a project that is enabled with Beehive facets because the Beehive runtime is required for the ALDSP Control runtime. If you select a container that is not Beehive-enabled, you will not be able to proceed.

    To check for the Beehive Control facets:

    1. Right-click your web service project and select Properties.
    2. From the Properties dialog box, select Project Facets. This displays the version number of the Beehive Control.
  5. Enter the name of the control in the File Name box and click Next.
  6. In the Select Control Attributes dialog box, you need to specify the location of the ALDSP dataspace project that the control needs to consume, as shown in Figure 7-3.
Note: A control can only invoke data service functions from a single dataspace project.
Figure 7-3 Select Control Attributes Dialog Box

Select Control Attributes Dialog Box

Note: You can choose to generate an ALDSP Control from dataspace projects in your local workspace instead of a deployed dataspace. However this option is available only if your Workshop platform can support ALDSP, otherwise it is disabled. This option will be enabled in a future release of ALDSP.

Select the From server option and then:

    1. Choose a local or remote server.
    2. Specify the user name and password to authenticate connection to the WebLogic Server where the dataspace is deployed.
    3. Click Get Dataspace projects. This shows a drop-down list of available dataspace projects at the selected location.
  1. Click Next to move to the Method selection Page as shown in Figure 7-4.
  2. Figure 7-4 Method Selection Page

    Method Selection Page

  3. Select the methods that you want to include in ALDSP Control and click Add > Finish. This completes the steps to create a new ALDSP Control.
Note: An ALDSP Control can access only public data service functions.
  1. Create a WebLogic Web Service:
    1. Right-click the package.
    2. Select New > WebLogic Web Service.
  2. Drag-and-drop the ALDSP Control file to the Design View of the web service as shown in Figure 7-5.
  3. Figure 7-5 ALDSP Control File Added to WebLogic Web Service

    ALDSP Control File Added to WebLogic Web Service

After creating the control, the following files are created:

The location of both these JAR files is shown in Figure 7-6.

Figure 7-6 Location of DSP_Control.jar

Location of DSP_Control.jar


Using ALDSP Control for Ad Hoc Queries

Client applications can issue ad hoc queries against data service functions. You can use ad hoc queries when you need to change the way a data service function returns data. Ad hoc queries are most often used to process data returned by data services deployed on a WebLogic Server. Ad hoc queries are especially useful when it is not convenient or feasible to add functions to an existing data service.

An ALDSP Control generated from a wizard contains a commented ad hoc query method template that can serve as a starting point for creating an ad hoc query. To create the ad hoc query:

  1. Generate an ALDSP Control file using the ALDSP Control wizard, if you do not already have it.
  2. Add the following lines of code in the ALDSP Control file:
  3. com.bea.xml.Object executeQuery(String query);

    Replace the function name with a meaningful name for your application. Be default, the ad hoc query returns a typed SDO or an object that matches the return type for the ad hoc query. You can also optionally supply ExternalVariables or QueryAttributes (or both) to an ad hoc query.

Note: ExternalVariable is used for binding variable name to value for use in adhoc query in ALDSP Control. In ALDSP Control, an xquery can be passed in as a string. If this query has declared external variables, then the value for these variables are passed in using ExternalVariable.

When invoking this ad hoc query function from an ALDSP Control, the caller needs to pass the query string (and the optional ExternalVariables binding and QueryAttributes). For example, an ad hoc query signature in a ALDSP Control will look like the following:

*     Object[] executeQuery(String xquery, ExternalVariables params);

The code to call this ALDSP Control (from a web service JWS file, for example) would be:

public void adHocAddressQuery()
	String adhocQuery =
	"declare namespace f1 = \"ld:ldc_produucerDataServices/ADDRESS\";\n" +
	"declare namespace ns0=\"ld:ldc_produucerDataServices/ADDRESS\";\n"+
	"<ns0:ArrayOfADDRESS>\n"+"{for $i in f1:ADDRESS()\n" +
	"where $i/STATE = \"TX\"\n"+" return $i}\n" +
	Object result = myldcontrol.adHocAddressQuery(adhocQuery);

ALDSP Control Backward Compatibility

In the 3.0 release, two types of backward compatibility is provided for ALDSP Control:

Note: If you using ALDSP 2.5 or any earlier version, then you need to upgrade ALDSP Control using the source upgrade feature. For more information on upgrading ALDSP Control, refer to ALDSP Control Source Upgrade on page 9-1.


Modifying Existing ALDSP Control

This section describes how you can modify an existing ALDSP Control. When you edit a control, the SDO classes that are available to the control are recompiled, which means that any changes to data service are incorporated to the controls also.

This section contains the following topics:

Adding and Removing Operations Used by a Control

To change a data service function in an ALDSP Control:

  1. In Workshop for WebLogic Platform, open the ALDSP Control file that you need to edit. This opens up the ALDSP Control .java file in Source View.
  2. Right-click the file in Source View.
  3. Select the Edit ALDSP Control > Edit ALDSP Control option. This displays the Edit DSP Control dialog box as shown in Figure 7-7.
  4. Figure 7-7 Changing a Function in a Data Service Control

    Changing a Function in a Data Service Control

  5. Enter the password of the ALDSP-enabled WebLogic Server where your project is deployed and click Next.
  6. From the Method Selection Page dialog box, select the functions that you want to add or remove from the control, as shown in Figure 7-8.
  7. Figure 7-8 Method Selection Page Dialog Box

    Method Selection Page Dialog Box

  8. Click Finish to complete the process.
  9. Rebuild the project after the control is edited.

Updating an Existing Control When Schemas Change

If any of the schemas corresponding to any operation in an ALDSP Control change, you need to edit the control by removing the operation and restoring it.

When you edit the control, its SDO classes are automatically regenerated.

Note: For details on working with static and dynamic SDO see Mediator API Basics.


Caching Considerations When Using Data Service Controls

The following scenario is very common: most of the time you can use cached data because it changes infrequently; however, on occasion, your application must fetch data directly from the data source. At the same time, you want to update your cache with the most up-to-date information. A typical example would be to refresh the cache at the beginning of every week or month.

You can accomplish this by passing the attribute GET_CURRENT_DATA with your function call.

Bypassing the Cache When Using a Data Service Control

To bypass the data in a cached query function result, your application will need to signal ALDSP to retrieve results directly from the data source, rather than from its cache. The steps required to accomplish this include:

Cache Bypass Example When Using a Data Service Control

Listing 7-2 shows example Java Page Flow (JPF) code that tests whether the user has requested a bypass of any cached data. If refreshCache is set to False then cached data (if any is available) is used. Otherwise the function will be invoked with the GET_CURRENT_DATA attribute and data will be retrieved from the data source. As a by-product, any cache is automatically refreshed.

Listing 7-2 Cache Bypass Example When Using Data Services Platform Control
    if (refreshCache == false) { 
address.ADDRESS[] addresses = control.ADDRESS();
 } else { 
	QueryAttributes attr = new 	QueryAttributes(); 
	attr.enableFeature	(QueryAttributes.GET_CURRENT_DATA); 	
	address.ADDRESS[] addresses = control.ADDRESS(attr);

An additional function is also needed in the ALDSP Control file. For the code shown in Listing 7-2, you need to add the following definition to the control:

@ALDSPControlMethodAnnotation(functionURI = "ld:ADDRESS", functionName ="ADDRESS", schemaURI = "ld:ADDRESS", schemaRootElement = "ADDRESS", locator = "0{ld:ADDRESS}ADDRESS", functionKind = "function") 
public address.ADDRESS[] ADDRESS(QueryAttributes attr) ;

ALDSP Control Security Considerations

This section describes security considerations for applications using an ALDSP Control. The following sections are included:

Security Credentials Used to Create Data Service Controls

When you create an ALDSP Control and connect to a local or remote Data Services Platform server (a WebLogic Server on a different domain from Workshop for WebLogic Platform), you specify the connection information in the ALDSP Control wizard as shown in Figure 7-3.

When you create an ALDSP Control, the ALDSP Control Wizard displays all queries to which the specified user has access privileges. The access privileges are defined by security policies set on the queries, either directly or indirectly.

Testing Controls in the JWS File

To test an ALDSP Control:

  1. Right-click the Web Service in Design View.
  2. Select Run As > Run on Server. The Run on Server dialog box is displayed.
  3. Select the WebLogic Server instance where your dataspace project is deployed and click Next.
  4. Click Finish. This generates a WebLogic Test Client where you can test the control as shown in Figure 7-9.
  5. Figure 7-9 WebLogic Test Client for ALDSP Control

    WebLogic Test Client for ALDSP Control

When a query is run from a dataspace, it must have a mechanism for getting the security credential. The credential can come from a login screen, it can be hard-coded in the dataspace, or it can be imbedded in a J2EE component (for example, using the run-as property in a JWS Web service file).

Note: You can enable the auditing if you want to monitor or debug ALDSP Control in a test environment. For more information about auditing, refer to the Working With Audit and Log Information chapter in the Administration Guide.

Trusted Domains

If the WebLogic Server that hosts the ALDSP project is on a different domain than Workshop for WebLogic Platform, then both domains must be set up as trusted domains.

Domains are considered trusted domains if they share the same security credentials. With trusted domains, a user known to one domain need not be authenticated on another domain, if the user is already known on that domain.

Note: After configuring domains as trusted, you must restart the domains before the trusted configuration takes effect.

For more details on WebLogic Server security, see:

For information on security, see:

Using ALDSP Control in Different Domains

If you deploy your application on a server, which is the source for ALDSP Control between different domains, then you must create a file in the domain directory of the cluster where ALDSP Control is deployed.

This property file should contain a key-value mapping where the key is the string representing the urlKey in the control file and the value is the T3 URL at which ALDSP server is found.

For example, if your ALDSP Control file contains urlKey = "", then your property file should contain<my-qa-prod-dev-url>.

Ensure that for each ALDSP Control that you deploy, there is a corresponding file entry.


  Back to Top       Previous  Next