| 套件 | flash.data |
| 類別 | public class SQLStatement |
| 繼承 | SQLStatement  EventDispatcher Object |
| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 1.0 |
將 SQLConnection 實體設定為 SQLStatement 實體之 sqlConnection 屬性的值，便可讓 SQLStatement 實體連結至 SQLConnection 實體。text 屬性會填入要執行之 SQL 陳述式的實際文字。若有必要，會使用 parameters 屬性指定 SQL 陳述式參數值，並呼叫 execute() 方法以執行該陳述式。
如需本機 SQL 資料庫中支援的 SQL 方言之完整說明，請參閱附錄「本機資料庫中的 SQL 支援」。
在非同步執行模式下，execute() 和 next() 方法會在背景中執行，而且在作業完成或失敗時，執行階段會將事件傳遞至已註冊的事件偵聽程式或指定的 Responder 實體。在同步模式下，這兩個方法會在主要應用程式執行序執行，這表示除非資料庫作業完成，否則其他程式碼都不會執行。此外，在同步模式下，如果這兩個方法失敗，執行階段便會擲回例外，而非傳送錯誤事件。
相關 API 元素
隱藏繼承公用屬性
顯示繼承公用屬性| 屬性 | 定義自 | ||
|---|---|---|---|
 | constructor : Object
