SQLStatement

包	flash.data
类	public class SQLStatement
继承	SQLStatement EventDispatcher Object

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0

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

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

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

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

相关 API 元素

flash.data.SQLConnection

公共属性

隐藏继承的公共属性

显示继承的公共属性

	属性		由以下参数定义
		constructor : Object 对类对象或给定对象实例的构造函数的引用。	Object
		executing : Boolean [只读] 表示当前是否正在执行语句。	SQLStatement
		itemClass : Class 表示一个类（数据类型），用于由于执行语句而返回的每个行。	SQLStatement
		parameters : Object [只读] 用作一个关联数组，将在其中添加 SQL 语句的 text 属性中指定的参数的值。	SQLStatement
		sqlConnection : SQLConnection 管理到执行语句的数据库的连接的 SQLConnection 对象。	SQLStatement
		text : String 语句的实际 SQL 文本。	SQLStatement

公共方法

隐藏继承的公共方法

显示继承的公共方法

	方法		由以下参数定义
		SQLStatement() 创建 SQLStatement 实例。	SQLStatement
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void 使用 EventDispatcher 对象注册事件侦听器对象，以使侦听器能够接收事件通知。	EventDispatcher
		cancel():void 取消执行此语句。	SQLStatement
		clearParameters():void 清除所有当前参数设置。	SQLStatement
		dispatchEvent(event:Event):Boolean 将事件调度到事件流中。	EventDispatcher
		execute(prefetch:int = -1, responder:Responder = null):void 针对连接到 sqlConnection 属性中的 SQLConnection 对象的数据库执行 text 属性中的 SQL。	SQLStatement
		getResult():SQLResult 提供对包含语句执行结果的 SQLResult 对象的访问，其中包括 SELECT 语句的任何结果行以及有关执行的所有语句的语句执行情况的其他信息。	SQLStatement
		hasEventListener(type:String):Boolean 检查 EventDispatcher 对象是否为特定事件类型注册了任何侦听器。	EventDispatcher
		hasOwnProperty(name:String):Boolean 表示对象是否已经定义了指定的属性。	Object
		isPrototypeOf(theClass:Object):Boolean 表示 Object 类的实例是否在指定为参数的对象的原型链中。	Object
		next(prefetch:int = -1, responder:Responder = null):void 检索 SELECT 语句的结果集的下一部分。	SQLStatement
		propertyIsEnumerable(name:String):Boolean 表示指定的属性是否存在、是否可枚举。	Object
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void 从 EventDispatcher 对象中删除侦听器。	EventDispatcher
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 设置循环操作动态属性的可用性。	Object
		toLocaleString():String 返回此对象的字符串表示形式，其格式设置遵守区域设置特定的约定。	Object
		toString():String 返回指定对象的字符串表示形式。	Object
		valueOf():Object 返回指定对象的原始值。	Object
		willTrigger(type:String):Boolean 检查是否用此 EventDispatcher 对象或其任何祖代为指定事件类型注册了事件侦听器。	EventDispatcher

事件

单击此处了解有关事件的更多信息

隐藏继承的事件

显示继承的事件

	摘要	由以下参数定义
activate	[广播事件] Flash Player 或 AIR 应用程序获得操作系统焦点并变为活动状态时将调度此事件。	EventDispatcher
deactivate	[广播事件] Flash Player 或 AIR 应用程序失去操作系统焦点并变为非活动状态时将调度此事件。	EventDispatcher
error	在执行操作期间发生错误时调度。	SQLStatement
result	execute() 或 next() 方法调用操作成功完成时调度。	SQLStatement

属性详细信息

executing

属性

executing:Boolean [只读]

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0

表示当前是否正在执行语句。

如果已调用 execute() 且尚未返回数据库中的所有结果，则此属性为 true。

实现
public function get executing():Boolean

相关 API 元素

execute()

itemClass

属性

itemClass:Class

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0

表示一个类（数据类型），用于由于执行语句而返回的每个行。

默认情况下，由 SELECT 语句返回的每个行都创建为 Object 实例，以结果集的列名作为该对象的属性名，每列的值作为其相关属性的值。

