diff options
Diffstat (limited to 'docs/TCF Service - Context Query.html')
| -rwxr-xr-x | docs/TCF Service - Context Query.html | 250 |
1 files changed, 250 insertions, 0 deletions
diff --git a/docs/TCF Service - Context Query.html b/docs/TCF Service - Context Query.html new file mode 100755 index 000000000..6271b4bd1 --- /dev/null +++ b/docs/TCF Service - Context Query.html @@ -0,0 +1,250 @@ +<!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 Services.html#ErrorFormat'>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><query></i> = ['/'], {<i><part></i>, '/'}, <i><part></i> ; +<i><part></i> = <i><string></i> | '*' | '**' | <i><properties></i> ; +<i><properties></i> = <i><property></i>, {',', <i><property></i>} ; +<i><property></i> = <i><string></i>, '=', <i><value></i> ; +<i><value></i> = <i><string></i> | <i><number></i> | <i><symbol></i> ; +<i><string></i> = <i><quoted string></i> | <i><symbol></i> ; +<i><quoted string></i> = '"', {any-character - ('"' | '\')|('\'), ('"' | '\')}, '"' ; +<i><symbol></i> = <i><letter></i>, {<i><letter></i> | <i><digit></i>} ; +<i><number></i> = <i><digit></i>, {<i><digit></i>} ; +<i><boolean></i> = 'true' | 'false' ; +<i><letter></i> = ? A-Z, a-z or _ ? ; +<i><digit></i> = ? 0-9 ? +<i><any-character></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 • <i><token></i> • ContextQuery • query • <i><query></i> • +</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 • <i><token></i> • <i><error report></i> • <i><array of context IDs></i> • +</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 • <i><token></i> • ContextQuery • getAttrNames • +</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 • <i><token></i> • <i><error report></i> • <i><array of attributes></i> • +</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> +<font color=#7F0055>public interface</font> IContextQuery <font color=#7F0055>extends</font> IService { + + <font color=#3F5FBF>/** + * Service name. + */</font> + <font color=#7F0055>static final</font> String NAME = "ContextQuery"; + + <font color=#3F5FBF>/** + * Execute a context query and return array of matching context IDs. + * @param query - context query string. + * @param done - command result call back object. + * @return - 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. + * @param token - command handle. + * @param error - error object or null. + * @param 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. + * @param done - command result call back object. + * @return - 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. + * @param token - command handle. + * @param error - error object or null. + * @param contexts - array of context IDs. + */</font> + <font color=#7F0055>void</font> doneGetAttrNames(IToken token, Exception error, String[] names); + } +} +</pre> + +</body> +</html> |