Skip navigation.
Downloads | Product Documentation | Support

Client Application Developer's Guide

# Accessing Data Services from Workshop Applications

This chapter describes how you can use the Liquid Data control in WebLogic Workshop to develop applications that consume data from data services. The following topics are included:

- WebLogic Workshop and Liquid Data
- Liquid Data Control JCX File
- Creating Liquid Data Controls
- Modifying Existing Liquid Data Controls
- Using Liquid Data with NetUI
- Using Liquid Data in Business Process Projects
- Security Considerations With Liquid Data Controls

# WebLogic Workshop and Liquid Data

The Liquid Data control gives WebLogic Workshop applications an easy way to use data services. When you use a Liquid Data control to invoke data services, 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 Client Programming with Service Data Objects (SDO).

Note that many of the features available through the Mediator API are also available through the Liquid Data control as well. These include:

- Function result filtering
- Ad hoc XQueries
- Result ordering, sorting, and truncating APIs

For more information on these features, see Advanced Topics.

## Liquid Data Control

The Liquid Data control is a wizard-generated Java file that exposes a data service functions to a Workshop client application.You can add functions to a control from data services deployed on any WebLogic server that is accessible to the client application, whether on the same WebLogic server as the client application or on a remote WebLogic server. In either case, the Liquid Data Control wizard retrieves all the data service functions on the server that you specify. It then lets you choose the ones to include in your control.

If accessing data services on a remote server, metadata describing information that the service functions return (in the form of XML schema files) is first downloaded from the remote server into the current application. These schema files are placed in a schema project named after the remote application. The directory structure within the project mirrors the directory structure of the remote server. Liquid Data generates interface files for the target schemas associated with the queries and the Liquid Data control (`.jcx`) file.

## Use With Page Flow, Web Services, Portals, Business Processes

Like any WebLogic Workshop control, you can use a Liquid Data control in 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 queries in the control in your application.

This chapter describes in detail how to use the control in a page flow-based web application. The steps for using it in Portals and other WebLogic Workshop Projects are similar.

# Liquid Data Control JCX File

When you create a Liquid Data control, WebLogic Workshop generates a Java Control Extension (`.jcx`) file. This file contains the methods included the control was created and a commented method that, when uncommented, allows you to pass any XQuery statement to the server (called ad hoc queries).

This section describes the Liquid Data control in detail and includes the following sections:

- Design View
- Source View
- Running Ad Hoc Queries Through a Liquid Data Control

## Design View

The Design View tab of the Liquid Data control shows a graphical view of the data service methods that were selected for inclusion in the control.

Figure 5-1 Design View of a Control File

Using the right-click menu, you can add or modify a control method (for example, by changing the data service function accessed by a method). The right-click menu is context sensitive—it displays different items if the mouse cursor is over a method or elsewhere in the control portion of the design pane.

## Source View

The Source View tab shows the source code of the Java Control Extension (`.jcx`) file. It includes as comments the name of the data service function 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="ld:DataServices/RTLServices/ApplOrderDetailView.ds" )

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 the Liquid Data control reside in the Libraries folder of the project. An interface is generated for each data service. The folder also contains a copy of the schema files associated with the functions in the Liquid Data control (`.jcx`) file.

The Java Control Extension instance is a generated file. The only time you should need to edit the source code is if you want to add a method to run an ad hoc query, as described in Running Ad Hoc Queries Through a Liquid Data Control.

The the following example (Listing 5-1) shows a generated Liquid Data control (`.jcx`) file. It shows the package declaration, import statements, and data service URI used with the queries.

Listing 5-1 Liquid Data Java Control Extension Sample

>     package Controls;

>     import weblogic.jws.control.*;
>     import com.bea.ld.control.LDControl;
>     import com.bea.ld.filter.FilterXQuery;
>     import com.bea.ld.QueryAttributes;

