| <!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> |