Setting up model-driven development with LiveCycle Data Services ES2

LiveCycle Data Services ES2 is an important component for many companies migrating to a three-tier architecture for enterprise RIA development. The advanced Message Exchange Patterns (MEPs) it enables are unparalleled and very robust. This article is aimed at developers and distills the essential steps needed to set up model-driven development with LiveCycle Data Services ES2 and Flash Builder 4 beta 2.

In this tutorial, we'll share these steps to help you get started quickly and walk through building a simple application using a new technology that brings model-driven development to Flex developers.

Note: You may have heard this technology referred to as "Fiber" (also sometimes spelled "Fibre"). This was the internal project name and the technology is now available for public download.

Here are the steps you need to get started developing in Flash Builder 4 using the Adobe Application Modeling Plug-in.

1. Download LiveCycle Data Services ES2 and install it using the standalone LiveCycle Data Services With Tomcat option.

   Note: Selecting LiveCycle Data Services Web Application to use your own application server is slightly more complicated; the standalone option makes it easier to get started quickly.

2. Download the Adobe Application Modeling Plug-in and unzip it.
3. After you unpack the ZIP file, copy all the files from its plugins folder into your <Flash_Builder_Home>/plugins directory.
4. Navigate to your <LCDS_INSTALL ROOT>/tomcat/webapps/lcds/WEB-INF/ directory and open web.xml with a text editor; for example, textEdit.app (Mac OS X) or Notepad (Windows).
5. Locate the section of code below (it begins around line 26):

6. To uncomment this code, change the first line from <!-- begin rds to <!-- begin rds --> and change the last line from end rds --> to <!-- end rds -->.
7. Change the useAppserverSecurity value from true to false. The code should now look like this:

This change removes application server security from RDSDispatchServlet so you can focus on writing code during development and not security issues. If you do not make this change, you'll see an error in Flash Builder 4 notifying you that the RDS server was successfully contacted, but your security credentials were invalid.

Note: When you have finished this tutorial, reset this parameter to true or disable RDSDispatchServlet to prevent unwanted access to the servlet, which could expose destination details on your server.

8. Save your changes and close the text editor. Now you're ready to start up the server. There are two components you will need to start up: a sample database and the server itself.
9. To start the database (an HSQLDB instance), open a terminal/command window, navigate to <LCDS_INSTALL ROOT>/sampledb, and type sh startdb.sh (Mac OS X and Linux) or startdb (Windows).
10. Open a second terminal/command window, navigate to <LCDS_INSTALL ROOT>/tomcat/bin, and type sh Catalina.sh run (Mac OS X and Linux) or Catalina run (Windows).

As the server starts up, you will see a line that shows the port that hsqldb is using. By default it is 9002 (see Figure 1). You'll use this information to configure the data source.

11. Navigate to the folder <LCDS_INSTALL ROOT>/tomcat/conf/Catalina/localhost and open the lcds.xml file with a text editor.
12. Edit the file and add a reference to the data source as follows:

There are two databases that you can use here: ordersdb and flexdemodb. The code above uses ordersdb.

13. Save your changes and close the text editor. You may need to restart your server for this change to take effect.

Your environment is now set up and you're ready to start building your first model-driven Flex application.

Follow these steps to build a simple model-driven Flex application:

1. Start Flash Builder 4 and choose File > New > Flex Project.
2. Type FiberTest for the Project Name, select J2EE and LiveCycle Data Services ES as the server technology (see Figure 2), and click Next.

3. To configure the J2EE server, make sure the settings for Root Folder, Root URL, and Context Root are correct. By default on Mac OS X they are as follows:

   Root Folder: <TOMCAT_ROOT_DIRECTORY>/tomcat/webapps/lcds/

   Root URL: http://localhost:8400/lcds

   Context Root: lcds/ (Mac OS X) or /lcds (Windows)

4. Click Validate Configuration (see Figure 3) to ensure the root folder and root URL are valid and then click Finish.

Next, you must configure Remote Data Services (RDS) to enable the modeler plug-in to access the data source you just configured.

5. Choose Window > Preferences.
6. From the list on the left, select Adobe and then RDS Configuration.
7. Click New.
8. For the Description type LCDS (localhost); for Host Name type 127.0.0.1; for Port type 8400; and for Context Root type lcds.
9. Leave the User Name and Password blank and click Test Connection to verify your settings (see Figure 4).
10. Click OK

11. Choose Window > Other Views", expand the Data Model folder, and select RDS Dataview (see Figure 5).