通过指定 itemClass 属性的类，由此 SQLStatement 实例执行的 SELECT 语句返回的每个行都创建为指定的类的实例。itemClass 实例的每个属性均赋予与该属性同名的列中的值。

分配给此属性的任何类必须具有不需要任何参数的构造函数。另外，对于由 SELECT 语句返回的每个列，该类必须具有一个单一的属性。如果 SELECT 列表中的列在 itemClass 类中没有相匹配的属性名称，系统会将其视为错误。

实现
public function get itemClass():Class
public function set itemClass(value:Class):void

相关 API 元素

flash.data.SQLResult.data

示例 ( 如何使用本示例 )

下面的代码演示如何使用 itemClass 属性让运行时从 SQL SELECT 语句结果创建自定义类的实例。

// Employee class definition
package
{
    public class Employee
    {
        public var name:String;
        public var ssn:String;
        public var id:uint;
        public override function toString():String
        {
            return "id: "+ id.toString() + " name: " + name + " ssn: " + ssn;
        }
    }
}


// using the Employee class as SQLStatement.itemClass
var conn:SQLConnection;
var dbStatement:SQLStatement;

function init():void
{
    conn = new SQLConnection();
    conn.addEventListener(SQLEvent.OPEN, connOpenHandler);
    
    dbStatement = new SQLStatement();
    dbStatement.sqlConnection = conn;
    dbStatement.text = "SELECT id, name, ssn FROM employees";
    dbStatement.itemClass = Employee;
    
    var dbFile:File = new File(File.separator + "employee.db");
    conn.open(dbFile);
}

function connOpenHandler(event:SQLEvent):void
{
    dbStatement.addEventListener(SQLEvent.RESULT, resultHandler);
    dbStatement.execute();
}

function resultHandler(event:SQLEvent):void
{
    var result:SQLResult = dbStatement.getResult();
    if (result != null)
    {
        var emp:Employee;
        var numRows:int = result.data.length;
        for (var i:int = 0; i < numRows; i++)
        {
            emp = result.data[i];
            trace(emp.toString());
        }
    }
}

parameters

属性

parameters:Object [只读]

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0

用作一个关联数组，将在其中添加 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;

使用语句参数而不将用户输入的值连接到语句的文本可防止 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;

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

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

实现
public function get parameters():Object

相关 API 元素

text
clearParameters()

示例 ( 如何使用本示例 )

下面的示例显示命名参数 :firstName 在 SQL 语句中的用法。

// employees is a SQLStatement instance
employees.text = "SELECT FROM employees WHERE first = :firstName";
employees.parameters[":firstName"] = "Sam";
employees.execute();

下面的示例显示未命名参数在 SQL 语句中的用法。

// employees is a SQLStatement instance
employees.text = "SELECT FROM employees WHERE first = ?";
employees.parameters[0] = "Sam";
employees.execute();

sqlConnection

属性

sqlConnection:SQLConnection

运行时版本:

AIR 1.0

管理到执行语句的数据库的连接的 SQLConnection 对象。

实现
public function get sqlConnection():SQLConnection
public function set sqlConnection(value:SQLConnection):void

引发

IllegalOperationError — 当该语句正在执行的同时尝试更改此属性的值时。

text

属性

text:String

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0

语句的实际 SQL 文本。

该文本可以是任何受支持的 SQL。有关本地 SQL 数据库中支持的 SQL 术语的完整说明，请参阅附录“本地数据库中的 SQL 支持”。

实现
public function get text():String
public function set text(value:String):void

引发

IllegalOperationError — 当该语句正在执行的同时尝试更改 text 属性时。

构造函数详细信息

()

构造函数

public function SQLStatement()

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0

创建 SQLStatement 实例。

引发

SecurityError — 如果从主应用程序沙箱外的任意沙箱中调用构造函数。

方法详细信息

cancel

()

方法

public function cancel():void

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0

取消执行此语句。与 SQLConnection.cancel() 一样，此方法用于停止长时间运行的查询或取消尚未完成的查询。但是，与 SQLConnection.cancel() 不同，此方法只取消单个语句。如果当前未执行该语句，则调用此方法不起作用。