類別物件的參照或是特定物件實體的建構函數。 | Object | |
| executing : Boolean [唯讀]
指出目前是否正在執行陳述式。 | SQLStatement | ||
| itemClass : Class
指出用於因為執行陳述式所傳回之每一列的類別 (資料類型)。 | SQLStatement | ||
| parameters : Object [唯讀]
做為關聯陣列，供您針對 SQL 陳述式之 text 屬性加入其指定的參數值。 | SQLStatement | ||
| sqlConnection : SQLConnection
負責管理 (已執行陳述式的) 資料庫之連線的 SQLConnection 物件。 | SQLStatement | ||
| text : String
陳述式的實際 SQL 文字。 | SQLStatement | ||
| 方法 | 定義自 | ||
|---|---|---|---|
建立 SQLStatement 實體。 | SQLStatement | ||
| addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
會在 EventDispatcher 物件註冊事件偵聽程式，以便讓偵聽程式收到事件的通知。 | EventDispatcher | |
取消執行此陳述式。 | SQLStatement | ||
清除目前所有的參數設定。 | SQLStatement | ||
|
會將事件傳送到事件流程。 | EventDispatcher | |
對 (連線至 sqlConnection 屬性中之 SQLConnection 物件的) 資料庫執行 text 屬性中的 SQL。 | SQLStatement | ||
讓使用者存取包含陳述式執行結果的 SQLResult 物件，這些結果包括任何來自 SELECT 陳述式的結果列，以及其他所有已執行之陳述式的陳述式執行相關資訊。 | SQLStatement | ||
|
會檢查 EventDispatcher 物件是否有對特定的事件類型註冊偵聽程式。 | EventDispatcher | |
|
指出物件是否有已定義的指定屬性。 | Object | |
|
指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。 | Object | |
擷取 SELECT 陳述式之結果集的下一部分。 | SQLStatement | ||
|
指出指定的屬性是否存在，以及是否可列舉。 | Object | |
|
會從 EventDispatcher 物件移除偵聽程式。 | EventDispatcher | |
|
為迴圈作業設定動態屬性的可用性。 | Object | |
|
傳回代表此物件的字串，根據地區特定慣例進行格式化。 | Object | |
|
會傳回指定之物件的字串形式。 | Object | |
|
會傳回指定之物件的基本值。 | Object | |
|
檢查此 EventDispatcher 物件是否已註冊事件偵聽程式，或者此物件的任何祖系已為特定事件類型註冊事件偵聽程式。 | EventDispatcher | |
| 事件 | 摘要 | 定義自 | ||
|---|---|---|---|---|
| [廣播事件] 當 Flash Player 或 AIR 應用程式取得作業系統焦點並成為作用中時傳送。 | EventDispatcher | ||
| [廣播事件] 當 Flash Player 或 AIR 應用程式失去作業系統焦點並成為非作用中時傳送。 | EventDispatcher | ||
| 當作業期間發生錯誤時傳送。 | SQLStatement | |||
| 當 execute() 或 next() 方法呼叫的作業成功完成時傳送。 | SQLStatement | |||
executing | 屬性 |
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 元素
範例 ( 如何使用本範例 )
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 元素
範例 ( 如何使用本範例 )
:firstName 在 SQL 陳述式中的用法。
// employees is a SQLStatement instance employees.text = "SELECT FROM employees WHERE first = :firstName"; employees.parameters[":firstName"] = "Sam"; employees.execute();
// 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 屬性時。
|
SQLStatement | () | 建構函式 |
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 | () | 方法 |
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 陳述式為 | |
responder:Responder (default = null)responder 引數為 null，則執行作業完成時會傳送 result 或 error 事件。
|
事件
result: — 當陳述式順利執行完成時傳送，或當已經指定了 prefetch 引數值且 SELECT 陳述式傳回一列或多列資料時傳送。
| |
error: — 當作業在非同步執行模式下失敗時傳送。
|
擲回值
IllegalOperationError — 如果 text 屬性為 null 或包含空字串 ("")、如果尚未設定 sqlConnection 屬性、如果指定給 sqlConnection 屬性的 SQLConnection 實體未連接，或者如果陳述式目前正在執行中。
| |
SQLError — 如果作業在同步執行模式下失敗。
|
相關 API 元素
範例 ( 如何使用本範例 )
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.");
}
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 陳述式時，如果搭配預設的 prefetch 引數值 (-1) 呼叫 execute() 方法，所傳回的 SQLResult 物件便包含查詢的整個結果集。
如果為 execute() 或 next() 方法呼叫指定 prefetch 引數，getResult() 方法的作用就和結果的先進先出佇列相同。每次傳送 result 事件時，新的 SQLResult 物件就會加入佇列。每次呼叫 getResult() 方法時，就會傳回最舊的 SQLResult 物件 (最先加入佇列的物件) 並從佇列移除該物件。佇列中沒有 SQLResult 物件時，getResult() 便傳回 null。
請注意，除非藉由呼叫 getResult() 來移除 SQLResult 物件，否則這些物件會持續存在於佇列中。例如，如果呼叫 execute() 方法多次而不呼叫 getResult()，與每個 execute() 呼叫有關的 SQLResult 物件將持續存在於佇列中。
SQLResult — SQLResult 物件，包含呼叫 execute() 或 next() 方法的結果。
|
相關 API 元素
next | () | 方法 |
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: — 當陳述式順利執行完成時傳送，或當已指定 prefetch 引數值且 next() 呼叫傳回一列或多列資料時傳送。
| |
error: — 當作業在非同步執行模式下失敗時傳送。
|
擲回值
IllegalOperationError — 未在陳述式執行期間呼叫此方法時 (executing 屬性為 false)。
| |
SQLError — 如果作業在同步執行模式下失敗。
|
相關 API 元素
範例 ( 如何使用本範例 )
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 常數會定義 error 事件的 type 屬性值，當對 SQLConnection 或 SQLStatement 實體的呼叫發生錯誤而結束時，便會傳送此事件。error 事件具有下列屬性：
| 屬性 | 值 |
|---|---|
bubbles | false |
cancelable | false；沒有要取消的預設行為指令。 |
error | SQLError 物件，其中包含發生的錯誤類型和造成錯誤的作業相關資訊。 |
currentTarget | 正主動使用事件偵聽程式處理 Event 物件的物件。 |
target | 報告錯誤的 SQLConnection 或 SQLStatement 物件。 |
相關 API 元素
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 元素
Tue Jun 12 2018, 03:47 PM Z