12. If you want, you can drag the RDS Dataview panel to the lower left hand side of Flash Builder 4.

    At this point, you should be able to expand LCDS (localhost) in the RDS Dataview panel and examine any of the database tables (see Figure 6). If you cannot connect to the server, right-click (or Control-Click) on LCDS (localhost), select RDS Configuration, and check your configuration settings. Common causes include security credentials (see the instructions on changing the useAppserverSecurity value in Setting up the environment) and a lack of data source mapping (see the instructions on adding a data source reference to lcds.xml in Setting up the environment).

13. To create a new FML file, switch to the Data/Services view and click the Edit Active Data Model button in the upper right (see Figure 7).

14. When the model editor opens, note that it supports Design view and Code view like other Flash Builder 4 editors.

    Note: The modeler plug-in stores data for the Design View layout in the FML file.

15. Drag the PUBLIC.PRODUCT table from the RDS Dataview panel to the Design view area of the FML file (see Figure 8).

16. To deploy the active model to the server, click the Deploy Model to LCDS Server button (see Figure 9).

    Note: You can use this same procedure to redeploy your model to the server if you later make changes to the model.

17. In the Deploy Data Model dialog box, type FiberTest (or use whatever name you gave your project), select Overwrite Existing Model, and Create/Recreate (see Figure 10). Click Finish.

18. Open FiberTest.mxml in Design view and drag a DataGrid component onto the Design area.
19. Click the Data/Services panel. If it is not visible, choose Window > Data/Services.
20. In the Data/Services panel, expand ProductService and then drag the getAll() method onto the DataGrid component in Design view (see Figure 11).

    For each model deployed on the server, LiveCycle Data Services and Flash Builder 4 will generate methods that you can use to perform basic operations on the table represented by the model. The basic operations enable you to get all records (getAll), create a record (createProduct), update a record (updateProduct), and delete a record (deleteProduct). Apart from these methods, there are methods that you can use to filter records based on a value in a column of the table; in this case they are getByProductname and getByPrice, for example. You can also add custom methods to perform your own queries, but that is outside the scope of this article.

The DataGrid column headers will change to reflect the data returned by the call to the service. A link icon appears, indicating that the data is bound to the component.

21. Choose Run > Run FiberTest to run your project.

It should fetch data from the server and display it in the DataGrid component (see Figure 12).

Adding create, read, update, and delete operations

Of course, as a developer, you want more than just a simple display application. You're ready to add a form to enable CRUD capabilities.

1. Right-click (Windows) or Control-Click (Mac OS X) the getAll() method in the Data/Services tab and select Generate Form.
2. In the Choose Form Type dialog box, click Model Driven Form and click OK (see Figure 13).

3. After the form is generated, move it below the DataGrid component in Design view.
4. Save your project and run the application again.
5. Within the application, click Add and type some sample input in the Description, Price, and Productname fields (see Figure 14).
6. Click Save to update the database.

   If you want, you can quit the application and rerun it to verify that the product you just added really was stored in the database.

   Note: If you enter a non-integer price, you will notice that the price read back from the database is not exactly the same as what you entered. For example, I added a product priced at 7.3, and the price stored in the database was 7.300000190734. To understand why, examine the Price field in the RDS Dataview panel; it is defined as a FLOAT17, whereas in the actual form the price is defined as a Number. When you specify a price, save it to the database, and reload it, you are loading the FLOAT17 version of the data. This problem can be remedied fairly easily, but enumerating the steps is beyond the scope of this article.

Now that you know you can create a new record, you can make a few more changes to enable update and delete functionality as well.

7. Open FiberTest.xml in Source view and locate the following line (it should be near line 31):

8. Edit the line so it reads as follows (your x and y values may differ from those shown):

This change will enable you to delete records and to make changes in the form and have them reflected in the data grid. The change is necessary because you generated the form from the data model, not from the data grid itself. As a result, the form was not automatically bound to the selected item of the data grid.

9. Switch to Design view and select the data grid.
10. In the Properties panel, set the DataGrid component's editable property to true.

    This will enable you to edit data directly in the data grid, without using the form.

11. Save your project and run the application again.

Now when you select an item from the data grid, it will appear for editing in the form. Alternatively, you can edit data directly in the data grid. Any changes you make will be committed to the database when you click Save. Also, when an item is selected you can click Delete to remove it from the database.

Where to go from here

That's it. You've built your first model-driven Flex application and added basic CRUD functionality with a bare minimum of coding.

For additional reading, see Model-driven Applications in Using LiveCycle Data Services. To access the LiveCycle Data Services ES Test Drive, use your browser to open

http://localhost:8400/lcds-samples/testdrive.htm.

Have fun unlocking the power of LiveCycle Data Services ES2 and Flash Builder 4.