# Client Application Developer’s Guide

# Accessing Data Services Through a Workshop for WebLogic Control

This chapter describes how you can use Data Service controls in applications generated by Workshop for WebLogic. The following topics are included:

- Introduction to Data Service Controls
- Creating Data Service Controls
- Modifying Existing Data Service control
- Caching Considerations When Using Data Service Controls
- Data Service control Security Considerations

## Introduction to Data Service Controls

An Data Service control enables Workshop for WebLogic Platform applications to easily access data services. When you use an Data Service 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 Chapter 2, “Data Programming Model and Update Framework.”

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

- Function result filtering
- Ad hoc query capability
- APIs for result ordering, sorting, and truncating

For more information on these features, see Chapter 8, “Advanced Topics.”

### Data Service Controls Defined

An Data Service control provides access to Oracle Data Service Integrator 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 Data Service control from data services deployed on any accessible Oracle WebLogic Server, both local or remote. The Data Service 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 Data Service 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 Data Service 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 Data Service 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

When you create an Data Service 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 6-1 Design View of a Web Service with Data Service control Methods

#### Source View

The Source View tab shows the source code of the Data Service 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 Data Service 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 Data Service control for Ad Hoc Queries.

Listing 6-1 shows portions of a generated Data Service control file. It shows the package declaration, import statements, and data service URI used with the queries.

Listing 6-1 Oracle Data Service Integrator 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;
    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. **/

Note: | 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 a Data Service control in Workshop for WebLogic. The general steps to create an Data Service control are:

- Step 1: Create a Project
- Step 2: Start Oracle WebLogic Server
- Step 3: Create a Package under src Folder
- Step 4: Create the Data Service Control

The following sections describe each of these steps in detail.

#### Step 1: Create a Project

Before you can create an Data Service control in Workshop for WebLogic, 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 Oracle WebLogic Server

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

#### 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 Data Service control:

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

Note: | A Data Service control can be created only in a project that is enabled with Beehive facets because the Beehive runtime is required for the Data Service 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.

4. Enter the name of the control in the File Name box and click Next.
5. In the Select Control Attributes dialog box, you need to specify the location of the Oracle Data Service Integrator dataspace project that the control needs to consume, as shown in Figure 6-3.

Note: | A control can only invoke data service functions from a single dataspace project.

Figure 6-3 Select Control Attributes Dialog Box

Note: | You can choose to generate an ODSI 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 Oracle Data Service Integrator, otherwise it is disabled. This option will be enabled in a future release of Oracle Data Service Integrator.

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 6-4.
Figure 6-4 Method Selection Page

2. Select the methods that you want to include in Data Service control and click Add > Finish. This completes the steps to create a new Data Service control.

Note: | An Data Service 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 Data Service control file to the Design View of the web service as shown in Figure 6-5.
Figure 6-5 Data Service control File Added to WebLogic Web Service

After creating the control, the following files are created:

- `DSP_Control.jar`: This JAR contains the required runtime components and is available under the WebApp Libraries folder.
- Schemas: Required schemas are downloaded to a temporary location, then built to SDO classes, made into JAR and moved into the library location. These JAR files have the following naming convention:

     aldspschemas_controlctrl_xsd_full_package_name.jar

Note: | Oracle Data Service Integrator generates interface files for the target schemas associated with the queries and the ODSI Control file.

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

Figure 6-6 Location of DSP_Control.jar

## Using Data Service 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 Oracle WebLogic Server. Ad hoc queries are especially useful when it is not convenient or feasible to add functions to an existing data service.

An Data Service 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 Data Service control file using the Data Service control wizard, if you do not already have it.
2. Add the following lines of code in the Data Service control file:

    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 Data Service control. In Data Service 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 Data Service 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 Data Service control will look like the following:

     @DSPControlAdhocQueryAnnotation(body="")

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

The code to call this Data Service 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);

    }

## Modifying Existing Data Service control

This section describes how you can modify an existing Data Service 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
- Updating an Existing Control When Schemas Change

### Adding and Removing Operations Used by a Control

To change a data service function in an Data Service control:

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

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

6. Click Finish to complete the process.
7. 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 Data Service 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” on page 3-41.

## 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 Oracle Data Service Integrator to retrieve results directly from the data source, rather than from its cache. The steps required to accomplish this include:

- Adding an additional function to the set already defined in your Data Service control file. This function will take a QueryAttribute object as a parameter.
- Instantiate a QueryAttribute object in your project and call the enableFeature( ) method, passing the GET_CURRENT_DATA attribute.
- Call the function you defined in your Data Service control, passing the QueryAttribute object.

#### Cache Bypass Example When Using a Data Service Control

Listing 6-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 6-2 Cache Bypass Example When Using Oracle Data Service Integrator 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 Data Service control file. For the code shown in Listing 6-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) ;

### Data Service control Security Considerations

This section describes security considerations for applications using an Data Service control. The following sections are included:

- Security Credentials Used to Create Data Service Controls
- Testing Controls in the JWS File
- Trusted Domains
- Using Data Service control in Different Domains

### Security Credentials Used to Create Data Service Controls

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

When you create an Data Service control, the Data Service 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 Data Service 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 6-9.
Figure 6-9 WebLogic Test Client for Data Service 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 Data Service 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 Oracle WebLogic Server that hosts the Oracle Data Service Integrator 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:

- Configuring Security for a WebLogic Domain in the Oracle WebLogic Server documentation.

For information on security, see:

- Securing Oracle Data Service Integrator Resources in the Administration Guide

### Using Data Service control in Different Domains

If you deploy your application on a server, which is the source for Data Service control between different domains, then you must create a `dspControlConfig.properties` file in the domain directory of the cluster where Data Service 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 Oracle Data Service Integrator server is found.

For example, if your Data Service 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 Data Service control that you deploy, there is a corresponding `dspControlConfig.properties` file entry.

.