1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
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>
|
