SQLStatement  - AS3

Indique si l’instruction est en cours d’exécution.

Cette propriété est true si la méthode execute() a été appelée et que tous les résultats n’ont pas été renvoyés de la base de données.

Eléments de l’API associés

Indique une classe (type de données) utilisée pour chaque ligne renvoyée en tant que résultat de l’exécution de l’instruction.

Par défaut, chaque ligne renvoyée par une instruction SELECT est créée en tant qu’occurrence Object, avec les noms de colonnes du jeu de résultats correspondant au nom des propriétés de l’objet, et la valeur de chaque colonne correspondant à la valeur de sa propriété associée.

En spécifiant la classe de la propriété itemClass, chaque ligne renvoyée par une instruction SELECT exécutée par cette occurrence SQLStatement et créée sous la forme d’une occurrence de la classe désignée. Chaque propriété de l’occurrence itemClass se voit affecter la valeur de la colonne portant le même nom que la propriété.

Toute classe affectée à cette propriété doit avoir un constructeur qui ne requiert aucun paramètre. En outre, la classe doit avoir une seule propriété pour chaque colonne renvoyée par l’instruction SELECT. Le fait qu’une colonne de la liste SELECT ne présente pas de nom de propriété correspondant dans la classe itemClass est considéré comme une erreur.

Plus d’exemples

Eléments de l’API associés

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

Joue le rôle de tableau associatif dans lequel vous ajoutez des valeurs pour les paramètres spécifiés dans la propriété text de l’instruction SQL. Les clés du tableau sont les noms des paramètres. Si un paramètre sans nom est spécifié dans la propriété text de l’instruction, sa clé est l’index du paramètre.

Dans le texte d’une instruction SQL, un paramètre est indiqué avec l’un des caractères suivants : « ? », « : » ou « @ ».

Les jetons « : » et « @ » indiquent un paramètre nommé ; les caractères qui suivent le jeton désignent le nom du paramètre.

Par exemple, dans l’instruction SQL suivante, un paramètre nommé firstName est spécifié à l’aide du caractère « : » :

SELECT FROM employees WHERE firstName = :firstName

Le jeton « ? » indique un paramètre indexé (numéroté) ; chaque paramètre se voit automatiquement attribué un index en fonction de la séquence des paramètres du texte de l’instruction. Les valeurs d’index des paramètres sont de base zéro. En d’autres termes, le premier index de paramètre est 0.

Les paramètres autorisent la substitution avec type de valeurs inconnues au moment de la construction de l’instruction SQL. L’utilisation des paramètres est le seul moyen de garantir la classe de stockage d’une valeur transmise à la base de données. Lorsque des paramètres ne sont pas utilisés, toutes les valeurs sont converties de leur représentation texte en une classe de stockage en fonction de l’affinité du type de la colonne associée. Pour plus d’informations sur les classes de stockage et l’affinité des colonnes, voir la section « Prise en charge des types de données » dans l’annexe « Prise en charge de SQL dans les bases de données locales ».

Les paramètres sont également utilisés comme mesure de sécurité pour empêcher une technique malveillante appelée attaque par injection de code SQL. Dans une attaque par injection de code SQL, l’utilisateur entre du code SQL dans un emplacement accessible (par exemple dans un champ de saisie de données). Si le code de l’application construit une instruction SQL en concaténant directement la saisie de l’utilisateur dans le texte SQL, le code SQL saisi par l’utilisateur est exécuté sur la base de données. L’exemple suivant illustre la concaténation de la saisie de l’utilisateur dans le texte SQL. N’utilisez pas cette technique :

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

L’utilisation des paramètres d’instruction à la place de la concaténation des valeurs entrées par l’utilisateur dans le texte d’une instruction empêche les attaques par injection de code SQL car les valeurs des paramètres sont traitées explicitement sous forme de valeurs substituées au lieu de devenir une partie du texte de l’instruction littérale. L’exemple suivant est l’alternative recommandée :

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

Toutes les valeurs des paramètres doivent être définies avant l’exécution de l’instruction. Les valeurs des paramètres spécifiés dans le tableau parameters sont liées (c’est-à-dire combinées avec le texte de l’instruction) lorsque la méthode execute() est appelée. Après l’appel de la méthode execute(), les modifications suivantes des valeurs ne sont pas appliquées à l’instruction en exécution. Toutefois, lors des appels consécutifs à execute(), les valeurs modifiées sont utilisées. Si le texte de l’instruction comprend un paramètre pour lequel aucune valeur n’a été spécifiée dans la propriété parameters, une erreur se produit.

Pour effacer toutes les valeurs de paramètres de la propriété parameters, utilisez la méthode clearParameters().

Plus d’exemples

Eléments de l’API associés

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

Objet SQLConnection qui gère la connexion à la ou aux bases de données dans lesquelles l’instruction est exécutée.

Véritable texte SQL de l’instruction.

Le texte peut être n’importe quel code SQL pris en charge. Pour obtenir une description complète du dialecte SQL pris en charge par les bases de données SQL locales, consultez l’annexe « Prise en charge de SQL dans les bases de données locales ».

Crée une occurrence SQLStatement.

