<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
    <title>Target Communication Framework Services - Context Query</title>
</head>

<body lang='EN-US'>

<h1>Target Communication Framework Services - Context Query</h1>

<ul>
    <li><a href='#VersionHistory'>Version History</a>
    <li><a href='#Overview'>Overview</a>
    <li><a href='#SyntaxandSemantics'>Syntax and Semantics</a>
    <li><a href='#Cmds'>Commands</a>
    <ul>
        <li><a href='#CmdQuery'>Query</a>
        <li><a href='#CmdGetAttrNames'>Get Attribute Names</a>
    </ul>

    <li><a href='#API'>API</a>
</ul>

<h1>Context Query Service</h1>

<h2><a name='VersionHistory'>Version History</a></h2>

<table border=1 cellpadding=8>
    <tr>
        <th>Version
        <th>Date
        <th>Change
    <tr>
        <td>0.1
        <td>2012-04-17
        <td>Initial contribution
</table>

<h2><a name='Overview'>Overview</a></h2>

<p>ContextQuery allows to search for context that match a pattern.</p>

<p>This module implements a query based system to specify subsets of contexts.
The queries specifies context properties and what values they need to have to match.
In addition a query can filter based on a contexts ancestors in the context hierarchy.</p>

<p>A query consists of a sequence of parts separated by "/". This
sequence specifies a path through the context tree. A context matches
the query if the last part of the query matches the properties of the
context and the parent of the context matches the query excluding the
last part. The properties of a context matches a part if each property
specified in the part matches the property of the same name in the
context or if the name of the context matches the string specified in
the part. There are also two wild cards. The part "*" matches any
context. The part "**" matches any sequence of contexts. If the query
starts with a "/" the first part of the query must match a child of
the root of the context tree.</p>

<p>The service uses standard format for error reports,
see <a href='TCF Error Report Format.html'>Error Report Format</a>.</p>

<h2><a name='SyntaxandSemantics'>Syntax and Semantics</a></h2>

<p>Here is how a query should be formed:</p>

