1 /* 2 * Copyright (c) 1999, 2018, 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 131 * <a href="{@docRoot}/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 147 * <a href="{@docRoot}/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 164 * <a href="{@docRoot}/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 182 * <a href="{@docRoot}/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 200 * <a href="{@docRoot}/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 218 * <a href="{@docRoot}/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 236 * <a href="{@docRoot}/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 255 * <a href="{@docRoot}/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 283 * <a href="{@docRoot}/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 323 * <a href="{@docRoot}/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 * <a href="{@docRoot}/serialized-form.html#javax.management.ClassAttributeValueExp"> 342 * javax.management.ClassAttributeValueExp</a>. 343 */ 344 public static AttributeValueExp classattr() { 345 return new ClassAttributeValueExp(); 346 } 347 348 /** 349 * Returns a constraint that is the negation of its argument. 350 * 351 * @param queryExp The constraint to negate. 352 * 353 * @return A negated constraint. The returned object will be 354 * serialized as an instance of the non-public class 355 * <a href="{@docRoot}/serialized-form.html#javax.management.NotQueryExp"> 356 * javax.management.NotQueryExp</a>. 357 */ 358 public static QueryExp not(QueryExp queryExp) { 359 return new NotQueryExp(queryExp); 360 } 361 362 /** 363 * Returns an expression constraining a value to be one of an explicit list. 364 * 365 * @param val A value to be constrained. 366 * @param valueList An array of ValueExps. 367 * 368 * @return A QueryExp that represents the constraint. The 369 * returned object will be serialized as an instance of the 370 * non-public class 371 * <a href="{@docRoot}/serialized-form.html#javax.management.InQueryExp"> 372 * javax.management.InQueryExp</a>. 373 */ 374 public static QueryExp in(ValueExp val, ValueExp valueList[]) { 375 return new InQueryExp(val, valueList); 376 } 377 378 /** 379 * Returns a new string expression. 380 * 381 * @param val The string value. 382 * 383 * @return A ValueExp object containing the string argument. 384 */ 385 public static StringValueExp value(String val) { 386 return new StringValueExp(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 instance of Number. 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 398 * <a href="{@docRoot}/serialized-form.html#javax.management.NumericValueExp"> 399 * javax.management.NumericValueExp</a>. 400 */ 401 public static ValueExp value(Number val) { 402 return new NumericValueExp(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 An int 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 414 * <a href="{@docRoot}/serialized-form.html#javax.management.NumericValueExp"> 415 * javax.management.NumericValueExp</a>. 416 */ 417 public static ValueExp value(int val) { 418 return new NumericValueExp((long) 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 long 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 430 * <a href="{@docRoot}/serialized-form.html#javax.management.NumericValueExp"> 431 * javax.management.NumericValueExp</a>. 432 */ 433 public static ValueExp value(long val) { 434 return new NumericValueExp(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 float 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 446 * <a href="{@docRoot}/serialized-form.html#javax.management.NumericValueExp"> 447 * javax.management.NumericValueExp</a>. 448 */ 449 public static ValueExp value(float val) { 450 return new NumericValueExp((double) val); 451 } 452 453 /** 454 * Returns a numeric value expression that can be used in any Query call 455 * that expects a ValueExp. 456 * 457 * @param val A double 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 462 * <a href="{@docRoot}/serialized-form.html#javax.management.NumericValueExp"> 463 * javax.management.NumericValueExp</a>. 464 */ 465 public static ValueExp value(double val) { 466 return new NumericValueExp(val); 467 } 468 469 /** 470 * Returns a boolean value expression that can be used in any Query call 471 * that expects a ValueExp. 472 * 473 * @param val A boolean value. 474 * 475 * @return A ValueExp object containing the argument. The 476 * returned object will be serialized as an instance of the 477 * non-public class 478 * <a href="{@docRoot}/serialized-form.html#javax.management.BooleanValueExp"> 479 * javax.management.BooleanValueExp</a>. 480 */ 481 public static ValueExp value(boolean val) { 482 return new BooleanValueExp(val); 483 } 484 485 /** 486 * Returns a binary expression representing the sum of two numeric values, 487 * or the concatenation of two string values. 488 * 489 * @param value1 The first '+' operand. 490 * @param value2 The second '+' operand. 491 * 492 * @return A ValueExp representing the sum or concatenation of 493 * the two arguments. The returned object will be serialized as 494 * an instance of the non-public class 495 * <a href="{@docRoot}/serialized-form.html#javax.management.BinaryOpValueExp"> 496 * javax.management.BinaryOpValueExp</a> with an {@code op} equal to 497 * {@link #PLUS}. 498 */ 499 public static ValueExp plus(ValueExp value1, ValueExp value2) { 500 return new BinaryOpValueExp(PLUS, value1, value2); 501 } 502 503 /** 504 * Returns a binary expression representing the product of two numeric values. 505 * 506 * 507 * @param value1 The first '*' operand. 508 * @param value2 The second '*' operand. 509 * 510 * @return A ValueExp representing the product. The returned 511 * object will be serialized as an instance of the non-public 512 * class 513 * <a href="{@docRoot}/serialized-form.html#javax.management.BinaryOpValueExp"> 514 * javax.management.BinaryOpValueExp</a> with an {@code op} equal to 515 * {@link #TIMES}. 516 */ 517 public static ValueExp times(ValueExp value1,ValueExp value2) { 518 return new BinaryOpValueExp(TIMES, value1, value2); 519 } 520 521 /** 522 * Returns a binary expression representing the difference between two numeric 523 * values. 524 * 525 * @param value1 The first '-' operand. 526 * @param value2 The second '-' operand. 527 * 528 * @return A ValueExp representing the difference between two 529 * arguments. The returned object will be serialized as an 530 * instance of the non-public class 531 * <a href="{@docRoot}/serialized-form.html#javax.management.BinaryOpValueExp"> 532 * javax.management.BinaryOpValueExp</a> with an {@code op} equal to 533 * {@link #MINUS}. 534 */ 535 public static ValueExp minus(ValueExp value1, ValueExp value2) { 536 return new BinaryOpValueExp(MINUS, value1, value2); 537 } 538 539 /** 540 * Returns a binary expression representing the quotient of two numeric 541 * values. 542 * 543 * @param value1 The first '/' operand. 544 * @param value2 The second '/' operand. 545 * 546 * @return A ValueExp representing the quotient of two arguments. 547 * The returned object will be serialized as an instance of the 548 * non-public class 549 * <a href="{@docRoot}/serialized-form.html#javax.management.BinaryOpValueExp"> 550 * javax.management.BinaryOpValueExp</a> with an {@code op} equal to 551 * {@link #DIV}. 552 */ 553 public static ValueExp div(ValueExp value1, ValueExp value2) { 554 return new BinaryOpValueExp(DIV, value1, value2); 555 } 556 557 /** 558 * Returns a query expression that represents a matching constraint on 559 * a string argument. The value must start with the given literal string 560 * value. 561 * 562 * @param a An attribute expression. 563 * @param s A string value expression representing the beginning of the 564 * string value. 565 * 566 * @return The constraint that a matches s. The returned object 567 * will be serialized as an instance of the non-public class 568 * 569 * <a href="{@docRoot}/serialized-form.html#javax.management.MatchQueryExp"> 570 * javax.management.MatchQueryExp</a>. 571 */ 572 public static QueryExp initialSubString(AttributeValueExp a, StringValueExp s) { 573 return new MatchQueryExp(a, 574 new StringValueExp(escapeString(s.getValue()) + "*")); 575 } 576 577 /** 578 * Returns a query expression that represents a matching constraint on 579 * a string argument. The value must contain the given literal string 580 * value. 581 * 582 * @param a An attribute expression. 583 * @param s A string value expression representing the substring. 584 * 585 * @return The constraint that a matches s. The returned object 586 * will be serialized as an instance of the non-public class 587 * 588 * <a href="{@docRoot}/serialized-form.html#javax.management.MatchQueryExp"> 589 * javax.management.MatchQueryExp</a>. 590 */ 591 public static QueryExp anySubString(AttributeValueExp a, StringValueExp s) { 592 return new MatchQueryExp(a, 593 new StringValueExp("*" + escapeString(s.getValue()) + "*")); 594 } 595 596 /** 597 * Returns a query expression that represents a matching constraint on 598 * a string argument. The value must end with the given literal string 599 * value. 600 * 601 * @param a An attribute expression. 602 * @param s A string value expression representing the end of the string 603 * value. 604 * 605 * @return The constraint that a matches s. The returned object 606 * will be serialized as an instance of the non-public class 607 * 608 * <a href="{@docRoot}/serialized-form.html#javax.management.MatchQueryExp"> 609 * javax.management.MatchQueryExp</a>. 610 */ 611 public static QueryExp finalSubString(AttributeValueExp a, StringValueExp s) { 612 return new MatchQueryExp(a, 613 new StringValueExp("*" + escapeString(s.getValue()))); 614 } 615 616 /** 617 * Returns a query expression that represents an inheritance constraint 618 * on an MBean class. 619 * <p>Example: to find MBeans that are instances of 620 * {@link NotificationBroadcaster}, use 621 * {@code Query.isInstanceOf(Query.value(NotificationBroadcaster.class.getName()))}. 622 * </p> 623 * <p>Evaluating this expression for a given 624 * <code>objectName</code> includes performing {@link 625 * MBeanServer#isInstanceOf MBeanServer.isInstanceOf(objectName, 626 * ((StringValueExp)classNameValue.apply(objectName)).getValue()}.</p> 627 * 628 * @param classNameValue The {@link StringValueExp} returning the name 629 * of the class of which selected MBeans should be instances. 630 * @return a query expression that represents an inheritance 631 * constraint on an MBean class. The returned object will be 632 * serialized as an instance of the non-public class 633 * <a href="{@docRoot}/serialized-form.html#javax.management.InstanceOfQueryExp"> 634 * javax.management.InstanceOfQueryExp</a>. 635 * @since 1.6 636 */ 637 public static QueryExp isInstanceOf(StringValueExp classNameValue) { 638 return new InstanceOfQueryExp(classNameValue); 639 } 640 641 /** 642 * Utility method to escape strings used with 643 * Query.{initial|any|final}SubString() methods. 644 */ 645 private static String escapeString(String s) { 646 if (s == null) 647 return null; 648 s = s.replace("\\", "\\\\"); 649 s = s.replace("*", "\\*"); 650 s = s.replace("?", "\\?"); 651 s = s.replace("[", "\\["); 652 return s; 653 } 654 }