Skip navigation.
Downloads | Product Documentation | Support

Application Developer's Guide

# Using Liquid Data Controls to Develop Workshop Applications

This chapter describes how to use the Liquid Data control in WebLogic Workshop to develop applications that use data from Liquid Data queries. Applications can use the data to display results in a web application, to use in a Web Service, to use as an input to a WebLogic Integration business process, or in many other ways. 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 NetUI to Display Liquid Data Results
- Security Considerations With Liquid Data Controls
- Moving Your Liquid Data Control Applications to Production

# WebLogic Workshop and Liquid Data

WebLogic Workshop allows you to create Liquid Data Controls. The Liquid Data Control is a Java Control, and it allows you to very rapidly generate robust applications that use results from Liquid Data queries (for example, to display in a web application or to use in a WebLogic Integration business process). This section describes the Liquid Data control and the applications you can create with it.

## Liquid Data Control

The Liquid Data Control is available in WebLogic Workshop. The Liquid Data Control is an extensible Java Control that accesses the Liquid Data server to execute queries from applications developed in WebLogic Workshop. The Liquid Data Control is available with all of the other Java Controls in WebLogic Workshop (for example, the database control). When you use the Liquid Data Control in WebLogic Workshop, Workshop displays a query wizard which connects to a Liquid Data server to get the query metadata needed for configuring the control. After you select the queries to use in your Liquid Data Control, Workshop generates `XMLBean` classes for the target schemas associated with the queries and then generates a Liquid Data Control (`.jcx`) file.

## XMLBean Generation

When you create a Liquid Data control in WebLogic Workshop, the Liquid Data Control wizard generates `XMLBean` classes for each query in the control. The Liquid Data Control wizard uses the schema associated with the stored query in the Liquid Data repository to generate the structure for the `XMLBean` classes. The `XMLBean` classes provide Java methods to traverse the XML result set returned from Liquid Data.

The `XMLBean` classes are automatically generated in a schema project in the workshop application. There is one schema project per Liquid Data Control (`.jcx`) file.

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

You can use the Liquid Data Control like other controls in WebLogic Workshop, and you can take advantage of Workshop features to use Liquid Data Controls in Web Services, Page Flows and WebLogic Integration business processs. For example, you can generate a page flow from your Liquid Data control and then use the `XMLBeans` to bind the data returned from Liquid Data to the JSPs in your application.

# Liquid Data Control JCX File

When you create a Liquid Data Control, WebLogic Workshop generates a Java Control Extension (`.jcx`) file. The file contains methods corresponding to the queries in which the control accesses, shows the schema files of each query as a comment, and contains a commented method which, when uncommented, allows you to pass any XQuery statement to execute an ad-hoc query. This section describes the Liquid Data Control (`.jcx`) file and includes the following sections:

- Design View
- Source View
- Schema Project Location
- Running Ad-Hoc Queries through the Liquid Data Control

## Design View

The design view of the Liquid Data Control (`.jcx`) file shows the available methods in a graphical view.

Figure 2-1 Design View of a Control File

With the right-click menu, you can add, modify (for example, change the query accessed by a method), rename, and delete methods. The right-click menu is context-sensitive; it displays different items if the mouse cursor is over a method, or in the control portion of the design pane.

## Source View

The source view shows the source code of the Java Control Extension (`.jcx`) file. It includes as comments the schema used to generate the `XMLBean` classes for each query. The signature for each method shows the return type of the method. The return type is the `XMLBean` class which was generated for the schemas.

This file is a generated file and 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 the Liquid Data Control.

The following shows the source code for a generated Liquid Data Control (`.jcx`) file. It shows the package declaration, import statements, connection properties, the schema project and filename used with the `ApplOrderDetailView` query, and the method that executes the `ApplOrderDetailView` query.

>     package myFolder;

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