>     /**
>      *   @jc:LiquidData application="RTLApp" urlKey="RTLApp.RTLSelfService.Controls.RTLControl"
>      */
>     public interface RTLControl extends LDControl, com.bea.control.ControlExtension
>     {

>       /* Generated methods corresponding to stored queries. */
>       /**

>          *
>          * @jc:XDS locator="ld:DataServices/RTLServices/ApplOrderDetailView.ds" functionName="submitApplOrderDetailView"
>          */
>         java.util.Properties[] submitApplOrderDetailView(retailer.ORDERDETAILDocument rootDataObject)
>     throws Exception;

>         /**
>          *
>          * @jc:XDS locator="ld:DataServices/RTLServices/ProfileView.ds" functionName="submitArrayOfProfileView"
>          */
>         java.util.Properties[] submitArrayOfProfileView(retailer.ArrayOfPROFILEDocument rootDataObject) throws Exception;

>         /**
>          *
>     locator="ld:DataServices/RTLServices/ElecOrderDetailView.ds" functionName="submitElecOrderDetailView"
>          */
>         java.util.Properties[] submitElecOrderDetailView(retailer.ORDERDETAILDocument rootDataObject) throws Exception;

>         /**
>          *
>          * @jc:XDS functionURI="ld:DataServices/CustomerDB/CUSTOMER" functionName="CUSTOMER" schemaURI="ld:DataServices/CustomerDB/CUSTOMER" schemaRootElement="ArrayOfCUSTOMER"
>          */
>         dataServices.customerDB.customer.ArrayOfCUSTOMERDocument CUSTOMER();

>         /**
>          *
>          * @jc:XDS functionURI="ld:DataServices/CustomerDB/CUSTOMER" functionName="CUSTOMER" schemaURI="ld:DataServices/CustomerDB/CUSTOMER" schemaRootElement="ArrayOfCUSTOMER"
>          */
>         dataServices.customerDB.customer.ArrayOfCUSTOMERDocument CUSTOMERWithFilter(FilterXQuery filter);

>         /**
>          *
>          * @jc:XDS functionURI="ld:DataServices/RTLServices/ApplOrderDetailView" functionName="getApplOrderDetailView"
>          */
>         retailer.ORDERDETAILDocument getApplOrderDetailView(java.lang.String p0);
>          .
>          .
>          .
>         /**
>          *
>          * @jc:XDS functionURI="ld:DataServices/RTLServices/ProfileView" functionName="getProfileView" schemaURI="urn:retailer" schemaRootElement="ArrayOfPROFILE"
>          */
>         retailer.ArrayOfPROFILEDocument getProfileViewWithFilter(java.lang.String p0, FilterXQuery filter);

>         /**
>          *  Default method to execute an ad hoc query.
>          *  This method can be customized to have a differnt method name (e.g.
>          *  runMyQuery), or to return an SDO generated class (e.g. Customer),
>           *  or to return the DataObject class, or to have one or both of the following
>          *  two extra parameters: com.bea.ld.ExternalVariables and
>          *  com.bea.ld.QueryAttributes
>          *  e.g. commonj.sdo.DataObject executeQuery(String xquery,
>          *   ExternalVariables params);
>          *   e.g. commonj.sdo.DataObject executeQuery(String xquery,
>          *   QueryAttributes attrs);
>          *   e.g. commonj.sdo.DataObject executeQuery(String xquery,
>          * ExternalVariables params, QueryAttributes attrs);
>          */
>         com.bea.xml.XmlObject executeQuery(String query);

>      }

## Running Ad Hoc Queries Through a Liquid Data Control

A client application 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.

A Liquid Data control generated from Liquid Data wizard has a commented ad hoc query method that can serve as a starting point for generating an ad hoc query. To generate the ad hoc query, follow these steps:

1. If you do not already have a Liquid Data control (`.jcx`) file, generate one using the Liquid Data Control wizard.
2. Add the following lines of code in the `.jcx` file:

>     com.bea.xml.XmlObject executeQuery(String query);

