Client Application Developer’s Guide

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.

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.

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.

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;
import com.bea.sdo.impl.data.DataObjectGeneral;

@ControlExtension
@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. **/

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.

Prerequisites

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

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:

Step 4: Create the Data Service Control

To create an ALDSP Control:

Select the From server option and then:

After creating the control, the following files are created:

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

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:

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:

 @DSPControlAdhocQueryAnnotation(body="")

*     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" +

	"</ns0:ArrayOfADDRESS>\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:

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:

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.

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.

    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:

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

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.

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 dspControlConfig.properties 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 = "ValidSample.com.LocalCtrl", then your property file should contain ValidSample.com.LocalCtrl=t3://<my-qa-prod-dev-url>.

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

.