>      /**
>      *   @jc:LiquidData urlKey="myApp.myAppWeb.myFolder.anotherLDControl"
>      */
>     public interface anotherLDControl extends LDControl, com.bea.control.ControlExtension
>      {

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

>         /**
>          * @return Schema Project: myAppWeb-myFolder-anotherLDControl-Schemas
>                Schema File: rtl\OrderDetailView.xsd
>                TargetNamespace: urn:retailer
>                Element Name: OrderDetailView
>          *
>          * @param orderid java.lang.String
>          *
>          * @param custid java.lang.String
>          *
>          * @jc:Stored-Query Name="rtl.ElecOrderDetailView"
>          */
>         retailer.OrderDetailViewDocument ElecOrderDetailView
>                         (java.lang.String orderid, java.lang.String custid);

>         /**
>          *  Default method to execute an ad hoc query.
>          *  This method can be customized to have a differnt method name
>          *  (e.g. runMyQuery), return a XML Bean class (e.g. Customer),
>          *  or to have one or both of the following two extra parameters:
>          *  com.bea.ldi.server.common.QueryParameters and

>          *  com.bea.ldi.server.common.QueryAttributes
>          *  e.g. exec(String query, QueryParameters params);
>          *  e.g. exec(String query, QueryAttributes attrs);
>          *  e.g. exec(String query, QueryParameters params,

>          *  QueryAttributes attrs);
>          *
>         com.bea.xml.XmlObject executeXQuery(String query);
>          */

>     }

## Schema Project Location

The `XMLBean` classes corresponding to the queries in the Liquid Data Control (`.jcx`) file are generated in a schema project. There is one schema project for each control. The schema project(s) also contain a copy of the schema files associated with the queries in the Liquid Data Control (`.jcx`) file. The JAR file for the `XMLBean` classes is generated in the `Libraries` directory of your WebLogic Workshop application.

The `@return Schema Project` section of the generated Liquid Data Control (`.jcx`) file displays the location of the schemas corresponding to the query method below this section in the control file. For example, the following code snippet from a generated Liquid Data Control (`.jcx`) file shows the name of the schema project and the name of the target schema.

>     /**
>          * @return Schema Project: myAppWeb-myFolder-anotherLDControl-Schemas
>                Schema File: rtl\OrderDetailView.xsd
>                TargetNamespace: urn:retailer
>                Element Name: OrderDetailView
>          *
>          * @param orderid java.lang.String
>          *
>          * @param custid java.lang.String
>          *
>          * @jc:Stored-Query Name="rtl.ElecOrderDetailView"
>          */
>         retailer.OrderDetailViewDocument ElecOrderDetailView
>                          (java.lang.String orderid, java.lang.String custid);

The name of the schema project is `myAppWeb-myFolder-anotherLDControl-Schemas`, and the schema file is in the `rtl` subdirectory and is named `OrderDetailView.xsd`. Figure 2-2 shows the generated schema project in WebLogic Workshop.

Figure 2-2 Generated Schema Project in WebLogic Workshop

## Running Ad-Hoc Queries through the Liquid Data Control

At the bottom of the generated Liquid Data Control (`.jcx`) file is a comment showing methods you can add which allow you to run an ad-hoc query through the control. To add one of these methods, uncomment the appropriate method and add a return type to the signature.

>     /**
>     *  Default method to execute an ad hoc query. This method can be customized
>     * to have a differnt method name (e.g. runMyQuery), return a XML Bean class
>     * (e.g. Customer), *  or to have one or both of the following two extra
>     * parameters: com.bea.ldi.server.common.QueryParameters and
>     * com.bea.ldi.server.common.QueryAttributes
>     *  e.g. exec(String query, QueryParameters params);
>     *  e.g. exec(String query, QueryAttributes attrs);
>     *  e.g. exec(String query, QueryParameters params, QueryAttributes attrs);
>     *             com.bea.xml.XmlObject executeXQuery(String query); */

# Creating Liquid Data Controls

You can create Liquid Data controls in a variety of WebLogic Workshop projects. This section includes the following procedures to create Liquid Data controls:

- General Steps to Create a Liquid Data Control
- To Create a Liquid Data Control in a Web Project
- To Create a Liquid Data Control in a Web Service Project
- To Add a Liquid Data Control to an Existing Web Service File
- To Create a Test Web Service From a Liquid Data Control

The steps are similar for creating Liquid Data controls in other types of WebLogic Workshop projects.

## General Steps to Create a Liquid Data Control

This section describes the general steps for creating a Liquid Data control. For detailed steps for creating a Liquid Data control in a Web Project or in a Web Service project, see To Create a Liquid Data Control in a Web Project or To Create a Liquid Data Control in a Web Service Project.

