Offline Synchronization using AIR and LiveCycle Data Services

As part of my MAX talks in Chicago and Barcelona, I used a simple Contact Manager application to demonstrate offline synchonization using AIR and LiveCycle Data Services (LCDS). Many people have asked me to share the code, so here it is… This is actually an update of an application I posted a few months ago (but that didn’t include the offline synchronization part at the time).

Using the Data Services to work with data in AIR offers several benefits:

First, just like for traditional browser-based Flex apps, the Data Management Service automates the synchronization of data between the client and the middle-tier. In other words, you don’t have to flag/keep track of the changes made at the client-side, and then make corresponding RPC calls to send changes to the server: this is all managed automatically.

Second, you can access and enter data while offline: the Data Management Service takes care of storing your data locally and synchronizing the changes with the server when you go back online. To enable offline synchronization, the Data Management Service API provides methods (such as saveCache() / clearCache()) to save data locally and manipulate the local data store. When you go back online, the commitRequired attribute of your dataService indicates if changes have been made offline. Invoking commit() on the dataService automatically synchronizes the offline changes with the server. See main.mxml for an example.

In the current AIR betas, the Flex Data Management Service uses Local Shared Objects as the local data store. For the AIR 1.0 release, we will use the SQLite database embedded in the AIR runtime instead.

In this application, I use the SQL assembler to provide the server-side persistence logic. Using the SQL assembler, you don’t have to write server-side components if you don’t want/need to: you just provide a series of SQL statements indicating how data should be retrieved, and how changes should be persisted in the database. The SQL assembler makes it extremely fast and easy to create applications that don’t require sophisticated persistence logic.

Installation instructions:

1. Install LiveCycle Data Services 2.5 here
2. In the samples web application, modify the flexdemodb database file to add the contact table: replace WEB-INF\db\flexdemodb\flexdemodb.script with this version.
3. Open WEB-INF\flex\data-management-config.xml and add the following destination.

   <destination id="sql-contact">
   
   	<adapter ref="java-dao" />
   
   	<properties>
   
   		<use-transactions>true</use-transactions>
   		<source>flex.data.assemblers.SQLAssembler</source>
   		<scope>application</scope>
   		<metadata>
   			<identity property="CONTACT_ID"/>
   		</metadata>
   
   		<network>
   			<session-timeout>20</session-timeout>
   			<paging enabled="false" pageSize="10" />
   			<throttle-inbound policy="ERROR" max-frequency="500"/>
   			<throttle-outbound policy="REPLACE" max-frequency="500"/>
   		</network>
   
   		<server>
   
   			<database>
   			    <driver-class>org.hsqldb.jdbcDriver</driver-class>
   			    <!-- Modify the URL below with the actual location of the flexdemodb database on your system -->
   			    <url>jdbc:hsqldb:file:C:/lcds/jrun4/servers/default/samples/WEB-INF/db/flexdemodb/flexdemodb</url>
   			    <username>sa</username>
   			    <password></password>
   				<login-timeout>15</login-timeout>
   			</database>
   
   			<actionscript-class>Contact</actionscript-class>
   
    			<fill>
      				<name>all</name>
      				<sql>SELECT * FROM CONTACT</sql>
    			</fill>
   
   			<get-item>
   				<sql>SELECT * FROM CONTACT WHERE CONTACT_ID = #CONTACT_ID#</sql>
   			</get-item>
   
    			<create-item>
   			  <sql>INSERT INTO CONTACT
   			  		(FIRST_NAME,LAST_NAME,EMAIL,PHONE,ADDRESS,CITY,STATE,ZIP,COUNTRY,NOTES)
   			  		VALUES (#FIRST_NAME#, #LAST_NAME#, #EMAIL#, #PHONE#, #ADDRESS#, #CITY#, #STATE#, #ZIP#, #COUNTRY#, #NOTES#)</sql>
   			  <id-query>CALL IDENTITY()</id-query> <!-- HSQLDB syntax to retrieve value of autoincremented column -->
   			</create-item>
   
    			<update-item>
   			  <sql>UPDATE CONTACT SET FIRST_NAME=#FIRST_NAME#,LAST_NAME=#LAST_NAME#,EMAIL=#EMAIL#,PHONE=#PHONE#,ADDRESS=#ADDRESS#,CITY=#CITY#,STATE=#STATE#,ZIP=#ZIP#,COUNTRY=#COUNTRY#,NOTES=#NOTES#
   			  		WHERE CONTACT_ID=#_PREV.CONTACT_ID#</sql>
   			</update-item>
   
    			<delete-item>
   			  <sql>DELETE FROM CONTACT WHERE CONTACT_ID=#CONTACT_ID#</sql>
   			</delete-item>
   
   			<count>
   				<name>all</name>
   				<sql>SELECT count(*) FROM CONTACT</sql>
   			</count>
   
   		</server>
   
   	</properties>
   
   </destination>
   

4. Start the server
5. Install contacts.air and run the application

NOTE: The application has been compiled assuming that an RTMP endpoint named my-rtmp is configured at rtmp://localhost:2037. If your server isn’t configured that way, you will have to recompile the application. You can also provide the endpoints at runtime. See my previous post for more information on defining a ChannelSet.

You can download the source code here.

Application Walkthrough

1. Start the application. Notice the green light in the upper right corner indicating that the dataService is connected to the server.
2. Double-click a contact in the list to open the details form. Modify some data and click “Save”.
3. Shut down your server. Notice that the connectivity status light is now red. Close the application to make it clear that your are not working with data cached in memory.
4. Restart the application. It will take a second before you see the data: the dataService first tries to connect to the server before loading the data from the local cache. Open a contact, make some changes to the data and click “Save”. Your change is saved to the local cache.
5. Close the application.
6. Restart your server.
7. Restart the application. Notice that the application automatically detects that changes have been made offline, and synchronizes the offline changes.