SQLStatement  - AS3

Wskazuje, czy instrukcja jest w tej chwili wykonywana.

Ta właściwość ma wartość true, jeśli wywołana została metoda execute() i nie wszystkie wyniki zostały zwrócone z bazy danych.

Powiązane elementy interfejsu API

Wskazuje klasę (typ danych) używaną dla każdego wiersza zwracanego jako wynik wykonania instrukcji.

Domyślnie każdy wiersz zwrócony za pomocą instrukcji SELECT jest tworzony jako instancja klasy Object z nazwami kolumn zestawu wyników jako nazwami właściwości instancji oraz wartością każdej kolumny przypisaną odpowiedniej właściwości.

Po określeniu klasy dla właściwości itemClass każdy wiersz zwrócony za pomocą instrukcji SELECT wykonanej przez instancję klasy SQLStatement zostanie utworzony jako instancja wyznaczonej klasy. Każdej właściwości instancji klasy itemClass przypisywana jest wartość z kolumny o tej samej nazwie, co właściwość.

Każda klasa przypisana do tej właściwości musi mieć konstruktor, który nie wymaga parametrów. Ponadto klasa musi mieć po jednej właściwości dla każdej kolumny zwracanej za pomocą instrukcji SELECT. Sytuacja, w której kolumna listy SELECT nie ma w klasie itemClass właściwości odpowiadającej jej nazwie, jest uznawana za błąd.

Powiązane elementy interfejsu 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());
        }
    }
}

Pełni funkcję tablicy asocjacyjnej, do której dodaje się wartości parametrów określonych we właściwości text instrukcji SQL. Klucze tablic są jednocześnie nazwami parametrów. Jeśli w instrukcji zostanie określony parametr bez nazwy, jego kluczem jest indeks parametru.

W instrukcji SQL parametr jest wskazywany za pomocą następujących znaków: "?", ":" lub "@".

Znaki ":" oraz "@" wskazują parametr nazwany, a kolejne znaki następujące po nich oznaczają jego nazwę.

Przykładowo w poniższej instrukcji SQL za pomocą znaku ":" określono parametr o nazwie firstName:

SELECT FROM employees WHERE firstName = :firstName

Znak "?" wskazuje zaindeksowany (numerowany) parametr; każdemu parametrowi automatycznie przypisywany jest indeks na podstawie kolejność parametrów w instrukcji. Parametry są indeksowane od zera. Inaczej mówiąc, pierwszy parametr ma indeks o wartości 0.

Parametry umożliwiają podstawianie wartości o określonym typie znanych dopiero w czasie wykonywania, ale nieznanych w chwili tworzenia instrukcji SQL. Korzystanie z parametrów jest jedynym sposobem na zagwarantowanie klasy danych wartości przekazywanej do bazy danych. Jeśli parametry nie są stosowane, wszystkie wartości są konwertowane z reprezentacji tekstowej do klasy danych opartej na typie skojarzonym z kolumną. Więcej informacji o klasach danych i powinowactwie kolumn zawiera sekcja „Obsługa typów danych” w dodatku „Obsługa języka SQL w lokalnych bazach danych”.

Parametry są również używane jako środek bezpieczeństwa zapobiegający wykorzystaniu złośliwej techniki znanej jako atak „SQL injection”. W ataku tego rodzaju użytkownik wprowadza kod SQL w miejscu dla niego dostępnym (na przykład w polu wprowadzania danych). Jeśli aplikacja utworzy instrukcję SQL, bezpośrednio dołączając do instrukcji SQL dane wprowadzane przez użytkownika, kod języka SQL wpisany przez użytkownika zostanie wykonany na bazie danych. Poniższy fragment kodu ilustruje przykład dołączania danych wprowadzanych przez użytkownika do instrukcji SQL. Nie należy stosować tej techniki:

     // 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;
     

Korzystanie z parametrów instrukcji zapobiega atakom bazującym na dodawaniu wartości wprowadzonych przez użytkownika do kodu instrukcji. Wartości parametrów są bowiem wartościami bezpośrednio podstawionymi, a nie stają się częścią samej instrukcji. Poniżej alternatywny do poprzedniej wersji i zalecany fragment kodu:

     // 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;
     

Wszystkie wartości parametrów należy ustawić zanim instrukcja zostanie wykonana. Wartości parametrów określone w tablicy parameters są dowiązywane (tj. są dołączane do tekstu instrukcji) w momencie wywoływania metody execute(). Po wywołaniu metody execute() kolejne zmiany wartości nie są dokonywane na instrukcji wykonującej. Jednak w kolejnym wywołaniu metody execute() zostaną użyte zmienione wartości. Jeśli instrukcja zawiera parametr, który nie ma wartości określonej we właściwości parameters, wystąpi błąd.

Aby usunąć wszystkie, wartości parametrów z właściwości parameters, należy skorzystać z metody clearParameters().

Powiązane elementy interfejsu 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();

Obiekt SQLConnection zarządzający połączeniami z bazami danych, na których wykonywana jest instrukcja.

Bieżąca wartość instrukcji SQL.

Wartością instrukcji może być każda wartość obsługiwana przez język SQL. Aby zapoznać się z pełnym opisem dialektu języka SQL obsługiwanego w lokalnych bazach danych, zobacz dodatek „Obsługa języka SQL w lokalnych bazach danych”.

Tworzy instancję klasy SQLStatement.

Anuluje wykonanie tej instrukcji. Ta metoda, podobnie jak metodaSQLConnection.cancel(), pozwala zatrzymać czasochłonne zapytanie lub anulować zapytanie, które nie zostało jeszcze zakończone. Jednak przeciwieństwie do metody SQLConnection.cancel(), ta metoda pozwala anulować jedynie pojedyncze instrukcje. Jeśli instrukcja nie jest obecnie wykonywana, wywołanie tej metody nie przynosi żadnego skutku.

