Creating a Simple Parcel Tracking application with Model Driven Development using LiveCycle Data Services (LCDS) and Flash Builder 4

October 19, 2009 at 8:01 pm | Posted in Data Centric Development(DCD), Flash Builder 4, Google Maps Flash API, LiveCycle Data Service(LCDS), Model Driven Development | 9 Comments

I have been very amazed by the data management capabilities of LCDS and have been tinkering around with it for a while now.  I shall now demonstrate how to create a simple parcel tracking application using model driven development.  Assume there is a parcel office and also assume there is a home that the parcel is to be delivered to. The customer will be able to enter the parcel number and find out where in the city the parcel is. Of course, in reality a GPS system would be needed to update the location of the package in the database. However for the purpose of the demo, ill update it using another flex application.  They say an image is worth a thousand words. Also, a video is actually a thousand or more images. So doing the math we conclude that I should show you a video of how the tracking application will look like rather than describing it here. Click here to view the video.  So now that we know what our end product is, let’s start making our application.

Installing LCDS and Flash Builder

Download and install the latest Beta Release of Flash Builder 4 from http://labs.adobe.com/technologies/flashbuilder4/ .

Download LiveCycle Data Services 3 from

http://labs.adobe.com/technologies/livecycle_dataservices3/. Install the executable (livecycle_dataservices3_b3_win_100509.exe) using the option “with tomcat” to C:/lcds3

Download Fiber modeler plugin from

http://labs.adobe.com/technologies/livecycle_dataservices3/. Extract the contents of the zip file (livecycle_dataservices3_modelerplugin_100509.zip) and copy the files under livecycle_dataservices3_modelerplugin_100509/plugins folder into C:\Program Files\Adobe\Adobe Flash Builder Beta 2\plugins.

The required software is now installed.

Google Maps Flash API

I have used the Google Maps flash API for working with maps. Go to

http://code.google.com/apis/maps/documentation/flash/

Sign up for an API key and download the SDK. You will need to put in the API key in your flex code. So store that safely. We will deal with how to make use of the library in the application in a later part of the post. You will be downloading a file called sdk.zip. Copy it to your desktop and extract to a folder called sdk.

Existing Database in MySQL

The database created using a simple MySQL command line client and is called Courier (Click here for .sql file). It comprises of 4 tables.

1.Centre – This is a list of all end points. They can be parcel offices or destinations of parcels. The schema is

2.Location – This is a list of all intermediary points where the delivery man can be. In a real time case a relay from the GPS system should be sent to update this table. Just a number is enough as primary ID. You may argue that there is no need for two tables(Centre and Location) here. However, in a real time case, this table will be constantly updated with GPS coordinates whereas the Centre table is more or less static and has a fixed set of values.

3.Delivery Man- This is a simple table mapping a delivery man to his current location.

4.PackageBox- This is the list of all packages.  The schema is shown below.

The important points to note here are the foreign key references. I’ve enlisted them here
1.Between the source attribute of the PackageBox table and the Centre Table.
2.Between the destination attribute of the PackageBox table and the Centre Table.
3.Between the deliveryman attribute of the PackageBox table and the DeliveryManTable.
4.Between the location attribute of the DeliveryMan table and the Location Table.

The Attributes have been named in such a way
{Attribute name}_{Primary key of the table it is referenced to}
So now that we have an idea of what the database is, let us see how to connect it to expose this database to the LCDS serve as data sources.

Configuring LCDS to the existing database

The fibre modeler plugin of Flash Builder uses the data sources configured on the web server to retrieve data from the tables of the database. Hence to make this data source, we must edit the configuration file of the web application. By default, there is a web application called lcds located at
C:\lcds\tomcat\webapps\lcds

We shall use this to create our datasources. Since the name is lcds there is a file called lcds.xml  in
C:\lcds\tomcat\conf\Catalina\localhost\

Make the following changes to the file
<Context privileged=”true” antiResourceLocking=”false” antiJARLocking=”false” reloadable=”true”>
<Transaction factory=”org.objectweb.jotm.UserTransactionFactory” jotm.timeout=”60″/>
<Resource name=”jdbc/courier” auth=”Container”
type=”javax.sql.DataSource”
username=”{your username}”
password=”{your password}”
driverClassName=”com.mysql.jdbc.Driver”
url=”jdbc:mysql://localhost:3306/courier?autoReconnect=true”/>
</Context>

