Главная / Action Script 3
(Только AIR)
Пакетflash.data
Классpublic class SQLStatement
НаследованиеSQLStatement Inheritance EventDispatcher Inheritance Object

Язык версии : ActionScript 3.0
Версии среды выполнения:  1.0

Экземпляр SQLStatement используется для выполнения инструкции SQL в локальной базе данных SQL, открытой с помощью экземпляра SQLConnection.

Чтобы связать экземпляр SQLStatement с экземпляром SQLConnection, необходимо задать экземпляр SQLConnection в качестве значения свойства sqlConnection экземпляра SQLStatement. Свойство text заполняется имеющимся текстом выполняемой инструкции SQL. При необходимости значения параметров инструкции SQL задаются с помощью свойства parameters, а для выполнения самой инструкции нужно вызвать метод execute().

Полное описание диалекта SQL, поддерживаемого в локальных базах данных SQL, см. в приложении "Поддержка SQL в локальных базах данных".

В асинхронном режиме выполнения методы execute() и next() выполняются в фоновом потоке, и при завершении или сбое операций среда выполнения отправляет события зарегистрированным прослушивателям событий или заданному экземпляру Responder. В синхронном режиме методы выполняются в основном потоке приложения. Это означает, что никакой другой код не может быть выполнен до тех пор, пока не завершатся текущие операции в базе данных. Кроме того, если в синхронном режиме выполнения произошел сбой метода, вместо отправки события ошибки среда выполнения генерирует исключение.

См. также

flash.data.SQLConnection


Общедоступные свойства
 СвойствоОпределено
 Inheritedconstructor : Object
Ссылка на объект класса или функцию конструктора для данного экземпляра объекта.
Object
  AIR-only executing : Boolean
[только для чтения] Указывает, выполняется ли инструкция в текущий момент.
SQLStatement
  AIR-only itemClass : Class
Обозначает класс (тип данных), который используется для каждой строки, возвращенной в результате выполнения инструкции.
SQLStatement
  AIR-only parameters : Object
[только для чтения] Служит в качестве ассоциативного массива, в который добавляются значения параметров, заданных в свойстве text инструкции SQL.
SQLStatement
 Inheritedprototype : Object
[статические] Ссылка на модель объекта класса или функции.
Object
  AIR-only sqlConnection : SQLConnection
Объект SQLConnection, который управляет подключением к одной или нескольким базам данных, применительно к которым выполняется инструкция.
SQLStatement
  AIR-only text : String
Фактический текст инструкции SQL.
SQLStatement
Общедоступные методы
 МетодОпределено
  
Создает экземпляр SQLStatement.
SQLStatement
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Регистрирует объект прослушивателя события в объекте EventDispatcher, в результате чего прослушиватель будет получать уведомления о событиях.
EventDispatcher
  
Отменяет выполнение инструкции.
SQLStatement
  
Удаляет все текущие значения параметров.
SQLStatement
 Inherited
Передает событие в поток событий.
EventDispatcher
  
AIR-only execute(prefetch:int = -1, responder:Responder = null):void
Выполняет инструкцию SQL, которая содержится в свойстве text, применительно к базе данных, подключенной к объекту SQLConnection в свойстве sqlConnection.
SQLStatement
  
Обеспечивает доступ к объекту SQLResult, который содержит результаты выполнения инструкции, включая все строки результата выполнения инструкции SELECT и другие сведения о выполнении всех выполненных инструкций.
SQLStatement
 Inherited
Проверяет наличие у объекта EventDispatcher прослушивателей событий, которые зарегистрированы для получения уведомлений о событиях определенного типа.
EventDispatcher
 Inherited
Показывает, определено ли заданное свойство для объекта.
Object
 Inherited
Показывает, есть ли экземпляр класса Object в цепи прототипов объекта, заданного в качестве параметра.
Object
  
AIR-only next(prefetch:int = -1, responder:Responder = null):void
Извлекает следующую часть результирующего набора инструкции SELECT.
SQLStatement
 Inherited
Показывает наличие заданного свойства и его перечисляемость.
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Удаляет прослушиватель из объекта EventDispatcher.
EventDispatcher
 Inherited
Задает доступность динамического свойства для операций цикла.
Object
 Inherited
Возвращает строковое представление заданного объекта.
Object
 Inherited
Возвращает элементарное значение заданного объекта.
Object
 Inherited