Annule l’exécution de cette instruction. Comme SQLConnection.cancel(), cette méthode est utilisée pour interrompre une requête d’exécution longue ou pour annuler une requête qui n’est pas encore terminée. Toutefois, contrairement à SQLConnection.cancel(), cette méthode n’annule que la seule instruction. Si l’instruction n’est pas en cours d’exécution, l’appel à cette méthode ne donne rien.

Aucun événement n’est déclenché en réponse directe à l’achèvement de l’opération cancel(). Toutefois, une fois que l’opération cancel() est terminée et que l’exécution de l’instruction est annulée, l’occurrence SQLStatement déclenche un événement error qui indique que l’exécution de l’instruction (l’appel execute() ou next()) ne s’est pas terminée. Alternativement, si une valeur a été spécifiée pour le paramètre responder de l’appel execute() ou next(), la méthode du gestionnaire de fautes spécifiée est appelée. Dans les deux cas, l’occurrence SQLError transmise aux écouteurs présente une propriété errorID avec la valeur 3118 (Opération annulée).

Efface tous les paramètres actuels.

Eléments de l’API associés

Exécute l’instruction SQL de la propriété text sur la base de données connectée à l’objet SQLConnection dans la propriété sqlConnection.

Si l’argument responder n’est pas null, l’objet Responder spécifié désigne les méthodes appelées pour gérer les résultats de l’opération. Lorsque l’argument responder est défini sur null en mode d’exécution asynchrone, un événement result est distribué si l’opération aboutit, ou un événement error si l’opération échoue.

Pour accéder aux résultats d’une instruction, notamment aux lignes de résultats d’une instruction SELECT ou à la clé primaire générée via la base de données d’une instruction INSERT, appelez la méthode getResult(). Ces résultats sont disponibles immédiatement après l’exécution de l’instruction en mode synchrone et lors de la distribution de l’événement result en mode asynchrone.

Chaque instruction doit être préparée (compilée) avant de pouvoir être exécutée. Lors du premier appel de la méthode execute() de l’occurrence SQLStatement, l’instruction est préparée par le moteur d’exécution. Une fois qu’une instruction est préparée, elle n’a pas besoin de l’être à nouveau sauf si la propriété text change. La définition d’une ou plusieurs valeurs de paramètres n’entraîne pas la nécessité de préparer de nouveau l’instruction.

Paramètres

Plus d’exemples

Eléments de l’API associés

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.");
}

Permet d’accéder à un objet SQLResult contenant les résultats de l’exécution de l’instruction, y compris les lignes de résultat d’une instruction SELECT et d’autres informations sur l’exécution de toutes les instructions exécutées. En mode d’exécution asynchrone, les informations de résultat ne sont pas disponibles avant le déclenchement de l’événement result.

Lorsqu’une instruction SELECT est exécutée, si la méthode execute() est appelée avec l’argument prefetch par défaut défini sur -1, l’objet SQLResult renvoyé contient l’ensemble du jeu de résultats de la requête.

Lorsqu’un argument prefetch est spécifié pour un appel de méthode execute() ou next(), la méthode getResult() se comporte comme une file d’attente de résultats premier arrivé-premier sorti. Chaque fois que l’événement result est distribué, un nouvel objet SQLResult est ajouté à la file d’attente. Chaque fois que la méthode getResult() est appelée, le premier objet SQLResult (celui qui a été ajouté le premier à la file d’attente) est renvoyé et supprimé de la file. Lorsqu’il ne reste plus aucun objet SQLResult dans la file d’attente, getResult() renvoie null.

Notez qu’à moins d’être supprimés par un appel de getResult(), les objets SQLResult demeurent dans la file d’attente. Par exemple, si la méthode execute() est appelée plusieurs fois sans appel à getResult(), les objets SQLResult associés à chaque appel execute() restent dans la file d’attente.

Plus d’exemples

Eléments de l’API associés

Récupère la partie suivante d’un jeu de résultats d’instruction SELECT. Si le jeu de résultats ne contient plus aucune ligne, un événement result est distribué, mais aucun autre objet SQLResult n’est ajouté dans la file d’attente getResult().

En mode d’exécution asynchrone, si l’argument responder n’est pas null, l’objet Responder spécifié indique les méthodes appelées pour gérer les résultats de l’opération. Si l’argument responder est null, un événement result est distribué si l’opération est réussie, ou un événement error si l’opération échoue.

Cette méthode ne peut être appelée que si l’instruction est encore en exécution. Lorsque l’instruction est une requête SELECT et qu’un argument prefetch supérieur à zéro est spécifié, l’instruction est censée s’exécuter jusqu’à ce que l’ensemble du jeu du résultats soit renvoyé ou que la méthode SQLStatement.cancel() ouSQLConnection.cancel() soit appelée.

Paramètres

Plus d’exemples

Eléments de l’API associés

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.");
}

Distribué lorsqu’une erreur se produit au cours d’une opération.

Eléments de l’API associés

Distribué lorsque l’opération d’un appel de méthode execute() ou next() se termine avec succès. Une fois que l’événement result est déclenché, la méthode getResult() peut être appelée pour récupérer les résultats de l’instruction.

Eléments de l’API associés