Managing the local database

You use a Session object to manage the data in the local SQLite database. You call the syncmanager.openSession method to create a session with a specific database file. The method returns a SessionToken token, and the SessionToken.session property provides access to the session. You use code in the token's openSessionSuccess responder event handler to provide access to the session object. This way, you do not access the session, and therefore the database, until it is successfully opened.

The following code expands on the session initialization code that was shown above. and shows an openSessionSuccess event handler that uses the session to save the contents of the remote database in the local image. In this example, users is the array collection fetched from server:

var dbFile:File = File.userDirectory.resolvePath("basic.db"); 
var token:SessionToken = syncmanager.openSession(dbFile, 113); 
token.addResponder(new mx.rpc.Responder(openSessionSuccess, openSessionFault)); 
function openSessionSuccess(event:SessionResultEvent):void 
{ 
        //Initialize a variable for access to the session. 
        var session:Session = event.sessionToken.session; 
        //Save the remote database data in the local database. 
        //users is the array collection fetched from server 
        var saveToken:SessionToken = session.saveCache(users); 
        //Add responder event handlers for successful and failed saves. 
        saveToken.addResponder(new mx.rpc.Responder(saveSuccess, saveFault)); 
}

Once you have access to the session, you can get (load) data from the SQLite database, and insert, delete, and update data database by calling the session objects methods. For details on the session object methods see ASDoc documentation.

Notes:

  • The SQLite database doesn't validate column types when it creates a table. If you give it an invalid value for column data type, it creates the column with that type.

  • When you pass a unique integer ID parameter (one that is not used in the application) to the OpenSession method, the method creates an intermediate database file, which tracks the client changes to be committed on the server. If you use more than one database in a single application, use a unique ID for each database. Using a single ID ensures that you use the correct database for each client-side transaction.

  • For asynchronous calls (such as SaveCache) that save fetched data in the local database, the call result can be available by using the session token when the call returns, before the responders are added. This situation occurs if the SaveCache operation tries to save null data. That is, if the fetch operation returned null data. In such cases, a responder is not required.

    There are two ways to handle this situation:

    1. Check whether the result property of the session token returned by the function is null:

      if (token.result == null) { 
        Add the responder here 
} 
else { 
        Directly use the token.result 
    }

    2. Check that the ArrayCollection that is input to the SaveCache function is not null. The null response indicates that the fetch operation did not get a result from the server:

      If (ArrayCollection != null) { 
        Call SaveCache() function 
        Add Responder to the SaveCache Token 
    } 
    else { 
        Handle the condition here. 
    }

  • If you call the SaveUpdate Method and a record with the specified primary key doesn't exist, the function inserts the record. The method updates an existing record only if the primary key exists in the client database.

  • After you fetch data from the server, use only the SaveCache and SaveCacheUpdate methods to save the fetched data into client side database. If you use the Save function to store the fetched data, the data is marked for insert on server on commit, and the data you just got is written back to the server. In this case, a conflict occurs for the server database primary key. If the server-side logic handles this conflict by ignoring the primary key ID from the client, and lets the server generate a new ID, then the records are inserted, resulting in multiple copies of the data with different IDs.