### 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 create a project in the application. You can create a Liquid Data control in most types of Workshop projects, but the most common projects in which you create Liquid Data controls are Web Projects, Web Service Projects, Portal Web Projects, or a Process Web Projects.

### Step 2: Start the Liquid Data Server, If It is Not Already Running

Make sure the Liquid Data server is running. The Liquid Data server can be running locally (on the same domain as WebLogic Workshop) or remote (on a different domain from workshop). If the Liquid Data server is not running, start up the domain in which it runs.

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

Create a folder in the project to hold the Liquid Data control(s). You can also create other controls (database controls, for example) in the same folder, if needed. Workshop controls cannot be created at the top-level of a project directory structure; they must be created in a folder. When you create the folder, enter a name that makes sense for your application.

Figure 2-3 Create a New Folder in WorkshopLiquid Data

### Step 4: Create the Liquid Data Control

The Liquid Data Control is a Java Control Extension. To create a Liquid Data Control, start the Java Control wizard by selecting your folder within a project, right-clicking, and selecting New —> Java Control, as shown in Figure 2-4. You can also create a control using the File —> New—> Java Control menu item.

Figure 2-4 Create a New Liquid Data Control

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

Figure 2-5 Liquid Data Control in WebLogic Workshop

Note: The `LiquidDataControl.jar` file is copied into the `Libraries` directory (if it does not already exist) of your application when you create a Liquid Data Control.

### Step 5: Enter Connection Information to the Liquid Data Server

A screen similar to the one in Figure 2-6 allows you to enter connection information to your Liquid Data server. 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 the IDE).

If the Liquid Data server is remote, click the Remote button and fill in the appropriate server URL, user name, and password.

Note: You can specify a different username and password with which you connect to a local machine on the Liquid Data Control Wizard Connection Information dialog, too. 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 2-6 Liquid Data Control Wizard—Connection Information

### Step 6: Select Queries to Add to the Control

In the Select Liquid Data Queries screen, select queries from the left pane and click Add to add those queries to the control. If you mouse over a query, the signature of the control method for the query appears in a tooltip popup. A "fetching metadata" message appears if the signature has not yet been retrieved from the Liquid Data server.

Note: Only stored queries with a schema configured appear in the Stored Queries list. For details on configuring stored queries, see Configuring Stored Queries in the Administration Guide. You can also deploy stored queries from directly from the Data View Builder, as described on Deploying a Query in Building Queries and Data Views.

Select one or more queries, add them to the right pane, and click Finish. When you click Finish, the Liquid Data Control (`.jcx`) file is generated and `XMLBean` classes corresponding to the schema for each stored query in the control are generated. The `XMLBeans` are stored in the `Libraries` directory of the Workshop Application. In the `Libraries` directory, there is one JAR file for each Liquid Data control, with the `XMLBeans` included in the JAR file. The JAR files are named according to the project and directory hierarchy for the control (`.jcx`) file.

Figure 2-7 Liquid Data Control Wizard—Select Queries

Note: The stored queries should be named according to the Naming Conventions for Stored Queries described in Building Queries and Data Views. If a stored query contains illegal characters (for example, a hyphen), the method generated in the Liquid Data Control (`.jcx`) file might be an invalid Java name, causing compilation errors. If a method name is invalid, you can change the name to make it valid.

#### New Query

Clicking the New Query button launches the Data View Builder. You can then use the Data View Builder to create, modify, test, and deploy new queries.

#### Refresh

The Refresh button updates the stored query list from the Liquid Data server. If you create and deploy a new query with the Data View Builder, click the Refresh button to display the new query in the wizard.

## To Create a Liquid Data Control in a Web Project

This section describes the basic steps for creating a Liquid Data control in a new Web Project. If you are adding the control to an existing project, you might not need to perform each step (for example, creating a new project). Perform the following steps to create a Liquid Data control in a new WebLogic Workshop Web Project.