Also, make sure that the MySQL Connector/J file is present in the tomcat’s lib folder.
Next, we must enable the RDSDispatchServlet which is present on the LCDS server and is used by Flash Builder+ Fibre Modeler Plugin to read the data sources. Go to
C:\lcds\tomcat\webapps\lcds\WEB-INF\web.xml

Uncomment the following section of the file
<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>

The important point here is the parameter useAppServerSecurity is by default true. Set it to false. That is the entire configuration that is required.  The next step is starting the server.

Starting the LCDS Server

Either

1. Go to Start->All Programs ->Adobe-> LiveCycle Data Services
2. Click on Start Samples Database
3. Click on Start LiveCycle Data Services Server.

Or

Execute these scripts in succession

1. C:\lcds\sampledb\startdb.bat
2. C:\lcds\tomcat\bin\startup.bat

The above are the two ways to start the server.

Start of application building

We shall go through this step by step
1.Open Flex Builder go to File->New Flex Project and give your project an appropriate name. I’ve named mine ParcelApplication. Under Server Technology choose
a.Application server type: J2EE
b.Check on Use remote object access service.
c.Select  LiveCycle Data services ES.

Leave the rest as default. Click Next.

2.Validate Configuration Screen: In this screen by the default path will be chosen. So unless there was a non standard installation no input needs to be given in this screen. Click on Validate Configuration and see if the the message “The web root folder and root URL are valid” appears on top. If it does, click Next. Else, there is something wrong with one of the paths. Check up for file path mistakes.

3.In the next menu, we shall include the libraries for the Google Maps Flash API. Click on the Add SWC button that has been highlighted in the picture below.

In the add SWC menu, click on browse. In the file browser window that will appear, find the map_flex_{version number}.swc file which will be under
Desktop\sdk\lib\   (if the sdk.zip folder was extracted to desktop)

Click Open on the File browser Menu. Click Ok on the Add SWC menu. Click Finish on build path menu.

4. Now that the project workspace, we can work on the RDS configuration. Click On Window (Alt+W) -> Preferences. On the list on the left of the Under Adobe, You will find RDS configuration window which looks like the image below.  Enter the configuration details as shown in the image and click on test connection (which has been highlighted in the image). If the connection is not established, then there must be an error in the path or the server must have stopped running.

5.We are now ready to create our Model

Creating a Model

We shall now look at how to use the fiber modeler plugin to make a model in Flash Builder.
1.Go to Window (Alt+W) -> Perspective -> and click on Data Model. The following image(click for larger image) shows what the data model looks like.  Click on the view Open Data Model for Active Project button (highlighted below) and you will now have the design view of the Model. You will notice that a file called ParcelApplication.fml has been created.  This is called the model file.

2.As highlighted in the image below(click for larger image), the RDS Data View menu lets you see all the databases that are available as datasources.

3.We will need all the tables. So just drag and drop the tables into the design view of ParcelApplication.fml.  You will be able to view the entities in the design view of the data model as shown in the image below(click to view larger image). You will also notice in the package explorer that a new package has been created with same name as the application which contains the classes generated by LCDS fiber modeler plugin for Flash Builder 4.

4.Click on the Deploy Model to LCDS Server button which is highlighted in the image above. And you get the menu shown below. Select the Create/Recreate option marked in red in the image. If you were doing this for a second time (say after including another table), then you need to use the Overwrite existing model option.

You can go to the tomcat command line output window and you will see the following lines displayed

This means that the model has been successfully deployed. Notice how it states that Fiber Assembler for all the four tables have been created.

5.Now switch back to Flash perspective. The image below(click for larger image) has a highlighted red box with a red circle inside it. The click the button in the circle and the menu that you see in the box drops down. Click on flash and the perspective changes. Select the ParcelApplication.mxml file.

6.If you select the data/services tab highlighted in the first image below(click to view larger image) and maximize it by double clicking on the tab, you will see that all the possible CRUD services have automatically been created. The list is also shown in the second image below(click to view larger image).

7.Now, I have posted a link to the code for logic involved in the application.