不会调度事件以直接响应 cancel() 操作的完成。但是，一旦 cancel() 操作完成并且取消语句执行后，SQLStatement 实例即会调度 error 事件，表示语句执行（execute() 或 next() 调用）没有完成。或者，如果为 execute() 或 next() 调用的 responder 参数指定了值，则会调用指定的错误处理函数方法。不管是哪种情况，传递给侦听器的 SQLError 实例将具有值为 3118（操作已终止）的 errorID 属性。

clearParameters

()

方法

public function clearParameters():void

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0

清除所有当前参数设置。

相关 API 元素

parameters

execute

()

方法

public function execute(prefetch:int = -1, responder:Responder = null):void

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0

针对连接到 sqlConnection 属性中的 SQLConnection 对象的数据库执行 text 属性中的 SQL。

如果 responder 参数不为 null，则指定的 Responder 对象将指定用于处理操作结果而调用的方法。当 responder 参数为 null 时，如果操作成功，则在异步执行模式中调度 result 事件；如果操作失败，则调度 error 事件。

若要访问执行语句的结果，例如 SELECT 语句的结果行或 INSERT 语句的数据库生成的主键，则调用 getResult() 方法。在同步模式中执行此语句后，以及在异步模式中调度 result 事件后，会立即显示结果。

每个语句必须在准备好（编译）后才能执行。首次调用 SQLStatement 实例的 execute() 方法时，运行时将准备好该语句。语句准备好后，除非 text 属性发生更改，否则不需要重新准备该语句。设置一个或多个参数值不需要重新准备该语句。

参数

	`prefetch:int` (default = `-1`) — 当该语句的 `text` 属性为 `SELECT` 语句时，此值表示该语句一次返回的行数。默认值为 -1，表示一次返回所有结果行。此参数与 `next()` 方法结合使用，可将大结果集拆分为较小的数据集。这样，通过更快地返回初始结果和划分结果处理操作，可以改善用户对应用程序性能的体验。当 SQL 语句为 `SELECT` 查询并指定了大于零的 `prefetch` 参数时，该语句将被视为正在执行，直到返回整个结果集或者调用了 `SQLStatement.cancel()` 或 `SQLConnection.cancel()` 方法。请注意，由于在执行时结果集中的行数是未知的，因此，数据库光标必须移动到结果集的最后一行以后，才会认为该语句完成。如果在 `execute()` 调用中指定了 `prefetch` 参数，则只有当所请求的行数至少比结果集中的总行数多一行（通过大于结果集中行数的 `prefetch` 值或通过对 `next()` 方法的后续调用）后，生成的 SQLResult 实例的 `complete` 属性才会为 `true`。

	`responder:Responder` (default = `null`) — 一个对象，指定操作成功或失败时要调用的方法。在异步执行模式中，如果 `responder` 参数为 `null`，则执行完成时将调度 `result` 或 `error` 事件。

事件

	`result:SQLEvent` — 语句成功执行时或指定了 `prefetch` 参数值且 `SELECT` 语句返回一行或多行数据时调度。

	`error:SQLErrorEvent` — 在异步执行模式中操作失败时调度。

引发

	`IllegalOperationError` — 如果 `text` 属性为 `null` 或包含空字符串（`""`）；如果未设置 `sqlConnection` 属性；如果未连接分配给 `sqlConnection` 属性的 SQLConnection 实例；或者该语句当前正在执行。

	`SQLError` — 如果该操作在同步执行模式中失败。

相关 API 元素

next()
getResult()

示例 ( 如何使用本示例 )

下面的示例演示如何使用事件侦听器执行 SQLStatement，以确定语句的执行何时完成或失败。

var conn:SQLConnection;
var dbStatement:SQLStatement;

function init():void
{
    conn = new SQLConnection();
    conn.addEventListener(SQLEvent.OPEN, connOpenHandler);
    
    dbStatement = new SQLStatement();
    dbStatement.sqlConnection = conn;
    dbStatement.text = "SELECT id, name, ssn FROM employees";
    
    var dbFile:File = new File(File.separator + "employee.db");
    conn.open(dbFile);
}