1. Make sure your Liquid Data domain is running.
2. Start WebLogic Workshop.
3. Either open an existing Workshop application or create a new application (File —> New —> Application).
4. Select the top-level folder of your Workshop application, right-click, and select New —> Project.
5. Select Web Project as the type of project, enter a name, and click Create.
6. Create a folder in your Web Project. To create the new folder, select the project folder you just created, right-click, and select New —> Folder (see Figure 2-3). Enter a name for the folder and click OK.
7. Select the new folder, right-click, and select New —> Java Control (see Figure 2-4).
8. In the New Java Control Extension wizard, select Liquid Data as the control type, enter a name, and click Next (see Figure 2-5).
9. If your Liquid Data server is local to your machine, accept the default and click Create (see Figure 2-6). If Liquid Data is running on a remote server, click the Remote button, enter your connection information, test your connection, and click Create.
10. In the Edit Liquid Data Control - Select Queries screen, select any queries you want accessible to your control from the left pane and click Add to add them to the right pane (see Figure 2-7).
11. If you want to create any new queries, click the Create New Query button to launch the Data View Builder, where you can create, test, and deploy queries.
12. If you have added any Liquid Data queries, click Refresh to display the new queries.
13. 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 `XMLBean` type corresponding to the stored query schema. The `XMLBean` classes for each query are automatically generated when you create the Liquid Data control. The `XMLBean` classes are stored in the `Libraries` directory of the Workshop Application.

## To Create a Liquid Data Control in a Web Service Project

This section describes the basic steps for creating a Liquid Data control in a new Web Service. If you are adding the control to an existing Web Service, you might not need to perform each step (for example, creating a new project). Perform the following steps to create a Liquid Data control in a new WebLogic Workshop Web Service Project.

1. Make sure your Liquid Data domain is running.
2. Start WebLogic Workshop.
3. Either open an existing Workshop application or create a new application (File —> New —> Application).
4. Select the top-level folder of your Workshop application, right-click, and select New —> Project.
5. Select Web Service Project as the type of project, enter a name, and click Create.
6. Create a folder in your Web Service Project. To create the new folder, select the project folder you just created, right-click, and select New —> Folder (see Figure 2-3). Enter a name for the folder and click OK.
7. Select the new folder, right-click, and select New —> Java Control (see Figure 2-4).
8. In the New Java Control Extension wizard, select Liquid Data as the control type, enter a name, and click Next (see Figure 2-5).
9. If your Liquid Data server is local to your machine, accept the default and click Create (see Figure 2-6). If Liquid Data is running on a remote server, click the Remote button, enter your connection information, test your connection, and click Create.
10. In the Edit Liquid Data Control - Select Queries screen, select any queries you want accessible to your control from the left pane and click Add to add them to the right pane (see Figure 2-7).
11. If you want to create any new queries, click the Create New Query button to launch the Data View Builder, where you can create, test, and deploy queries.
12. If you have added any Liquid Data queries, click Refresh to display the new queries.
13. 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 `XMLBean` of the type corresponding to the schema from the stored query. The `XMLBean` for each query is automatically generated when you create the Liquid Data control. The `XMLBeans` are stored in the `Libraries` directory of the Workshop Application.

## To Add a Liquid Data Control to an Existing Web Service File

Perform the following steps to add a Liquid Data Control to an existing Web Service `.jws` file.

1. Make sure your Liquid Data domain is running.
2. In WebLogic Workshop, open an existing Web Service `.jws` file.
3. Click the Design View tab on the Web Service.
4. In the graphical representation of the Web Service, right-click and select Add Control —> Liquid Data.

Figure 2-8 Add a Liquid Data Control to Web Service

5. In the Insert Control Wizard, enter a variable name for the control (STEP 1 in the dialog in Figure 2-9). The variable name can be any valid variable name that is unique in the Web Service.
6. In the Insert Control Wizard, either browse to an existing Liquid Data Control (it must be in the same project as the Web Service) or click the Create a New Liquid Data Control button.
7. If you want the control to be a factory, check the Make This a Control Factory button. If the control is a factory, it will create multiple instances at runtime if a query is called multiple times. Otherwise, requests to the control are serialized and each request for a given query must complete before another can begin.

Figure 2-9 Insert Control Wizard

8. If your Liquid Data server is running on a separate domain from Workshop, click remote (in STEP 3 of the Insert Control Wizard dialog). For details about specifying local or remote Liquid Data server, see Step 5: Enter Connection Information to the Liquid Data Server.
9. Click the Create button on the Insert Control Wizard.
10. If you created a new control, choose the queries for your control, as described in Step 6: Select Queries to Add to the Control.

## To Create a Test Web Service From a Liquid Data Control