1. ParcelApplication.mxml – This is the source of the main application

2.ParcelApplication.fml – This is the model file’s source
It is fairly simple to understand and has been heavily commented for proper understanding. Please do feel free to comment and ask if you have any doubts.  This is all that needs to be done for parcel tracking application.

Creating the application to update the location of the parcel
Follow the same steps 1 and 2 of “Start of application building” as you did with the tracking application. Here, I have named the application ParcelLocationUpdater. We do not need to import any special libraries here. So we can click Finish at the Configure J2EE server page. Then follow these steps

1.Select Data(Alt+t)  -> Connect to LCDS and you will get the following screen. Select ParcelApplication.DeliveryMan, which is the same Data Source that was used in the previous application and click Finish. Remember that only if the same data source that was used in the earlier application is used in this application, the Automatic Sync functionality of LCDS can be used. What is the automatic Syn feature. According to this, if there are two flex applications which use the same data source. Then if one of them has a Bindable data type(like arraycollection or Datagrid) bound to a service call, a change or update made by the other application will automatically be reflected in the bindable arraycollection or DataGrid.

2.If you now look at the Data/Services tab, you will see that the services have been imported. Similarly, import ParcelApplication.Location.

3.Switch to design view and from the components menu select Datagrid (look at the image below). Drag and drop it twice to the design view.  Look at the second image below to see if the result is the same.

4. I have named the first DataGrid locationDataGrid and the second one deliveryManDataGrid. Drag and drop the getAll() service under Location Services to locationDataGrid. See image below.

5.Repeat the process for the getAll() service of DeliveryMan Object as well.

6.If you look at the deliveryManDataGrid, it does not let you see the entire details of the location corresponding to the deliveryman. Let us generate a details form for this so that we can see what the exact data is. Right click on the dataGrid for location and click generate details form as shown below.

7.You will then be asked what type of form to choose. Choose Flex form which will enable the DCD form. Click OK

8.In the following form, Master details have automatically been selected. The other options are to bind the form to a service call (input and output) as well as to bind the call to a data type. However for our example, we need only to select the Master details. Click Next.

9.In this menu, you can include what properties are shown. Since we want to see all the details of the location corresponding to the delivery man object that is selected in the data grid, click all details as shown in the image below.

10.You will see the generated form as shown below

11.We shall now run the program and take a look at what we get. If you click on any one of the entries in the deliveryManDataGrid, you can view the corresponding values in the details form.

12.Now what we will do is add a button to replace the value of the location attribute corresponding to the item selected in the deliveryManDataGrid with the selected item in the locationDataGrid. Drag and Drop a button from the components menu and right click to choose generate service call.(click to view larger image)

13.In the next menu that appears choose, the service call to be generated and Click OK.

14.The following is the Code that is generated.
protected function button_clickHandler(event:MouseEvent):void
{
updateDeliverymanResult.token = deliverymanService.updateDeliveryman(/*enter the value for*/deliveryman);
}
15.We shall now take a look at what needs to be added to the code to perform the updation.

protected function button_clickHandler(event:MouseEvent):void
{
var deliveryman:Deliveryman=deliverManDataGrid.selectedItem as Deliveryman;
deliveryman.locationLocationid=locationDataGrid.selectedItem as Location;
updateDeliverymanResult.token = deliverymanService.updateDeliveryman(deliveryman);
}

As you can see, what the code essentially does is assigns the value of the location object selected in the Location datagrid to the location attribute of the selected DeliveryMan Object in the other datagrid and calls the service to update that Delivery man object.
16.    Presto!! The application for updating the location of the delivery man ready now. I have changed the text in the button to UPDATE for it be more in context.   Here are screen shots of it working.

Running both applications

Please play the video whose link is given in the introduction section to see how to run the two applications together. Hence, we have created two applications.
1.An application that accesses a database for a courier company and displays the location of a package on a map given the package number as input.
2.An application that updates the location of the package in the database. Hence, in a real time situation, this application can be called by a system which is hooked to the GPS coordinates of the delivery truck and hence update the location of the delivery truck in the data base.
We have demonstrated how to create a model from a MySQL database and also shown how useful the automatic data source sync feature of LCDS is. Please do post any comments if you experience any problems while trying out these features.