001 /*
002 * Copyright 1999-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.management;
027
028 /**
029 * <p>Constructs query object constraints. The static methods provided
030 * return query expressions that may be used in listing and
031 * enumerating MBeans. Individual constraint construction methods
032 * allow only appropriate types as arguments. Composition of calls can
033 * construct arbitrary nestings of constraints, as the following
034 * example illustrates:</p>
035 *
036 * <pre>
037 * QueryExp exp = Query.and(Query.gt(Query.attr("age"),Query.value(5)),
038 * Query.match(Query.attr("name"),
039 * Query.value("Smith")));
040 * </pre>
041 *
042 * @since 1.5
043 */
044 public class Query extends Object {
045
046 /**
047 * A code representing the {@link Query#gt} query. This is chiefly
048 * of interest for the serialized form of queries.
049 */
050 public static final int GT = 0;
051
052 /**
053 * A code representing the {@link Query#lt} query. This is chiefly
054 * of interest for the serialized form of queries.
055 */
056 public static final int LT = 1;
057
058 /**
059 * A code representing the {@link Query#geq} query. This is chiefly
060 * of interest for the serialized form of queries.
061 */
062 public static final int GE = 2;
063
064 /**
065 * A code representing the {@link Query#leq} query. This is chiefly
066 * of interest for the serialized form of queries.
067 */
068 public static final int LE = 3;
069
070 /**
071 * A code representing the {@link Query#eq} query. This is chiefly
072 * of interest for the serialized form of queries.
073 */
074 public static final int EQ = 4;
075
076 /**
077 * A code representing the {@link Query#plus} expression. This
078 * is chiefly of interest for the serialized form of queries.
079 */
080 public static final int PLUS = 0;
081
082 /**
083 * A code representing the {@link Query#minus} expression. This
084 * is chiefly of interest for the serialized form of queries.
085 */
086 public static final int MINUS = 1;
087
088 /**
089 * A code representing the {@link Query#times} expression. This
090 * is chiefly of interest for the serialized form of queries.
091 */
092 public static final int TIMES = 2;
093
094 /**
095 * A code representing the {@link Query#div} expression. This is
096 * chiefly of interest for the serialized form of queries.
097 */
098 public static final int DIV = 3;
099
100 /**
101 * Basic constructor.
102 */
103 public Query() {
104 }
105
106 /**
107 * Returns a query expression that is the conjunction of two other query
108 * expressions.
109 *
110 * @param q1 A query expression.
111 * @param q2 Another query expression.
112 *
113 * @return The conjunction of the two arguments. The returned object
114 * will be serialized as an instance of the non-public class {@link
115 * <a href="../../serialized-form.html#javax.management.AndQueryExp">
116 * javax.management.AndQueryExp</a>}.
117 */
118 public static QueryExp and(QueryExp q1, QueryExp q2) {
119 return new AndQueryExp(q1, q2);
120 }
121
122 /**
123 * Returns a query expression that is the disjunction of two other query
124 * expressions.
125 *
126 * @param q1 A query expression.
127 * @param q2 Another query expression.
128 *
129 * @return The disjunction 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.OrQueryExp">
132 * javax.management.OrQueryExp</a>}.
133 */
134 public static QueryExp or(QueryExp q1, QueryExp q2) {
135 return new OrQueryExp(q1, q2);
136 }
137
138 /**
139 * Returns a query expression that represents a "greater than" constraint on
140 * two values.
141 *
142 * @param v1 A value expression.
143 * @param v2 Another value expression.
144 *
145 * @return A "greater than" constraint on the arguments. The
146 * returned object will be serialized as an instance of the
147 * non-public class {@link <a
148 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
149 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
150 * to {@link #GT}.
151 */
152 public static QueryExp gt(ValueExp v1, ValueExp v2) {
153 return new BinaryRelQueryExp(GT, v1, v2);
154 }
155
156 /**
157 * Returns a query expression that represents a "greater than or equal
158 * to" constraint on two values.
159 *
160 * @param v1 A value expression.
161 * @param v2 Another value expression.
162 *
163 * @return A "greater than or equal to" constraint on the
164 * arguments. The returned object will be serialized as an
165 * instance of the non-public class {@link <a
166 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
167 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
168 * to {@link #GE}.
169 */
170 public static QueryExp geq(ValueExp v1, ValueExp v2) {
171 return new BinaryRelQueryExp(GE, v1, v2);
172 }
173
174 /**
175 * Returns a query expression that represents a "less than or equal to"
176 * constraint on two values.
177 *
178 * @param v1 A value expression.
179 * @param v2 Another value expression.
180 *
181 * @return A "less than or equal to" constraint on the arguments.
182 * The returned object will be serialized as an instance of the
183 * non-public class {@link <a
184 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
185 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
186 * to {@link #LE}.
187 */
188 public static QueryExp leq(ValueExp v1, ValueExp v2) {
189 return new BinaryRelQueryExp(LE, v1, v2);
190 }
191
192 /**
193 * Returns a query expression that represents a "less than" constraint on
194 * two values.
195 *
196 * @param v1 A value expression.
197 * @param v2 Another value expression.
198 *
199 * @return A "less than" constraint on the arguments. The
200 * returned object will be serialized as an instance of the
201 * non-public class {@link <a
202 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
203 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
204 * to {@link #LT}.
205 */
206 public static QueryExp lt(ValueExp v1, ValueExp v2) {
207 return new BinaryRelQueryExp(LT, v1, v2);
208 }
209
210 /**
211 * Returns a query expression that represents an equality constraint on
212 * two values.
213 *
214 * @param v1 A value expression.
215 * @param v2 Another value expression.
216 *
217 * @return A "equal to" constraint on the arguments. The
218 * returned object will be serialized as an instance of the
219 * non-public class {@link <a
220 * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">
221 * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal
222 * to {@link #EQ}.
223 */
224 public static QueryExp eq(ValueExp v1, ValueExp v2) {
225 return new BinaryRelQueryExp(EQ, v1, v2);
226 }
227
228 /**
229 * Returns a query expression that represents the constraint that one
230 * value is between two other values.
231 *
232 * @param v1 A value expression that is "between" v2 and v3.
233 * @param v2 Value expression that represents a boundary of the constraint.
234 * @param v3 Value expression that represents a boundary of the constraint.
235 *
236 * @return The constraint that v1 lies between v2 and v3. The
237 * returned object will be serialized as an instance of the
238 * non-public class {@link <a
239 * href="../../serialized-form.html#javax.management.BetweenQueryExp">
240 * javax.management.BetweenQueryExp</a>}.
241 */
242 public static QueryExp between(ValueExp v1, ValueExp v2, ValueExp v3) {
243 return new BetweenQueryExp(v1, v2, v3);
244 }
245
246 /**
247 * Returns a query expression that represents a matching constraint on
248 * a string argument. The matching syntax is consistent with file globbing:
249 * supports "<code>?</code>", "<code>*</code>", "<code>[</code>",
250 * each of which may be escaped with "<code>\</code>";
251 * character classes may use "<code>!</code>" for negation and
252 * "<code>-</code>" for range.
253 * (<code>*</code> for any character sequence,
254 * <code>?</code> for a single arbitrary character,
255 * <code>[...]</code> for a character sequence).
256 * For example: <code>a*b?c</code> would match a string starting
257 * with the character <code>a</code>, followed
258 * by any number of characters, followed by a <code>b</code>,
259 * any single character, and a <code>c</code>.
260 *
261 * @param a An attribute expression
262 * @param s A string value expression representing a matching constraint
263 *
264 * @return A query expression that represents the matching
265 * constraint on the string argument. The returned object will
266 * be serialized as an instance of the non-public class {@link <a
267 * href="../../serialized-form.html#javax.management.MatchQueryExp">
268 * javax.management.MatchQueryExp</a>}.
269 */
270 public static QueryExp match(AttributeValueExp a, StringValueExp s) {
271 return new MatchQueryExp(a, s);
272 }
273
274 /**
275 * <p>Returns a new attribute expression.</p>
276 *
277 * <p>Evaluating this expression for a given
278 * <code>objectName</code> includes performing {@link
279 * MBeanServer#getAttribute MBeanServer.getAttribute(objectName,
280 * name)}.</p>
281 *
282 * @param name The name of the attribute.
283 *
284 * @return An attribute expression for the attribute named name.
285 */
286 public static AttributeValueExp attr(String name) {
287 return new AttributeValueExp(name);
288 }
289
290 /**
291 * <p>Returns a new qualified attribute expression.</p>
292 *
293 * <p>Evaluating this expression for a given
294 * <code>objectName</code> includes performing {@link
295 * MBeanServer#getObjectInstance
296 * MBeanServer.getObjectInstance(objectName)} and {@link
297 * MBeanServer#getAttribute MBeanServer.getAttribute(objectName,
298 * name)}.</p>
299 *
300 * @param className The name of the class possessing the attribute.
301 * @param name The name of the attribute.
302 *
303 * @return An attribute expression for the attribute named name.
304 * The returned object will be serialized as an instance of the
305 * non-public class {@link <a
306 * href="../../serialized-form.html#javax.management.QualifiedAttributeValueExp">
307 * javax.management.QualifiedAttributeValueExp</a>}.
308 */
309 public static AttributeValueExp attr(String className, String name) {
310 return new QualifiedAttributeValueExp(className, name);
311 }
312
313 /**
314 * <p>Returns a new class attribute expression which can be used in any
315 * Query call that expects a ValueExp.</p>
316 *
317 * <p>Evaluating this expression for a given
318 * <code>objectName</code> includes performing {@link
319 * MBeanServer#getObjectInstance
320 * MBeanServer.getObjectInstance(objectName)}.</p>
321 *
322 * @return A class attribute expression. The returned object
323 * will be serialized as an instance of the non-public class
324 * {@link <a
325 * href="../../serialized-form.html#javax.management.ClassAttributeValueExp">
326 * javax.management.ClassAttributeValueExp</a>}.
327 */
328 public static AttributeValueExp classattr() {
329 return new ClassAttributeValueExp();
330 }
331
332 /**
333 * Returns a constraint that is the negation of its argument.
334 *
335 * @param queryExp The constraint to negate.
336 *
337 * @return A negated constraint. The returned object will be
338 * serialized as an instance of the non-public class {@link <a
339 * href="../../serialized-form.html#javax.management.NotQueryExp">
340 * javax.management.NotQueryExp</a>}.
341 */
342 public static QueryExp not(QueryExp queryExp) {
343 return new NotQueryExp(queryExp);
344 }
345
346 /**
347 * Returns an expression constraining a value to be one of an explicit list.
348 *
349 * @param val A value to be constrained.
350 * @param valueList An array of ValueExps.
351 *
352 * @return A QueryExp that represents the constraint. The
353 * returned object will be serialized as an instance of the
354 * non-public class {@link <a
355 * href="../../serialized-form.html#javax.management.InQueryExp">
356 * javax.management.InQueryExp</a>}.
357 */
358 public static QueryExp in(ValueExp val, ValueExp valueList[]) {
359 return new InQueryExp(val, valueList);
360 }
361
362 /**
363 * Returns a new string expression.
364 *
365 * @param val The string value.
366 *
367 * @return A ValueExp object containing the string argument.
368 */
369 public static StringValueExp value(String val) {
370 return new StringValueExp(val);
371 }
372
373 /**
374 * Returns a numeric value expression that can be used in any Query call
375 * that expects a ValueExp.
376 *
377 * @param val An instance of Number.
378 *
379 * @return A ValueExp object containing the argument. The
380 * returned object will be serialized as an instance of the
381 * non-public class {@link <a
382 * href="../../serialized-form.html#javax.management.NumericValueExp">
383 * javax.management.NumericValueExp</a>}.
384 */
385 public static ValueExp value(Number val) {
386 return new NumericValueExp(val);
387 }
388
389 /**
390 * Returns a numeric value expression that can be used in any Query call
391 * that expects a ValueExp.
392 *
393 * @param val An int value.
394 *
395 * @return A ValueExp object containing the argument. The
396 * returned object will be serialized as an instance of the
397 * non-public class {@link <a
398 * href="../../serialized-form.html#javax.management.NumericValueExp">
399 * javax.management.NumericValueExp</a>}.
400 */
401 public static ValueExp value(int val) {
402 return new NumericValueExp((long) val);
403 }
404
405 /**
406 * Returns a numeric value expression that can be used in any Query call
407 * that expects a ValueExp.
408 *
409 * @param val A long value.
410 *
411 * @return A ValueExp object containing the argument. The
412 * returned object will be serialized as an instance of the
413 * non-public class {@link <a
414 * href="../../serialized-form.html#javax.management.NumericValueExp">
415 * javax.management.NumericValueExp</a>}.
416 */
417 public static ValueExp value(long val) {
418 return new NumericValueExp(val);
419 }
420
421 /**
422 * Returns a numeric value expression that can be used in any Query call
423 * that expects a ValueExp.
424 *
425 * @param val A float value.
426 *
427 * @return A ValueExp object containing the argument. The
428 * returned object will be serialized as an instance of the
429 * non-public class {@link <a
430 * href="../../serialized-form.html#javax.management.NumericValueExp">
431 * javax.management.NumericValueExp</a>}.
432 */
433 public static ValueExp value(float val) {
434 return new NumericValueExp((double) val);
435 }
436
437 /**
438 * Returns a numeric value expression that can be used in any Query call
439 * that expects a ValueExp.
440 *
441 * @param val A double value.
442 *
443 * @return A ValueExp object containing the argument. The
444 * returned object will be serialized as an instance of the
445 * non-public class {@link <a
446 * href="../../serialized-form.html#javax.management.NumericValueExp">
447 * javax.management.NumericValueExp</a>}.
448 */
449 public static ValueExp value(double val) {
450 return new NumericValueExp(val);
451 }
452
453 /**
454 * Returns a boolean value expression that can be used in any Query call
455 * that expects a ValueExp.
456 *
457 * @param val A boolean value.
458 *
459 * @return A ValueExp object containing the argument. The
460 * returned object will be serialized as an instance of the
461 * non-public class {@link <a
462 * href="../../serialized-form.html#javax.management.BooleanValueExp">
463 * javax.management.BooleanValueExp</a>}.
464 */
465 public static ValueExp value(boolean val) {
466 return new BooleanValueExp(val);
467 }
468
469 /**
470 * Returns a binary expression representing the sum of two numeric values,
471 * or the concatenation of two string values.
472 *
473 * @param value1 The first '+' operand.
474 * @param value2 The second '+' operand.
475 *
476 * @return A ValueExp representing the sum or concatenation of
477 * the two arguments. The returned object will be serialized as
478 * an instance of the non-public class {@link <a
479 * href="../../serialized-form.html#javax.management.BinaryOpValueExp">
480 * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to
481 * {@link #PLUS}.
482 */
483 public static ValueExp plus(ValueExp value1, ValueExp value2) {
484 return new BinaryOpValueExp(PLUS, value1, value2);
485 }
486
487 /**
488 * Returns a binary expression representing the product of two numeric values.
489 *
490 *
491 * @param value1 The first '*' operand.
492 * @param value2 The second '*' operand.
493 *
494 * @return A ValueExp representing the product. The returned
495 * object will be serialized as an instance of the non-public
496 * class {@link <a
497 * href="../../serialized-form.html#javax.management.BinaryOpValueExp">
498 * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to
499 * {@link #TIMES}.
500 */
501 public static ValueExp times(ValueExp value1, ValueExp value2) {
502 return new BinaryOpValueExp(TIMES, value1, value2);
503 }
504
505 /**
506 * Returns a binary expression representing the difference between two numeric
507 * values.
508 *
509 * @param value1 The first '-' operand.
510 * @param value2 The second '-' operand.
511 *
512 * @return A ValueExp representing the difference between two
513 * arguments. The returned object will be serialized as an
514 * instance of the non-public class {@link <a
515 * href="../../serialized-form.html#javax.management.BinaryOpValueExp">
516 * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to
517 * {@link #MINUS}.
518 */
519 public static ValueExp minus(ValueExp value1, ValueExp value2) {
520 return new BinaryOpValueExp(MINUS, value1, value2);
521 }
522
523 /**
524 * Returns a binary expression representing the quotient of two numeric
525 * values.
526 *
527 * @param value1 The first '/' operand.
528 * @param value2 The second '/' operand.
529 *
530 * @return A ValueExp representing the quotient of two arguments.
531 * The returned object will be serialized as an instance of the
532 * non-public class {@link <a
533 * href="../../serialized-form.html#javax.management.BinaryOpValueExp">
534 * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to
535 * {@link #DIV}.
536 */
537 public static ValueExp div(ValueExp value1, ValueExp value2) {
538 return new BinaryOpValueExp(DIV, value1, value2);
539 }
540
541 /**
542 * Returns a query expression that represents a matching constraint on
543 * a string argument. The value must start with the given literal string
544 * value.
545 *
546 * @param a An attribute expression.
547 * @param s A string value expression representing the beginning of the
548 * string value.
549 *
550 * @return The constraint that a matches s. The returned object
551 * will be serialized as an instance of the non-public class
552 * {@link <a
553 * href="../../serialized-form.html#javax.management.MatchQueryExp">
554 * javax.management.MatchQueryExp</a>}.
555 */
556 public static QueryExp initialSubString(AttributeValueExp a,
557 StringValueExp s) {
558 return new MatchQueryExp(a, new StringValueExp(escapeString(s
559 .getValue())
560 + "*"));
561 }
562
563 /**
564 * Returns a query expression that represents a matching constraint on
565 * a string argument. The value must contain the given literal string
566 * value.
567 *
568 * @param a An attribute expression.
569 * @param s A string value expression representing the substring.
570 *
571 * @return The constraint that a matches s. The returned object
572 * will be serialized as an instance of the non-public class
573 * {@link <a
574 * href="../../serialized-form.html#javax.management.MatchQueryExp">
575 * javax.management.MatchQueryExp</a>}.
576 */
577 public static QueryExp anySubString(AttributeValueExp a,
578 StringValueExp s) {
579 return new MatchQueryExp(a, new StringValueExp("*"
580 + escapeString(s.getValue()) + "*"));
581 }
582
583 /**
584 * Returns a query expression that represents a matching constraint on
585 * a string argument. The value must end with the given literal string
586 * value.
587 *
588 * @param a An attribute expression.
589 * @param s A string value expression representing the end of the string
590 * value.
591 *
592 * @return The constraint that a matches s. The returned object
593 * will be serialized as an instance of the non-public class
594 * {@link <a
595 * href="../../serialized-form.html#javax.management.MatchQueryExp">
596 * javax.management.MatchQueryExp</a>}.
597 */
598 public static QueryExp finalSubString(AttributeValueExp a,
599 StringValueExp s) {
600 return new MatchQueryExp(a, new StringValueExp("*"
601 + escapeString(s.getValue())));
602 }
603
604 /**
605 * Returns a query expression that represents an inheritance constraint
606 * on an MBean class.
607 * <p>Example: to find MBeans that are instances of
608 * {@link NotificationBroadcaster}, use
609 * {@code Query.isInstanceOf(Query.value(NotificationBroadcaster.class.getName()))}.
610 * </p>
611 * <p>Evaluating this expression for a given
612 * <code>objectName</code> includes performing {@link
613 * MBeanServer#isInstanceOf MBeanServer.isInstanceOf(objectName,
614 * ((StringValueExp)classNameValue.apply(objectName)).getValue()}.</p>
615 *
616 * @param classNameValue The {@link StringValueExp} returning the name
617 * of the class of which selected MBeans should be instances.
618 * @return a query expression that represents an inheritance
619 * constraint on an MBean class. The returned object will be
620 * serialized as an instance of the non-public class {@link <a
621 * href="../../serialized-form.html#javax.management.InstanceOfQueryExp">
622 * javax.management.InstanceOfQueryExp</a>}.
623 * @since 1.6
624 */
625 public static QueryExp isInstanceOf(StringValueExp classNameValue) {
626 return new InstanceOfQueryExp(classNameValue);
627 }
628
629 /**
630 * Utility method to escape strings used with
631 * Query.{initial|any|final}SubString() methods.
632 */
633 private static String escapeString(String s) {
634 if (s == null)
635 return null;
636 s = s.replace("\\", "\\\\");
637 s = s.replace("*", "\\*");
638 s = s.replace("?", "\\?");
639 s = s.replace("[", "\\[");
640 return s;
641 }
642 }
|