function connOpenHandler(event:SQLEvent):void
{
    dbStatement.addEventListener(SQLEvent.RESULT, resultHandler);
    dbStatement.addEventListener(SQLErrorEvent.ERROR, errorHandler);
    dbStatement.execute();
}

function resultHandler(event:SQLEvent):void
{
    var result:SQLResult = dbStatement.getResult();
    if (result != null)
    {
        var numRows:int = result.data.length;
        for (var i:int = 0; i < numRows; i++)
        {
            var row:Object = result.data[i];
            trace("id:", row.id, ", name:", row.name, ", ssn:", row.ssn);
        }
    }
}

function errorHandler(event:SQLErrorEvent):void
{
    trace("An error occured while executing the statement.");
}

下面的示例演示如何执行 SQLStatement，该示例使用 Responder 对象来表示语句执行完成或失败时所调用的函数。

var conn:SQLConnection;
var dbStatement:SQLStatement;
var employeeResponder:Responder;

function init():void
{
    conn = new SQLConnection();
    conn.addEventListener(SQLEvent.OPEN, connOpenHandler);
    
    dbStatement = new SQLStatement();
    dbStatement.sqlConnection = conn;
    dbStatement.text = "SELECT id, name, ssn FROM employees";
    
    var dbFile:File = new File(File.separator + "employee.db");
    conn.open(dbFile);
}

function connOpenHandler(event:SQLEvent):void
{
    employeeResponder = new Responder(resultHandler, errorHandler);
    dbStatement.execute(-1, employeeResponder);
}

function resultHandler(result:SQLResult):void
{
    if (result != null)
    {
        var numRows:int = result.data.length;
        for (var i:int = 0; i < numRows; i++)
        {
            var row:Object = result.data[i];
            trace("id:", row.id, ", name:", row.name, ", ssn:", row.ssn);
        }
    }
}

function errorHandler(error:SQLError):void
{
    trace("An error occured while executing the statement.");
}

getResult

()

方法

public function getResult():SQLResult

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0

提供对包含语句执行结果的 SQLResult 对象的访问，其中包括 SELECT 语句的任何结果行以及有关执行的所有语句的语句执行情况的其他信息。在异步执行模式中，在调度 result 事件之前结果信息不可用。

执行 SELECT 语句时，如果所调用的 execute() 方法的默认 prefetch 参数为 -1，则返回的 SQLResult 对象包含整个查询结果集。

如果为 execute() 或 next() 方法调用指定了 prefetch 参数，则 getResult() 方法的行为与先进先出结果队列相同。每次调度 result 事件时，即会向队列中添加一个新的 SQLResult 对象。每次调用 getResult() 方法时，即会返回最早的 SQLResult 对象（最先添加到队列中的对象）并从队列中删除该对象。当队列中不再有 SQLResult 对象时，getResult() 将返回 null。

请注意，除非通过调用 getResult() 来删除 SQLResult 对象，否则这些对象会保留在队列中。例如，如果调用多次 execute() 方法而没有调用 getResult()，则与每个 execute() 调用相关联的 SQLResult 对象将保留在队列中。

SQLResult — 一个 SQLResult 对象，其中包含对 execute() 或 next() 方法调用的结果。

相关 API 元素

execute()
next()
result 事件

()

方法

public function next(prefetch:int = -1, responder:Responder = null):void

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0

检索 SELECT 语句的结果集的下一部分。如果结果集中不再有行，则调度 result 事件，但不再向 getResult() 队列中添加 SQLResult 对象。

在异步执行模式中，如果 responder 参数不为 null，则指定的 Responder 对象表示为处理操作结果而调用的方法。当 responder 参数为 null 时，如果操作成功，则调度 result 事件；如果操作失败，则调度 error 事件。

只能在该语句仍在执行时才能调用此方法。当语句为 SELECT 查询并指定了大于零的 prefetch 参数时，该语句将被视为正在执行，直到返回整个结果集或者调用了 SQLStatement.cancel() 或 SQLConnection.cancel() 方法。

