1 /*
2 * Copyright (c) 1999, 2008, Oracle and/or its affiliates. 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * 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>As an example, suppose you wanted to find all MBeans where the {@code
44 * Enabled} attribute is {@code true} and the {@code Owner} attribute is {@code
45 * "Duke"}. Here is how you could construct the appropriate {@code QueryExp} by
46 * chaining together method calls:</p>
47 *
48 * <pre>
49 * QueryExp query =
50 * Query.and(Query.eq(Query.attr("Enabled"), Query.value(true)),
51 * Query.eq(Query.attr("Owner"), Query.value("Duke")));
52 * </pre>
53 *
54 * @since 1.5
55 */
56 public class Query extends Object {
57
58
59 /**
60 * A code representing the {@link Query#gt} query. This is chiefly
61 * of interest for the serialized form of queries.
62 */
63 public static final int GT = 0;
64
65 /**
66 * A code representing the {@link Query#lt} query. This is chiefly
67 * of interest for the serialized form of queries.
68 */
69 public static final int LT = 1;
70
71 /**
72 * A code representing the {@link Query#geq} query. This is chiefly
73 * of interest for the serialized form of queries.
74 */
75 public static final int GE = 2;
76
77 /**
78 * A code representing the {@link Query#leq} query. This is chiefly
79 * of interest for the serialized form of queries.
80 */
81 public static final int LE = 3;
82
83 /**
84 * A code representing the {@link Query#eq} query. This is chiefly
85 * of interest for the serialized form of queries.
86 */
87 public static final int EQ = 4;
88
89
90 /**
91 * A code representing the {@link Query#plus} expression. This
92 * is chiefly of interest for the serialized form of queries.
93 */
94 public static final int PLUS = 0;
95
96 /**
97 * A code representing the {@link Query#minus} expression. This
98 * is chiefly of interest for the serialized form of queries.
99 */
100 public static final int MINUS = 1;
101
102 /**
103 * A code representing the {@link Query#times} expression. This
104 * is chiefly of interest for the serialized form of queries.
105 */
106 public static final int TIMES = 2;
107
108 /**
109 * A code representing the {@link Query#div} expression. This is
110 * chiefly of interest for the serialized form of queries.
111 */
112 public static final int DIV = 3;
113
114
115 /**
116 * Basic constructor.
117 */
118 public Query() {
119 }
120
121
122 /**
123 * Returns a query expression that is the conjunction of two other query
124 * expressions.
125 *
126 * @param q1 A query expression.
127 * @param q2 Another query expression.
128 *
129 * @return The conjunction of the two arguments. The returned object
130 * will be serialized as an instance of the non-public class {@link
131 * <a href="../../serialized-form.html#javax.management.AndQueryExp">
132 * javax.management.AndQueryExp</a>}.
133 */
134 public static QueryExp and(QueryExp q1, QueryExp q2) {
135 return new AndQueryExp(q1, q2);
136 }
137
138 /**
139 * Returns a query expression that is the disjunction of two other query
140 * expressions.
141 *
142 * @param q1 A query expression.
143 * @param q2 Another query expression.
144 *
145 * @return The disjunction of the two arguments. The returned object
146 * will be serialized as an instance of the non-public class {@link
147 * <a href="../../serialized-form.html#javax.management.OrQueryExp">
148 * javax.management.OrQueryExp</a>}.
149 */
150 public static QueryExp or(QueryExp q1, QueryExp q2) {
151 return new OrQueryExp(q1, q2);
152 }
153
154 /**
155 * Returns a query expression that represents a "greater than" constraint on
156 * two values.
157 *
158 * @param v1 A value expression.
159 * @param v2 Another value expression.
160 *
161 * @return A "greater than" constraint on the arguments. The
162 * returned object will be serialized as an instance of the
163 * non-public class {@link <a
164 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
165 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
166 * to {@link #GT}.
167 */
168 public static QueryExp gt(ValueExp v1, ValueExp v2) {
169 return new BinaryRelQueryExp(GT, v1, v2);
170 }
171
172 /**
173 * Returns a query expression that represents a "greater than or equal
174 * to" constraint on two values.
175 *
176 * @param v1 A value expression.
177 * @param v2 Another value expression.
178 *
179 * @return A "greater than or equal to" constraint on the
180 * arguments. The returned object will be serialized as an
181 * instance of the non-public class {@link <a
182 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
183 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
184 * to {@link #GE}.
185 */
186 public static QueryExp geq(ValueExp v1, ValueExp v2) {
187 return new BinaryRelQueryExp(GE, v1, v2);
188 }
189
190 /**
191 * Returns a query expression that represents a "less than or equal to"
192 * constraint on two values.
193 *
194 * @param v1 A value expression.
195 * @param v2 Another value expression.
196 *
197 * @return A "less than or equal to" constraint on the arguments.
198 * The returned object will be serialized as an instance of the
199 * non-public class {@link <a
200 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
201 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
202 * to {@link #LE}.
203 */
204 public static QueryExp leq(ValueExp v1, ValueExp v2) {
205 return new BinaryRelQueryExp(LE, v1, v2);
206 }
207
208 /**
209 * Returns a query expression that represents a "less than" constraint on
210 * two values.
211 *
212 * @param v1 A value expression.
213 * @param v2 Another value expression.
214 *
215 * @return A "less than" constraint on the arguments. The
216 * returned object will be serialized as an instance of the
217 * non-public class {@link <a
218 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
219 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
220 * to {@link #LT}.
221 */
222 public static QueryExp lt(ValueExp v1, ValueExp v2) {
223 return new BinaryRelQueryExp(LT, v1, v2);
224 }
225
226 /**
227 * Returns a query expression that represents an equality constraint on
228 * two values.
229 *
230 * @param v1 A value expression.
231 * @param v2 Another value expression.
232 *
233 * @return A "equal to" constraint on the arguments. The
234 * returned object will be serialized as an instance of the
235 * non-public class {@link <a
236 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
237 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
238 * to {@link #EQ}.
239 */
240 public static QueryExp eq(ValueExp v1, ValueExp v2) {
241 return new BinaryRelQueryExp(EQ, v1, v2);
242 }
243
244 /**
245 * Returns a query expression that represents the constraint that one
246 * value is between two other values.
247 *
248 * @param v1 A value expression that is "between" v2 and v3.
249 * @param v2 Value expression that represents a boundary of the constraint.
250 * @param v3 Value expression that represents a boundary of the constraint.
251 *
252 * @return The constraint that v1 lies between v2 and v3. The
253 * returned object will be serialized as an instance of the
254 * non-public class {@link <a
255 * href="../../serialized-form.html#javax.management.BetweenQueryExp">
256 * javax.management.BetweenQueryExp</a>}.
257 */
258 public static QueryExp between(ValueExp v1, ValueExp v2, ValueExp v3) {
259 return new BetweenQueryExp(v1, v2, v3);
260 }
261
262 /**
263 * Returns a query expression that represents a matching constraint on
264 * a string argument. The matching syntax is consistent with file globbing:
265 * supports "<code>?</code>", "<code>*</code>", "<code>[</code>",
266 * each of which may be escaped with "<code>\</code>";
267 * character classes may use "<code>!</code>" for negation and
268 * "<code>-</code>" for range.
269 * (<code>*</code> for any character sequence,
270 * <code>?</code> for a single arbitrary character,
271 * <code>[...]</code> for a character sequence).
272 * For example: <code>a*b?c</code> would match a string starting
273 * with the character <code>a</code>, followed
274 * by any number of characters, followed by a <code>b</code>,
275 * any single character, and a <code>c</code>.
276 *
277 * @param a An attribute expression
278 * @param s A string value expression representing a matching constraint
279 *
280 * @return A query expression that represents the matching
281 * constraint on the string argument. The returned object will
282 * be serialized as an instance of the non-public class {@link <a
283 * href="../../serialized-form.html#javax.management.MatchQueryExp">
284 * javax.management.MatchQueryExp</a>}.
285 */
286 public static QueryExp match(AttributeValueExp a, StringValueExp s) {
287 return new MatchQueryExp(a, s);
288 }
289
290 /**
291 * <p>Returns a new attribute expression. See {@link AttributeValueExp}
292 * for a detailed description of the semantics of the expression.</p>
293 *
294 * <p>Evaluating this expression for a given
295 * <code>objectName</code> includes performing {@link
296 * MBeanServer#getAttribute MBeanServer.getAttribute(objectName,
297 * name)}.</p>
298 *
299 * @param name The name of the attribute.
300 *
301 * @return An attribute expression for the attribute named {@code name}.
302 */
303 public static AttributeValueExp attr(String name) {
304 return new AttributeValueExp(name);
305 }
306
307 /**
308 * <p>Returns a new qualified attribute expression.</p>
309 *
310 * <p>Evaluating this expression for a given
311 * <code>objectName</code> includes performing {@link
312 * MBeanServer#getObjectInstance
313 * MBeanServer.getObjectInstance(objectName)} and {@link
314 * MBeanServer#getAttribute MBeanServer.getAttribute(objectName,
315 * name)}.</p>
316 *
317 * @param className The name of the class possessing the attribute.
318 * @param name The name of the attribute.
319 *
320 * @return An attribute expression for the attribute named name.
321 * The returned object will be serialized as an instance of the
322 * non-public class {@link <a
323 * href="../../serialized-form.html#javax.management.QualifiedAttributeValueExp">
324 * javax.management.QualifiedAttributeValueExp</a>}.
325 */
326 public static AttributeValueExp attr(String className, String name) {
327 return new QualifiedAttributeValueExp(className, name);
328 }
329
330 /**
331 * <p>Returns a new class attribute expression which can be used in any
332 * Query call that expects a ValueExp.</p>
333 *
334 * <p>Evaluating this expression for a given
335 * <code>objectName</code> includes performing {@link
336 * MBeanServer#getObjectInstance
337 * MBeanServer.getObjectInstance(objectName)}.</p>
338 *
339 * @return A class attribute expression. The returned object
340 * will be serialized as an instance of the non-public class
341 * {@link <a
342 * href="../../serialized-form.html#javax.management.ClassAttributeValueExp">
343 * javax.management.ClassAttributeValueExp</a>}.
344 */
345 public static AttributeValueExp classattr() {
346 return new ClassAttributeValueExp();
347 }
348
349 /**
350 * Returns a constraint that is the negation of its argument.
351 *
352 * @param queryExp The constraint to negate.
353 *
354 * @return A negated constraint. The returned object will be
355 * serialized as an instance of the non-public class {@link <a
356 * href="../../serialized-form.html#javax.management.NotQueryExp">
357 * javax.management.NotQueryExp</a>}.
358 */
359 public static QueryExp not(QueryExp queryExp) {
360 return new NotQueryExp(queryExp);
361 }
362
363 /**
364 * Returns an expression constraining a value to be one of an explicit list.
365 *
366 * @param val A value to be constrained.
367 * @param valueList An array of ValueExps.
368 *
369 * @return A QueryExp that represents the constraint. The
370 * returned object will be serialized as an instance of the
371 * non-public class {@link <a
372 * href="../../serialized-form.html#javax.management.InQueryExp">
373 * javax.management.InQueryExp</a>}.
374 */
375 public static QueryExp in(ValueExp val, ValueExp valueList[]) {
376 return new InQueryExp(val, valueList);
377 }
378
379 /**
380 * Returns a new string expression.
381 *
382 * @param val The string value.
383 *
384 * @return A ValueExp object containing the string argument.
385 */
386 public static StringValueExp value(String val) {
387 return new StringValueExp(val);
388 }
389
390 /**
391 * Returns a numeric value expression that can be used in any Query call
392 * that expects a ValueExp.
393 *
394 * @param val An instance of Number.
395 *
396 * @return A ValueExp object containing the argument. The
397 * returned object will be serialized as an instance of the
398 * non-public class {@link <a
399 * href="../../serialized-form.html#javax.management.NumericValueExp">
400 * javax.management.NumericValueExp</a>}.
401 */
402 public static ValueExp value(Number val) {
403 return new NumericValueExp(val);
404 }
405
406 /**
407 * Returns a numeric value expression that can be used in any Query call
408 * that expects a ValueExp.
409 *
410 * @param val An int value.
411 *
412 * @return A ValueExp object containing the argument. The
413 * returned object will be serialized as an instance of the
414 * non-public class {@link <a
415 * href="../../serialized-form.html#javax.management.NumericValueExp">
416 * javax.management.NumericValueExp</a>}.
417 */
418 public static ValueExp value(int val) {
419 return new NumericValueExp((long) val);
420 }
421
422 /**
423 * Returns a numeric value expression that can be used in any Query call
424 * that expects a ValueExp.
425 *
426 * @param val A long value.
427 *
428 * @return A ValueExp object containing the argument. The
429 * returned object will be serialized as an instance of the
430 * non-public class {@link <a
431 * href="../../serialized-form.html#javax.management.NumericValueExp">
432 * javax.management.NumericValueExp</a>}.
433 */
434 public static ValueExp value(long val) {
435 return new NumericValueExp(val);
436 }
437
438 /**
439 * Returns a numeric value expression that can be used in any Query call
440 * that expects a ValueExp.
441 *
442 * @param val A float value.
443 *
444 * @return A ValueExp object containing the argument. The
445 * returned object will be serialized as an instance of the
446 * non-public class {@link <a
447 * href="../../serialized-form.html#javax.management.NumericValueExp">
448 * javax.management.NumericValueExp</a>}.
449 */
450 public static ValueExp value(float val) {
451 return new NumericValueExp((double) val);
452 }
453
454 /**
455 * Returns a numeric value expression that can be used in any Query call
456 * that expects a ValueExp.
457 *
458 * @param val A double value.
459 *
460 * @return A ValueExp object containing the argument. The
461 * returned object will be serialized as an instance of the
462 * non-public class {@link <a
463 * href="../../serialized-form.html#javax.management.NumericValueExp">
464 * javax.management.NumericValueExp</a>}.
465 */
466 public static ValueExp value(double val) {
467 return new NumericValueExp(val);
468 }
469
470 /**
471 * Returns a boolean value expression that can be used in any Query call
472 * that expects a ValueExp.
473 *
474 * @param val A boolean value.
475 *
476 * @return A ValueExp object containing the argument. The
477 * returned object will be serialized as an instance of the
478 * non-public class {@link <a
479 * href="../../serialized-form.html#javax.management.BooleanValueExp">
480 * javax.management.BooleanValueExp</a>}.
481 */
482 public static ValueExp value(boolean val) {
483 return new BooleanValueExp(val);
484 }
485
486 /**
487 * Returns a binary expression representing the sum of two numeric values,
488 * or the concatenation of two string values.
489 *
490 * @param value1 The first '+' operand.
491 * @param value2 The second '+' operand.
492 *
493 * @return A ValueExp representing the sum or concatenation of
494 * the two arguments. The returned object will be serialized as
495 * an instance of the non-public class {@link <a
496 * href="../../serialized-form.html#javax.management.BinaryOpValueExp">
497 * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to
498 * {@link #PLUS}.
499 */
500 public static ValueExp plus(ValueExp value1, ValueExp value2) {
501 return new BinaryOpValueExp(PLUS, value1, value2);
502 }
503
504 /**
505 * Returns a binary expression representing the product of two numeric values.
506 *
507 *
508 * @param value1 The first '*' operand.
509 * @param value2 The second '*' operand.
510 *
511 * @return A ValueExp representing the product. The returned
512 * object will be serialized as an instance of the non-public
513 * class {@link <a
514 * href="../../serialized-form.html#javax.management.BinaryOpValueExp">
515 * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to
516 * {@link #TIMES}.
517 */
518 public static ValueExp times(ValueExp value1,ValueExp value2) {
519 return new BinaryOpValueExp(TIMES, value1, value2);
520 }
521
522 /**
523 * Returns a binary expression representing the difference between two numeric
524 * values.
525 *
526 * @param value1 The first '-' operand.
527 * @param value2 The second '-' operand.
528 *
529 * @return A ValueExp representing the difference between two
530 * arguments. The returned object will be serialized as an
531 * instance of the non-public class {@link <a
532 * href="../../serialized-form.html#javax.management.BinaryOpValueExp">
533 * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to
534 * {@link #MINUS}.
535 */
536 public static ValueExp minus(ValueExp value1, ValueExp value2) {
537 return new BinaryOpValueExp(MINUS, value1, value2);
538 }
539
540 /**
541 * Returns a binary expression representing the quotient of two numeric
542 * values.
543 *
544 * @param value1 The first '/' operand.
545 * @param value2 The second '/' operand.
546 *
547 * @return A ValueExp representing the quotient of two arguments.
548 * The returned object will be serialized as an instance of the
549 * non-public class {@link <a
550 * href="../../serialized-form.html#javax.management.BinaryOpValueExp">
551 * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to
552 * {@link #DIV}.
553 */
554 public static ValueExp div(ValueExp value1, ValueExp value2) {
555 return new BinaryOpValueExp(DIV, value1, value2);
556 }
557
558 /**
559 * Returns a query expression that represents a matching constraint on
560 * a string argument. The value must start with the given literal string
561 * value.
562 *
563 * @param a An attribute expression.
564 * @param s A string value expression representing the beginning of the
565 * string value.
566 *
567 * @return The constraint that a matches s. The returned object
568 * will be serialized as an instance of the non-public class
569 * {@link <a
570 * href="../../serialized-form.html#javax.management.MatchQueryExp">
571 * javax.management.MatchQueryExp</a>}.
572 */
573 public static QueryExp initialSubString(AttributeValueExp a, StringValueExp s) {
574 return new MatchQueryExp(a,
575 new StringValueExp(escapeString(s.getValue()) + "*"));
576 }
577
578 /**
579 * Returns a query expression that represents a matching constraint on
580 * a string argument. The value must contain the given literal string
581 * value.
582 *
583 * @param a An attribute expression.
584 * @param s A string value expression representing the substring.
585 *
586 * @return The constraint that a matches s. The returned object
587 * will be serialized as an instance of the non-public class
588 * {@link <a
589 * href="../../serialized-form.html#javax.management.MatchQueryExp">
590 * javax.management.MatchQueryExp</a>}.
591 */
592 public static QueryExp anySubString(AttributeValueExp a, StringValueExp s) {
593 return new MatchQueryExp(a,
594 new StringValueExp("*" + escapeString(s.getValue()) + "*"));
595 }
596
597 /**
598 * Returns a query expression that represents a matching constraint on
599 * a string argument. The value must end with the given literal string
600 * value.
601 *
602 * @param a An attribute expression.
603 * @param s A string value expression representing the end of the string
604 * value.
605 *
606 * @return The constraint that a matches s. The returned object
607 * will be serialized as an instance of the non-public class
608 * {@link <a
609 * href="../../serialized-form.html#javax.management.MatchQueryExp">
610 * javax.management.MatchQueryExp</a>}.
611 */
612 public static QueryExp finalSubString(AttributeValueExp a, StringValueExp s) {
613 return new MatchQueryExp(a,
614 new StringValueExp("*" + escapeString(s.getValue())));
615 }
616
617 /**
618 * Returns a query expression that represents an inheritance constraint
619 * on an MBean class.
620 * <p>Example: to find MBeans that are instances of
621 * {@link NotificationBroadcaster}, use
622 * {@code Query.isInstanceOf(Query.value(NotificationBroadcaster.class.getName()))}.
623 * </p>
624 * <p>Evaluating this expression for a given
625 * <code>objectName</code> includes performing {@link
626 * MBeanServer#isInstanceOf MBeanServer.isInstanceOf(objectName,
627 * ((StringValueExp)classNameValue.apply(objectName)).getValue()}.</p>
628 *
629 * @param classNameValue The {@link StringValueExp} returning the name
630 * of the class of which selected MBeans should be instances.
631 * @return a query expression that represents an inheritance
632 * constraint on an MBean class. The returned object will be
633 * serialized as an instance of the non-public class {@link <a
634 * href="../../serialized-form.html#javax.management.InstanceOfQueryExp">
635 * javax.management.InstanceOfQueryExp</a>}.
636 * @since 1.6
637 */
638 public static QueryExp isInstanceOf(StringValueExp classNameValue) {
639 return new InstanceOfQueryExp(classNameValue);
640 }
641
642 /**
643 * Utility method to escape strings used with
644 * Query.{initial|any|final}SubString() methods.
645 */
646 private static String escapeString(String s) {
647 if (s == null)
648 return null;
649 s = s.replace("\\", "\\\\");
650 s = s.replace("*", "\\*");
651 s = s.replace("?", "\\?");
652 s = s.replace("[", "\\[");
653 return s;
654 }
655 }