Проверяет, зарегистрирован ли прослушиватель событий в объекте EventDispatcher или в любом из его предков для получения уведомлений о событиях определенного типа.
EventDispatcher
События
 Событие Сводка Определено
 Inherited[многоадресное событие] Отправляется, когда проигрыватель Flash Player перемещается в фокус операционной системы и становится активным.EventDispatcher
 Inherited[многоадресное событие] Отправляется, когда проигрыватель Flash Player покидает фокус операционной системы и становится неактивным.EventDispatcher
  Отправляется, если во время операции произошла ошибка.SQLStatement
  Отправляется при успешном вызове метода execute() или next().SQLStatement
Сведения о свойстве
AIR-only executingсвойство
executing:Boolean  [только для чтения]

Язык версии : ActionScript 3.0
Версии среды выполнения:  1.0

Указывает, выполняется ли инструкция в текущий момент.

Это свойство имеет значение true, если после вызова метода execute() из базы данных были возвращены не все результаты.



Реализация
    public function get executing():Boolean

См. также

AIR-only itemClassсвойство 
itemClass:Class  [чтение и запись]

Язык версии : ActionScript 3.0
Версии среды выполнения:  1.0

Обозначает класс (тип данных), который используется для каждой строки, возвращенной в результате выполнения инструкции.

По умолчанию каждая строка, возвращаемая инструкцией SELECT, создается в виде экземпляра Object, при этом имена столбцов результирующего набора совпадают с именами свойств объекта, а значение каждого столбца равно значению соответствующего свойства.

Если в свойстве itemClass указать класс, каждая строка, возвращаемая инструкцией SELECT, которая выполняется данным экземпляром SQLStatement, создается в виде объекта заданного класса. Каждому свойству экземпляра itemClass присваивается значение из столбца с таким же именем, как и у свойства.

Любой класс, указанный в этом свойстве, должен иметь конструктор без параметров. Кроме того, в этом классе должно быть определено по одному свойству для каждого столбца, возвращаемого инструкцией SELECT. Считается ошибкой, если у столбца из списка SELECT в классе itemClass нет свойства с соответствующим именем.



Реализация
    public function get itemClass():Class
    public function set itemClass(value:Class):void

См. также

AIR-only parametersсвойство 
parameters:Object  [только для чтения]

Язык версии : ActionScript 3.0
Версии среды выполнения:  1.0

Служит в качестве ассоциативного массива, в который добавляются значения параметров, заданных в свойстве text инструкции SQL. Ключами массива являются имена параметров. Если в тексте инструкции имеется параметр без имени, его ключом является индекс параметра.

Внутри текста инструкции 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;
     

Перед выполнением инструкции должны быть заданы значения всех параметров. Связывание (т. е. объединение с текстом инструкции) значений параметров, заданных в массиве parameters, осуществляется при вызове метода execute(). После вызова метода execute() никакие последующие изменения значений не будут применены к выполняемой инструкции. Однако при последующем вызове метода execute() будут использоваться измененные значения. Если в тексте инструкции есть параметр, для которого в свойстве parameters не задано значение, возникнет ошибка.

Чтобы удалить значения всех параметров в свойстве parameters, используется метод clearParameters().



Реализация
    public function get parameters():Object

См. также

AIR-only sqlConnectionсвойство 
sqlConnection:SQLConnection  [чтение и запись]

Версии среды выполнения:  1.0

Объект SQLConnection, который управляет подключением к одной или нескольким базам данных, применительно к которым выполняется инструкция.



Реализация
    public function get sqlConnection():SQLConnection
    public function set sqlConnection(value:SQLConnection):void

Выдает
IllegalOperationError — Если во время выполнения инструкции была предпринята попытка изменить значение этого свойства.
AIR-only textсвойство 
text:String  [чтение и запись]

Язык версии : ActionScript 3.0
Версии среды выполнения:  1.0

Фактический текст инструкции SQL.

Текстом может быть любая допустимая конструкция языка SQL. Полное описание диалекта SQL, поддерживаемого в локальных базах данных SQL, см. в приложении "Поддержка SQL в локальных базах данных".



Реализация
    public function get text():String
    public function set text(value:String):void

Выдает
IllegalOperationError — Если во время выполнения инструкции была предпринята попытка изменить значение свойства text.
Сведения о конструкторе
AIR-only SQLStatement()Конструктор
public function SQLStatement()

Язык версии : ActionScript 3.0
Версии среды выполнения:  1.0

Создает экземпляр SQLStatement.


