To obtain view schema information for a database, use the
Generally, developer code does not construct SQLViewSchema instances directly.
To obtain column schema information for one or more tables in a database, use the
Generally, developer code does not construct SQLColumnSchema instances directly.
If the result set contains multiple columns with the same name, only one property with that
name is added to the result object. The value assigned to that property is taken from the last
column with that name in the result row. For example, consider the following
SELECT customers.customerId, addresses.customerId FROM customers INNER JOIN addresses ON customers.customerId = addresses.customerId
When this statement is executed on a SQLConnection instance with short column name format,
each result object has a property named
To obtain schema information for a database, use the
Generally, developer code does not construct SQLSchema instances directly.
For example, if a database index is created using the following SQL statement, the value of the
For example, if a database index is created using the following SQL:
the
These values represent different collation sequences that can be specified for a column in a database table. A collation sequence is a way of sorting and comparing data, for example whether the database differentiates between uppercase and lowercase characters.
For more information about defining and using collation sequences, see the
"COLLATE" section in the appendix
"
When binary collation is used with values of the
To retrieve the SQLSchemaResult instance for a
The functionality of the SQLConnection class falls into several categories:
A local SQL database file is created or opened by calling the
The SQLConnection class also provides state for SQL statements, including a
mechanism for executing multiple statements in a transaction. Transactions are managed using the
The SQLConnection class provides access to database schema information for connected
databases. A database's schema describes the definitions of its tables, columns, indices, and triggers.
See the
The SQLConnection class provides the ability to encrypt databases using AES with CCM. This provides
both authentication and privacy for data. To encrypt a database, a 16 byte key (specified using a
ByteArray) must be specified when the database is created. This key can later be changed
using the
A SQLConnection instance can be used to receive database-level event notifications and provide configuration control for all aspects of a database, including cache page size, process canceling, and statement execution options.
A
When you're using asynchronous execution, you use event listeners or a Responder instance to determine when an operation completes or fails. The operations run in the background rather than in the main application thread, so the application continues to run and respond to user interaction even while the database operations are being performed. Each asynchronous SQLConnection instance executes SQL statements in its own thread.
In asynchronous execution mode, you begin a specific operation
by calling the appropriate method, and you can detect the completion (or failure) of the operation
by registering a listener for the appropriate event. Each operation has an associated event that
is dispatched when the operation completes successfully; for example, when an
When you're using synchronous execution, you do not need to register event
listeners to determine when an operation completes or fails. To identify errors,
enclose the error-throwing statements in a
The function can have any name.
Class-level member functions are not subject to garbage
collection, so you can set
After you successfully register an event listener, you cannot change its priority
through additional calls to
Keep in mind that after the listener is registered, subsequent calls to
You cannot register an event listener for only the target phase or the bubbling phase. Those phases are coupled during registration because bubbling applies only to the ancestors of the target node.
If you no longer need an event listener, remove it by calling
Copying an EventDispatcher instance does not copy the event listeners attached to it. (If your newly created node needs an event listener, you must attach the listener after creating the node.) However, if you move an EventDispatcher instance, the event listeners attached to it move along with it.
If the event listener is being registered on a node while an event is being processed on this node, the event listener is not triggered during the current phase but can be triggered during a later phase in the event flow, such as the bubbling phase.
If an event listener is removed from a node while an event is being processed on the node, it is still triggered by the current actions. After it is removed, the event listener is never invoked again (unless registered again for future processing).
If a database has indices defined, but the
When a table's data changes (as a result of
The
Each time this method is called, any previously created statistical
data is purged and recreated for the database or table specified in the
To remove the statistical data created with the
If the parameter's value is
A valid encryption key is 16 bytes long. An in-memory database cannot be encrypted, so this
parameter must be
When attaching an encrypted database, if the encryption key provided doesn't match the
database's encryption key, an exception occurs. In synchronous execution mode, a SQLError
exception is thrown. In asynchronous execution mode, a SQLErrorEvent is dispatched, and the event
object's
The
If a database is already attached using the specified name, calling
Any SQL statement can be executed on a database connected using
To remove a database attached using the
The attached database uses the same execution mode (synchronous or asynchronous) as
the main database, depending on whether the main database was connected using the
The default value (
By default, each SQL statement
is executed within its own transaction, and the transaction ends when
the statement's execution succeeds or fails. Creating a transaction using the
To end a transaction, call the
Nested calls to
If the database connection closes while a transaction is currently open, AIR rolls back the transaction automatically. (Note: for AIR 1.1 and previous versions, an open transaction is automatically committed when a connection closes.)
A transaction is not limited to statement executions in a single database; it can include statements executed on different attached databases.
If there are statements executing when the
If there is an open
transaction when
Intermediate savepoints, which are like bookmarks in a transaction, can be created
by calling the
For a transaction that uses savepoints, any statements that were rolled back
using the
The
Because the statistics generated by the
This operation is not included in an active transaction.
When the database connection is closed the method returns
If the specified value is not valid an
If the
To access the loaded schema use the
In asynchronous execution mode, a
The combination of the
If the combination of
If the database is empty (it doesn't contain any tables, views, triggers,
or indices), calling the
This parameter is ignored when the
A valid encryption key is 16 bytes long. An in-memory database cannot be encrypted, so this
parameter must be
When opening an encrypted database, if the encryption key provided doesn't match the
database's encryption key, a SQLErrorEvent is dispatched. The event object's
The
Once a database is connected, use a
A database that is connected using the
This parameter is ignored when the
A valid encryption key is 16 bytes long. An in-memory database cannot be encrypted, so this
parameter must be
When opening an encrypted database, if the encryption key provided doesn't match the
database's encryption key, a SQLError exception is thrown. In that case the SQLError object's
The
Once a database is connected, use a
A database that is connected using the
The reencryption operation runs in its own transaction. If the reencryption process is interrupted, the database rolls back the transaction and the encryption key is not changed.
Note that until the entire transaction is committed, any changes are not
permanently saved to the database. If the transaction is started using the
If the code calls the
If this method is called with no parameters (or with
If a value is provided for the
Once a savepoint is released or rolled back, that savepoint and any more
recent savepoints are removed. If code executes additional SQL operations after
a
Note that if the entire transaction is committed by calling the
If this method is called with no parameters (or with
If a value is provided for the
Once a savepoint is released or rolled back, that savepoint and any more
recent savepoints are removed. If code executes additional SQL operations after
a
Intermediate savepoints can be marked within a transaction by calling the
If the name provided is a duplicate of a previous named savepoint, the next call
to either
The
When the
Note that until the entire transaction is committed, any changes are not
permanently saved to the database. If the transaction is started using the
You can specify a name for a savepoint by providing a value for the
Once a savepoint is released or rolled back, that savepoint and any more
recent savepoints are removed. If code executes additional SQL operations
after a
If the
The constants defined in the SQLColumnNameStyle class represent the possible values for this property:
The value is zero if no database is connected or no
The row identifier for a single SQL
For more information on primary keys and generated row identifiers,
see the "
If the
The page size for a database can be changed (using the
When the database connection is closed, the value is reset to 0. When the SQLConnection instance isn't connected to a database, the value is 0.
To obtain trigger schema information for a database, use the
Generally, developer code does not construct SQLTriggerSchema instances directly.
A SQLStatement instance is linked to a SQLConnection instance by setting the SQLConnection instance as the
value of the SQLStatement instance's
For a complete description of the SQL dialect supported in local SQL databases, see the appendix
In asynchronous execution mode, the
No events are dispatched in direct response to the completion of the
When the SQL statement is a
If the
To access the results of a statement, such as the result rows of a
Every statement must be prepared (compiled) before it can be executed. The first time
a SQLStatement instance's
When a
When a
Note that unless they are removed by calling
In asynchronous execution mode, if the
This method can only be called when the statement is still executing.
When the statement is a
This property is true if
By default, each row returned by a
By specifying a class for the
Any class assigned to this property must have a constructor
that does not require any parameters. In addition, the class must
have a single property for each column returned by the
Within the text of a SQL statement, a parameter is indicated with one of the following characters: "?", ":", or "@".
The ":" and "@" tokens indicate a named parameter; the characters following the token designate the name of the parameter.
For example, in the following SQL statement, a parameter named
SELECT FROM employees WHERE firstName = :firstName
The "?" token indicates an indexed (numbered) parameter; each parameter is automatically given an index according to the sequence of parameters in the statement text. Parameter index values are zero based. In other words, the first parameter's index is 0.
Parameters are used to allow for typed substitution of
values that are unknown at the time the SQL statement is constructed.
The use of parameters is the only way to guarantee the storage class for
a value passed in to the database. When parameters are not used, all values are
converted from their text representation to a storage class based on the
associated column's type affinity. For more information on storage classes and
column affinity, see the
"Data type support" section
in the appendix
"
Parameters are also used as a security measure to prevent a malicious technique known as a SQL injection attack. In a SQL injection attack, a user enters SQL code in a user-accessible location (for example, a data entry field). If application code constructs a SQL statement by directly concatenating user input into the SQL text, the user-entered SQL code is executed against the database. The following listing shows an example of concatenating user input into SQL text. Do not use this technique:
Using statement parameters instead of concatenating user-entered values into a statement's text prevents a SQL injection attack, because the parameter values are treated explicitly as substituted values, rather than becoming part of the literal statement text. The following is the recommended alternative to the previous listing:
All parameter values must be set before
the statement is executed. Parameter values specified in the
To clear all the parameter values from the
The text can be any supported SQL. For a complete description of the
SQL dialect supported in local SQL databases, see the appendix
"
AIR profile support: This feature is supported
on all desktop operating systems, but is not supported on mobile devices or AIR for TV devices. You can test
for support at run time using the
AIR provides an encrypted local store (ELS) for each AIR application installed on a user's computer. This lets you save and retrieve data that is stored on the user’s local hard drive in an encrypted format that cannot easily be deciphered by other users. A separate encrypted local store is used for each AIR application, and each AIR application uses a separate encrypted local store for each user account on the computer.
Use the encrypted local store to cache information that must be secured, such as login credentials for web services. The ELS is appropriate for storing information that must be kept private from other users. It does not, however, protect the data from other processes run under the same user account. It is thus not appropriate for protecting secret application data, such as DRM or encryption keys.
AIR uses DPAPI on Windows, KeyChain on Mac OS, and KeyRing or KWallet on Linux to associate the encrypted local store to each application and user. The encrypted local store uses AES-CBC 128-bit encryption.
Information in the encrypted local store is only available to AIR application content in the application security sandbox.
If you update an AIR application, the updated version retains access to any existing data in the encrypted local store unless:
Limitations of the encrypted local store
The data in the encrypted local store is protected by the user’s operating system account credentials. Other entities cannot access the data in the store unless they can login as that user. However, the data is not secure against access by other applications run by an authenticated user. Thus, data that your application may want to keep secret from users, such as keys used for licensing or digital rights management, is not secure. The ELS is not an appropriate location for storing such information. It is only an appropriate place for storing a user’s private data, such as passwords.
Data in the ELS can be lost for a variety of reasons. For example, the user could uninstall the application and delete the encrypted file. Or, the publisher ID could be changed as a result of an update. Thus the ELS should be treated as a private cache, not permanent data storage.
The
The encrypted local store may perform more slowly if the stored data exceeds 10MB.
When you uninstall an AIR application, the uninstaller does not delete data stored in the encrypted local store.
The best practices for using the ELS include:
Items in the encrypted local store are identified with a string. All items are stored as byte array data.
Encrypted local store data is put in a subdirectory of the user's application data directory; the subdirectory path is Adobe/AIR/ELS/ followed by the application ID.
If an item does not exist by the specified name, this method returns
To obtain index schema information for a database, use the
Generally, developer code does not construct SQLIndexSchema instances directly.
To obtain table schema information for a database, use the
Generally, developer code does not construct SQLTableSchema instances directly.
The SQLResult instance for a SQL statement is accessed by calling the
You use a SQLResult object to access the rows of data returned from a
When a statement returns one or more rows this property indicates
whether all of the rows have been returned. When a SQLStatement object's
Note that because the number of rows is unknown at execution time, the database cursor must move beyond
the last row before a statement's execution is considered complete. When the
When a statement returns one or more rows this property is an array containing objects that represent the rows of result data. Each object in the array has property names that correspond to the result data set's column names.
For example, suppose you execute the following SQL
Assuming the
The situation is more complex when you are using a
In the results from this statement, each object in the
In this statement's
The
After executing the query the
If there are duplicate column names in the result data, for example if the
By default the objects in the
If a statement does not return any data this property is
The value is 0 if the executed statement was not an
A row identifier is used to uniquely identify a row in a table within the database. The value is frequently generated by the database.
For more information about primary keys and generated row identifiers,
see the "CREATE TABLE" and
"Expressions" sections in the appendix
"
Auxiliary changes caused by triggers are not counted.
Use the
Note that when the related SQL operation is a