(You can replace the function name in with your own to impart meaning to the ad hoc query function. The ad hoc query returns an XMLObject by default, but you can return a typed SDO or typed XMLBean class that matches the return type XML for the ad hoc query. You can also optionally supply ExternalVariables or QueryAttributes (or both) to an ad hoc query.)

When invoking this ad hoc query function from a Liquid Data control, the caller needs to pass the query string (and the optional ExternalVariables binding and QueryAttributes if desired). For example, a ad-hoc query signature in a Liquid Data control will look like the following:

>     public interface MyLDControl extends LDControl,
>                                          com.bea.control.ControlExtension
>     {
>         ldcProduucerDataServices.address.ArrayOfADDRESSDocument
>                                                       adHocAddressQuery(String xquery);
>     }

The code to call this Liquid Data control (from a WebService .jws file for example) would be:

>     /** @common:control */
>     public ldcontrol.MyLDControl myldcontrol;

>     /** @common:operation */
>     public ldcProduucerDataServices.address.ArrayOfADDRESSDocument
>                                                           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";
>      return myldcontrol.adHocAddressQuery(adhocQuery);
>     }

# Creating Liquid Data Controls

This section describes the steps for creating a Liquid Data control and using it in a web project. The general steps to Create a Liquid Data control are:

Step 1: Create a Project in an Application

Step 2: Start WebLogic Server, If Not Already Running

Step 3: Create a Folder in a Project

Step 4: Create the Liquid Data Control

Step 5: Enter Connection Information to the WebLogic Server

Step 6: Select Data Service Functions to Add to the Control

The following sections describe each of these steps in detail.

### Step 1: Create a Project in an Application

Before you can create a Liquid Data control in WebLogic Workshop, you must create an application and a project in that application. You can create a Liquid Data control in most types of Workshop projects. The most common projects in which you create Liquid Data controls are:

- Web Projects
- Web Service Projects
- Portal Web Projects
- Process Web Projects

### Step 2: Start WebLogic Server, If Not Already Running

Make sure that the WebLogic Server that host the Liquid Data-enabled application is running. WebLogic Server can be running locally (on the same domain as WebLogic Workshop) or remotely (on a different domain from Workshop).

### Step 3: Create a Folder in a Project

Create a folder in the project to hold the Liquid Data control by selecting a folder and right-clicking (as shown in Figure 5-2). You can also create other controls (database controls, for example) in the same folder as needed. Workshop controls cannot be created at the top level of a project directory structure. Instead, they must be created in a folder. When you create the folder, enter a name that makes sense for your application.

Figure 5-2 Create a New Folder

### Step 4: Create the Liquid Data Control

To create a Liquid Data control, start the Java Control Wizard by right-clicking on the new folder in your project and choosing New —> Java Control as shown in Figure 5-3. (You can also create a control using the File —> New —> Java Control menu item.)

Figure 5-3 Create a New Liquid Data Control

Next, select Liquid Data from the New Java Control dialog as shown in Figure 5-4. Enter a filename for the control (`.jcx`) file and click Next.

Figure 5-4 New Java Control Dialog

### Step 5: Enter Connection Information to the WebLogic Server

The New Java Control - Liquid Data dialog (Figure 5-5) allows you to enter connection information for the WebLogic Server that hosts your Liquid Data application or project. If the server is local, the Liquid Data control uses the connection information stored in the application properties. (To view these settings, access the Tools —> Application Properties menu item in Workshop.)

If the server is remote, choose the Remote option and fill in the appropriate server URL, user name, and password.

Note: You can specify a different username and password with which to connect to a local machine in the Liquid Data Control Wizard as well. To do this, click the Remote button and enter the connection information (with a different username and password) for your local machine. The security credentials specified through the Application Properties or through the Liquid Data Control Wizard are only used for creating the Liquid Data Control (`.jcx`) file, not for testing queries through the control. For more details, see Security Considerations With Liquid Data Controls.

When the information is correct, click Create to go to the next step.

