SQLStatement  - AS3

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

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

Связанные элементы API

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

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

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

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

Связанные элементы API

// 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());
        }
    }
}

Служит в качестве ассоциативного массива, в который добавляются значения параметров, заданных в свойстве 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;
     

Использование параметров инструкции вместо добавления в его текст пользовательских значений предотвращает атаку путем внедрения кода 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;
     

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

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

Связанные элементы API

// 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, который управляет подключением к одной или нескольким базам данных, применительно к которым выполняется инструкция.

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

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

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

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

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

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

Связанные элементы API

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

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

Чтобы просмотреть результат выполнения инструкции, например строки, созданные в результате выполнения инструкции SELECT, или первичный ключ инструкции INSERT, созданный базой данных, необходимо вызвать метод getResult(). Результаты можно просмотреть сразу после выполнения инструкции в синхронном режиме, а также после отправки события result в асинхронном режиме.

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

Параметры

Связанные элементы 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.");
}

Обеспечивает доступ к объекту 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(), остаются в очереди.

Связанные элементы API

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

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

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

Параметры

Связанные элементы 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(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.");
}

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

Связанные элементы API

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

Связанные элементы API