LCDS 2.6 allows you to build AIR applications with automatic offline data synchronization. This feature leverages the SQLite relational database system embedded in the AIR runtime, but the advantage is that the data synchronization process is entirely automatic: you don’t have to write SQL statements or synchronization logic to keep your local database in sync with your central database.

I have been getting a number of questions related to this feature, so I decided to build a sample application that demonstrates how it works.

In this application the synchronization process is implicit. When you are online, the cache (a SQLite database) is automatically updated along with the server database to make sure the user can go offline with the latest data without explicitly triggering a synchronization process. When you are offline, the changes are saved in the local cache. If the network becomes available while working in the application, the application will detect the network status change and automatically synchronize data (send your offline changes to the server, and get changes made by other users while you were offline).

Installation Instructions

1. If you haven’t already done so, install LCDS 2.6.
2. Unzip insync.zip
3. Copy the content of the sampledb folder in the sampledb folder of your existing LCDS directory
4. Copy the content of the tomcat folder in the tomcat folder of your existing LCDS directory
5. Add the following destination to data-management-config.xml

   <destination id="insync">
       <adapter ref="java-dao" />
       <properties>
           <source>lcds.samples.contact.ContactAssembler</source>
           <scope>application</scope>
           <metadata>
               <identity property="contactId" undefined-value="0"/>
           </metadata>
       </properties>
   </destination>
   

6. Restart the sample database: run sampledb.bat (Windows) or sampledb.sh (Unix) in the sampledb directory
7. Restart your application server

Quick Tour

1. Install and run the AIR application. Notice the green light in the status bar indicating that the application is in online mode.
   Please upgrade your Flash Player This is the content that would be shown if the user does not have Flash Player 9.0.115 or higher installed.

2. Double click a contact to view the contact details.
3. Modify the data in a few fields and click Save. Your server console indicates that the contact has been updated.
4. Click the + button in the application title bar. Enter a first name, last name, etc and click Save. Your server console indicates that the contact has been updated.
5. Shut down the server
6. Notice that the green light turns grey to indicate that the application is now working in offline mode.
7. Repeat steps 2 to 4 above: changes are saved locally. Notice that the offline status (not modified, created, or updated is displayed in the contact form (bottom left corner)
8. Restart the server.
9. The green light appears in that status bar as soon as the server is up and running. Notice that LCDS automatically detects the offline changes and sends them to the server.

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.

Here is an updated/rewritten version of my AIR SQLite Admin application. You can use this application to examine the structure of a database, create a new database or open an existing one, execute any type of SQL statement, etc.

An interesting aspect of this new version is that the application itself uses a database (sqladmincache.db) to keep track of the databases you opened and the statements you executed. This is useful if you want to quickly re-open a recently accessed database, or re-execute a recently executed statement.

This new version uses synchronous database operations (AIR beta 1 only supported asynchronous database access), and uses the schema API (also new in beta 2) to show you the list of tables and columns available in your database.

The UI is still simple, but uses some new AIR and Flex 3 features such as the AdvancedDataGrid and Native Windows.

Click here to install the application.

Click here to download the source code.

Click here to install the application.

Click here to download the source code.

Follow this script for a guide tour of the application.