aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorManuel Coutand2012-04-17 11:38:06 (EDT)
committerEugene Tarassov2012-04-17 13:24:33 (EDT)
commit0ab25ec2dd87d63d057b2ff7ce309bf8a6af7098 (patch)
tree072e59ce83de244a529470a8ba0a27f61f282f98
parent8e16f7108454d72421123b1f4d1357a97e076611 (diff)
downloadorg.eclipse.tcf-0ab25ec2dd87d63d057b2ff7ce309bf8a6af7098.zip
org.eclipse.tcf-0ab25ec2dd87d63d057b2ff7ce309bf8a6af7098.tar.gz
org.eclipse.tcf-0ab25ec2dd87d63d057b2ff7ce309bf8a6af7098.tar.bz2
Add html doc for Context Query service
-rwxr-xr-xdocs/TCF Service - Context Query.html250
-rw-r--r--docs/TCF Services.html1
2 files changed, 251 insertions, 0 deletions
diff --git a/docs/TCF Service - Context Query.html b/docs/TCF Service - Context Query.html
new file mode 100755
index 0000000..6271b4b
--- /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>&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>
+<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>
diff --git a/docs/TCF Services.html b/docs/TCF Services.html
index 2895de1..36b269e 100644
--- a/docs/TCF Services.html
+++ b/docs/TCF Services.html
@@ -206,6 +206,7 @@ same way as "OTHER".</p>
<li><a href='TCF Service - Terminals.html'>Terminals Service</a>
<li><a href='TCF Service - Streams.html'>Streams Service</a>
<li><a href='TCF Service - Disassembly.html'>Disassembly Service</a>
+ <li><a href='TCF Service - Context Query.html'>Context Query Service</a>
</ul>
</body>