Perform the following steps to generate and test a web service from a Liquid Data Control.

1. Select a Liquid Data Control (`.jcx`) file, right-click, and select Generate Test JWS File.

Workshop generates the `.jws` Java Web Service file for your Liquid Data control.

2. Select your Web Service project, right-click, and select Build Project.

Workshop builds an asynchronous Web Service from the `.jws` file.

3. When the build is complete, double-click the `.jws` file to open it.
4. On the Design View of the Web Service, notice the `startTestDrive` and `finishTestDrive` methods, as well as a method for each of the queries you specified in the Liquid Data Control wizard.
5. Click the test button (or select Debug —> Start from the Workshop menu) to test the web service.
6. Click the `startTestDrive` button to start the conversation for the Web Service.
7. Click the Continue this Conversation link (in the left corner of the test page).
8. Enter values for any query parameters (if the query has parameters) and click the button with the name corresponding to the query you want to execute.

The Web Service executes the query and the results are returned to the test browser.

9. If you want to run the query again or run other queries in the Web Service, click Continue this Conversation, enter any needed parameters and click the button with the name corresponding to the query you want to execute.
10. To end the Web Service conversation, click the Continue this Conversation link and then click the `finishTestDrive` button.

# Modifying Existing Liquid Data Controls

This section describes the ways you can modify an existing Liquid Data control. It contains the following procedures:

- To Change the Query Associated With a Single Control Method
- To Add a New Method to a Control
- To Invoke the Query Wizard to Modify an Existing Control
- Updating an Existing Control if Schemas Change

## To Change the Query Associated With a Single Control Method

Perform the following steps to change the query that a method in a Liquid Data Control accesses.

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 Stored-Query Name to bring up the Liquid Data Control Wizard.

Figure 2-10 Changing the Query a Method Accesses

Note: You can also access the Liquid Data Control Wizard from the property editor

Figure 2-11 Opening the Property Editor from the Stored-Query Name Property

1. If you are accessing a remote Liquid Data server, enter a password on the connection information screen. If you are using a local Liquid Data server, the connection information screen does not appear.
2. In the Property editor, navigate to the query you want the method to access, select it, and click OK.

## To Add a New Method to a Control

Perform the following steps to add a new method to an existing Liquid Data control.

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, and select Add Method, as shown in Figure 2-12.

Figure 2-12 Add a Method to a Control

3. Enter a name for the new method.
4. Move your mouse over the new method, right-click, and select Edit Stored-Query Name to launch the query wizard (see Figure 2-10).

Alternately, you can launch the query wizard from the Stored-Query name property, as shown in Figure 2-11.

5. If you are accessing a remote Liquid Data server, enter a password on the connection information screen. If you are using a local Liquid Data server, the connection information screen does not appear.
6. In the Property editor, navigate to the query you want the method to access, select it, and click OK.

## To Invoke the Query Wizard to Modify an Existing Control

You can use the query wizard to modify one or more queries accessed in an existing Liquid Data Control. A query corresponds to a method in the Liquid Data Control (`.jcx`) file. Perform the following to invoke the Liquid Data query wizard and modify the query selection for an existing Liquid Data Control.

1. In WebLogic Workshop, open the Design View for a Liquid Data Control (`.jcx`) file.
2. If you are not already viewing the Property Editor, select View —> Property Editor from the Workshop menu.
3. If you want to change any of the connection information, enter a value for the `url` or `username` attributes in the property editor.
4. In the Liquid Data section of the property editor, click the three dots (see Figure 2-13) to launch the query wizard.

Figure 2-13 Invoking the Query Wizard from the Workshop Property Editor

5. If you entered new values for the `url` or `username` attributes, or if the Liquid Data Server is in a remote domain, the Liquid Data Connection Information screen appears. Enter a password and click OK. If you did not change the value of these attributes, then the wizard opens to the Property Editor where you select queries.
6. Add or remove queries as you need in the Property Editor screen and click OK. For details, see Step 6: Select Queries to Add to the Control.

## Updating an Existing Control if Schemas Change

If any of the schemas corresponding to any methods in a Liquid Data Control change, then you must update the Liquid Data Control to regenerate the `XMLBeans` for the changed schemas. Perform the following steps to update a Liquid Data Control

