hanyeah

SQLConnection 

SQLConnection 实例用于管理本地 SQL 数据库文件（本地数据库）的创建和连接过程。

通过调用 open() 方法或 openAsync() 方法可以创建或打开本地 SQL 数据库文件。如果数据库文件不存在，则这些方法也可以在打开连接的同时创建数据库文件。建立了到数据库的连接后，可以通过创建 SQLStatement 实例并将 SQLConnection 实例分配给 SQLStatement 的 sqlConnection 属性来创建并对数据库执行 SQL 语句。

SQLConnection 类还提供 SQL 语句的状态，包括使用 begin()、commit() 和 rollback() 方法在一个事务中执行多个语句的机制。

另外，SQLConnection 类还提供对已连接的数据库的数据库架构信息的访问。数据库的架构说明数据库的表、列、索引和触发器的定义。有关详细信息，请参阅 loadSchema() 方法。

最后，可以使用 SQLConnection 实例来接收数据库级别的事件通知并提供数据库各个方面的配置控制，包括缓存页大小、进度取消和语句执行选项。

SQLConnection 实例可在异步和同步这两种完全不同的执行模式之一中运行。若要使用同步执行模式，请使用 open() 方法连接到 SQLConnection 实例的主数据库。若要使用异步执行模式，请使用 openAsync() 方法连接该实例的主数据库。

在使用异步执行模式时，可以使用事件侦听器或 Responder 实例来确定操作何时完成或失败。由于操作是在后台而不是在主应用程序线程中运行，因此即使数据库操作正在执行，应用程序也可以继续运行并响应用户交互。

在异步执行模式中，可以通过调用相应的方法来开始特定操作，并可以通过对相应的事件注册侦听器来检测操作的完成（或失败）。每个操作都有一个相关联的事件，操作成功完成时将调度该事件；例如，当一个 openAsync() 方法调用成功完成时（数据库连接打开时），将会调度 open 事件。当任何操作失败时，将调度 error 事件。SQLErrorEvent 对象的 error 属性中的 SQLError 实例包含有关特定错误的信息，包括尝试的操作和操作失败的原因。

在使用同步执行模式时，不必注册事件侦听器即可以确定操作何时完成或失败。若要识别错误，请将引发错误的语句括在 try..catch 块中。由于同步操作是在主执行线程中执行的，因此执行数据库操作时，所有应用程序功能（包括刷新屏幕和允许鼠标和键盘互操作）都暂停。对于长时间运行的操作，这会导致应用程序中出现明显的暂停。

SQLStatement 

SQLStatement 实例用于针对通过 SQLConnection 实例打开的本地 SQL 数据库执行 SQL 语句。

SQLStatement 实例通过将 SQLConnection 实例设置为 SQLStatement 实例的 sqlConnection 属性的值来链接到 SQLConnection 实例。text 属性用要执行的 SQL 语句的实际文本进行填充。如有必要，可以使用 parameters 属性指定 SQL 语句参数的值，并通过调用 execute() 方法执行该语句。

有关本地 SQL 数据库中支持的 SQL 术语的完整说明，请参阅附录本地数据库中的 SQL 支持。

在异步执行模式中，execute() 和 next() 方法在后台执行，并且当操作完成或失败时，运行时会对注册的事件侦听器或指定的 Responder 实例调度事件。在同步模式中，这些方法在主应用程序线程上执行，这意味着数据库操作完成之前不执行其他代码。另外，在同步模式中，如果方法失败，运行时将引发异常而不调度错误事件。

使用同步数据库操作

SQLStatement 

parameters

用作一个关联数组，将在其中添加 SQL 语句的 text 属性中指定的参数的值。数组键是参数的名称。如果在语句文本中指定了未命名的参数，则其键是该参数的索引。

在 SQL 语句的文本内，参数由以下字符之一批示：“?”、“:”或“@”。

“:”和“@”标记指示命名的参数；标记后面的字符指定参数的名称。

例如，在下面的 SQL 语句中，使用“:”字符指定了一个名为 firstName 的参数：

SELECT FROM employees WHERE firstName = :firstName

标记指示索引（编号）参数；系统根据参数在语句文本中的顺序自动为每个参数赋予一个索引。参数的索引值从零开始。也就是说，第一个参数的索引为 0。

参数用于允许对构造 SQL 语句时未知的值进行类型替代。使用参数是保证将值的存储类传递到数据库的唯一方式。不使用参数时，所有值都将根据相关联列的类型关系从其文本表示形式转换为存储类。有关存储类和列关系的详细信息，请参阅附录“本地数据库中的 SQL 支持”中的“数据类型支持”部分。

参数也可用作一种安全措施，防止恶意技术攻击（称为 SQL 注入攻击）。在 SQL 注入攻击中，用户在用户可访问的位置（例如数据输入字段）输入 SQL 代码。如果应用程序代码通过将用户输入直接连接到 SQL 文本来构造 SQL 语句，则将对数据库执行用户输入的 SQL 代码。下面的列表显示将用户输入连接到 SQL 文本的示例。不要使用此技术：

  // assume the variables "username" and "password"
     // contain user-entered data
     var sql:String =
         "SELECT userId " +
         "FROM users " +
         "WHERE username = '" + username + "' " +
         "    AND password = '" + password + "'";
     var statement:SQLStatement = new SQLStatement();
     statement.text = sql;

  // assume the variables "username" and "password"
     // contain user-entered data
     var sql =
         "SELECT userId " +
         "FROM users " +
         "WHERE username = '" + username + "' " +
         "    AND password = '" + password + "'";
     var statement = new air.SQLStatement();
     statement.text = sql;

使用语句参数而不将用户输入的值连接到语句的文本可防止 SQL 注入攻击，因为系统将参数值显式视为替代值，而不是作为字面语句文本的一部分。下面是对前面列表的建议替代方法：

  // assume the variables "username" and "password"
     // contain user-entered data
     var sql:String =
         "SELECT userId " +
         "FROM users " +
         "WHERE username = :username " +
         "    AND password = :password";
     var statement:SQLStatement = new SQLStatement();
     statement.text = sql;
     // set parameter values
     statement.parameters[":username"] = username;
     statement.parameters[":password"] = password;

  // assume the variables "username" and "password"
     // contain user-entered data
     var sql =
         "SELECT userId " +
         "FROM users " +
         "WHERE username = :username " +
         "    AND password = :password";
     var statement = new air.SQLStatement();
     statement.text = sql;
     // set parameter values
     statement.parameters[":username"] = username;
     statement.parameters[":password"] = password;

执行语句之前必须设置所有参数值。在调用 execute() 方法时，将会绑定 parameters 数组中指定的参数值（即与语句文本合并）。一旦调用 execute() 后，对值进行的任何后续更改都不会应用于正在执行的语句。不过，后续的 execute() 调用将使用更改的值。如果语句文本包括的参数没有 parameters 属性中指定的值，则结果会出错。

若要清除 parameters 属性中的所有参数值，请使用 clearParameters() 方法。