Figure 5-5 Liquid Data Control Wizard: Connection Information

### Step 6: Select Data Service Functions to Add to the Control

In the Select Liquid Data Queries screen, select the data service functions you want to use in your application from the left pane and click Add. When done, click Finish. At that point, the Liquid Data Control (`.jcx`) file is generated, with a call for each selected function.

Figure 5-6 Liquid Data Control Wizard—Select Queries

The `LiquidDataControl.jar` file is copied into the `Libraries` directory of your application when you create the Liquid Data Control.

The control appears with the functions you chose. Also, WithFilter functions are added for each function, such as `getCustomerWithFilter()`. A filter function lets you further filter the results normally returned by a function. For more information, see Applying Filter Data Service Results in Advanced Topics.

After you have added all the queries you need in the wizard, click Finish. Workshop generates the `.jcx` Java Control Extension file for your Liquid Data control. Each method in the `.jcx` file returns an `SDO` type corresponding to the appropriate (or corresponding) data service schema. The `SDO` classes are stored in the `Libraries` directory of the Workshop Application.

# Modifying Existing Liquid Data Controls

This section describes the ways you can modify an existing Liquid Data 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 at that point as well.

This section contains the following procedures:

- Changing a Method Used by a Control
- Adding a New Method to a Control
- Updating an Existing Control if Schemas Change

## Changing a Method Used by a Control

To change a data service function in a Liquid Data control, perform the following steps:

1. In WebLogic Workshop, open the Design View for a Liquid Data control (`.jcx`) file.
2. Select the method you want to change, right-click, and select Edit in source view to bring up the source editor. (See Figure 5-7.)

Figure 5-7 Changing a Function in the Control

3. In the source view, change the comment for the function. Change the functionName value to the new function you want to use. If necessary, change the functionURI value as well. This should be the path to the data service that contains the function.
4. Change the return type, parameters, and name of the function.

When you save your changes, the SDO classes based on the control are automatically recompiled.

## Adding a New Method to a Control

To add a new method to an existing Liquid Data control, perform the following steps:

1. In Workshop, open an existing control in Design View.
2. In the control Design View, move your mouse inside the box showing the control methods, right-click, then select Add Method as shown in Figure 5-8.

Figure 5-8 Adding a Method to a Control

3. Enter a name for the new method.
4. Right-click the new method, and select Edit in Source View to bring up the source editor.
5. In the Source View, add a comment for the function. Change the functionName value to the new function you want to use. If necessary, change the functionURI value as well. This should be the path to the data service that contains the function.
6. Change the return type, parameters, and name of the function.

## Updating an Existing Control if Schemas Change

If any of the schemas corresponding to any methods in a Liquid Data control change, you must build the Liquid Data data service folders to regenerate the SDO classes for the changed schemas. If the changes result in a different return type for any of the functions, you must also modify the function in the control.

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

# Using Liquid Data with NetUI

The WebLogic NetUI tag library allows you to rapidly assemble JSP-based applications that display data returned by Liquid Data. The following sections list the basic steps for using NetUI to display results from a Liquid Data control:

- Generating a Page Flow From a Control
- Adding a Liquid Data Control to an Existing Page Flow
- Adding Service Data Objects (SDO) Variables to the Page Flow
- Displaying Array Values in a Table or List

## Generating a Page Flow From a Control

When you ask Workshop to generate a page flow, Workshop creates the page flow, a start page (`index.jsp`), and a JSP file and action for each method you specify in the Page Flow wizard.

### To Generate a Page Flow From a Control

Perform the following steps to generate a page flow from a Liquid Data control.

1. Select a Liquid Data control (`.jcx`) file from the application file browser, right-click, and select Generate Page Flow.
2. In the Page Flow Wizard (see Figure 5-9), enter a name for your Page Flow and click Next.

Figure 5-9 Enter a Name for the Page Flow

3. On the Page Flow Wizard - Select Actions dialog, check the methods for which you want a new page created. The wizard has a check box for each method in the control. (See Figure 5-10.)