1. In WebLogic Workshop, open the Liquid Data Control (`.jcx`) file.
2. In the Liquid Data section of the property editor, click the three dots (see Figure 2-13) to invoke the Liquid Data query wizard.
3. If you are accessing a remote Liquid Data server, enter a password on the connection information screen. If you are using a local Liquid Data server, the connection information screen does not appear.
4. In the query wizard Property Editor, click OK. Workshop regenerates the Liquid Data Control and the `XMLBeans` for all the schemas used by queries in the control.

# Using NetUI to Display Liquid Data Results

WebLogic Workshop includes NetUI, which allows you to rapidly assemble applications that display data returned from Liquid Data queries.

When you create a Liquid Data control, `XMLBean` classes are generated for the target schema of each stored query included as a method in the control. The following sections represent 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 XMLBean Variables to the Page Flow
- Displaying Query Results in a Table or List

## Generating a Page Flow From a Control

You can generate a page flow from a Liquid Data Control (`.jcx`) file. When you generate the page flow, Workshop creates the page flow, a start page (`index.jsp`), and a JSP file 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, enter a name for your Page Flow and click Next.

Figure 2-14 Enter a Name for the Page Flow

3. On the Page Flow Wizard - Select Actions screen, check the methods for which you want a new page created. The wizard has a check box for each method in the control.

Figure 2-15 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 the variables to the `.jpf` file for the XMLBeans. For details, see Adding XMLBean Variables to the Page Flow.
6. Drag and drop the XMLBean variables to your JSPs to bind the data from Liquid Data to your page layout. For details, see Displaying Query Results 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, described in To Add a Liquid Data Control to an Existing Web Service File, except instead of opening the Web Service in Design View, 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 2-16.

Figure 2-16 Adding a Control to a Page Flow from the Data Palette

## Adding XMLBean Variables to the Page Flow

In order to use the NetUI features to drag and drop data from an `XMLBean` into a JSP, you must first create one or more variables in the page flow `.jpf` file. The variables must be of the `XMLBean` type corresponding to the schema associated with the query. If you create a single variable at the top level of the `XMLBean` class (the same as the return type of the method in the Liquid Data Control (`.jcx`) file), the `NetUI` repeater wizard can then access all the data from the query.

Defining a single variable in the page flow `.jpf` file for the top-level class of the `XMLBean` (the same as the return type of the method in the Liquid Data Control (`.jcx`) file) provides you access to all the data from the query (through the NetUI repeater wizard). When you create the Liquid Data control and the `XMLBeans` are generated, the `XMLBean` generation defines an array for each element in the schema that is repeatable. You might want to add other variables corresponding to other arrays in the `XMLBean` classes to make it more convenient to drag and drop data onto a JSP, but it is not required. Define each variable with a type corresponding to the `XMLBean` object of the parent node.

Define the variables in the class that extend the `PageFlowController` class. For example, consider the case where you are trying to display XML data of the following form:

>     <CUSTOMER>data</CUSTOMER>
>     ......<PROMOTION>promotion data</PROMOTION>
>     ......

You can add the following code snippet, which shows two variables (shown in bold type) added to the page flow:

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

>        // Add public Variables with XMLBeam types from the generated XMLBeans.
>        // The type matches the return type of the method corresponding to the
>        // query in the Liquid Data Control (.jcx) file.
>        public com.mycorp.crm.CUSTDocument aVar;

This code snippet declares one variable in the page flow, `aVar`, and the variable will display in the IDE to allow for drag-and-drop operations onto JSP files.

Note: The variables of `XMLBean` type in the page flow must be declared `public`.

You must also 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.

Figure 2-17 Page Flow Variables for XMLBean Objects

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.

### To Add a Variable to a Page Flow

Perform the following steps to add a variable of `XMLBean` type for your query.

1. Open your Page Flow (`.jpf`) file in Workshop.
2. In the variable declarations section of your Page Flow class, enter a variable with the `XMLBean` 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.
3. To determine the `XMLBean` type for the variables, perform the following:
4. In your Liquid Data control, examine the method signature for each method that corresponds to a query. The return type is the root level of the `XMLBean`. Create a variable of that type. For example, if the signature for a control method is as follows:

>     mySchema.CUSTOMERPROFILEDocument myQuery(java.lang.String custid);

