Langage d'interrogation de XAM

Aussi bien que fournir des moyens fournisseur-ind�pendants de la cr�ation, recherchant, modifiant et supprimant XSets, les sp�cifications de SNIA XAM v1.0 d�finissent �galement un langage d'interrogation (XAM QL), bas� sur un sous-ensemble de la langue de SQL, parce que de choisir et de rechercher le XUIDs de XSets bas� sur des crit�res contenu-d�finis.

L'ensemble de mots r�serv�s pour ce langage d'interrogation est tout � fait petit : choisissez, o�, et, ou, pas, comme, existe, lier, inalt�rable, typeof, longueur, date, VRAIS, FAUX, avant que, apr�s, contienne, et en dedans. Par conception, les questions de XAM ressemblent � un rapport choisi de SQL. Le langage d'interrogation est ne distinguant pas majuscules et minuscules et emploie le jeu de caract�res d'ASCII.

Voici un exemple d'une question simple de XAM :

select ".xset.xuid" where "com.example.name" = ’Tuckers Plantation'

La version 1.0 des sp�cifications de XAM d�finit deux niveaux d'appui de langage d'interrogation, le niveau 1 c.-�-d. du niveau 1 et du niveau 2. d�finit des questions sur des propri�t�s et des attributs de champ dans XSets et est obligatoire. N'importe quelles valeurs d'une propri�t� de XSet qui sont accessibles � un programme d'application par l'interm�diaire de la biblioth�que de XAM peuvent �tre questionn�es. Le niveau 2 prolonge le niveau 1 aux questions de soutien sur XStreams et est facultatif. Les deux niveaux de question sont acc�d�s par un type simple et d�fini du travail que tous les fournisseurs de XAM doivent soutenir. Puisqu'aucun fournisseur que je me rends compte de n'a des questions du niveau r�ellement mis en application 2, le reste des foyers de ce poteau sur des questions du niveau 1.

