1 /*
2 * Copyright 1999-2005 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.management;
27
28
29 /**
30 * <p>Constructs query object constraints.</p>
31 *
32 * <p>The MBean Server can be queried for MBeans that meet a particular
33 * condition, using its {@link MBeanServer#queryNames queryNames} or
34 * {@link MBeanServer#queryMBeans queryMBeans} method. The {@link QueryExp}
35 * parameter to the method can be any implementation of the interface
36 * {@code QueryExp}, but it is usually best to obtain the {@code QueryExp}
37 * value by calling the static methods in this class. This is particularly
38 * true when querying a remote MBean Server: a custom implementation of the
39 * {@code QueryExp} interface might not be present in the remote MBean Server,
40 * but the methods in this class return only standard classes that are
41 * part of the JMX implementation.</p>
42 *
43 * <p>There are two ways to create {@code QueryExp} objects using the methods
44 * in this class. The first is to build them by chaining together calls to
45 * the various methods. The second is to use the Query Language described
46 * <a href="#ql">below</a> and produce the {@code QueryExp} by calling
47 * {@link #fromString Query.fromString}. The two ways are equivalent:
48 * every {@code QueryExp} returned by {@code fromString} can also be
49 * constructed by chaining method calls.</p>
50 *
51 * <p>As an example, suppose you wanted to find all MBeans where the {@code
52 * Enabled} attribute is {@code true} and the {@code Owner} attribute is {@code
53 * "Duke"}. Here is how you could construct the appropriate {@code QueryExp} by
54 * chaining together method calls:</p>
55 *
56 * <pre>
57 * QueryExp query =
58 * Query.and(Query.eq(Query.attr("Enabled"), Query.value(true)),
59 * Query.eq(Query.attr("Owner"), Query.value("Duke")));
60 * </pre>
61 *
62 * <p>Here is how you could construct the same {@code QueryExp} using the
63 * Query Language:</p>
64 *
65 * <pre>
66 * QueryExp query = Query.fromString("Enabled = true and Owner = 'Duke'");
67 * </pre>
68 *
69 * <p>The principal advantage of the method-chaining approach is that the
70 * compiler will check that the query makes sense. The principal advantage
71 * of the Query Language approach is that it is easier to write and especially
72 * read.</p>
73 *
74 *
75 * <h4 id="ql">Query Language</h4>
76 *
77 * <p>The query language is closely modeled on the WHERE clause of
78 * SQL SELECT statements. The formal specification of the language
79 * appears <a href="#formal-ql">below</a>, but it is probably easier to
80 * understand it with examples such as the following.</p>
81 *
82 * <dl>
83 * <dt>{@code Message = 'OK'}
84 * <dd>Selects MBeans that have a {@code Message} attribute whose value
85 * is the string {@code OK}.
86 *
87 * <dt>{@code FreeSpacePercent < 10}
88 * <dd>Selects MBeans that have a {@code FreeSpacePercent} attribute whose
89 * value is a number less than 10.
90 *
91 * <dt>{@code FreeSpacePercent < 10 and WarningSent = false}
92 * <dd>Selects the same MBeans as the previous example, but they must
93 * also have a boolean attribute {@code WarningSent} whose value
94 * is false.
95 *
96 * <dt>{@code SpaceUsed > TotalSpace * (2.0 / 3.0)}
97 * <dd>Selects MBeans that have {@code SpaceUsed} and {@code TotalSpace}
98 * attributes where the first is more than two-thirds the second.
99 *
100 * <dt>{@code not (FreeSpacePercent between 10 and 90)}
101 * <dd>Selects MBeans that have a {@code FreeSpacePercent} attribute whose
102 * value is not between 10 and 90, inclusive.
103 *
104 * <dt>{@code FreeSpacePercent not between 10 and 90}
105 * <dd>Another way of writing the previous query.
106 *
107 * <dt>{@code Status in ('STOPPED', 'STARTING', 'STARTED')}
108 * <dd>Selects MBeans that have a {@code Status} attribute whose value
109 * is one of those three strings.
110 *
111 * <dt>{@code Message like 'OK: %'}
112 * <dd>Selects MBeans that have a {@code Message} attribute whose value
113 * is a string beginning with {@code "OK: "}. <b>Notice that the
114 * wildcard characters are SQL's ones.</b> In the query language,
115 * {@code %} means "any sequence of characters" and {@code _}
116 * means "any single character". In the rest of the JMX API, these
117 * correspond to {@code *} and {@code %} respectively.
118 *
119 * <dt>{@code instanceof 'javax.management.NotificationBroadcaster'}
120 * <dd>Selects MBeans that are instances of
121 * {@link javax.management.NotificationBroadcaster}, as reported by
122 * {@link javax.management.MBeanServer#isInstanceOf MBeanServer.isInstanceOf}.
123 *
124 * <dt>{@code like 'mydomain:*'}
125 * <dd>Selects MBeans whose {@link ObjectName}s have the domain {@code mydomain}.
126 *
127 * </dl>
128 *
129 * <p>The last two examples do not correspond to valid SQL syntax, but all
130 * the others do.</p>
131 *
132 * <p>The remainder of this description is a formal specification of the
133 * query language.</p>
134 *
135 *
136 * <h4 id="formal-ql">Lexical elements</h4>
137 *
138 * <p>Keywords such as <b>and</b>, <b>like</b>, and <b>between</b> are not
139 * case sensitive. You can write <b>between</b>, <b>BETWEEN</b>, or
140 * <b>BeTwEeN</b> with the same effect.</p>
141 *
142 * <p>On the other hand, attribute names <i>are</i> case sensitive. The
143 * attribute {@code Name} is not the same as the attribute {@code name}.</p>
144 *
145 * <p>To access an attribute whose name, ignoring case, is the same as one of
146 * the keywords {@code not}, {@code instanceof}, {@code like}, {@code true},
147 * or {@code false}, you can use double quotes, for example {@code "not"}.
148 * Double quotes can also be used to include non-identifier characters in
149 * the name of an attribute, for example {@code "attribute-name-with-hyphens"}.
150 * To include the double quote character in the attribute name, write it
151 * twice. {@code "foo""bar""baz"} represents the attribute called
152 * {@code foo"bar"baz}.
153 *
154 * <p>String constants are written with single quotes like {@code 'this'}. A
155 * single quote within a string constant must be doubled, for example
156 * {@code 'can''t'}.</p>
157 *
158 * <p>Integer constants are written as a sequence of decimal digits,
159 * optionally preceded by a plus or minus sign. An integer constant must be
160 * a valid input to {@link Long#valueOf(String)}.</p>
161 *
162 * <p>Floating-point constants are written using the Java syntax. A
163 * floating-point constant must be a valid input to
164 * {@link Double#valueOf(String)}.</p>
165 *
166 * <p>A boolean constant is either {@code true} or {@code false}, ignoring
167 * case.</p>
168 *
169 * <p>Spaces cannot appear inside identifiers (unless written with double
170 * quotes) or keywords or multi-character tokens such as {@code <=}. Spaces can
171 * appear anywhere else, but are not required except to separate tokens. For
172 * example, the query {@code a < b and 5 = c} could also be written {@code a<b
173 * and 5=c}, but no further spaces can be removed.</p>
174 *
175 *
176 * <h4 id="grammar-ql">Grammar</h4>
177 *
178 * <dl>
179 * <dt id="query">query:
180 * <dd><a href="#andquery">andquery</a> [<b>OR</b> <a href="#query">query</a>]
181 *
182 * <dt id="andquery">andquery:
183 * <dd><a href="#predicate">predicate</a> [<b>AND</b> <a href="#andquery">andquery</a>]
184 *
185 * <dt id="predicate">predicate:
186 * <dd><b>(</b> <a href="#query">query</a> <b>)</b> |<br>
187 * <b>NOT</b> <a href="#predicate">predicate</a> |<br>
188 * <b>INSTANCEOF</b> <a href="#stringvalue">stringvalue</a> |<br>
189 * <b>LIKE</b> <a href="#objectnamepattern">objectnamepattern</a> |<br>
190 * <a href="#value">value</a> <a href="#predrhs">predrhs</a>
191 *
192 * <dt id="predrhs">predrhs:
193 * <dd><a href="#compare">compare</a> <a href="#value">value</a> |<br>
194 * [<b>NOT</b>] <b>BETWEEN</b> <a href="#value">value</a> <b>AND</b>
195 * <a href="#value">value</a> |<br>
196 * [<b>NOT</b>] <b>IN (</b> <a href="#value">value</a>
197 * <a href="#commavalues">commavalues</a> <b>)</b> |<br>
198 * [<b>NOT</b>] <b>LIKE</b> <a href="#stringvalue">stringvalue</a>
199 *
200 * <dt id="commavalues">commavalues:
201 * <dd>[ <b>,</b> <a href="#value">value</a> <a href="#commavalues">commavalues</a> ]
202 *
203 * <dt id="compare">compare:
204 * <dd><b>=</b> | <b><</b> | <b>></b> |
205 * <b><=</b> | <b>>=</b> | <b><></b> | <b>!=</b>
206 *
207 * <dt id="value">value:
208 * <dd><a href="#factor">factor</a> [<a href="#plusorminus">plusorminus</a>
209 * <a href="#value">value</a>]
210 *
211 * <dt id="plusorminus">plusorminus:
212 * <dd><b>+</b> | <b>-</b>
213 *
214 * <dt id="factor">factor:
215 * <dd><a href="#term">term</a> [<a href="#timesordivide">timesordivide</a>
216 * <a href="#factor">factor</a>]
217 *
218 * <dt id="timesordivide">timesordivide:
219 * <dd><b>*</b> | <b>/</b>
220 *
221 * <dt id="term">term:
222 * <dd><a href="#attr">attr</a> | <a href="#literal">literal</a> |
223 * <b>(</b> <a href="#value">value</a> <b>)</b>
224 *
225 * <dt id="attr">attr:
226 * <dd><a href="#name">name</a> [<b>#</b> <a href="#name">name</a>]
227 *
228 * <dt id="name">name:
229 * <dd><a href="#identifier">identifier</a> [<b>.</b><a href="#name">name</a>]
230 *
231 * <dt id="identifier">identifier:
232 * <dd><i>Java-identifier</i> | <i>double-quoted-identifier</i>
233 *
234 * <dt id="literal">literal:
235 * <dd><a href="#booleanlit">booleanlit</a> | <i>longlit</i> |
236 * <i>doublelit</i> | <i>stringlit</i>
237 *
238 * <dt id="booleanlit">booleanlit:
239 * <dd><b>FALSE</b> | <b>TRUE</b>
240 *
241 * <dt id="stringvalue">stringvalue:
242 * <dd><i>stringlit</i>
243 *
244 * <dt id="objectnamepattern">objectnamepattern:
245 * <dd><i>stringlit</i>
246 *
247 * </dl>
248 *
249 *
250 * <h4>Semantics</h4>
251 *
252 * <p>The meaning of the grammar is described in the table below.
253 * This defines a function <i>q</i> that maps a string to a Java object
254 * such as a {@link QueryExp} or a {@link ValueExp}.</p>
255 *
256 * <table border="1" cellpadding="5">
257 * <tr><th>String <i>s</i></th><th><i>q(s)</th></tr>
258 *
259 * <tr><td><i>query1</i> <b>OR</b> <i>query2</i>
260 * <td>{@link Query#or Query.or}(<i>q(query1)</i>, <i>q(query2)</i>)
261 *
262 * <tr><td><i>query1</i> <b>AND</b> <i>query2</i>
263 * <td>{@link Query#and Query.and}(<i>q(query1)</i>, <i>q(query2)</i>)
264 *
265 * <tr><td><b>(</b> <i>queryOrValue</i> <b>)</b>
266 * <td><i>q(queryOrValue)</i>
267 *
268 * <tr><td><b>NOT</b> <i>query</i>
269 * <td>{@link Query#not Query.not}(<i>q(query)</i>)
270 *
271 * <tr><td><b>INSTANCEOF</b> <i>stringLiteral</i>
272 * <td>{@link Query#isInstanceOf Query.isInstanceOf}(<!--
273 * -->{@link Query#value(String) Query.value}(<i>q(stringLiteral)</i>))
274 *
275 * <tr><td><b>LIKE</b> <i>stringLiteral</i>
276 * <td>{@link ObjectName#ObjectName(String) new ObjectName}(<!--
277 * --><i>q(stringLiteral)</i>)
278 *
279 * <tr><td><i>value1</i> <b>=</b> <i>value2</i>
280 * <td>{@link Query#eq Query.eq}(<i>q(value1)</i>, <i>q(value2)</i>)
281 *
282 * <tr><td><i>value1</i> <b><</b> <i>value2</i>
283 * <td>{@link Query#lt Query.lt}(<i>q(value1)</i>, <i>q(value2)</i>)
284 *
285 * <tr><td><i>value1</i> <b>></b> <i>value2</i>
286 * <td>{@link Query#gt Query.gt}(<i>q(value1)</i>, <i>q(value2)</i>)
287 *
288 * <tr><td><i>value1</i> <b><=</b> <i>value2</i>
289 * <td>{@link Query#leq Query.leq}(<i>q(value1)</i>, <i>q(value2)</i>)
290 *
291 * <tr><td><i>value1</i> <b>>=</b> <i>value2</i>
292 * <td>{@link Query#geq Query.geq}(<i>q(value1)</i>, <i>q(value2)</i>)
293 *
294 * <tr><td><i>value1</i> <b><></b> <i>value2</i>
295 * <td>{@link Query#not Query.not}({@link Query#eq Query.eq}(<!--
296 * --><i>q(value1)</i>, <i>q(value2)</i>))
297 *
298 * <tr><td><i>value1</i> <b>!=</b> <i>value2</i>
299 * <td>{@link Query#not Query.not}({@link Query#eq Query.eq}(<!--
300 * --><i>q(value1)</i>, <i>q(value2)</i>))
301 *
302 * <tr><td><i>value1</i> <b>BETWEEN</b> <i>value2</i> AND <i>value3</i>
303 * <td>{@link Query#between Query.between}(<i>q(value1)</i>,
304 * <i>q(value2)</i>, <i>q(value3)</i>)
305 *
306 * <tr><td><i>value1</i> <b>NOT BETWEEN</b> <i>value2</i> AND <i>value3</i>
307 * <td>{@link Query#not Query.not}({@link Query#between Query.between}(<!--
308 * --><i>q(value1)</i>, <i>q(value2)</i>, <i>q(value3)</i>))
309 *
310 * <tr><td><i>value1</i> <b>IN (</b> <i>value2</i>, <i>value3</i> <b>)</b>
311 * <td>{@link Query#in Query.in}(<i>q(value1)</i>,
312 * <code>new ValueExp[] {</code>
313 * <i>q(value2)</i>, <i>q(value3)</i><code>}</code>)
314 *
315 * <tr><td><i>value1</i> <b>NOT IN (</b> <i>value2</i>, <i>value3</i> <b>)</b>
316 * <td>{@link Query#not Query.not}({@link Query#in Query.in}(<i>q(value1)</i>,
317 * <code>new ValueExp[] {</code>
318 * <i>q(value2)</i>, <i>q(value3)</i><code>}</code>))
319 *
320 * <tr><td><i>value</i> <b>LIKE</b> <i>stringLiteral</i>
321 * <td>{@link Query#match Query.match}(<i>q(value)</i>,
322 * <i><a href="#translateWildcards">translateWildcards</a>(q(stringLiteral))</i>)
323 *
324 * <tr><td><i>value</i> <b>NOT LIKE</b> <i>stringLiteral</i>
325 * <td>{@link Query#not Query.not}({@link Query#match Query.match}(<i>q(value)</i>,
326 * <i><a href="#translateWildcards">translateWildcards</a>(q(stringLiteral))</i>))
327 *
328 * <tr><td><i>value1</i> <b>+</b> <i>value2</i>
329 * <td>{@link Query#plus Query.plus}(<i>q(value1)</i>, <i>q(value2)</i>)
330 *
331 * <tr><td><i>value1</i> <b>-</b> <i>value2</i>
332 * <td>{@link Query#minus Query.minus}(<i>q(value1)</i>, <i>q(value2)</i>)
333 *
334 * <tr><td><i>value1</i> <b>*</b> <i>value2</i>
335 * <td>{@link Query#times Query.times}(<i>q(value1)</i>, <i>q(value2)</i>)
336 *
337 * <tr><td><i>value1</i> <b>/</b> <i>value2</i>
338 * <td>{@link Query#div Query.div}(<i>q(value1)</i>, <i>q(value2)</i>)
339 *
340 * <tr><td><i>name</i>
341 * <td>{@link Query#attr(String) Query.attr}(<i>q(name)</i>)
342 *
343 * <tr><td><i>name1<b>#</b>name2</i>
344 * <td>{@link Query#attr(String,String) Query.attr}(<i>q(name1)</i>,
345 * <i>q(name2)</i>)
346 *
347 * <tr><td><b>FALSE</b>
348 * <td>{@link Query#value(boolean) Query.value}(false)
349 *
350 * <tr><td><b>TRUE</b>
351 * <td>{@link Query#value(boolean) Query.value}(true)
352 *
353 * <tr><td><i>decimalLiteral</i>
354 * <td>{@link Query#value(long) Query.value}(<!--
355 * -->{@link Long#valueOf(String) Long.valueOf}(<i>decimalLiteral</i>))
356 *
357 * <tr><td><i>floatingPointLiteral</i>
358 * <td>{@link Query#value(double) Query.value}(<!--
359 * -->{@link Double#valueOf(String) Double.valueOf}(<!--
360 * --><i>floatingPointLiteral</i>))
361 * </table>
362 *
363 * <p id="translateWildcards">Here, <i>translateWildcards</i> is a function
364 * that translates from the SQL notation for wildcards, using {@code %} and
365 * {@code _}, to the JMX API notation, using {@code *} and {@code ?}. If the
366 * <b>LIKE</b> string already contains {@code *} or {@code ?}, these characters
367 * have their literal meanings, and will be quoted in the call to
368 * {@link Query#match Query.match}.</p>
369 *
370 * @since 1.5
371 */
372 public class Query extends Object {
373
374
375 /**
376 * A code representing the {@link Query#gt} query. This is chiefly
377 * of interest for the serialized form of queries.
378 */
379 public static final int GT = 0;
380
381 /**
382 * A code representing the {@link Query#lt} query. This is chiefly
383 * of interest for the serialized form of queries.
384 */
385 public static final int LT = 1;
386
387 /**
388 * A code representing the {@link Query#geq} query. This is chiefly
389 * of interest for the serialized form of queries.
390 */
391 public static final int GE = 2;
392
393 /**
394 * A code representing the {@link Query#leq} query. This is chiefly
395 * of interest for the serialized form of queries.
396 */
397 public static final int LE = 3;
398
399 /**
400 * A code representing the {@link Query#eq} query. This is chiefly
401 * of interest for the serialized form of queries.
402 */
403 public static final int EQ = 4;
404
405
406 /**
407 * A code representing the {@link Query#plus} expression. This
408 * is chiefly of interest for the serialized form of queries.
409 */
410 public static final int PLUS = 0;
411
412 /**
413 * A code representing the {@link Query#minus} expression. This
414 * is chiefly of interest for the serialized form of queries.
415 */
416 public static final int MINUS = 1;
417
418 /**
419 * A code representing the {@link Query#times} expression. This
420 * is chiefly of interest for the serialized form of queries.
421 */
422 public static final int TIMES = 2;
423
424 /**
425 * A code representing the {@link Query#div} expression. This is
426 * chiefly of interest for the serialized form of queries.
427 */
428 public static final int DIV = 3;
429
430
431 /**
432 * Basic constructor.
433 */
434 public Query() {
435 }
436
437
438 /**
439 * Returns a query expression that is the conjunction of two other query
440 * expressions.
441 *
442 * @param q1 A query expression.
443 * @param q2 Another query expression.
444 *
445 * @return The conjunction of the two arguments. The returned object
446 * will be serialized as an instance of the non-public class {@link
447 * <a href="../../serialized-form.html#javax.management.AndQueryExp">
448 * javax.management.AndQueryExp</a>}.
449 */
450 public static QueryExp and(QueryExp q1, QueryExp q2) {
451 return new AndQueryExp(q1, q2);
452 }
453
454 /**
455 * Returns a query expression that is the disjunction of two other query
456 * expressions.
457 *
458 * @param q1 A query expression.
459 * @param q2 Another query expression.
460 *
461 * @return The disjunction of the two arguments. The returned object
462 * will be serialized as an instance of the non-public class {@link
463 * <a href="../../serialized-form.html#javax.management.OrQueryExp">
464 * javax.management.OrQueryExp</a>}.
465 */
466 public static QueryExp or(QueryExp q1, QueryExp q2) {
467 return new OrQueryExp(q1, q2);
468 }
469
470 /**
471 * Returns a query expression that represents a "greater than" constraint on
472 * two values.
473 *
474 * @param v1 A value expression.
475 * @param v2 Another value expression.
476 *
477 * @return A "greater than" constraint on the arguments. The
478 * returned object will be serialized as an instance of the
479 * non-public class {@link <a
480 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
481 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
482 * to {@link #GT}.
483 */
484 public static QueryExp gt(ValueExp v1, ValueExp v2) {
485 return new BinaryRelQueryExp(GT, v1, v2);
486 }
487
488 /**
489 * Returns a query expression that represents a "greater than or equal
490 * to" constraint on two values.
491 *
492 * @param v1 A value expression.
493 * @param v2 Another value expression.
494 *
495 * @return A "greater than or equal to" constraint on the
496 * arguments. The returned object will be serialized as an
497 * instance of the non-public class {@link <a
498 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
499 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
500 * to {@link #GE}.
501 */
502 public static QueryExp geq(ValueExp v1, ValueExp v2) {
503 return new BinaryRelQueryExp(GE, v1, v2);
504 }
505
506 /**
507 * Returns a query expression that represents a "less than or equal to"
508 * constraint on two values.
509 *
510 * @param v1 A value expression.
511 * @param v2 Another value expression.
512 *
513 * @return A "less than or equal to" constraint on the arguments.
514 * The returned object will be serialized as an instance of the
515 * non-public class {@link <a
516 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
517 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
518 * to {@link #LE}.
519 */
520 public static QueryExp leq(ValueExp v1, ValueExp v2) {
521 return new BinaryRelQueryExp(LE, v1, v2);
522 }
523
524 /**
525 * Returns a query expression that represents a "less than" constraint on
526 * two values.
527 *
528 * @param v1 A value expression.
529 * @param v2 Another value expression.
530 *
531 * @return A "less than" constraint on the arguments. The
532 * returned object will be serialized as an instance of the
533 * non-public class {@link <a
534 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
535 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
536 * to {@link #LT}.
537 */
538 public static QueryExp lt(ValueExp v1, ValueExp v2) {
539 return new BinaryRelQueryExp(LT, v1, v2);
540 }
541
542 /**
543 * Returns a query expression that represents an equality constraint on
544 * two values.
545 *
546 * @param v1 A value expression.
547 * @param v2 Another value expression.
548 *
549 * @return A "equal to" constraint on the arguments. The
550 * returned object will be serialized as an instance of the
551 * non-public class {@link <a
552 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
553 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
554 * to {@link #EQ}.
555 */
556 public static QueryExp eq(ValueExp v1, ValueExp v2) {
557 return new BinaryRelQueryExp(EQ, v1, v2);
558 }
559
560 /**
561 * Returns a query expression that represents the constraint that one
562 * value is between two other values.
563 *
564 * @param v1 A value expression that is "between" v2 and v3.
565 * @param v2 Value expression that represents a boundary of the constraint.
566 * @param v3 Value expression that represents a boundary of the constraint.
567 *
568 * @return The constraint that v1 lies between v2 and v3. The
569 * returned object will be serialized as an instance of the
570 * non-public class {@link <a
571 * href="../../serialized-form.html#javax.management.BetweenQueryExp">
572 * javax.management.BetweenQueryExp</a>}.
573 */
574 public static QueryExp between(ValueExp v1, ValueExp v2, ValueExp v3) {
575 return new BetweenQueryExp(v1, v2, v3);
576 }
577
578 /**
579 * Returns a query expression that represents a matching constraint on
580 * a string argument. The matching syntax is consistent with file globbing:
581 * supports "<code>?</code>", "<code>*</code>", "<code>[</code>",
582 * each of which may be escaped with "<code>\</code>";
583 * character classes may use "<code>!</code>" for negation and
584 * "<code>-</code>" for range.
585 * (<code>*</code> for any character sequence,
586 * <code>?</code> for a single arbitrary character,
587 * <code>[...]</code> for a character sequence).
588 * For example: <code>a*b?c</code> would match a string starting
589 * with the character <code>a</code>, followed
590 * by any number of characters, followed by a <code>b</code>,
591 * any single character, and a <code>c</code>.
592 *
593 * @param a An attribute expression
594 * @param s A string value expression representing a matching constraint
595 *
596 * @return A query expression that represents the matching
597 * constraint on the string argument. The returned object will
598 * be serialized as an instance of the non-public class {@link <a
599 * href="../../serialized-form.html#javax.management.MatchQueryExp">
600 * javax.management.MatchQueryExp</a>}.
601 */
602 public static QueryExp match(AttributeValueExp a, StringValueExp s) {
603 return new MatchQueryExp(a, s);
604 }
605
606 /**
607 * <p>Returns a new attribute expression. See {@link AttributeValueExp}
608 * for a detailed description of the semantics of the expression.</p>
609 *
610 * @param name The name of the attribute.
611 *
612 * @return An attribute expression for the attribute named {@code name}.
613 */
614 public static AttributeValueExp attr(String name) {
615 return new AttributeValueExp(name);
616 }
617
618 /**
619 * <p>Returns a new qualified attribute expression.</p>
620 *
621 * <p>Evaluating this expression for a given
622 * <code>objectName</code> includes performing {@link
623 * MBeanServer#getObjectInstance
624 * MBeanServer.getObjectInstance(objectName)} and {@link
625 * MBeanServer#getAttribute MBeanServer.getAttribute(objectName,
626 * name)}.</p>
627 *
628 * @param className The name of the class possessing the attribute.
629 * @param name The name of the attribute.
630 *
631 * @return An attribute expression for the attribute named name.
632 * The returned object will be serialized as an instance of the
633 * non-public class {@link <a
634 * href="../../serialized-form.html#javax.management.QualifiedAttributeValueExp">
635 * javax.management.QualifiedAttributeValueExp</a>}.
636 */
637 public static AttributeValueExp attr(String className, String name) {
638 return new QualifiedAttributeValueExp(className, name);
639 }
640
641 /**
642 * <p>Returns a new class attribute expression which can be used in any
643 * Query call that expects a ValueExp.</p>
644 *
645 * <p>Evaluating this expression for a given
646 * <code>objectName</code> includes performing {@link
647 * MBeanServer#getObjectInstance
648 * MBeanServer.getObjectInstance(objectName)}.</p>
649 *
650 * @return A class attribute expression. The returned object
651 * will be serialized as an instance of the non-public class
652 * {@link <a
653 * href="../../serialized-form.html#javax.management.ClassAttributeValueExp">
654 * javax.management.ClassAttributeValueExp</a>}.
655 */
656 public static AttributeValueExp classattr() {
657 return new ClassAttributeValueExp();
658 }
659
660 /**
661 * Returns a constraint that is the negation of its argument.
662 *
663 * @param queryExp The constraint to negate.
664 *
665 * @return A negated constraint. The returned object will be
666 * serialized as an instance of the non-public class {@link <a
667 * href="../../serialized-form.html#javax.management.NotQueryExp">
668 * javax.management.NotQueryExp</a>}.
669 */
670 public static QueryExp not(QueryExp queryExp) {
671 return new NotQueryExp(queryExp);
672 }
673
674 /**
675 * Returns an expression constraining a value to be one of an explicit list.
676 *
677 * @param val A value to be constrained.
678 * @param valueList An array of ValueExps.
679 *
680 * @return A QueryExp that represents the constraint. The
681 * returned object will be serialized as an instance of the
682 * non-public class {@link <a
683 * href="../../serialized-form.html#javax.management.InQueryExp">
684 * javax.management.InQueryExp</a>}.
685 */
686 public static QueryExp in(ValueExp val, ValueExp valueList[]) {
687 return new InQueryExp(val, valueList);
688 }
689
690 /**
691 * Returns a new string expression.
692 *
693 * @param val The string value.
694 *
695 * @return A ValueExp object containing the string argument.
696 */
697 public static StringValueExp value(String val) {
698 return new StringValueExp(val);
699 }
700
701 /**
702 * Returns a numeric value expression that can be used in any Query call
703 * that expects a ValueExp.
704 *
705 * @param val An instance of Number.
706 *
707 * @return A ValueExp object containing the argument. The
708 * returned object will be serialized as an instance of the
709 * non-public class {@link <a
710 * href="../../serialized-form.html#javax.management.NumericValueExp">
711 * javax.management.NumericValueExp</a>}.
712 */
713 public static ValueExp value(Number val) {
714 return new NumericValueExp(val);
715 }
716
717 /**
718 * Returns a numeric value expression that can be used in any Query call
719 * that expects a ValueExp.
720 *
721 * @param val An int value.
722 *
723 * @return A ValueExp object containing the argument. The
724 * returned object will be serialized as an instance of the
725 * non-public class {@link <a
726 * href="../../serialized-form.html#javax.management.NumericValueExp">
727 * javax.management.NumericValueExp</a>}.
728 */
729 public static ValueExp value(int val) {
730 return new NumericValueExp((long) val);
731 }
732
733 /**
734 * Returns a numeric value expression that can be used in any Query call
735 * that expects a ValueExp.
736 *
737 * @param val A long value.
738 *
739 * @return A ValueExp object containing the argument. The
740 * returned object will be serialized as an instance of the
741 * non-public class {@link <a
742 * href="../../serialized-form.html#javax.management.NumericValueExp">
743 * javax.management.NumericValueExp</a>}.
744 */
745 public static ValueExp value(long val) {
746 return new NumericValueExp(val);
747 }
748
749 /**
750 * Returns a numeric value expression that can be used in any Query call
751 * that expects a ValueExp.
752 *
753 * @param val A float value.
754 *
755 * @return A ValueExp object containing the argument. The
756 * returned object will be serialized as an instance of the
757 * non-public class {@link <a
758 * href="../../serialized-form.html#javax.management.NumericValueExp">
759 * javax.management.NumericValueExp</a>}.
760 */
761 public static ValueExp value(float val) {
762 return new NumericValueExp((double) val);
763 }
764
765 /**
766 * Returns a numeric value expression that can be used in any Query call
767 * that expects a ValueExp.
768 *
769 * @param val A double value.
770 *
771 * @return A ValueExp object containing the argument. The
772 * returned object will be serialized as an instance of the
773 * non-public class {@link <a
774 * href="../../serialized-form.html#javax.management.NumericValueExp">
775 * javax.management.NumericValueExp</a>}.
776 */
777 public static ValueExp value(double val) {
778 return new NumericValueExp(val);
779 }
780
781 /**
782 * Returns a boolean value expression that can be used in any Query call
783 * that expects a ValueExp.
784 *
785 * @param val A boolean value.
786 *
787 * @return A ValueExp object containing the argument. The
788 * returned object will be serialized as an instance of the
789 * non-public class {@link <a
790 * href="../../serialized-form.html#javax.management.BooleanValueExp">
791 * javax.management.BooleanValueExp</a>}.
792 */
793 public static ValueExp value(boolean val) {
794 return new BooleanValueExp(val);
795 }
796
797 /**
798 * Returns a binary expression representing the sum of two numeric values,
799 * or the concatenation of two string values.
800 *
801 * @param value1 The first '+' operand.
802 * @param value2 The second '+' operand.
803 *
804 * @return A ValueExp representing the sum or concatenation of
805 * the two arguments. The returned object will be serialized as
806 * an instance of the non-public class {@link <a
807 * href="../../serialized-form.html#javax.management.BinaryOpValueExp">
808 * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to
809 * {@link #PLUS}.
810 */
811 public static ValueExp plus(ValueExp value1, ValueExp value2) {
812 return new BinaryOpValueExp(PLUS, value1, value2);
813 }
814
815 /**
816 * Returns a binary expression representing the product of two numeric values.
817 *
818 *
819 * @param value1 The first '*' operand.
820 * @param value2 The second '*' operand.
821 *
822 * @return A ValueExp representing the product. The returned
823 * object will be serialized as an instance of the non-public
824 * class {@link <a
825 * href="../../serialized-form.html#javax.management.BinaryOpValueExp">
826 * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to
827 * {@link #TIMES}.
828 */
829 public static ValueExp times(ValueExp value1,ValueExp value2) {
830 return new BinaryOpValueExp(TIMES, value1, value2);
831 }
832
833 /**
834 * Returns a binary expression representing the difference between two numeric
835 * values.
836 *
837 * @param value1 The first '-' operand.
838 * @param value2 The second '-' operand.
839 *
840 * @return A ValueExp representing the difference between two
841 * arguments. The returned object will be serialized as an
842 * instance of the non-public class {@link <a
843 * href="../../serialized-form.html#javax.management.BinaryOpValueExp">
844 * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to
845 * {@link #MINUS}.
846 */
847 public static ValueExp minus(ValueExp value1, ValueExp value2) {
848 return new BinaryOpValueExp(MINUS, value1, value2);
849 }
850
851 /**
852 * Returns a binary expression representing the quotient of two numeric
853 * values.
854 *
855 * @param value1 The first '/' operand.
856 * @param value2 The second '/' operand.
857 *
858 * @return A ValueExp representing the quotient of two arguments.
859 * The returned object will be serialized as an instance of the
860 * non-public class {@link <a
861 * href="../../serialized-form.html#javax.management.BinaryOpValueExp">
862 * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to
863 * {@link #DIV}.
864 */
865 public static ValueExp div(ValueExp value1, ValueExp value2) {
866 return new BinaryOpValueExp(DIV, value1, value2);
867 }
868
869 /**
870 * Returns a query expression that represents a matching constraint on
871 * a string argument. The value must start with the given literal string
872 * value.
873 *
874 * @param a An attribute expression.
875 * @param s A string value expression representing the beginning of the
876 * string value.
877 *
878 * @return The constraint that a matches s. The returned object
879 * will be serialized as an instance of the non-public class
880 * {@link <a
881 * href="../../serialized-form.html#javax.management.MatchQueryExp">
882 * javax.management.MatchQueryExp</a>}.
883 */
884 public static QueryExp initialSubString(AttributeValueExp a, StringValueExp s) {
885 return new MatchQueryExp(a,
886 new StringValueExp(escapeString(s.getValue()) + "*"));
887 }
888
889 /**
890 * Returns a query expression that represents a matching constraint on
891 * a string argument. The value must contain the given literal string
892 * value.
893 *
894 * @param a An attribute expression.
895 * @param s A string value expression representing the substring.
896 *
897 * @return The constraint that a matches s. The returned object
898 * will be serialized as an instance of the non-public class
899 * {@link <a
900 * href="../../serialized-form.html#javax.management.MatchQueryExp">
901 * javax.management.MatchQueryExp</a>}.
902 */
903 public static QueryExp anySubString(AttributeValueExp a, StringValueExp s) {
904 return new MatchQueryExp(a,
905 new StringValueExp("*" + escapeString(s.getValue()) + "*"));
906 }
907
908 /**
909 * Returns a query expression that represents a matching constraint on
910 * a string argument. The value must end with the given literal string
911 * value.
912 *
913 * @param a An attribute expression.
914 * @param s A string value expression representing the end of the string
915 * value.
916 *
917 * @return The constraint that a matches s. The returned object
918 * will be serialized as an instance of the non-public class
919 * {@link <a
920 * href="../../serialized-form.html#javax.management.MatchQueryExp">
921 * javax.management.MatchQueryExp</a>}.
922 */
923 public static QueryExp finalSubString(AttributeValueExp a, StringValueExp s) {
924 return new MatchQueryExp(a,
925 new StringValueExp("*" + escapeString(s.getValue())));
926 }
927
928 /**
929 * Returns a query expression that represents an inheritance constraint
930 * on an MBean class.
931 * <p>Example: to find MBeans that are instances of
932 * {@link NotificationBroadcaster}, use
933 * {@code Query.isInstanceOf(Query.value(NotificationBroadcaster.class.getName()))}.
934 * </p>
935 * <p>Evaluating this expression for a given
936 * <code>objectName</code> includes performing {@link
937 * MBeanServer#isInstanceOf MBeanServer.isInstanceOf(objectName,
938 * ((StringValueExp)classNameValue.apply(objectName)).getValue()}.</p>
939 *
940 * @param classNameValue The {@link StringValueExp} returning the name
941 * of the class of which selected MBeans should be instances.
942 * @return a query expression that represents an inheritance
943 * constraint on an MBean class. The returned object will be
944 * serialized as an instance of the non-public class {@link <a
945 * href="../../serialized-form.html#javax.management.InstanceOfQueryExp">
946 * javax.management.InstanceOfQueryExp</a>}.
947 * @since 1.6
948 */
949 public static QueryExp isInstanceOf(StringValueExp classNameValue) {
950 return new InstanceOfQueryExp(classNameValue);
951 }
952
953 /**
954 * <p>Return a string representation of the given query. The string
955 * returned by this method can be converted back into an equivalent
956 * query using {@link #fromString fromString}.</p>
957 *
958 * <p>(Two queries are equivalent if they produce the same result in
959 * all cases. Equivalent queries are not necessarily identical:
960 * for example the queries {@code Query.lt(Query.attr("A"), Query.attr("B"))}
961 * and {@code Query.not(Query.ge(Query.attr("A"), Query.attr("B")))} are
962 * equivalent but not identical.)</p>
963 *
964 * <p>The string returned by this method is only guaranteed to be converted
965 * back into an equivalent query if {@code query} was constructed, or
966 * could have been constructed, using the methods of this class.
967 * If you make a custom query {@code myQuery} by implementing
968 * {@link QueryExp} yourself then the result of
969 * {@code Query.toString(myQuery)} is unspecified.</p>
970 *
971 * @param query the query to convert. If it is null, the result will
972 * also be null.
973 * @return the string representation of the query, or null if the
974 * query is null.
975 *
976 * @since 1.7
977 */
978 public static String toString(QueryExp query) {
979 if (query == null)
980 return null;
981
982 // This is ugly. At one stage we had a non-public class called
983 // ToQueryString with the toQueryString() method, and every class
984 // mentioned here inherited from that class. But that interfered
985 // with serialization of custom subclasses of e.g. QueryEval. Even
986 // though we could make it work by adding a public constructor to this
987 // non-public class, that seemed fragile because according to the
988 // serialization spec it shouldn't work. If only non-public interfaces
989 // could have non-public methods.
990 if (query instanceof ObjectName)
991 return ((ObjectName) query).toQueryString();
992 if (query instanceof QueryEval)
993 return ((QueryEval) query).toQueryString();
994
995 return query.toString();
996 }
997
998 /**
999 * <p>Produce a query from the given string. The query returned
1000 * by this method can be converted back into a string using
1001 * {@link #toString(QueryExp) toString}. The resultant string will
1002 * not necessarily be equal to {@code s}.</p>
1003 *
1004 * @param s the string to convert.
1005 *
1006 * @return a {@code QueryExp} derived by parsing the string, or
1007 * null if the string is null.
1008 *
1009 * @throws IllegalArgumentException if the string is not a valid
1010 * query string.
1011 *
1012 * @since 1.7
1013 */
1014 public static QueryExp fromString(String s) {
1015 if (s == null)
1016 return null;
1017 return new QueryParser(s).parseQuery();
1018 }
1019
1020 /**
1021 * Utility method to escape strings used with
1022 * Query.{initial|any|final}SubString() methods.
1023 */
1024 private static String escapeString(String s) {
1025 if (s == null)
1026 return null;
1027 s = s.replace("\\", "\\\\");
1028 s = s.replace("*", "\\*");
1029 s = s.replace("?", "\\?");
1030 s = s.replace("[", "\\[");
1031 return s;
1032 }
1033 }
Save This Page