Выдает
SecurityError — Если конструктор вызывается из какой-либо "песочницы" за пределами главной "песочницы" приложения.
Сведения о методе
AIR-only cancel()метод
public function cancel():void

Язык версии : ActionScript 3.0
Версии среды выполнения:  1.0

Отменяет выполнение инструкции. Как и метод SQLConnection.cancel(), данный метод используется, чтобы остановить продолжительный запрос или отменить запрос, находящийся в процессе выполнения. Однако, в отличие от метода SQLConnection.cancel(), этот метод отменяет только одну инструкцию. Если инструкции в текущий момент не выполняются, в результате вызова этого метода ничего не произойдет.

Непосредственно в ответ на завершение операции cancel() события не отправляются. Однако, если завершается операция cancel() и отменяется выполнение инструкции, экземпляр SQLStatement отправляет событие error, которое обозначает, что выполнение инструкции (вызов метода execute() или next()) не завершено. Если же при вызове метода execute() или next() задано значение параметра responder, будет вызван соответствующий обработчик ошибки. В любом случае у экземпляра SQLError, передаваемого прослушивателям, свойство errorID будет иметь значение 3118 ("Операция прервана").

AIR-only clearParameters()метод 
public function clearParameters():void

Язык версии : ActionScript 3.0
Версии среды выполнения:  1.0

Удаляет все текущие значения параметров.

См. также

AIR-only execute()метод 
public function execute(prefetch:int = -1, responder:Responder = null):void

Язык версии : ActionScript 3.0
Версии среды выполнения:  1.0

Выполняет инструкцию SQL, которая содержится в свойстве text, применительно к базе данных, подключенной к объекту SQLConnection в свойстве sqlConnection.

В асинхронном режиме выполнения, если аргумент responder имеет значение, отличное от null, указанный объект Responder содержит методы, вызываемые для обработки результатов операции. Если аргумент responder имеет значение null, при успешном завершении операции отправляется событие result, а при сбое — событие error.

После завершения события в синхронном режиме или отправки события result в асинхронном к результатам операции можно будет обратиться с помощью метода SQLStatement.getResult().

Перед выполнением каждая инструкция должна быть подготовлена (скомпилирована). При первом вызове метода execute() экземпляра SQLStatement среда выполнения подготавливает инструкцию. Когда инструкция подготовлена, она больше не требует повторной подготовки до тех пор, пока не изменится свойство text. Задание одного или нескольких параметров не требует повторной подготовки инструкцию.

Параметры

prefetch:int (default = -1) — Когда в свойстве text задана инструкция SELECT, это значение обозначает количество строк, возвращаемых инструкцией за один раз. Значение по умолчанию равно -1. Это значит, что все строки результата будут возвращены инструкцией за один раз. Этот параметр используется совместно с методом next() для разделения больших результирующих наборов на меньшие наборы данных. При более быстром возврате результатов и разделении операций по их обработке приложение будет восприниматься пользователями как более производительное.

Если инструкция SQL представляет собой запрос SELECT и задан аргумент prefetch, значение которого больше нуля, данная инструкция будет выполняться до тех пор, пока не будет возвращен весь результирующий набор или не будет вызван один из методов SQLStatement.cancel() или SQLConnection.cancel(). Следует заметить, что из-за того, что во время выполнения количество строк неизвестно, курсор базы данных должен переместиться за последнюю строку до того, как завершится выполнение инструкции. Если аргумент prefetch задан при вызове метода execute(), необходимо запросить не менее чем на одну запись больше, чем общее количество записей в результирующем наборе, прежде чем свойство complete экземпляра SQLResult станет равным true. Это достигается либо с помощью значения prefetch, которое превышает количество строк в результирующем наборе, либо с помощью последующих вызовов метода next().

 
responder:Responder (default = null) — Объект, для которого определены методы, вызываемые при успешном выполнении или сбое операции. При асинхронном режиме выполнения, если аргумент responder имеет значение null, по окончании выполнения отправляется событие result или error.


События
result:SQLEvent — Отправляется после успешного выполнения инструкции или в том случае, если задано значение аргумента prefetch, а инструкция SELECT возвращает одну или несколько строк данных.
 
error:SQLErrorEvent — Отправляется после сбоя операции в асинхронном режиме выполнения.

Выдает
IllegalOperationError — Если свойство text имеет значение null или содержит пустую строку (""); если свойство sqlConnection не задано; если экземпляр SQLConnection, указанный в свойстве sqlConnection, не подключен или если инструкция выполняется в текущий момент.
 
