# 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 Liquid Data, If It is Not Already Running

Make sure Liquid Data is running. Liquid Data can be running locally (on the same domain as WebLogic Workshop) or remote (on a different domain from workshop). If Liquid Data 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 1-2 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 1-3. You can also create a control using the File —> New—> Java Control menu item.

Figure 1-3 Create a New Liquid Data Control

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

Figure 1-4 Liquid Data Control in WebLogic Workshop

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

A screen similar to the one in Figure 1-5 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 1-5 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.

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 1-6 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 1-2). Enter a name for the folder and click OK.
7. Select the new folder, right-click, and select New —> Java Control (see Figure 1-3).
8. In the New Java Control Extension wizard, select Liquid Data as the control type, enter a name, and click Next (see Figure 1-4).
9. If your Liquid Data server is local to your machine, accept the default and click Create (see Figure 1-5). 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 1-6).
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 1-2). Enter a name for the folder and click OK.
7. Select the new folder, right-click, and select New —> Java Control (see Figure 1-3).
8. In the New Java Control Extension wizard, select Liquid Data as the control type, enter a name, and click Next (see Figure 1-4).
9. If your Liquid Data server is local to your machine, accept the default and click Create (see Figure 1-5). 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 1-6).
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 1-7 Add a Liquid Data Control to Web Service

1. In the Insert Control Wizard, enter a variable name for the control (STEP 1 in the dialog in Figure 1-8). The variable name can be any valid variable name that is unique in the Web Service.
2. 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.
3. 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 1-8 Insert Control Wizard

1. 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.
2. Click the Create button on the Insert Control Wizard.
3. 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.