Une instruction du langage de requ�tes de XAM se compose d'une clause choisie obligatoire suivie d'un facultatif o� clause. Pour XAM v1.0 la seule clause choisie valide est le `choisi .xset.xuid'. Ceci sp�cifie que l'application demande une liste de valeurs de XUID. Par exemple

select ".xset.xuid "

renverra une liste de chaque XSet qui est lisible � l'heure de la question.

O� la clause est employ�e pour sp�cifier un sous-ensemble de XSets � assortir. Pour des questions du niveau 1 elle est limit�e aux comparaisons entre les propri�t�s de XSet et les valeurs et/ou les attributs de champ litt�raux et les valeurs litt�rales.

select ".xset.xuid" where ".xam.time.xuid" > date(’2009-02-01T00:00:00.0’)

renverra la liste de tout le Xsets qui ont �t� cr��s dessus ou apr�s le 1er f�vrier 2009.

Les expositions suivantes de table qui mettent en place et des types litt�raux peuvent �tre bien compar�s.

Les s�quences d'�chappement soutenues sont les suivantes. N'importe quelle autre s�quence d'�chappement produira d'une erreur non fatale.

select ".xset.xuid" where "com.example.string-property" = ’This is a string literal’

Pour employer une apostrophe dans une corde, gardez-la avec une barre oblique inverse

select ".xset.xuid" where "com.example.claimed.ownership" = ’Tucker\’s’

Tous les exemples des noms de champ dans une corde de question de XAM doivent �tre cit�s avec des guillemets. Si un nom de champ contient des caract�res de guillemets, chaque caract�re de guillemets doit �tre �chapp� utilisant une barre oblique inverse. Par exemple, le nom de champ pour la propri�t� xam_boolean com.example. �� qstring�� devrait �tre repr�sent� dans une question As

select ".xam.xuid" where "com.example.\"qstring\"" = TRUE

Si un nom de champ contient un caract�re de barre oblique inverse, la barre oblique inverse elle-m�me doit �tre �chapp�e avec une autre barre oblique inverse. Par exemple, le nom de champ pour la propri�t� xam_double com.example.file \ rapport devrait �tre repr�sent� dans une question As

select ".xam.xuid" where "com.example.file\\ratio" = 100.1

Le langage d'interrogation accepte date-heure et les coquilles XUID-�valu�es utilisant les fonctions de s�lecteur datent () et xuid () respectivement. La fonction de date () prend une valeur date-heure correctement form�e, sp�cifique car une corde litt�rale qui est compatible aux sp�cifications de date-heure de XAM.

select ".xset.xuid" where ".xam.time.xuid" = date(’2009-06-01T00:00:00.0’)

La fonction de xuid () attend un XUID qui est sous forme de constante de cha�ne cod�e par base64. Une constante de cha�ne incorrectement form�e produit d'une erreur non fatale pendant l'analyse de question.

Des attributs de champ sont acc�d�s utilisant existe, typeof, inalt�rable, attache, et fonctions d'acc�dant d'attribut de champ de longueur. Existe () les essais de fonction pour l'existence d'un attribut de zone identification (propri�t�) dans un XSet. Il �value POUR RECTIFIER si un XSet contient la zone identification autrement qu'elle �value FAUX.

select ".xset.xuid" where exists("com.example.name")

La fonction de typeof () renvoie le type de MIME d'une zone identification dans un XSet qui est une propri�t� corde-�valu�e.

select ".xset.xuid" where typeof("com.example.data") = ’text/plain’
select ".xset.xuid" where typeof("com.example.data") like ’text%’

Cette fonction peut �tre employ�e toutes les fois qu'une application pourrait employer une r�f�rence de champ � une propri�t� corde-�valu�e. Notez que les comparaisons avec n'importe quelle valeur litt�rale de non-corde produisent d'une erreur non fatale pendant l'analyse de la question.

() La fonction inalt�rable �value POUR RECTIFIER quand un champ dans un XSet est marqu� comme inalt�rable.

select ".xset.xuid" where readonly("com.example.flag")
select ".xset.xuid" where not readonly("com.example.name")

() La fonction obligatoire �value POUR RECTIFIER quand un champ dans un XSet est marqu� comme liant.

select ".xset.xuid" where binding("com.example.case_id")
select ".xset.xuid" where not binding("com.example.subject")

La fonction de longueur () renvoie la longueur, en bytes, d'une zone identification.

select ".xset.xuid" where length("com.example.data") > 1024

Une fois utilis� sur la propri�t� met en place des retours de cette fonction la longueur comme d�finie pour des stypes. Notez que cette fonction ne devrait pas �tre employ�e pour comparer le nombre de caract�res dans une corde pendant que cette comparaison d�pend du codage de caract�re �tant employ�.

Se tourner maintenant vers les op�rateurs logiques. Paragraphes dans o� la clause peut �tre combin�e et modifi�e en employant les op�rateurs logiques et, ou et pas. Ces op�rateurs sont semblables � leurs contre-parties de SQL.

Et op�rateur exige des deux paragraphes d'�valuer POUR RECTIFIER avant comprenant un XSet dans les r�sultats. Par exemple

select ".xset.xuid" where typeof("com.example.stream") = ’image/gif’ and length("com.example.stream") > 4096

choisit seulement ces XSets contenant les images de GIF dont la taille est plus grande que 4096 bytes. Ou op�rateur �value POUR RECTIFIER si l'un ou l'autre paragraphe �value POUR RECTIFIER. Par exemple

select ".xset.xuid" where typeof("com.example.stream") = ’image/jpeg’ or typeof("com.example.stream") = ’image/gif’

choisit seulement ces XSets contenant un jet appel� du type JPEG ou GIF d'image. Pas l'op�rateur nie une expression bool�enne. Par exemple

select ".xset.xuid" where not binding("com.example.property")

choisit tout le XSets avec la propri�t� non contraignante com.example.property.

Comme dans certains op�rateurs de SQL ayez la priorit� au-dessus d'autres op�rateurs dans les questions. La priorit� d'op�rateur de XAM QL est comme suit :

select ".xset.xuid" where not "com.example.bool-prop" and  "com.example.int-prop" = 64
select ".xset.xuid" where not ("com.example.bool-prop" and "com.example.int-prop" = 64)

Dans le premier exemple, pas l'op�rateur s'applique seulement � la propri�t� de com.example.bool-prop. Dans le deuxi�me exemple, pas l'op�rateur s'applique � com.example.bool-prop et � com.example.int-prop = 42.

Maintenant que nous sommes quelque peu au courant de la syntaxe de XAM QL, la prochaine question � r�pondre est comment nous disons un syst�me de stockage de XAM d'ex�cuter une question et de nous renvoyer les r�sultats. Bien elle s'av�re qu'une question est ex�cut�e comme un type particulier de travail de XAM a appel� un travail de question. L'entr�e � un travail de question est un XSet que vous devez cr�er. Ce XSet doit contenir deux articles - le mand d'org.snia.xam.job.com de champ qui est toujours plac� au `xam.job.query et � un mand de XStream xam.job.query.com qui est un jet des textes UTF-8 (type texte de MIME de `/plat ; charset=utf-8') contenir la corde r�elle d'expression de question.

Un travail de question peut sur option �tre commis avant ou pendant l'ex�cution du travail, mais ceci commettent n'est pas exig�. La capacit� de commettre un JOB en cours d'ex�cution est personne � charge facultative et d'ex�cution. Une application peut d�terminer si le travail commettent est soutenu en v�rifiant la propri�t� bool�enne .xsystem.job.com mit.supported de XSystem. Le manque de commettre un travail de question avant que la fermeture du XSet signifie les r�sultats du travail de question ne sont pas constamment stock�s.

Un travail de question est ex�cut� en appelant le submitJob. Si l'un ou l'autre des deux articles exig�s dans le travail XSet de question n'est pas correctement compl�t�, le champ standard .xam.job.error d'erreur du travail est ajout� au travail XSet de question et c'est valeur est plac� � l'un ou l'autre org.snia.xam : : not_a_job ou org.snia.xam : : l'unspecified_command et le travail de question est avort�. Suivant les indications de l'application d'�chantillon ci-dessous, l'�tat d'un travail de question peut �tre d�termin� en examinant la valeur de .xam.job.status.

Quand un travail de question est r�ussi, les r�sultats sont stock�s dans le travail XSet de question sous forme de nouveau XStream appel� xam.job.query.results. Ce XStream a un type de MIME d'application/vnd.snia.xam.query.xuid_list et contient le XUIDs pour l'ensemble de XSets r�sultant de l'�valuation de la question. Chaque XUID est stock� dans un format binaire en tant qu'�l�ment d'un disque de 80 octets. Si un XUID est plus court que 80 bytes, le disque est z�ro capitonn� � 80 bytes.

Un certain nombre d'autres propri�t�s concernant les r�sultats XStream sont �galement install�es. La propri�t� xam.job.query.results.count de xam_int contient le compte courant des disques de XUID dans les r�sultats XStream. Cette propri�t� est mise � jour comme r�sultat sont �crits dans les r�sultats XStream pendant le traitement de question. Une application peut employer ceci pour fournir des informations de statut aux utilisateurs pendant que le travail de question s'ex�cute. La propri�t� xam_string xam.job.query.level indique le niveau de question qui assortit les r�sultats. Sa valeur est org.snia.xam.job.query.level.1 ou org.snia.xam.job.query.level.2.

Il est important de se rappeler qu'un travail de question fonctionne dans les r�les et les permissions accord�s au raccordement. Cela signifie que les r�sultats XStream inclut seulement ces XSets qui sont �vidents et accessibles � une application, au moins d'une perspective lue, selon le r�le sous lequel le travail de question est ex�cut�.

Le travail de question peut placer les codes d'erreur suivants dans .xam.job.error :

Notez que, � la diff�rence d'un RDBMS traditionnel, il n'y a aucun verrouillage d'un syst�me de stockage de XAM pendant l'ex�cution d'un travail de question. Ainsi un r�sultat de question n'est pas un instantan� instantan� d'un syst�me de stockage de XAM. Le contenu d'un syst�me de stockage de XAM peut ou peut ne pas changer tandis qu'un travail de question est ex�cut�. La r�gle g�n�rale est qu'aucun XSet qui a �t� stock� avant que le d�but du travail de question soit inclus dans les r�sultats XStream s'il r�pond aux crit�res de question, et aucun XSet qui a �t� stock� apr�s que le travail de question ait accompli ne doit �tre inclus dans les r�sultats XStream. XSets qui sont stock�s pendant l'ex�cution d'une t�che de question peut ou peut ne pas �tre inclus. Les m�mes crit�res s'applique aux r�sultats XStream. Il peut inclure XUIDs de XSets qui ne sont plus dans le syst�me de stockage de XAM et le XUIDs de XSets qui ne r�pondent plus aux crit�res de recherche dus � un changement du XSet apr�s que le d�tail XSet ait �t� questionn�.

Voici une application de Java simple qui questionne un syst�me de stockage de XAM pour le d�terminer est niveau de soutien des questions de XAM.

import org.snia.xam.XAMException;
import org.snia.xam.XAMLibrary;
import org.snia.xam.XSystem;
import org.snia.xam.toolkit.XAMXUID;
import org.snia.xam.util.XAMLibraryFactory;

public class CheckQuerySupport
{
    private static XAMLibrary xamLib;
    private static XSystem xSystem;

    public static void main(String[] args)
    {
        String xri = "snia-xam://centera_vim!XXX.XXXX.XXX.XXX?/home/fpm/xam/xamconnect.pea";

        long exitCode = 0;
        boolean isSupported = false;

        try
        {
            xamLib = XAMLibraryFactory.newXAMLibrary();
            System.out.println("Connecting to XSystem: " + xri + "\n");

            xSystem = xamLib.connect(xri);

            // support job commit?
            isSupported = xSystem.getBoolean(XSystem.XAM_XSYSTEM_JOB_COMMIT_SUPPORTED);
            System.out.println("Support job commit? " + (isSupported ? "Yes" : "No"));

            // support continuance of job?
            isSupported = xSystem.getBoolean(XSystem.XAM_XSYSTEM_JOB_QUERY_CONTINUANCE_SUPPORTED);
            System.out.println("Support job continuance? " + (isSupported ? "Yes" : "No"));

            // support level 1 query?
            isSupported = xSystem.getBoolean(XSystem.XAM_XSYSTEM_JOB_QUERY_LEVEL1_SUPPORTED);
            System.out.println("Support level 1 query? " + (isSupported ? "Yes" : "No"));

            // support level 2 query?
            isSupported = xSystem.getBoolean(XSystem.XAM_XSYSTEM_JOB_QUERY_LEVEL2_SUPPORTED);
            System.out.println("Support level 2 query? " + (isSupported ? "Yes" : "No"));

            xSystem.close();
            System.out.println("\nClosed connection to XSystem");

        } catch (XAMException xe) {
            exitCode = xe.getStatusCode();
            System.err.println("XAM Error occured: " + xe.getMessage());
        } catch (IllegalArgumentException e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
            exitCode = 1;
        }

        System.exit((int) exitCode);
    }
}

Voici le rendement de cette application une fois reli� � un syst�me de stockage d'EMC Centera XAM

Connecting to XSystem: snia-xam://centera_vim!XXX.XXX.XXX.XXX?/home/fpm/xam/xamconnect.pea

Support job commit? No
Support job continuance? No
Support level 1 query? Yes
Support level 2 query? No

Closed connection to XSystem

Voici une plus longue application de Java qui met en application trois l'�chantillon XSets et les questions d'�chantillon qui sont discut�s dans la section 10.8 du document de l'architecture V1.0 de XAM.

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;

import org.snia.xam.XAMException;
import org.snia.xam.XAMLibrary;
import org.snia.xam.XSet;
import org.snia.xam.XStream;
import org.snia.xam.XSystem;
import org.snia.xam.XUID;
import org.snia.xam.toolkit.XAMXUID;
import org.snia.xam.util.XAMLibraryFactory;

public class QueryExample
{
    private static XAMLibrary xamLib;
    private static XSystem xSystem;

    private static void CreateXset(int parm1, String parm2, double parm3)
             throws XAMException
    {
        System.out.print("Create XSet 1 ....  ");

        XSet xSet = xSystem.createXSet(XSet.MODE_UNRESTRICTED);
        xSet.createProperty("com.example.rhc", false, true);
        xSet.createProperty("com,example.foo", false, parm1);
        xSet.createProperty("com.example.bar", false, parm2);
        xSet.createProperty("com.example.num", false, parm3);

        XUID xuID = xSet.commit();
        System.out.println("XUID: " + xuID.toString());

        xSet.close();
    }

   private static void CreateXset(int parm1, int parm2, int parm3)
             throws XAMException
    {
        System.out.print("Create XSet 2 ....  ");

        XSet xSet = xSystem.createXSet(XSet.MODE_UNRESTRICTED);
        xSet.createProperty("com.example.rhc", false, true);
        xSet.createProperty("com,example.foo", false, parm1);
        xSet.createProperty("com.example.bar", false, parm2);
        xSet.createProperty("com.example.num", false, parm3);

        XUID xuID = xSet.commit();
        System.out.println("XUID: " + xuID.toString());

        xSet.close();
    }

    private static void CreateXset(int parm1, int parm2)
             throws XAMException
    {
        System.out.print("Create XSet 3 ....  ");

        XSet xSet = xSystem.createXSet(XSet.MODE_UNRESTRICTED);
        xSet.createProperty("com.example.rhc", false, true);
        xSet.createProperty("com,example.foo", false, parm1);
        xSet.createProperty("com.example.num", false, parm2);

        XUID xuID = xSet.commit();
        System.out.println("XUID: " + xuID.toString());

        xSet.close();
    }

    private static void QueryXsystem(String queryString)
            throws XAMException
    {
        boolean finished = false;
        final int XAM_MAX_XUID = 80;
        int resultCount = 0;
        String status;

        System.out.println("Create query XSet. Query string: " + queryString);

        XSet query = xSystem.createXSet(XSet.MODE_UNRESTRICTED);
        query.createProperty(XSet.XAM_JOB_COMMAND, true, XSet.XAM_JOB_QUERY);

        byte[] buffer = queryString.getBytes();
        XStream queryStream = query.createXStream(XSet.XAM_JOB_QUERY_COMMAND, true, XAMLibrary.TEXT_PLAIN_MIME_TYPE);
        queryStream.write(buffer);
        queryStream.close();

        System.out.println("Submit query job ....");
        query.submitJob();

        System.out.println("Wait for query job to finish ....");

        while (!finished)
        {
            // check  status of query job
            status = query.getString(XSet.XAM_JOB_ERRORHEALTH);
            if (status.equals(XSet.XAM_JOB_ERRORHEALTH_ERROR))
            {
                System.out.println("ERROR: Errorhealth - " + query.getString(XSet.XAM_JOB_ERROR));
                query.haltJob();
                System.out.println("ERROR: Job halted");
                break;
            }

            status = query.getString(XSet.XAM_JOB_STATUS);
            resultCount = (int) query.getLong(XSet.XAM_JOB_QUERY_RESULTS_COUNT);

            // uncomment if you want continuous job status
            // System.out.println("Job Status: " + status + "  Result count: " + resultCount);

            // exit loop if job complete
            if (status.equals(XSet.XAM_JOB_STATUS_COMPLETE))
            {
                finished = true;
            }
       }

        System.out.println("Query job completed ....");
        System.out.println("Result set final count is: " + resultCount);

        if (resultCount > 0)
        {
             // open query job result stream
             XStream results = query.openXStream(XSet.XAM_JOB_QUERY_RESULTS, XStream.MODE_READ_ONLY);

             byte rawXUID[] = new byte[XAM_MAX_XUID];
             long bytesRead = 0;

             // output XUIDs in result set
             while( (bytesRead = results.read(rawXUID, XAM_MAX_XUID)) >= 0 )
             {
                 XAMXUID resultXUID = new XAMXUID(rawXUID);
                 System.out.println("XUID: " + resultXUID.toString());
             }

             results.close();
        }

        query.close();
    }

    public static void main(String[] args)
    {
        String xri = "snia-xam://centera_vim!XXX.XXX.XXX.XXX?/home/fpm/xam/xamconnect.pea";
        long exitCode = 0;

        try
        {
            xamLib = XAMLibraryFactory.newXAMLibrary();

            // uncomment next 2 lines if you want extensive XAM Library logging
            // xamLib.setProperty(XAMLibrary.XAM_LOG_VERBOSITY, 1);
            // xamLib.setProperty(XAMLibrary.XAM_LOG_LEVEL, 5);

            System.out.println("Connecting to XSystem " +  xri + "\n");

            xSystem = xamLib.connect(xri);
            xSystem.setProperty(".xsystem.log.verbosity", 1);
            xSystem.setProperty(".xsystem.log.level", 5);

            CreateXset(1, "string", 123.55);
            CreateXset(77, 42, 100);
            CreateXset(6, 200);

            xSystem.close();

            System.out.println("\nClose/reopen XSystem\n");

            xSystem = xamLib.connect(xri);

            // uncomment one or more of the following queries
            // QueryXsystem("select \".xset.xuid\"");
            QueryXsystem("select \".xset.xuid\" where (\"com.example.foo\" > 0) and (\"com.example.foo\" < 50)");
            // QueryXsystem("select \".xset.xuid\" where (\"com.example.bar\" > 0) and (\"com.example.bar\" < 100)");
            // QueryXsystem("select \".xset.xuid\" where exists (\"com.example.bar\")");
            // QueryXsystem("select \".xset.xuid\" where \"com.example.bar\" like '%ing%'");
            // QueryXsystem("select \".xset.xuid\" where \"com.example.num\" >= 124");
            // QueryXsystem("select \".xset.xuid\" where \"com.example.num\" >= 124.6 ");
            // QueryXsystem("select \".xset.xuid\" where (\"com.example.num\" >= 123) and typeof(\"com.example.num\") = 'application/vnd.snia.xam.int'");

            xSystem.close();
            System.out.println("\nClosed connection to XSystem");

        } catch (XAMException xe) {
            exitCode = xe.getStatusCode();
            System.err.println("XAM Error occured: " + xe.getMessage() + "("
                    + exitCode + ")");
        } catch (IllegalArgumentException e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
            exitCode = -1;
        }

        System.exit((int) exitCode);
    }
}

Notez que des r�sultats XStream produit par un travail de question peuvent �tre consomm�s par une application avant que le syst�me de stockage de XAM ait fini de stocker tout les XUIDs dans les r�sultats XStream si XStream.asyncRead est employ� au lieu de XStream.read.

Bien je pense que j'ai fourni assez d'information et d'exemples pour te permettre d'aller jeu avec le langage d'interrogation de XAM par vous-m�me. Il vous a besoin de l'aide je suis s�r que le groupe de r�alisateur de XAM sur des groupes de Google sera davantage qu'heureux de vous aider.

Dans le d�part je pr�ciserais que puisque des fournisseurs de syst�me de stockage de XAM actuellement sont seulement exig�s pour mettre en application le soutien des questions au-dessus des m�ta-donn�es contentes, je suspecte que le soutien des recherches compl�tement contenu-bas�es r�elles utilisant XAM puisse ne pas se produire pendant quelque temps.