create a variable as follows:

>     public mySchema.CUSTOMERPROFILEDocument myCustomerVar;

5. After you create your variables, initialize them as described in To Initialize the Variable in the Page Flow.

### To Initialize the Variable in the Page Flow

You must initialize your `XMLBean` variables in the Page Flow. 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 `XMLBean` variables in the Page Flow:

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

The following sample code shows an example of initializing a variable on the Page Flow. The code (and comments) in bold is what was added. The rest of the code was generated when the Page Flow was generated from the Liquid Data control (see Generating a Page Flow From a Control).

>     /**
>          * Action encapsulating the control method :RTLCustomerProfile
>          * @jpf:action
>          * @jpf:forward name="success" path="index.jsp"
>          * @jpf:catch method="exceptionHandler" type="Exception"
>          */
>         public Forward RTLCustomerProfile( RTLCustomerProfileForm aForm )
>             throws Exception
>         {
>             schemasBeaComLdCustview.PROFILEVIEWDocument var =
>                          myControl.RTLCustomerProfile( aForm.custid );
>             getRequest().setAttribute( "results", var );

>             //initialize the profile variable to var from the above statement

>             profile=var;

>             return new Forward( "success" );
>         }

## Displaying Query Results in a Table or List

Once you create and initialize your variables in the Page Flow, you can drag and drop the variables onto a JSP file. When you drag and drop an `XMLBean` variable onto a JSP File, 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.

### To Add a Repeater to a JSP File

Perform the following to add a NetUI repeater tag (used to display the data from a Liquid Data query) to a JSP file.

1. Open a JSP file in your Page Flow project where you want to display data.
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 and drag and drop it onto the location of your JSP file in which you want to display the data. You can do this either in Design View or Source View.

Note: You can only drag and drop leaf nodes from the Page Flow Properties.

1. Workshop displays the repeater wizard.

Figure 2-18 Repeater Wizard

2. 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.
3. Click Next. The Select Format screen appears.

Figure 2-19 Repeater Wizard Select Format Screen

4. Choose the format to display your data in and click Create.

Workshop generates the layout for your data.

5. Click the test button to see your data display.

### To Add a Nested Level to an Existing Repeater

You can create repeater tags inside of 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).

Perform the following steps to create a nested repeater tag.

1. Add a repeater tag as described in To Add 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. Click the test button to test the application.

### To Add Code to Handle Null Values

Perform the following steps to add code in your JSP file to handle null values for your data. It is a common JSP design pattern to add conditional code to handle null values. If you do not handle null values, your page will display tag errors if it is rendered before the queries on it are executed.

1. Add a repeater tag as described in To Add 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 does not work 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.

# Security Considerations With Liquid Data Controls

This section describes security considerations to be aware of when developing 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 (Liquid Data on a different domain from Workshop), you specify the connection information in the Liquid Data Control Wizard Connection information dialog (see Figure 2-6).

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 any 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

For testing, 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. Queries run through a Liquid Data Control used by the Web Service

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

Note: The Liquid Data Control property editor shows a run-as property, but the run-as property in the Liquid Data Control does not cause the Liquid Data Control to run as the specified user. If you want to use this feature, you must specify the run-as property in the `.jws` file, not in the `.jcx` file.

## Trusted Domains

If the Liquid Data server is on different domain from 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 that exists on one domain need not be authenticated on the other domain (as long as the user exists on both domains).

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

### To Configure Trusted Domains

Perform the following steps to configure domains as a trusted:

1. Log into the WebLogic Administration Console as an administrator.
2. 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 Links."
4. Click the Advanced tab.

Figure 2-20 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.

# Moving Your Liquid Data Control Applications to Production

When you move any Liquid Data deployment from development to production, you must move Liquid Data and WebLogic Server resources (JDBC Connection Pools, Liquid Data Data Sources, the Liquid Data repository, and so on) from the development environment to the production environment. For details about deploying Liquid Data, see the Liquid Data Deployment Guide.

For applications that use Liquid Data controls, you must also deploy and update the `ldcontrol.properties` file, which contains connection information for Liquid Data controls. This section describes the development to production lifecycle and provides the basic steps for moving an application containing Liquid Data controls from development to production. The following sections are included:

- Development to Production Lifecycle Architecture
- Steps For Deploying to Production

