1 /*
   2  * Copyright (c) 1999, 2004, 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  * Represents values that can be passed as arguments to
  31  * relational expressions. Strings, numbers, attributes are valid values
  32  * and should be represented by implementations of <CODE>ValueExp</CODE>.
  33  *
  34  * @since 1.5
  35  */
  36 /*
  37   We considered generifying this interface as ValueExp<T>, where T is
  38   the Java type that this expression generates.  This allows some additional
  39   checking in the various methods of the Query class, but in practice
  40   not much.  Typically you have something like
  41   Query.lt(Query.attr("A"), Query.value(5)).  We can arrange for Query.value
  42   to have type ValueExp<Integer> (or maybe ValueExp<Long> or ValueExp<Number>)
  43   but for Query.attr we can't do better than ValueExp<?> or plain ValueExp.
  44   So even though we could define Query.lt as:
  45   QueryExp <T> lt(ValueExp<T> v1, ValueExp<T> v2)
  46   and thus prevent comparing a
  47   number against a string, in practice the first ValueExp will almost always
  48   be a Query.attr so this check serves no purpose.  You would have to
  49   write Query.<Number>attr("A"), for example, which would be awful.  And,
  50   if you wrote Query.<Integer>attr("A") you would then discover that you
  51   couldn't compare it against Query.value(5) if the latter is defined as
  52   ValueExp<Number>, or against Query.value(5L) if it is defined as
  53   ValueExp<Integer>.
  54 
  55   Worse, for Query.in we would like to define:
  56   QueryExp <T> in(ValueExp<T> val, ValueExp<T>[] valueList)
  57   but this is unusable because you cannot write
  58   "new ValueExp<Integer>[] {...}" (the compiler forbids it).
  59 
  60   The few mistakes you might catch with this generification certainly
  61   wouldn't justify the hassle of modifying user code to get the checks
  62   to be made and the "unchecked" warnings that would arise if it
  63   wasn't so modified.
  64 
  65   We could reconsider this if the Query methods were augmented, for example
  66   with:
  67   AttributeValueExp<Number> numberAttr(String name);
  68   AttributeValueExp<String> stringAttr(String name);
  69   AttributeValueExp<Boolean> booleanAttr(String name);
  70   QueryExp <T> in(ValueExp<T> val, Set<ValueExp<T>> valueSet).
  71   But it's not really clear what numberAttr should do if it finds that the
  72   attribute is not in fact a Number.
  73  */
  74 public interface ValueExp extends java.io.Serializable {
  75 
  76     /**
  77      * Applies the ValueExp on a MBean.
  78      *
  79      * @param name The name of the MBean on which the ValueExp will be applied.
  80      *
  81      * @return  The <CODE>ValueExp</CODE>.
  82      *
  83      * @exception BadStringOperationException
  84      * @exception BadBinaryOpValueExpException
  85      * @exception BadAttributeValueExpException
  86      * @exception InvalidApplicationException
  87      */
  88     public ValueExp apply(ObjectName name)
  89             throws BadStringOperationException, BadBinaryOpValueExpException,
  90                    BadAttributeValueExpException, InvalidApplicationException;
  91 
  92     /**
  93      * Sets the MBean server on which the query is to be performed.
  94      *
  95      * @param s The MBean server on which the query is to be performed.
  96      *
  97      * @deprecated This method is not needed because a
  98      * <code>ValueExp</code> can access the MBean server in which it
  99      * is being evaluated by using {@link QueryEval#getMBeanServer()}.
 100      */
 101     @Deprecated
 102     public  void setMBeanServer(MBeanServer s) ;
 103 }