<pre><b><font face="Courier New" size=2 color=#333399>
<i>&lt;query&gt;</i> = ['/'], {<i>&lt;part&gt;</i>, '/'}, <i>&lt;part&gt;</i> ;
<i>&lt;part&gt;</i> = <i>&lt;string&gt;</i> | '*' | '**' | <i>&lt;properties&gt;</i> ;
<i>&lt;properties&gt;</i> = <i>&lt;property&gt;</i>, {',', <i>&lt;property&gt;</i>} ;
<i>&lt;property&gt;</i> = <i>&lt;string&gt;</i>, '=', <i>&lt;value&gt;</i> ;
<i>&lt;value&gt;</i> = <i>&lt;string&gt;</i> | <i>&lt;number&gt;</i> | <i>&lt;symbol&gt;</i> ;
<i>&lt;string&gt;</i> = <i>&lt;quoted string&gt;</i> | <i>&lt;symbol&gt;</i> ;
<i>&lt;quoted string&gt;</i> = '"', {any-character - ('"' | '\')|('\'), ('"' | '\')}, '"' ;
<i>&lt;symbol&gt;</i> = <i>&lt;letter&gt;</i>, {<i>&lt;letter&gt;</i> | <i>&lt;digit&gt;</i>} ;
<i>&lt;number&gt;</i> = <i>&lt;digit&gt;</i>, {<i>&lt;digit&gt;</i>} ;
<i>&lt;boolean&gt;</i> = 'true' | 'false' ;
<i>&lt;letter&gt;</i> = ? A-Z, a-z or _ ? ;
<i>&lt;digit&gt;</i> = ? 0-9 ?
<i>&lt;any-character&gt;</i> = ? any character ? ;
</font></b></pre>

<h2><a name='Cmds'>Commands</a></h2>

<h3><a name='CmdQuery'>Query</a></h3>

<pre><b><font face="Courier New" size=2 color=#333399>
C &bull; <i>&lt;token&gt;</i> &bull; ContextQuery &bull; query &bull; <i>&lt;query&gt;</i> &bull;
</font></b></pre>

<p>Execute a context query and return array of matching context IDs.</p>

<p>Reply:</p>

<pre><b><font face="Courier New" size=2 color=#333399>
R &bull; <i>&lt;token&gt;</i> &bull; <i>&lt;error report&gt;</i> &bull; <i>&lt;array of context IDs&gt;</i> &bull;
</font></b></pre>

<p>The contexts are assumed to be placed in a tree. Each context has zero
or one parent. If it has zero parents it is a child of the root of the
tree.</p>

<p><b>Examples:</b></p>

<code>'httpd'</code>
<ul><p>Matches all contexts named "httpd".</p></ul>

<code>'pid=4711'</code>
<ul><p>Matches any context with a property pid, which has the value 4711.</p></ul>

<code>'/server/**'</code>
<ul><p>Matches all contexts which are descendants of the top level context
        named "server".</p></ul>

<code>'"Linux 2.6.14"/Kernel/*'</code>
<ul><p>Matches all kernel processes in operating systems named "Linux 2.6.14".</p></ul>

<code>'pid=4711/*'</code>
<ul><p>All threads in processes with the pid 4711.</p></ul>

<code>'/server/**/HasState=true'</code>
<ul><p>All threads which are descendants of the context "server".</p></ul>

<h3><a name='CmdGetAttrNames'>Get Attributes Names</a></h3>

<pre><b><font face="Courier New" size=2 color=#333399>
C &bull; <i>&lt;token&gt;</i> &bull; ContextQuery &bull; getAttrNames &bull;
</font></b></pre>

<p>Get the list of attribute names available for context queries. The "*"
attribute means that a default attribute comparator exists, in which case,
the back-end may support additional attributes that are not listed in the reply.</p>

<p>Reply:</p>

<pre><b><font face="Courier New" size=2 color=#333399>
R &bull; <i>&lt;token&gt;</i> &bull; <i>&lt;error report&gt;</i> &bull; <i>&lt;array of attributes&gt;</i> &bull;
</font></b></pre>

<h2><a name='API'>API</a></h2>

<pre>
<font color=#3F5FBF>/**
 * ContextQuery allows to search for context that match a pattern.
 *
 * Query Syntax and Semantics
 *
 *        query = [ "/" ], { part, "/" }, part ;
 *        part = string | "*" | "**" | properties ;
 *        properties = property, { ",", property } ;
 *        property = string, "=", value ;
 *        value = string | number | boolean ;
 *        string = quoted string | symbol ;
 *        quoted string = '"', {any-character - ('"' | '\') | ('\', ('"' | '\'))}, '"' ;
 *        symbol = letter, { letter | digit } ;
 *        number = digit, { digit } ;
 *        boolean = "true" | "false" ;
 *        letter = ? A-Z, a-z or _ ? ;
 *        digit = ? 0-9 ? ;
 *        any-character = ? any character ? ;
 *
 * To give a feel for the syntax, here are some examples, and what a user
 * might mean when providing such a query:
 *
 * httpd
 *        Matches all contexts named "httpd".
 *
 * pid=4711
 *        Matches any context with a property pid, which has the value 4711.
 *
 * /server/**
 *        Matches all contexts which are descendants of the top level context
 *        named "server".
 *
 * "Linux 2.6.14"/Kernel/*
 *       Matches all kernel processes in operating systems named "Linux 2.6.14".
 *
 * pid=4711/*
 *        All threads in processes with the pid 4711.
 *
 * /server/** /HasState=true
 *        All threads which are descendants of the context "server".
 *
 * The contexts are assumed to be placed in a tree. Each context has zero
 * or one parent. If it has zero parents it is a child of the root of the
 * tree.
 *
 * A query consists of a sequence of parts separated by "/". This
 * sequence specifies a path through the context tree. A context matches
 * the query if the last part of the query matches the properties of the
 * context and the parent of the context matches the query excluding the
 * last part. The properties of a context matches a part if each property
 * specified in the part matches the property of the same name in the
 * context or if the name of the context matches the string specified in
 * the part. There are also two wild cards. The part "*" matches any
 * context. The part "**" matches any sequence of contexts. If the query
 * starts with a "/" the first part of the query must match a child of
 * the root of the context tree.
 *
 * <font color=#7F9FBF>@noimplement</font> This interface is not intended to be implemented by clients.
 */</font>
<font color=#7F0055>public interface</font> IContextQuery <font color=#7F0055>extends</font> IService {

    <font color=#3F5FBF>/**
     * This service name, as it appears on the wire - a TCF name of the service.
     */</font>
    <font color=#7F0055>static final</font> String NAME = "ContextQuery";

    <font color=#3F5FBF>/**
     * Execute a context query and return array of matching context IDs.
     * <font color=#7F9FBF>@param</font> query - context query string.
     * <font color=#7F9FBF>@param</font> done - command result call back object.
     * <font color=#7F9FBF>@return</font> - pending command handle.
     */</font>
    IToken query(String query, DoneQuery done);

    <font color=#3F5FBF>/**
     * Call back interface for 'query' command.
     */</font>
    <font color=#7F0055>interface</font> DoneQuery {
        <font color=#3F5FBF>/**
         * Called when 'query' command is done.
         * <font color=#7F9FBF>@param</font> token - command handle.
         * <font color=#7F9FBF>@param</font> error - error object or null.
         * <font color=#7F9FBF>@param</font> contexts - array of context IDs.
         */</font>
        <font color=#7F0055>void</font> doneQuery(IToken token, Exception error, String[] contexts);
    }

    <font color=#3F5FBF>/**
     * Get list of attribute names available for context queries.
     * <font color=#7F9FBF>@param</font> done - command result call back object.
     * <font color=#7F9FBF>@return</font> - pending command handle.
     */</font>
    IToken getAttrNames(DoneGetAttrNames done);

    <font color=#3F5FBF>/**
     * Call back interface for 'getAttrNames' command.
     */</font>
    <font color=#7F0055>interface</font> DoneGetAttrNames {
        <font color=#3F5FBF>/**
         * Called when 'query' command is done.
         * <font color=#7F9FBF>@param</font> token - command handle.
         * <font color=#7F9FBF>@param</font> error - error object or null.
         * <font color=#7F9FBF>@param</font> contexts - array of context IDs.
         */</font>
        <font color=#7F0055>void</font> doneGetAttrNames(IToken token, Exception error, String[] names);
    }
}
</pre>

</body>
</html>