Figure 5-10 Choose Liquid Data Methods for the Page Flow

4. Click Create.

Workshop generates the `.jpf` Java Page Flow file, a start page (`index.jsp`), and a JSP file for each method you specify in the Page Flow wizard.

5. Add and initialize variables to the `.jpf` file based on the SDO classes. For details, see Adding Service Data Objects (SDO) Variables to the Page Flow.
6. Drag and drop the SDO variables to your JSPs to bind the data from Liquid Data to your page layout. For details, see Displaying Array Values in a Table or List.
7. Build and test the application in WebLogic Workshop.

## Adding a Liquid Data Control to an Existing Page Flow

You can add a Liquid Data control to an existing Page Flow `.jpf` file. The procedure is the same as adding a Liquid Data control to a Web Service as described in the section Adding a Liquid Data Control to a Web Service Project in Exposing Data Services through Web Services. However, Instead of opening the Web Service in Design View as described in that chapter, you open the Page Flow `.jpf` file in Action View.

You can also add a control to an existing page flow from the Page Flow Data Palette (available in Flow View and Action View of a Page Flow) as shown in Figure 5-11.

Figure 5-11 Adding a Control to a Page Flow from the Data Palette

## Adding Service Data Objects (SDO) Variables to the Page Flow

To use the NetUI features to drag and drop data into a JSP, you must first create one or more variables in the page flow `.jpf` file. The variables must be of the data object type corresponding to the schema associated with the query.

Note: A data object is the fundamental component of the SDO architecture. For more information, see Client Programming with Service Data Objects (SDO).

Defining a variable in the page flow `.jpf` file of the top-level class of the SDO function return type provides you access to all the data from the query through the NetUI repeater wizard. The top-level class, which corresponds to the global element of the data service type, has "Document" appended to its name, such as `CUSTOMERDocument`.

When you create the Liquid Data control and the SDO variables are generated, an array is created for each element in the schema that is repeatable. You may want to add other variables corresponding to other arrays in the classes to make it more convenient to drag and drop data onto a JSP, but it is not required. For example. when an array of CUSTOMER objects can contain an array of ORDER objects, you can define two variables: one for the CUSTOMER array and one for the ORDER array. You can then drag the variables to different JSP pages.

Define each variable with a type corresponding to an SDO object. Define the variables in the source view of the page flow controller class. The variables should be declared public. In the following example, the bold-typed variable declarations show an example of user variable declarations:

