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. The static methods provided

    31  * return query expressions that may be used in listing and

    32  * enumerating MBeans. Individual constraint construction methods

    33  * allow only appropriate types as arguments. Composition of calls can

    34  * construct arbitrary nestings of constraints, as the following

    35  * example illustrates:</p>

    36  *

    37  * <pre>

    38  * QueryExp exp = Query.and(Query.gt(Query.attr("age"),Query.value(5)),

    39  *                          Query.match(Query.attr("name"),

    40  *                                      Query.value("Smith")));

    41  * </pre>

    42  *

    43  * @since 1.5

    44  */

    45  public class Query extends Object   {

    46 

    47 

    48      /**

    49       * A code representing the {@link Query#gt} query.  This is chiefly

    50       * of interest for the serialized form of queries.

    51       */

    52      public static final int GT  = 0;

    53 

    54      /**

    55       * A code representing the {@link Query#lt} query.  This is chiefly

    56       * of interest for the serialized form of queries.

    57       */

    58      public static final int LT  = 1;

    59 

    60      /**

    61       * A code representing the {@link Query#geq} query.  This is chiefly

    62       * of interest for the serialized form of queries.

    63       */

    64      public static final int GE  = 2;

    65 

    66      /**

    67       * A code representing the {@link Query#leq} query.  This is chiefly

    68       * of interest for the serialized form of queries.

    69       */

    70      public static final int LE  = 3;

    71 

    72      /**

    73       * A code representing the {@link Query#eq} query.  This is chiefly

    74       * of interest for the serialized form of queries.

    75       */

    76      public static final int EQ  = 4;

    77 

    78 

    79      /**

    80       * A code representing the {@link Query#plus} expression.  This

    81       * is chiefly of interest for the serialized form of queries.

    82       */

    83      public static final int PLUS  = 0;

    84 

    85      /**

    86       * A code representing the {@link Query#minus} expression.  This

    87       * is chiefly of interest for the serialized form of queries.

    88       */

    89      public static final int MINUS = 1;

    90 

    91      /**

    92       * A code representing the {@link Query#times} expression.  This

    93       * is chiefly of interest for the serialized form of queries.

    94       */

    95      public static final int TIMES = 2;

    96 

    97      /**

    98       * A code representing the {@link Query#div} expression.  This is

    99       * chiefly of interest for the serialized form of queries.

   100       */

   101      public static final int DIV   = 3;

   102 

   103 

   104      /**

   105       * Basic constructor.

   106       */

   107      public Query() {

   108      }

   109 

   110 

   111      /**

   112       * Returns a query expression that is the conjunction of two other query

   113       * expressions.

   114       *

   115       * @param q1 A query expression.

   116       * @param q2 Another query expression.

   117       *

   118       * @return  The conjunction of the two arguments.  The returned object

   119       * will be serialized as an instance of the non-public class {@link

   120       * <a href="../../serialized-form.html#javax.management.AndQueryExp">

   121       * javax.management.AndQueryExp</a>}.

   122       */

   123      public static QueryExp and(QueryExp q1, QueryExp q2)  {

   124          return new AndQueryExp(q1, q2);

   125      }

   126 

   127      /**

   128       * Returns a query expression that is the disjunction of two other query

   129       * expressions.

   130       *

   131       * @param q1 A query expression.

   132       * @param q2 Another query expression.

   133       *

   134       * @return  The disjunction of the two arguments.  The returned object

   135       * will be serialized as an instance of the non-public class {@link

   136       * <a href="../../serialized-form.html#javax.management.OrQueryExp">

   137       * javax.management.OrQueryExp</a>}.

   138       */

   139      public static QueryExp or(QueryExp q1, QueryExp q2)  {

   140          return new OrQueryExp(q1, q2);

   141      }

   142 

   143      /**

   144       * Returns a query expression that represents a "greater than" constraint on

   145       * two values.

   146       *

   147       * @param v1 A value expression.

   148       * @param v2 Another value expression.

   149       *

   150       * @return A "greater than" constraint on the arguments.  The

   151       * returned object will be serialized as an instance of the

   152       * non-public class {@link <a

   153       * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">

   154       * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal

   155       * to {@link #GT}.

   156       */

   157      public static QueryExp gt(ValueExp v1, ValueExp v2)  {

   158          return new BinaryRelQueryExp(GT, v1, v2);

   159      }

   160 

   161      /**

   162       * Returns a query expression that represents a "greater than or equal

   163       * to" constraint on two values.

   164       *

   165       * @param v1 A value expression.

   166       * @param v2 Another value expression.

   167       *

   168       * @return A "greater than or equal to" constraint on the

   169       * arguments.  The returned object will be serialized as an

   170       * instance of the non-public class {@link <a

   171       * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">

   172       * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal

   173       * to {@link #GE}.

   174       */

   175      public static QueryExp geq(ValueExp v1, ValueExp v2)  {

   176          return new BinaryRelQueryExp(GE, v1, v2);

   177      }

   178 

   179      /**

   180       * Returns a query expression that represents a "less than or equal to"

   181       * constraint on two values.

   182       *

   183       * @param v1 A value expression.

   184       * @param v2 Another value expression.

   185       *

   186       * @return A "less than or equal to" constraint on the arguments.

   187       * The returned object will be serialized as an instance of the

   188       * non-public class {@link <a

   189       * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">

   190       * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal

   191       * to {@link #LE}.

   192       */

   193      public static QueryExp leq(ValueExp v1, ValueExp v2)  {

   194          return new BinaryRelQueryExp(LE, v1, v2);

   195      }

   196 

   197      /**

   198       * Returns a query expression that represents a "less than" constraint on

   199       * two values.

   200       *

   201       * @param v1 A value expression.

   202       * @param v2 Another value expression.

   203       *

   204       * @return A "less than" constraint on the arguments.  The

   205       * returned object will be serialized as an instance of the

   206       * non-public class {@link <a

   207       * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">

   208       * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal

   209       * to {@link #LT}.

   210       */

   211      public static QueryExp lt(ValueExp v1, ValueExp v2)  {

   212          return new BinaryRelQueryExp(LT, v1, v2);

   213      }

   214 

   215      /**

   216       * Returns a query expression that represents an equality constraint on

   217       * two values.

   218       *

   219       * @param v1 A value expression.

   220       * @param v2 Another value expression.

   221       *

   222       * @return A "equal to" constraint on the arguments.  The

   223       * returned object will be serialized as an instance of the

   224       * non-public class {@link <a

   225       * href="../../serialized-form.html#javax.management.BinaryRelQueryExp">

   226       * javax.management.BinaryRelQueryExp</a>} with a {@code relOp} equal

   227       * to {@link #EQ}.

   228       */

   229      public static QueryExp eq(ValueExp v1, ValueExp v2)  {

   230          return new BinaryRelQueryExp(EQ, v1, v2);

   231      }

   232 

   233      /**

   234       * Returns a query expression that represents the constraint that one

   235       * value is between two other values.

   236       *

   237       * @param v1 A value expression that is "between" v2 and v3.

   238       * @param v2 Value expression that represents a boundary of the constraint.

   239       * @param v3 Value expression that represents a boundary of the constraint.

   240       *

   241       * @return The constraint that v1 lies between v2 and v3.  The

   242       * returned object will be serialized as an instance of the

   243       * non-public class {@link <a

   244       * href="../../serialized-form.html#javax.management.BetweenQueryExp">

   245       * javax.management.BetweenQueryExp</a>}.

   246       */

   247      public static QueryExp between(ValueExp v1, ValueExp v2, ValueExp v3) {

   248          return new BetweenQueryExp(v1, v2, v3);

   249      }

   250 

   251      /**

   252       * Returns a query expression that represents a matching constraint on

   253       * a string argument. The matching syntax is consistent with file globbing:

   254       * supports "<code>?</code>", "<code>*</code>", "<code>[</code>",

   255       * each of which may be escaped with "<code>\</code>";

   256       * character classes may use "<code>!</code>" for negation and

   257       * "<code>-</code>" for range.

   258       * (<code>*</code> for any character sequence,

   259       * <code>?</code> for a single arbitrary character,

   260       * <code>[...]</code> for a character sequence).

   261       * For example: <code>a*b?c</code> would match a string starting

   262       * with the character <code>a</code>, followed

   263       * by any number of characters, followed by a <code>b</code>,

   264       * any single character, and a <code>c</code>.

   265       *

   266       * @param a An attribute expression

   267       * @param s A string value expression representing a matching constraint

   268       *

   269       * @return A query expression that represents the matching

   270       * constraint on the string argument.  The returned object will

   271       * be serialized as an instance of the non-public class {@link <a

   272       * href="../../serialized-form.html#javax.management.MatchQueryExp">

   273       * javax.management.MatchQueryExp</a>}.

   274       */

   275      public static QueryExp match(AttributeValueExp a, StringValueExp s)  {

   276          return new MatchQueryExp(a, s);

   277      }

   278 

   279      /**

   280       * <p>Returns a new attribute expression.</p>

   281       *

   282       * <p>Evaluating this expression for a given

   283       * <code>objectName</code> includes performing {@link

   284       * MBeanServer#getAttribute MBeanServer.getAttribute(objectName,

   285       * name)}.</p>

   286       *

   287       * @param name The name of the attribute.

   288       *

   289       * @return  An attribute expression for the attribute named name.

   290       */

   291      public static AttributeValueExp attr(String name)  {

   292          return new AttributeValueExp(name);

   293      }

   294 

   295      /**

   296       * <p>Returns a new qualified attribute expression.</p>

   297       *

   298       * <p>Evaluating this expression for a given

   299       * <code>objectName</code> includes performing {@link

   300       * MBeanServer#getObjectInstance

   301       * MBeanServer.getObjectInstance(objectName)} and {@link

   302       * MBeanServer#getAttribute MBeanServer.getAttribute(objectName,

   303       * name)}.</p>

   304       *

   305       * @param className The name of the class possessing the attribute.

   306       * @param name The name of the attribute.

   307       *

   308       * @return An attribute expression for the attribute named name.

   309       * The returned object will be serialized as an instance of the

   310       * non-public class {@link <a

   311       * href="../../serialized-form.html#javax.management.QualifiedAttributeValueExp">

   312       * javax.management.QualifiedAttributeValueExp</a>}.

   313       */

   314      public static AttributeValueExp attr(String className, String name)  {

   315          return new QualifiedAttributeValueExp(className, name);

   316      }

   317 

   318      /**

   319       * <p>Returns a new class attribute expression which can be used in any

   320       * Query call that expects a ValueExp.</p>

   321       *

   322       * <p>Evaluating this expression for a given

   323       * <code>objectName</code> includes performing {@link

   324       * MBeanServer#getObjectInstance

   325       * MBeanServer.getObjectInstance(objectName)}.</p>

   326       *

   327       * @return A class attribute expression.  The returned object

   328       * will be serialized as an instance of the non-public class

   329       * {@link <a

   330       * href="../../serialized-form.html#javax.management.ClassAttributeValueExp">

   331       * javax.management.ClassAttributeValueExp</a>}.

   332       */

   333      public static AttributeValueExp classattr()  {

   334          return new ClassAttributeValueExp();

   335      }

   336 

   337      /**

   338       * Returns a constraint that is the negation of its argument.

   339       *

   340       * @param queryExp The constraint to negate.

   341       *

   342       * @return A negated constraint.  The returned object will be

   343       * serialized as an instance of the non-public class {@link <a

   344       * href="../../serialized-form.html#javax.management.NotQueryExp">

   345       * javax.management.NotQueryExp</a>}.

   346       */

   347      public static QueryExp not(QueryExp queryExp)  {

   348          return new NotQueryExp(queryExp);

   349      }

   350 

   351      /**

   352       * Returns an expression constraining a value to be one of an explicit list.

   353       *

   354       * @param val A value to be constrained.

   355       * @param valueList An array of ValueExps.

   356       *

   357       * @return A QueryExp that represents the constraint.  The

   358       * returned object will be serialized as an instance of the

   359       * non-public class {@link <a

   360       * href="../../serialized-form.html#javax.management.InQueryExp">

   361       * javax.management.InQueryExp</a>}.

   362       */

   363      public static QueryExp in(ValueExp val, ValueExp valueList[])  {

   364          return new InQueryExp(val, valueList);

   365      }

   366 

   367      /**

   368       * Returns a new string expression.

   369       *

   370       * @param val The string value.

   371       *

   372       * @return  A ValueExp object containing the string argument.

   373       */

   374      public static StringValueExp value(String val)  {

   375          return new StringValueExp(val);

   376      }

   377 

   378      /**

   379       * Returns a numeric value expression that can be used in any Query call

   380       * that expects a ValueExp.

   381       *

   382       * @param val An instance of Number.

   383       *

   384       * @return A ValueExp object containing the argument.  The

   385       * returned object will be serialized as an instance of the

   386       * non-public class {@link <a

   387       * href="../../serialized-form.html#javax.management.NumericValueExp">

   388       * javax.management.NumericValueExp</a>}.

   389       */

   390      public static ValueExp value(Number val)  {

   391          return new NumericValueExp(val);

   392      }

   393 

   394      /**

   395       * Returns a numeric value expression that can be used in any Query call

   396       * that expects a ValueExp.

   397       *

   398       * @param val An int value.

   399       *

   400       * @return A ValueExp object containing the argument.  The

   401       * returned object will be serialized as an instance of the

   402       * non-public class {@link <a

   403       * href="../../serialized-form.html#javax.management.NumericValueExp">

   404       * javax.management.NumericValueExp</a>}.

   405       */

   406      public static ValueExp value(int val)  {

   407          return new NumericValueExp((long) val);

   408      }

   409 

   410      /**

   411       * Returns a numeric value expression that can be used in any Query call

   412       * that expects a ValueExp.

   413       *

   414       * @param val A long value.

   415       *

   416       * @return A ValueExp object containing the argument.  The

   417       * returned object will be serialized as an instance of the

   418       * non-public class {@link <a

   419       * href="../../serialized-form.html#javax.management.NumericValueExp">

   420       * javax.management.NumericValueExp</a>}.

   421       */

   422      public static ValueExp value(long val)  {

   423          return new NumericValueExp(val);

   424      }

   425 

   426      /**

   427       * Returns a numeric value expression that can be used in any Query call

   428       * that expects a ValueExp.

   429       *

   430       * @param val A float value.

   431       *

   432       * @return A ValueExp object containing the argument.  The

   433       * returned object will be serialized as an instance of the

   434       * non-public class {@link <a

   435       * href="../../serialized-form.html#javax.management.NumericValueExp">

   436       * javax.management.NumericValueExp</a>}.

   437       */

   438      public static ValueExp value(float val)  {

   439          return new NumericValueExp((double) val);

   440      }

   441 

   442      /**

   443       * Returns a numeric value expression that can be used in any Query call

   444       * that expects a ValueExp.

   445       *

   446       * @param val A double value.

   447       *

   448       * @return  A ValueExp object containing the argument.  The

   449       * returned object will be serialized as an instance of the

   450       * non-public class {@link <a

   451       * href="../../serialized-form.html#javax.management.NumericValueExp">

   452       * javax.management.NumericValueExp</a>}.

   453       */

   454      public static ValueExp value(double val)  {

   455          return new NumericValueExp(val);

   456      }

   457 

   458      /**

   459       * Returns a boolean value expression that can be used in any Query call

   460       * that expects a ValueExp.

   461       *

   462       * @param val A boolean value.

   463       *

   464       * @return A ValueExp object containing the argument.  The

   465       * returned object will be serialized as an instance of the

   466       * non-public class {@link <a

   467       * href="../../serialized-form.html#javax.management.BooleanValueExp">

   468       * javax.management.BooleanValueExp</a>}.

   469       */

   470      public static ValueExp value(boolean val)  {

   471          return new BooleanValueExp(val);

   472      }

   473 

   474      /**

   475       * Returns a binary expression representing the sum of two numeric values,

   476       * or the concatenation of two string values.

   477       *

   478       * @param value1 The first '+' operand.

   479       * @param value2 The second '+' operand.

   480       *

   481       * @return A ValueExp representing the sum or concatenation of

   482       * the two arguments.  The returned object will be serialized as

   483       * an instance of the non-public class {@link <a

   484       * href="../../serialized-form.html#javax.management.BinaryOpValueExp">

   485       * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to

   486       * {@link #PLUS}.

   487       */

   488      public static ValueExp plus(ValueExp value1, ValueExp value2) {

   489          return new BinaryOpValueExp(PLUS, value1, value2);

   490      }

   491 

   492      /**

   493       * Returns a binary expression representing the product of two numeric values.

   494       *

   495       *

   496       * @param value1 The first '*' operand.

   497       * @param value2 The second '*' operand.

   498       *

   499       * @return A ValueExp representing the product.  The returned

   500       * object will be serialized as an instance of the non-public

   501       * class {@link <a

   502       * href="../../serialized-form.html#javax.management.BinaryOpValueExp">

   503       * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to

   504       * {@link #TIMES}.

   505       */

   506      public static ValueExp times(ValueExp value1,ValueExp value2) {

   507          return new BinaryOpValueExp(TIMES, value1, value2);

   508      }

   509 

   510      /**

   511       * Returns a binary expression representing the difference between two numeric

   512       * values.

   513       *

   514       * @param value1 The first '-' operand.

   515       * @param value2 The second '-' operand.

   516       *

   517       * @return A ValueExp representing the difference between two

   518       * arguments.  The returned object will be serialized as an

   519       * instance of the non-public class {@link <a

   520       * href="../../serialized-form.html#javax.management.BinaryOpValueExp">

   521       * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to

   522       * {@link #MINUS}.

   523       */

   524      public static ValueExp minus(ValueExp value1, ValueExp value2) {

   525          return new BinaryOpValueExp(MINUS, value1, value2);

   526      }

   527 

   528      /**

   529       * Returns a binary expression representing the quotient of two numeric

   530       * values.

   531       *

   532       * @param value1 The first '/' operand.

   533       * @param value2 The second '/' operand.

   534       *

   535       * @return A ValueExp representing the quotient of two arguments.

   536       * The returned object will be serialized as an instance of the

   537       * non-public class {@link <a

   538       * href="../../serialized-form.html#javax.management.BinaryOpValueExp">

   539       * javax.management.BinaryOpValueExp</a>} with an {@code op} equal to

   540       * {@link #DIV}.

   541       */

   542      public static ValueExp div(ValueExp value1, ValueExp value2) {

   543          return new BinaryOpValueExp(DIV, value1, value2);

   544      }

   545 

   546      /**

   547       * Returns a query expression that represents a matching constraint on

   548       * a string argument. The value must start with the given literal string

   549       * value.

   550       *

   551       * @param a An attribute expression.

   552       * @param s A string value expression representing the beginning of the

   553       * string value.

   554       *

   555       * @return The constraint that a matches s.  The returned object

   556       * will be serialized as an instance of the non-public class

   557       * {@link <a

   558       * href="../../serialized-form.html#javax.management.MatchQueryExp">

   559       * javax.management.MatchQueryExp</a>}.

   560       */

   561      public static QueryExp initialSubString(AttributeValueExp a, StringValueExp s)  {

   562          return new MatchQueryExp(a,

   563              new StringValueExp(escapeString(s.getValue()) + "*"));

   564      }

   565 

   566      /**

   567       * Returns a query expression that represents a matching constraint on

   568       * a string argument. The value must contain the given literal string

   569       * value.

   570       *

   571       * @param a An attribute expression.

   572       * @param s A string value expression representing the substring.

   573       *

   574       * @return The constraint that a matches s.  The returned object

   575       * will be serialized as an instance of the non-public class

   576       * {@link <a

   577       * href="../../serialized-form.html#javax.management.MatchQueryExp">

   578       * javax.management.MatchQueryExp</a>}.

   579       */

   580      public static QueryExp anySubString(AttributeValueExp a, StringValueExp s) {

   581          return new MatchQueryExp(a,

   582              new StringValueExp("*" + escapeString(s.getValue()) + "*"));

   583      }

   584 

   585      /**

   586       * Returns a query expression that represents a matching constraint on

   587       * a string argument. The value must end with the given literal string

   588       * value.

   589       *

   590       * @param a An attribute expression.

   591       * @param s A string value expression representing the end of the string

   592       * value.

   593       *

   594       * @return The constraint that a matches s.  The returned object

   595       * will be serialized as an instance of the non-public class

   596       * {@link <a

   597       * href="../../serialized-form.html#javax.management.MatchQueryExp">

   598       * javax.management.MatchQueryExp</a>}.

   599       */

   600      public static QueryExp finalSubString(AttributeValueExp a, StringValueExp s) {

   601          return new MatchQueryExp(a,

   602              new StringValueExp("*" + escapeString(s.getValue())));

   603      }

   604 

   605      /**

   606       * Returns a query expression that represents an inheritance constraint

   607       * on an MBean class.

   608       * <p>Example: to find MBeans that are instances of

   609       * {@link NotificationBroadcaster}, use

   610       * {@code Query.isInstanceOf(Query.value(NotificationBroadcaster.class.getName()))}.

   611       * </p>

   612       * <p>Evaluating this expression for a given

   613       * <code>objectName</code> includes performing {@link

   614       * MBeanServer#isInstanceOf MBeanServer.isInstanceOf(objectName,

   615       * ((StringValueExp)classNameValue.apply(objectName)).getValue()}.</p>

   616       *

   617       * @param classNameValue The {@link StringValueExp} returning the name

   618       *        of the class of which selected MBeans should be instances.

   619       * @return a query expression that represents an inheritance

   620       * constraint on an MBean class.  The returned object will be

   621       * serialized as an instance of the non-public class {@link <a

   622       * href="../../serialized-form.html#javax.management.InstanceOfQueryExp">

   623       * javax.management.InstanceOfQueryExp</a>}.

   624       * @since 1.6

   625       */

   626      public static QueryExp isInstanceOf(StringValueExp classNameValue) {

   627         return new InstanceOfQueryExp(classNameValue);

   628      }

   629 

   630      /**

   631       * Utility method to escape strings used with

   632       * Query.{initial|any|final}SubString() methods.

   633       */

   634      private static String escapeString(String s) {

   635          if (s == null)

   636              return null;

   637          s = s.replace("\\", "\\\\");

   638          s = s.replace("*", "\\*");

   639          s = s.replace("?", "\\?");

   640          s = s.replace("[", "\\[");

   641          return s;

   642      }

   643  }