Setting up model-driven development with LiveCycle Data Services

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.5 and Flash Builder 4.

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.

Requirements

In order to make the most of this article, you need the following software and files:

• Flash Builder 4 plugin for Ecipse 3.5
• Eclipse 3.5 for Java Developers
• LiveCycle Data Services 3.1
• The Adobe Application Modeling plug-in

Here are the steps you need to get started developing in Flash Builder 4 using the modeler plug-in.

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

2.    Follow the instructions to install Eclipse 3.5 and then install the Flash Player 4 plug in as documented within both those software packages

3.    After you unpack the ZIP file, copy all the files from its plugins folder into your <Eclipse_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):

<!-- begin rds
    <servlet>
        <servlet-name>RDSDispatchServlet</servlet-name>
      <display-name>RDSDispatchServlet</display-name>
        <servlet-class>flex.rds.server.servlet.FrontEndServlet</servlet-class>
      <init-param>
         <param-name>useAppserverSecurity</param-name>
         <param-value>true</param-value>
      </init-param>        
        <load-on-startup>10</load-on-startup>
    </servlet>

    <servlet-mapping id="RDS_DISPATCH_MAPPING">
        <servlet-name>RDSDispatchServlet</servlet-name>
        <url-pattern>/CFIDE/main/ide.cfm</url-pattern>
    </servlet-mapping>    
end rds -->

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:

<!-- begin rds -->
    <servlet>
        <servlet-name>RDSDispatchServlet</servlet-name>
      <display-name>RDSDispatchServlet</display-name>
        <servlet-class>flex.rds.server.servlet.FrontEndServlet</servlet-class>
      <init-param>
         <param-name>useAppserverSecurity</param-name>
         <param-value>false</param-value>
      </init-param>        
        <load-on-startup>10</load-on-startup>
    </servlet>

    <servlet-mapping id="RDS_DISPATCH_MAPPING">
        <servlet-name>RDSDispatchServlet</servlet-name>
        <url-pattern>/CFIDE/main/ide.cfm</url-pattern>
    </servlet-mapping>    
<!-- end rds -->

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


Figure 1. Startup information showing the port that the database is using

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:

<Context privileged="true" antiResourceLocking="false" antiJARLocking="false" reloadable="true">
   <!-- JOTM -->
   <Transaction factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/>
    
   <Resource name="jdbc/ordersDB" type="javax.sql.DataSource" 
        driverClassName="org.hsqldb.jdbcDriver" 
        maxIdle="2" maxWait="5000" 
        url="jdbc:hsqldb:hsql://localhost:9002/ordersdb" 
username="sa" password="" maxActive="4"/>
</Context>

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.

Building a 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.



Figure 2. Creating the new project


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.



Figure 3. Configuring the server

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



Figure 4. Configuring RDS

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



Figure 5. Opening the RDS Dataview view

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 the previous section: 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).



Figure 7. The Edit Active Data Model button

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



Figure 8. The PUBLIC.PRODUCT table in Design view

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.



Figure 9. The Deploy Model to LCDS Server button

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.



Figure 10. Deploying the data model to LiveCycle Data Services ES2

18.    Open

19.    FiberTest.mxml in Design view and drag a DataGrid component onto the Design area.

20.    Click the Data/Services panel. If it is not visible,  choose Window > Data/Services.

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


Figure 11. Binding the getAll() method to the DataGrid component

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.

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



Figure 12. Live data in the DataGrid component

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



Figure 13. Choosing a model driven form

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.



Figure 14. Adding a new product

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 33):
<forms:ProductForm id="ProductForm1" valueObject="{Product}" x="159" y="233">

8.    Edit the line so it reads as follows (your x and y values may differ from those shown):
<forms:ProductForm id="ProductForm1" valueObject="{dataGrid.selectedItem as Product}" x="159" y="233">

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.

About the authors

Duane Nickull is a Sr. Technical Evangelist with Adobe Systems and regularly writes articles for architects and developers.  His blog can be found at http://technoracle.blogspot.com and is ranked in the top 100 at the time of this article for Technorati’s Information and Technology category and regularly contributes to DZone.

Sujit Reddy G is a Technical Evangelist for Flex at Adobe. Combining expertise in Flex, J2EE, and PHP, he specializes in building enterprise applications on the Adobe Flash Platform and has a blog focusing on the integration of Adobe Flex with Adobe LiveCycle Data Services ES and BlazeDS at http://sujitreddyg.wordpress.com.