>     public class CustomerPFController extends PageFlowController
>     {
>         /**
>          * This is the control used to generate this pageflow
>          *  @common:control
>          */
>         private DanubeCtrl myControl;

>         public CUSTOMERDocument var;
>         public POITEM currentItem;
>         public PAYMENTListDocument payments;

Once defined in the page flow controller, the variables appear on the Data Palette tab. From there, you can drag-and-drop them onto JSP files. When you drag-and-drop an array onto a JSP file, the NetUI Repeater Wizard appears and guides you through selecting the data you want to display. (See Figure 5-12.)

Figure 5-12 Page Flow Variables for XMLBean Objects

To populate the variable with data, initialize the variable in the page flow method corresponding to the page flow action that calls the query. For details, see To Initialize the Variable in the Page Flow.

### To Add a Variable to a Page Flow

Perform the following steps to add a variable to the page flow:

1. Open your Page Flow (`.jpf`) file in Workshop.
2. Open the Source View tab.
3. In the variable declarations section of your Page Flow class, enter a variable with the SDO type corresponding to the schema elements you want to display. Depending on your schema, what you want to display, and how many queries you are using, you might need to add several variables.
4. To determine the SDO type for the variables, examine the method signature for each method that corresponds to a query in the Liquid Data control. The return type is the root level of the SDO class. Create a variable of that type. For example, if the signature for a control method is:

>     org.openuri.temp.schemas.customer.CUSTOMERDocument getCustomer(int p1);

create a variable as follows:

>     public org.openuri.temp.schemas.customer.CUSTOMERDocument var;

5. After you create the variables, initialize them as described in the following section.

### To Initialize the Variable in the Page Flow

You can initialize the variable by calling a Liquid Data control function, which will populate the variable with the returned data. Initializing the variables ensures that the data bindings to the variables work correctly and that there are no tag exceptions when the JSP displays the results the first time.

Perform the following steps to initialize the variables in Page Flow:

1. Open your Page Flow (`.jpf`) file in Workshop.
2. Open the Source View.
3. In the page flow action that corresponds to the Liquid Data query for which you are going to display the data, add the code to initialize the variable.

The following example shows how to initialize an object on the Page Flow. The code (and comments) in bold has been added. The rest of the code was generated when the Page Flow was created from the Liquid Data control (see Generating a Page Flow From a Control).

>     public class CustomerPFController extends PageFlowController
>     {
>         /**
>          * This is the control used to generate this pageflow
>          *  @common:control
>          */
>         private DanubeCtrl myControl;

>         public CUSTOMERDocument var;
>         ...
>         /**
>          * Action encapsulating the control method :getCustomer
>          * @jpf:action
>          * @jpf:forward name="success" path="viewCustomer.jsp"
>          * @jpf:catch method="exceptionHandler" type="Exception"
>          */
>         public Forward getCustomer(GetCustomerForm aForm)
>             throws Exception
>         {
>             var = myControl.getCustomer(aForm.p1);
>             ...
>             return new Forward("success");
>         }
>     }

### Working with Data Objects

After creating and initializing a data objects as a public variable in the Page Flow, you can drag and drop elements of the object onto your application pages (such as JSPs) from the Data Palette.

The elements appear in dot-delimited chain format, such as:

>     	pageFlow.var.CUSTOMER.CUSTOMERNAME

Notice that the function that actually returns the element value is `getCUSTOMERNAME()`, which returns a `java.lang.String` value, the name of a customer.

As you edit code in the source view, Workshop offers code completion for method and member names as you type. A selection box of available elements appears in the data object variable as shown in Figure 5-13.

Figure 5-13 DataObject Method Name Completion

Note: For more information on programming with Liquid Data data objects, see Client Programming with Service Data Objects (SDO).

## Displaying Array Values in a Table or List

Liquid Data maps to an array any data element specified to have unbounded maximum cardinality in its XML schema definition. Unbounded cardinality means that there can be zero to many (unlimited) occurrences of the element (indicated by an asterisk in the return type view of the Liquid Data Console). Such elements are named with the prefix `ArrayOf`.

When you drag and drop an array value onto a JSP File, BEA WebLogic Workshop displays the Repeater wizard to guide you through the process of selecting the data you want to display. The Repeater wizard provides choices for displaying the results in an HTML table or in a list.

### Adding a Repeater to a JSP File

To add a NetUI repeater tag (used to display the data from a Liquid Data query) to a JSP file, perform the following steps:

1. Open a JSP file in your Page Flow project where you want to display data. This should be the page corresponding to the action in which the variable is initialized.
2. In the Data Palette —>Page Flow Properties, locate the variable containing the data you want to display.
3. Expand the nodes of the variable to expose the node that contains the data you want to display. If the variable does not traverse deep enough into your schema, you will have to create another variable to expose the part of your schema you require. For details, see To Initialize the Variable in the Page Flow.
4. Select the node you want, then drag and drop it onto the location of the JSP file in which you want to display the data. You can do this either in Design View or Source View. Workshop displays the repeater wizard as shown in Figure 5-14.

Figure 5-14 Repeater Wizard

5. In the repeater wizard, navigate to the data you want to display and uncheck any fields that you do not want to display. There might be multiple levels in the repeater tag, depending on your schema.
6. Click Next. The Select Format screen appears as shown in Figure 5-15.

Figure 5-15 Repeater Wizard Select Format Screen

7. Choose the display format for your data and click Create.
8. Right-click on the JSP page and choose Run Page to see the results.

### Adding a Nested Level to an Existing Repeater

You can create repeater tags inside other repeater tags. You can display nested repeaters on the same page (in nested tables, for example) or you can set up Page Flow actions to display the nested level on another page (with a link, for example).

To create a nested repeater tag, perform the following steps:

1. Add a repeater tag as described in Adding a Repeater to a JSP File.
2. Add a column to the table where you want to add the nested level.
3. Drag and drop the array from your variable corresponding to your nested level into the data cell you created in the table.
4. In the repeater wizard, select the items you want to display.
5. Click the Create button in the repeater wizard to create the repeater tags.
6. Right-click on the JSP page and choose Run Page to see the results.

### Adding Code to Handle Null Values

It is a common JSP design pattern to add conditional code to handle null checks. If you do not check for null values returned by function invocations, your page will display tag errors if it is rendered before the functions on it are executed.

To add code to handle null values, perform the following steps:

1. Add a repeater tag as described in Adding a Repeater to a JSP File.
2. Open the JSP file in source view.
3. Find the `netui-data:repeater` tag in the JSP file.
4. If the `dataSource` attribute of the `netui-data:repeater` tag directly accesses an array variable from the page flow, then you can set the `defaultText` attribute of the `netui-data:repeater` tag. For example:

>     <netui-data:repeater dataSource="{pageFlow.promo}" defaultText="no data">

If the `dataSource` attribute of the `netui-data:repeater` tag accesses a child of the variable from the page flow, you must add `if/else` logic in the JSP file as described below.

1. If the `defaultText` attribute can have a null value for your `netui-data:repeater` tag, add code before and after the tag to test for null values. The following is sample code. The code in bold is added, the rest is generated by the repeater wizard. This code uses the profile variable initialized in To Initialize the Variable in the Page Flow.

>     <%
>     PageFlowController pageFlow = PageFlowUtils.getCurrentPageFlow(request);
>     if ( ((pF2Controller)pageFlow).profile == null
>             || ((pF2Controller)pageFlow).profile.getPROFILEVIEW().getCUSTOMERPROFILEArray() == null
>             || ((pF2Controller)pageFlow).profile.getPROFILEVIEW().getCUSTOMERPROFILEArray().length == 0){
>           %>
>              <p>No data</p>
>              <% } else {%>
>     <netui-data:repeater dataSource=
>             "{pageFlow.profile.PROFILEVIEW.CUSTOMERPROFILEArray}">
>             <netui-data:repeaterHeader>
>                 <table cellpadding="2" border="1" class="tablebody" >
>                 <tr>
>     <!- the rest of the table and NetUI code goes here -->
>     <td><netui:label value
>           ="{container.item.PROFILE.DEFAULTSHIPMETHOD}"></netui:label></td>
>                 </tr>
>             </netui-data:repeaterItem>
>             <netui-data:repeaterFooter></table></netui-data:repeaterFooter>
>         </netui-data:repeater>
>              <% }%>

1. Test the application.

# Using Liquid Data in Business Process Projects

You can use data services in WebLogic Integration (WLI) business process applications through a Liquid Data control. Liquid Data information can be used, for example, in decision-making logic in the business process. The procedure for adding a Liquid Data control to a business process application is similar to adding a control to a web project.

However, an important difference exists in how data objects are unmarshalled in business processes from web applications. As a result, you need to serialize the data graph manually when submitting changed data objects as described in this section.

There are three basic steps to adding Liquid Data Queries to a WebLogic Integration business processes:

- Creating a Liquid Data Control
- Adding a Liquid Data Control to a JPD File
- Setting Up the Control in the Business Process

Note: For comprehensive information about WebLogic Integration, see the WebLogic Integration documentation.

## Creating a Liquid Data Control

Before you can run a Liquid Data query in a WLI business process, you must create a Liquid Data Control that accesses the query or queries you want to run in your business process. For details, see Liquid Data Control.

## Adding a Liquid Data Control to a JPD File

Once you have created a Liquid Data Control, you can add it to a business process the same way you add any other control to a business process. For example, you can drag and drop the control into the WebLogic Integration business process in the place where you want to run your Liquid Data query or you can add the Liquid Data Control to the Data Palette. For comprehensive information about using WebLogic Integration, see the WebLogic Integration documentation.

## Setting Up the Control in the Business Process

Once you have added the Liquid Data control to the business process, you can use its functions in the business process.

As shown in Figure 5-16, you must select the query in the General Settings section of the Liquid Data control portion of the business process, specify input parameters for the query in the Send Data section, and specify the output of the query in the Receive Data section.

Figure 5-16 WebLogic Integration Business Process Accessing a Liquid Data Control

## Submitting Changes from a Business Process

By default, a business processes (JPD) converts XML objects to an XML proxy class by implementing an interface named ProcessXML. However, ProcessXML is not completely compatible with SDO. In particular, it does not accommodate SDO specific features such as change summaries. As a result, the default XML processing performed in a business process must be overridden.

You can override the business process by performing the following steps in the workflow:

1. In the JPD you need to turn off default ProcessXML deserialization and enable XBean serialization on the XML object factory by calling the `XmlObjectVariableFactory.setXBean()`.
2. Invoke the Liquid Data control.
3. In the JPD you need to disable the XBean serialization and turn on the default ProcessXML deserialization on the XML object by calling`XmlObjectVariableFactory.unset()`.

# Security Considerations With Liquid Data Controls

This section describes security considerations for applications using Liquid Data controls. The following sections are included:

- Security Credentials Used to Create Liquid Data Control
- Testing Controls With the Run-As Property in the JWS File
- Trusted Domains

## Security Credentials Used to Create Liquid Data Control

The WebLogic Workshop Application Properties (Tools —>Application Properties) allow you to set the connection information to connect to the domain in which you are running. You can either use the connection information specified in the domain `boot.properties` file or override that information with a specified username and password.

When you create a Liquid Data control (`.jcx`) file and are connecting to a local Liquid Data server (Liquid Data on the same domain as Workshop), the user specified in the Application Properties is used to connect to the Liquid Data server. When you create a Liquid Data control and are connecting to a remote Liquid Data server (a WebLogic Server on a different domain from Workshop), you specify the connection information in the Liquid Data Control Wizard Connection information dialog (see Figure 5-5).

When you create a Liquid Data control, the 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.

Note: The security credentials specified through the Application Properties or through the Liquid Data Control Wizard are only used for creating the Liquid Data control (`.jcx`) file, not for testing queries through the control. To test a query through the control, you must get the user credentials either through the application (from a login page, for example) or by using the run-as property in the Web Service file.

## Testing Controls With the Run-As Property in the JWS File

You can use the run-as property to test a control running as a specified user. To set the run-as property in a Web Service, open the Web Service and enter a user for the run-as property in the WebLogic Workshop property editor.

When a query is run from an application, the application must have a mechanism for getting the security credential. The credential can come from a login screen, it can be hard-coded in the application, 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 Liquid Data project is on a different domain than WebLogic Workshop, 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.

### Configuring Trusted Domains

To configure domains as a trusted user, perform the following steps:

1. Log into the WebLogic Administration Console as an administrator.
2. In the left-frame navigation tree, click the node corresponding to your domain.
3. At the bottom of the General tab for the domain configuration, click the link labeled View Domain-wide Security Settings Links.
4. Click the Advanced tab. (See Figure 5-17.)

Figure 5-17 Setting up Trusted Domains

5. Uncheck the Enable Generated Credential box, enter and confirm a credential (usually a password), and click Apply.
6. Repeat this procedure for all of the domains you want to set up as trusted. The credential must be the same on each domain.

For more details on WebLogic security, see:

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

For information on Liquid Data security, see:

- Securing Liquid Data Resources in the Administration Guide.