参数

	`prefetch:int` (default = `-1`) — 当该语句的 `text` 属性为 `SELECT` 语句时，此值表示该语句一次返回的行数。默认值为 -1，表示一次返回所有结果行。这样，通过更快地返回初始结果和划分结果处理操作，可以改善用户对应用程序性能的体验。

	`responder:Responder` (default = `null`) — 一个对象，指定操作成功或失败时要调用的方法。如果 `responder` 参数为 `null`，则执行完成时将调度 `result` 或 `error` 事件。

事件

	`result:SQLEvent` — 语句成功执行时或指定了 `prefetch` 参数值且 `next()` 调用返回一行或多行数据时调度。

	`error:SQLErrorEvent` — 在异步执行模式中操作失败时调度。

引发

	`IllegalOperationError` — 在该语句不是当前正在执行的语句时调用该方法的情况下（`executing` 属性为 `false`）。

	`SQLError` — 如果该操作在同步执行模式中失败。

相关 API 元素

execute()

示例 ( 如何使用本示例 )

下面的示例演示如何执行 SQLStatement，明确表示第一次返回结果时仅返回结果集的前 10 行。代码检查 SQLResult 的 complete 属性，如果尚未检索所有行，则调用 next() 方法。

var conn:SQLConnection;
var dbStatement:SQLStatement;

function init():void
{
    conn = new SQLConnection();
    conn.addEventListener(SQLEvent.OPEN, connOpenHandler);
    
    dbStatement = new SQLStatement();
    dbStatement.sqlConnection = conn;
    dbStatement.text = "SELECT id, name, ssn FROM employees";
    
    var dbFile:File = new File(File.separator + "employee.db");
    conn.open(dbFile);
}

function connOpenHandler(event:SQLEvent):void
{
    dbStatement.addEventListener(SQLEvent.RESULT, resultHandler);
    dbStatement.addEventListener(SQLErrorEvent.ERROR, errorHandler);
    dbStatement.execute(10);
}

function resultHandler(event:SQLEvent):void
{
    var result:SQLResult = dbStatement.getResult();
    if (result != null)
    {
        var numRows:int = result.data.length;
        for (var i:int = 0; i < numRows; i++)
        {
            var row:Object = result.data[i];
            trace("id:", row.id, ", name:", row.name, ", ssn:", row.ssn);
        }
        if (!result.complete)
        {
            dbStatement.next(10);
        }
    }
}

function errorHandler(event:SQLErrorEvent):void
{
    trace("An error occured while executing the statement.");
}

事件详细信息

error

事件

事件对象类型: flash.events.SQLErrorEvent
属性 SQLErrorEvent.type = flash.events.SQLErrorEvent.ERROR

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0

在执行操作期间发生错误时调度。

SQLErrorEvent.ERROR 常量定义在 SQLConnection 方法调用或 SQLStatement 实例出错完成时调度的 error 事件的 type 属性值。error 事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`error`	一个 SQLError 对象，其中包含有关出现的错误的类型和导致该错误的操作的信息。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`target`	报告错误的 SQLConnection 或 SQLStatement 对象。

相关 API 元素

execute()
next()

result

事件

事件对象类型: flash.events.SQLEvent
属性 SQLEvent.type = flash.events.SQLEvent.RESULT

语言版本:

ActionScript 3.0

运行时版本:

AIR 1.0

execute() 或 next() 方法调用操作成功完成时调度。一旦调度 result 事件后，即可以调用 getResult() 方法以检索语句结果。

SQLEvent.RESULT 常量定义 result 事件对象的 type 属性值。在 SQLStatement.execute() 方法或 SQLStatement.next() 方法成功完成时调度。调度 SQLEvent.RESULT 事件之后，即可调用 SQLStatement.getResult() 方法来访问结果数据。result 事件具有以下属性：

属性	值
`bubbles`	`false`
`cancelable`	`false`；没有要取消的默认行为。
`currentTarget`	当前正在使用某个事件侦听器处理 Event 对象的对象。
`target`	执行操作的 SQLStatement 对象。

相关 API 元素

execute()
next()
getResult()

法律声明 | 在线隐私策略

SQLStatement - AS3

类 x

executing

itemClass

parameters

sqlConnection

text

SQLStatement

cancel

clearParameters

execute

getResult

next

error

result