Żadne zdarzenia nie są wywoływane jako bezpośrednia odpowiedź na zakończenie operacji cancel(). Jednak po zakończeniu operacji cancel() i anulowaniu wywołania instrukcji instancja klasy SQLStatement wywoła zdarzenie error informujące o tym, że wykonanie instrukcji (wywołanie metody execute() lub metody next()) nie zostało zakończone. W innym przypadku, jeśli określono wartość parametru responder wywołania metody execute() lub next(), wywołana zostanie określona metoda obsługi błędu. W obu przypadkach instancja klasy SQLError, która jest przekazywana do detektorów, będzie miała właściwość errorID o wartości 3118 (Operację przerwano).

Czyści wszystkie aktualne ustawienia parametrów.

Powiązane elementy interfejsu API

Wykonuje instrukcję SQL zapisaną we właściwości text na bazie danych podłączonej do instancji klasy SQLConnection, określonej we właściwości sqlConnection.

Jeśli argument responder ma wartość inną niż null, określona instancja klasy Responder wskazuje metody wywoływane w celu obsługi wyników operacji. Jeśli w trybie wykonywania asynchronicznego argument responder ma wartość null, wywoływane jest zdarzenie result dla operacji zakończonych powodzeniem lub zdarzenie error dla operacji zakończonych niepowodzeniem.

Aby uzyskać dostęp do wyników instrukcji, takich jak wiersze wyników instrukcji SELECT lub klucza głównego instrukcji INSERT (wygenerowanego przez bazę danych), należy wywołać metodę getResult(). Wyniki są dostępne bezpośrednio po wykonaniu instrukcji w trybie asynchronicznym, a także, gdy zdarzenie result jest wywoływane w trybie asynchronicznym.

Każda instrukcja musi być przygotowana (skompilowana), zanim zostanie wykonana. Przy pierwszym wywołaniu metody execute() instancji klasy SQLStatement instrukcja jest przygotowywana w środowisku wykonawczym. Przygotowana instrukcja nie wymaga ponownej kompilacji, o ile nie wprowadzono zmian we właściwości text. Ustawianie wartości jednego lub wielu parametrów nie powoduje konieczności ponownej kompilacji instrukcji.

Parametry

Powiązane elementy interfejsu 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.");
}

Zapewnia dostęp do instancji klasy SQLResult zawierającej wyniki wykonania instrukcji, łącznie z wierszami wynikowymi z instrukcji SELECT oraz pozostałymi informacjami o wykonaniu wszystkich wykonanych instrukcji. W asynchronicznym trybie wykonywania informacja o wyniku jest niedostępna do momentu wywołania zdarzenia result.

Jeśli w czasie wykonywania instrukcji SELECT wywołana zostanie metoda execute() z domyślnym argumentem prefetch równym -1, zwrócona instancja klasy SQLResult będzie zawierała cały zestaw wyników zapytania.

Jeśli argument prefetch został określony dla wywołania metod execute() lub next(), metoda getResult() działa jak kolejka FIFO (pierwszy na wejściu — pierwszy na wyjściu) z wynikami. Za każdym razem, kiedy wywoływane jest zdarzenie result, do kolejki dodawana jest nowa instancja klasy SQLResult. Za każdym razem kiedy wywoływana jest metoda getResult(), pierwsza instancja klasy SQLResult (ta, która jako pierwsza została dodana do kolejki) jest zwracana i usuwana z kolejki. Jeśli już żadna instancja klasy SQLResult nie pozostanie w kolejce, metoda getResult() zwraca wartość null.

Należy zauważyć, że instancje klasy SQLResult pozostają w kolejce, dopóki są usuwane za pomocą metody getResult(). Przykładowo, jeśli metoda execute() jest wywoływana wielokrotnie bez wywoływania metody getResult(), instancje klasy SQLResult skojarzone z każdym wywołaniem metody execute() pozostają w kolejce.

Powiązane elementy interfejsu API

Pobiera kolejną porcję zestawu wyników instrukcji SELECT. Jeśli w zestawie wyników nie ma więcej wierszy, wywoływane jest zdarzenie result, lecz do kolejki getResult() nie jest dodawany kolejny obiekt SQLResult.

Jeśli w asynchronicznym trybie wykonywania argument responder ma wartość inną niż null, określona instancja klasy Responder wskazuje metody wywoływane w celu obsługi wyników operacji. Jeśli argument responder ma wartość null, wywoływane jest zdarzenie result dla operacji zakończonych powodzeniem lub zdarzenie error dla operacji zakończonych niepowodzeniem.

Ta metoda może być wywoływana jedynie wtedy, gdy instrukcja jest wciąż wykonywana. Jeśli instrukcją jest zapytanie SELECT, a określona wartość argumentu prefetch jest większa niż zero, instrukcja będzie wykonywana, dopóki cały zestaw wyników nie zostanie zwrócony lub do momentu wywołania metody SQLStatement.cancel() lub metody SQLConnection.cancel().

Parametry

Powiązane elementy interfejsu 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.");
}

Wywoływane, gdy w czasie wykonywania operacji wystąpi błąd.

Powiązane elementy interfejsu API

Wywoływane, gdy operacja wywołania metody execute() lub next() zakończy się pomyślnie. Po wywołaniu zdarzenia result istnieje możliwość pobrania wyników instrukcji za pomocą wywołania metody getResult().

Powiązane elementy interfejsu API