Creating a SQLConnection

In order to work with a local SQLite database, an application needs to establish a connection to it. The AIR runtime provides facilities for creating database connections that operate in either synchronous or asynchronous execution mode. After a connection to a database has been established in one of the two execution modes, all database operations on that connection will operate using that mode. It is impossible to mix the two execution modes on the same connection.

A synchronous connection operates like calling a method that performs some database operation and returns the result to the next line of code. An asynchronous connection uses user-specified functions that are called when the database operation completes and are either registered as event listeners or bundled in a Responder instance. Think of it like a function associated with the click operation on a Button that gets called when the user clicks the Button, but in this case the function gets called when the database operation finishes.

Based on the execution mode, one of the primary differences is the programming model used to interact with the API. As described above, a synchronous connection works like a call to a method while an asynchronous connection requires the use of functions that will be notified when the database operation completes. Before diving into a discussion about the other differences in execution modes, let's look at how to create a connection of each execution type, which will give a feel for the two programming models.

The following examples create an in-memory database. Examples of creating and connecting to a database on the file system are in the sample application described later and in the SQLConnection documentation.

To open a synchronous connection, use the open() method on an instance of the SQLConnection class.

var sqlConnection:SQLConnection = new SQLConnection();
// This will create a new in-memory database and a synchronous connection.
sqlConnection.open(null, SQLMode.CREATE);
// The connection has been established and sqlConnection can be used for other database operations at this point.

To open an asynchronous connection, you must use either event listeners or Responders to receive the notification that the connection has been established. Each database operation specifies an event type that it will dispatch when it completes. In the case of the openAsync() method, used to create an asynchronous mode connection, an event type of SQLEvent.OPEN is dispatched. The API documentation lists the event types that are dispatched for other database operations. The following example uses an event listener to handle the dispatched event:

var sqlConnection:SQLConnection = new SQLConnection();
// The handleConnectionOpen function will be called when the connection has been established.
sqlConnection.addEventListener(SQLEvent.OPEN, handleConnectionOpen);
// This will create a new in-memory database and an asynchronous connection.
sqlConnection.openAsync(null, SQLMode.CREATE);
// The connection is not established and sqlConnection can not be used for other database operations at this point.

Instead of adding an event listener to receive the event, you can specify a Responder instance. The Responder constructor takes two parameters: the function to call if the method succeeds and the function to call if the method fails. The error case is explored in the next section. For now I'll only specify the function to call if the openAsync() method succeeds:

var sqlConnection:SQLConnection = new SQLConnection();
// This will create a new in-memory database and an asynchronous connection.
// The handleConnectionOpen function will be called when the connection has been established.
sqlConnection.openAsync(null, SQLMode.CREATE, new Responder(handleConnectionOpen));
// The connection is not established and sqlConnection cannot be used for other database operations at this point.

For both the event listener and the Responder, the function specified must declare that it takes a single parameter of type SQLEvent. The definition of the handleConnectionOpen() function used above would have the following form:

function handleConnectionOpen(sqlEvent:SQLEvent) {
    // Handle connection having been established.
}

When opening an asynchronous connection, if both an event listener and a Responder are specified, the Responder will take precedence and be called instead of the registered event listener.

Page 2 of 8

Previous Page

Next Page