## Development to Production Lifecycle Architecture

In a typical development scenario, you will develop your applications in one environment and then deploy them in another. There are two main artifacts that you need to deploy on the production environment:

- Packaging Liquid Data JAR Files in Application .ear Files
- Liquid Data ldcontrol.properties File

Figure 2-21 Development to Production Lifecycle

### Packaging Liquid Data JAR Files in Application .ear Files

After you have developed and tested your application using WebLogic Workshop in your development environment, you must create a `.ear` file for deployment to your production server(s). All the resources the application needs are already included in the application `Libraries` directory, so the only thing you need to do is create the `.ear` file for the application.

#### To Generate the .ear File in Workshop

Perform the following steps to generate an enterprise archive file (.ear) in WebLogic Workshop:

1. Open your application in WebLogic Workshop, if it is not already opened.
2. Select Build —>Build EAR from the Workshop menu.

When the build is complete, WebLogic Workshop lists the `.ear` file location in the Build window.

### Liquid Data ldcontrol.properties File

Each domain that runs Liquid Data Control applications has a single `ldcontrol.properties` file, which stores the connection information for all Liquid Data Control applications running in the domain. The `ldcontrol.properties` file is located at the root directory of your domain where the Liquid Data Control application `.ear` file is deployed. There is an entry in the `ldcontrol.properties` file for each control you have created in each application.

The entries in the `ldcontrol.properties` file are of the following form:

>     AppName.ProjectName.FolderName.jcxName=t3\://hostname\:port

where:

Name | Description
--- | ---
>     AppName
| The name of the WebLogic Workshop application.
>     ProjectName
| The name of the WebLogic Workshop Project which contains the Liquid Data Control.
>     FolderName
| The name of the folder which contains the Liquid Data Control.
>     jcxName
| The name of the Liquid Data Control file (without the `.jcx` extension). For example, if the control file is named `myLDControl.jcx`, the entry in this file is `myLDControl`.
>     hostname
| The hostname or IP address of the Liquid Data Server for this control.
>     port
| The port number for the Liquid Data Server for this control.

Note: The colons (`:`) in the URL must be escaped with a backslash (`\`) character.

If the URL value is missing, the Liquid Data Control uses the connection information from the domain `config.xml` file.

The following is a sample `ldcontrol.properties` file.

>     #Fri Oct 31 15:30:36 PST 2003
>     myTest.myTestWeb.myFolder.Untitled=t3\:myLDServer\:7001
>     myTest.myTestWeb.myFolder.myControl=
>     SampleApp.LiquidDataSampleApp.Controls.RTLControl=t3\:myLDServer\:7001
>     SampleApp.Untitled.NewFolder.Untitled=t3\:yourLDServer\:7001
>     testnew.Untitled.NewFolder.ldc=
>     test.testWeb.NewFolder.Untitled=

## Steps For Deploying to Production

This section describes the following basic steps for moving an application from development to production:

- Step 1: Generate Enterprise Application Archive (.ear) in Workshop
- Step 2: Merge ldcontrol.properties File entries to Production Server
- Step 3: Deploy Enterprise Application Archive (.ear) on Production Server

### Step 1: Generate Enterprise Application Archive (.ear) in Workshop

Use WebLogic Workshop to generate the .ear file for your application as described in To Generate the .ear File in Workshop.

### Step 2: Merge ldcontrol.properties File entries to Production Server

Merge the entries in the `ldcontrol.properties` file from the root level of your development domain with the `ldcontrol.properties` file in the root level of the production domain. There must be one entry for each Liquid Data Control. If the `ldcontrol.properties` file does not exist in the production domain, copy it from your development domain.

You must also update the URLs in each entry of the file to reference the production Liquid Data servers. For details on and for the syntax of the `ldcontrol.properties` file, see Liquid Data ldcontrol.properties File.

### Step 3: Deploy Enterprise Application Archive (.ear) on Production Server

Deploy your enterprise archive (`.ear`) file on the production WebLogic Server. You deploy the `.ear` file from the domain —> Deployments —> Applications node of the WebLogic Server Administration Console. The `.ear` file must be accessible from the filesystem in which the WebLogic administration server is running. For details on deploying `.ear` files, see Deploying WebLogic Server Applications from the WebLogic Server documentation.