SQLError — Если произошел сбой операции в синхронном режиме выполнения.

См. также

AIR-only getResult()метод 
public function getResult():SQLResult

Язык версии : ActionScript 3.0
Версии среды выполнения:  1.0

Обеспечивает доступ к объекту SQLResult, который содержит результаты выполнения инструкции, включая все строки результата выполнения инструкции SELECT и другие сведения о выполнении всех выполненных инструкций. В асинхронном режиме выполнения данные результата не будут доступны, пока не отправлено событие result.

Если при выполнении инструкции SELECT метод execute() вызван с аргументом prefetch, имеющим значение по умолчанию -1, возвращаемый объект SQLResult будет содержать весь результирующий набор запроса.

Если аргумент prefetch указан при вызове метода execute() или next(), метод getResult() работает как очередь результатов с порядком доступа к элементам "первым поступил — первым обслужен" (FIFO, First In — First Out). Каждый раз при отправке события result к очереди добавляется новый объект SQLResult. Каждый раз при вызове метода getResult() возвращается и удаляется из очереди самый первый объект SQLResult (тот, который был добавлен в очередь первым). Если в очереди не осталось объектов SQLResult, метод getResult() возвращает null.

Следует заметить, что до удаления с помощью метода getResult() объекты SQLResult остаются в очереди. Например, если метод execute() вызывается несколько раз без вызова метода getResult(), объекты SQLResult, связанные с каждым вызовом метода execute(), остаются в очереди.

Возвращает
SQLResult — Объект SQLResult, который содержит результат вызова метода execute() или next().

См. также

AIR-only next()метод 
public function next(prefetch:int = -1, responder:Responder = null):void

Язык версии : ActionScript 3.0
Версии среды выполнения:  1.0

Извлекает следующую часть результирующего набора инструкции SELECT. Если в результирующем наборе больше не осталось строк, событие result отправляется, но в очередь getResult() больше не добавляются объекты SQLResult.

В асинхронном режиме выполнения, если аргумент responder имеет значение, отличное от null, указанный объект Responder содержит методы, вызываемые для обработки результатов операции. Если аргумент responder имеет значение null, при успешном завершении операции отправляется событие result, а при сбое — событие error.

Этот метод может быть вызван только во время выполнения инструкции. Если инструкция SQL представляет собой запрос 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 — если произошел сбой операции в синхронном режиме выполнения.

См. также

Сведения о событии
AIR-only error Событие
Тип объекта события: flash.events.SQLErrorEvent
свойство SQLErrorEvent.type = flash.events.SQLErrorEvent.ERROR

Язык версии : ActionScript 3.0
Версии среды выполнения:  1.0

Отправляется, если во время операции произошла ошибка.

Константа SQLErrorEvent.ERROR определяет значение свойства type события ошибки, отправляемого, когда вызов метода экземпляра SQLConnection или SQLStatement завершается ошибкой. Объект события error имеет следующие свойства.
СвойствоЗначение
bubblesfalse
cancelablefalse; нет поведения по умолчанию для отмены.
errorОбъект SQLError, содержащий информацию о типе возникшей ошибки и о вызвавшей ее операции.
currentTargetОбъект, активно обрабатывающий объект Event с помощью прослушивателя событий.
targetОбъект SQLConnection или SQLStatement, сообщающий об ошибке.

См. также

AIR-only result Событие  
Тип объекта события: flash.events.SQLEvent
свойство SQLEvent.type = flash.events.SQLEvent.RESULT

Язык версии : ActionScript 3.0
Версии среды выполнения:  1.0

Отправляется при успешном вызове метода execute() или next(). После того как было отправлено событие result, для получения результатов выполнения инструкции можно вызвать метод getResult().

Константа SQLEvent.RESULT определяет значение свойства typeобъекта события result. Отправляется, когда успешно завершается выполнение метода SQLStatement.execute() или SQLStatement.next() После отправки события SQLEvent.RESULT можно вызвать метод SQLStatement.getResult() для просмотра результатов. Объект события result имеет следующие свойства.
СвойствоЗначение
bubblesfalse
cancelablefalse; нет поведения по умолчанию для отмены.
currentTargetОбъект, активно обрабатывающий объект Event с помощью прослушивателя событий.
targetОбъект SQLStatement, выполнивший операцию.

См. также