29 import com.sun.jmx.mbeanserver.MBeanInjector;

    30 import com.sun.jmx.remote.util.ClassLogger;

    31 import java.beans.BeanInfo;

    32 import java.beans.PropertyDescriptor;

    33 import java.io.IOException;

    34 import java.io.Serializable;

    36 import java.lang.reflect.InvocationTargetException;

    37 import java.lang.reflect.Method;

    39 import java.util.Map;

    40 import java.util.TreeMap;

    41 import javax.management.namespace.JMXNamespaces;

    42 import javax.management.openmbean.MXBeanMappingFactory;

    63    /**

    64      * The name of the <a

    65      * href="Descriptor.html#descriptionResourceBundleBaseName">{@code

    66      * descriptionResourceBundleBaseName}</a> field.

    67      */

    68     public static final String DESCRIPTION_RESOURCE_BUNDLE_BASE_NAME_FIELD =

    69             "descriptionResourceBundleBaseName";

    70 

    71     /**

    72      * The name of the <a href="Descriptor.html#descriptionResourceKey">{@code

    73      * descriptionResourceKey}</a> field.

    74      */

    75     public static final String DESCRIPTION_RESOURCE_KEY_FIELD =

    76             "descriptionResourceKey";

    77 

    78     /**

    79      * The name of the <a href="Descriptor.html#exceptions">{@code

    80      * exceptions}</a> field.

    81      */

    82     public static final String EXCEPTIONS_FIELD = "exceptions";

    83 

   103      * The name of the <a href="Descriptor.html#locale">{@code locale}</a>

   104      * field.

   105      */

   106     public static final String LOCALE_FIELD = "locale";

   107 

   108     /**

   127      * The name of the

   128      * <a href="Descriptor.html#mxbeanMappingFactoryClass">{@code

   129      * mxbeanMappingFactoryClass}</a> field.

   130      */

   131     public static final String MXBEAN_MAPPING_FACTORY_CLASS_FIELD =

   132             "mxbeanMappingFactoryClass";

   133 

   134     /**

   145 

   146     /**

   147      * The name of the <a href="Descriptor.html#setExceptions">{@code

   148      * setExceptions}</a> field.

   149      */

   150     public static final String SET_EXCEPTIONS_FIELD = "setExceptions";

   151 

   152     /**

   153      * The name of the <a href="Descriptor.html#objectNameTemplate">{@code

   154      * objectNameTemplate}</a> field.

   155      */

   156     public static final String OBJECT_NAME_TEMPLATE = "objectNameTemplate";

   157 

   158     /**

   159      * <p>Options to apply to an MBean proxy or to an instance of {@link

   160      * StandardMBean}.</p>

   161      *

   162      * <p>For example, to specify the "wrapped object visible" option for a

   163      * {@code StandardMBean}, you might write this:</p>

   164      *

   165      * <pre>

   166      * StandardMBean.Options opts = new StandardMBean.Options();

   167      * opts.setWrappedObjectVisible(true);

   168      * StandardMBean mbean = new StandardMBean(impl, intf, opts);

   169      * </pre>

   170      *

   171      * @see javax.management.JMX.ProxyOptions

   172      * @see javax.management.StandardMBean.Options

   173      */

   174     public static class MBeanOptions implements Serializable, Cloneable {

   175         private static final long serialVersionUID = -6380842449318177843L;

   176 

   177         static final MBeanOptions MXBEAN = new MBeanOptions();

   178         static {

   179             MXBEAN.setMXBeanMappingFactory(MXBeanMappingFactory.DEFAULT);

   180         }

   181 

   182         private MXBeanMappingFactory mappingFactory;

   183 

   184         /**

   185          * <p>Construct an {@code MBeanOptions} object where all options have

   186          * their default values.</p>

   187          */

   188         public MBeanOptions() {}

   189 

   190         @Override

   191         public MBeanOptions clone() {

   192             try {

   193                 return (MBeanOptions) super.clone();

   194             } catch (CloneNotSupportedException e) {

   195                 throw new AssertionError(e);

   196             }

   197         }

   198 

   199         /**

   200          * <p>True if this is an MXBean proxy or a StandardMBean instance

   201          * that is an MXBean.  The default value is false.</p>

   202          *

   203          * <p>This method is equivalent to {@link #getMXBeanMappingFactory()

   204          * this.getMXBeanMappingFactory()}{@code != null}.</p>

   205          *

   206          * @return true if this is an MXBean proxy or a StandardMBean instance

   207          * that is an MXBean.

   208          */

   209         public boolean isMXBean() {

   210             return (this.mappingFactory != null);

   211         }

   212 

   213         /**

   214          * <p>The mappings between Java types and Open Types to be used in

   215          * an MXBean proxy or a StandardMBean instance that is an MXBean,

   216          * or null if this instance is not for an MXBean.

   217          * The default value is null.</p>

   218          *

   219          * @return the mappings to be used in this proxy or StandardMBean,

   220          * or null if this instance is not for an MXBean.

   221          */

   222         public MXBeanMappingFactory getMXBeanMappingFactory() {

   223             return mappingFactory;

   224         }

   225 

   226         /**

   227          * <p>Set the {@link #getMXBeanMappingFactory() MXBeanMappingFactory} to

   228          * the given value.  The value should be null if this instance is not

   229          * for an MXBean.  If this instance is for an MXBean, the value should

   230          * usually be either a custom mapping factory, or

   231          * {@link MXBeanMappingFactory#forInterface

   232          * MXBeanMappingFactory.forInterface}{@code (mxbeanInterface)}

   233          * which signifies

   234          * that the {@linkplain MXBeanMappingFactory#DEFAULT default} mapping

   235          * factory should be used unless an {@code @}{@link

   236          * javax.management.openmbean.MXBeanMappingFactoryClass

   237          * MXBeanMappingFactoryClass} annotation on {@code mxbeanInterface}

   238          * specifies otherwise.</p>

   239          *

   240          * <p>Examples:</p>

   241          * <pre>

   242          * MBeanOptions opts = new MBeanOptions();

   243          * opts.setMXBeanMappingFactory(myMappingFactory);

   244          * MyMXBean proxy = JMX.newMBeanProxy(

   245          *         mbeanServerConnection, objectName, MyMXBean.class, opts);

   246          *

   247          * // ...or...

   248          *

   249          * MBeanOptions opts = new MBeanOptions();

   250          * MXBeanMappingFactory defaultFactoryForMyMXBean =

   251          *         MXBeanMappingFactory.forInterface(MyMXBean.class);

   252          * opts.setMXBeanMappingFactory(defaultFactoryForMyMXBean);

   253          * MyMXBean proxy = JMX.newMBeanProxy(

   254          *         mbeanServerConnection, objectName, MyMXBean.class, opts);

   255          * </pre>

   256          *

   257          * @param f the new value.  If null, this instance is not for an

   258          * MXBean.

   259          */

   260         public void setMXBeanMappingFactory(MXBeanMappingFactory f) {

   261             this.mappingFactory = f;

   262         }

   263 

   264         /* To maximise object sharing, classes in this package can replace

   265          * a private MBeanOptions with no MXBeanMappingFactory with one

   266          * of these shared instances.  But they must be EXTREMELY careful

   267          * never to give out the shared instances to user code, which could

   268          * modify them.

   269          */

   270         private static final MBeanOptions[] CANONICALS = {

   271             new MBeanOptions(), MXBEAN,

   272         };

   273         // Overridden in local subclasses:

   274         MBeanOptions[] canonicals() {

   275             return CANONICALS;

   276         }

   277 

   278         // This is only used by the logic for canonical instances.

   279         // Overridden in local subclasses:

   280         boolean same(MBeanOptions opt) {

   281             return (opt.mappingFactory == mappingFactory);

   282         }

   283 

   284         final MBeanOptions canonical() {

   285             for (MBeanOptions opt : canonicals()) {

   286                 if (opt.getClass() == this.getClass() && same(opt))

   287                     return opt;

   288             }

   289             return this;

   290         }

   291 

   292         final MBeanOptions uncanonical() {

   293             for (MBeanOptions opt : canonicals()) {

   294                 if (this == opt)

   295                     return clone();

   296             }

   297             return this;

   298         }

   299 

   300         private Map<String, Object> toMap() {

   301             Map<String, Object> map = new TreeMap<String, Object>();

   302             try {

   303                 BeanInfo bi = java.beans.Introspector.getBeanInfo(getClass());

   304                 PropertyDescriptor[] pds = bi.getPropertyDescriptors();

   305                 for (PropertyDescriptor pd : pds) {

   306                     String name = pd.getName();

   307                     if (name.equals("class"))

   308                         continue;

   309                     Method get = pd.getReadMethod();

   310                     if (get != null)

   311                         map.put(name, get.invoke(this));

   312                 }

   313             } catch (Exception e) {

   314                 Throwable t = e;

   315                 if (t instanceof InvocationTargetException)

   316                     t = t.getCause();

   317                 map.put("Exception", t);

   318             }

   319             return map;

   320         }

   321 

   322         @Override

   323         public String toString() {

   324             return getClass().getSimpleName() + toMap();

   325             // For example "MBeanOptions{MXBean=true, <etc>}".

   326         }

   327 

   328         /**

   329          * <p>Indicates whether some other object is "equal to" this one. The

   330          * result is true if and only if the other object is also an instance

   331          * of MBeanOptions or a subclass, and has the same properties with

   332          * the same values.</p>

   333          * @return {@inheritDoc}

   334          */

   335         @Override

   336         public boolean equals(Object obj) {

   337             if (obj == this)

   338                 return true;

   339             if (obj == null || obj.getClass() != this.getClass())

   340                 return false;

   341             return toMap().equals(((MBeanOptions) obj).toMap());

   342         }

   343 

   344         @Override

   345         public int hashCode() {

   346             return toMap().hashCode();

   347         }

   348     }

   349 

   350     /**

   351      * <p>Options to apply to an MBean proxy.</p>

   352      *

   353      * @see #newMBeanProxy

   354      */

   355     public static class ProxyOptions extends MBeanOptions {

   356         private static final long serialVersionUID = 7238804866098386559L;

   357 

   358         private boolean notificationEmitter;

   359 

   360         /**

   361          * <p>Construct a {@code ProxyOptions} object where all options have

   362          * their default values.</p>

   363          */

   364         public ProxyOptions() {}

   365 

   366         @Override

   367         public ProxyOptions clone() {

   368             return (ProxyOptions) super.clone();

   369         }

   370 

   371         /**

   372          * <p>Defines whether the returned proxy should

   373          * implement {@link NotificationEmitter}.  The default value is false.</p>

   374          *

   375          * @return true if this proxy will be a NotificationEmitter.

   376          *

   377          * @see JMX#newMBeanProxy(MBeanServerConnection, ObjectName, Class,

   378          * MBeanOptions)

   379          */

   380         public boolean isNotificationEmitter() {

   381             return this.notificationEmitter;

   382         }

   383 

   384         /**

   385          * <p>Set the {@link #isNotificationEmitter NotificationEmitter} option to

   386          * the given value.</p>

   387          * @param emitter the new value.

   388          */

   389         public void setNotificationEmitter(boolean emitter) {

   390             this.notificationEmitter = emitter;

   391         }

   392 

   393         // Canonical objects for each of (MXBean,!MXBean) x (Emitter,!Emitter)

   394         private static final ProxyOptions[] CANONICALS = {

   395             new ProxyOptions(), new ProxyOptions(),

   396             new ProxyOptions(), new ProxyOptions(),

   397         };

   398         static {

   399             CANONICALS[1].setMXBeanMappingFactory(MXBeanMappingFactory.DEFAULT);

   400             CANONICALS[2].setNotificationEmitter(true);

   401             CANONICALS[3].setMXBeanMappingFactory(MXBeanMappingFactory.DEFAULT);

   402             CANONICALS[3].setNotificationEmitter(true);

   403         }

   404         @Override

   405         MBeanOptions[] canonicals() {

   406             return CANONICALS;

   407         }

   408 

   409         @Override

   410         boolean same(MBeanOptions opt) {

   411             return (super.same(opt) && opt instanceof ProxyOptions &&

   412                     ((ProxyOptions) opt).notificationEmitter == notificationEmitter);

   413         }

   414     }

   504      * <p>This method is equivalent to {@link

   505      * #newMBeanProxy(MBeanServerConnection, ObjectName, Class, JMX.MBeanOptions)

   506      * newMBeanProxy(connection, objectName, interfaceClass, opts)}, where

   507      * {@code opts} is a {@link JMX.ProxyOptions} representing the

   508      * {@code notificationEmitter} parameter.</p>

   509      *

   644      * <p>This method is equivalent to {@link

   645      * #newMBeanProxy(MBeanServerConnection, ObjectName, Class, JMX.MBeanOptions)

   646      * newMBeanProxy(connection, objectName, interfaceClass, opts)}, where

   647      * {@code opts} is a {@link JMX.ProxyOptions} where the {@link

   648      * JMX.ProxyOptions#getMXBeanMappingFactory() MXBeanMappingFactory}

   649      * property is

   650      * {@link MXBeanMappingFactory#forInterface(Class)

   651      * MXBeanMappingFactory.forInterface(interfaceClass)} and the {@link

   652      * JMX.ProxyOptions#isNotificationEmitter() notificationEmitter} property

   653      * is equal to the {@code notificationEmitter} parameter.</p>

   654      *

   763     }

   764 

   765     private static <T> T newMBeanProxy2(MBeanServerConnection connection,

   766                                         ObjectName objectName,

   767                                         Class<T> interfaceClass,

   768                                         MBeanOptions opts)

   769     throws NotCompliantMBeanException {

   770 

   771         if (opts == null)

   772             opts = new MBeanOptions();

   773 

   774         boolean notificationEmitter = opts instanceof ProxyOptions &&

   775                 ((ProxyOptions) opts).isNotificationEmitter();

   776 

   777         MXBeanMappingFactory mappingFactory = opts.getMXBeanMappingFactory();

   778 

   779         if (mappingFactory != null) {

   780             // Check interface for MXBean compliance

   781             Introspector.testComplianceMXBeanInterface(interfaceClass,

   782                     mappingFactory);

   783         }

   784 

   825 

   826     /**

   827      * <p>Test if an MBean can emit notifications.  An MBean can emit

   828      * notifications if either it implements {@link NotificationBroadcaster}

   829      * (perhaps through its child interface {@link NotificationEmitter}), or

   830      * it uses <a href="MBeanRegistration.html#injection">resource

   831      * injection</a> to obtain an instance of {@link SendNotification}

   832      * through which it can send notifications.</p>

   833      *

   834      * @param mbean an MBean object.

   835      * @return true if the given object is a valid MBean that can emit

   836      * notifications; false if the object is a valid MBean but that

   837      * cannot emit notifications.

   838      * @throws NotCompliantMBeanException if the given object is not

   839      * a valid MBean.

   840      */

   841     public static boolean isNotificationSource(Object mbean)

   842             throws NotCompliantMBeanException {

   843         for (int i = 0; i < 2; i++) {

   844             if (mbean instanceof NotificationBroadcaster ||

   845                     MBeanInjector.injectsSendNotification(mbean))

   846                 return true;

   847             if (mbean instanceof DynamicWrapperMBean)

   848                 mbean = ((DynamicWrapperMBean) mbean).getWrappedObject();

   849             else

   850                 break;

   851         }

   852         return false;

   853     }

   854 

   855     /**

   856      * <p>Return the version of the JMX specification that a (possibly remote)

   857      * MBean Server is using.  The JMX specification described in this

   858      * documentation is version 2.0.  The earlier versions that might be

   859      * reported by this method are 1.0, 1.1, 1.2, and 1.4.  (There is no 1.3.)

   860      * All of these versions and all future versions can be compared using

   861      * {@link String#compareTo(String)}.  So, for example, to tell if

   862      * {@code mbsc} is running at least version 2.0 you can write:</p>

   863      *

   864      * <pre>

   865      * String version = JMX.getSpecificationVersion(mbsc, null);

   866      * boolean atLeast2dot0 = (version.compareTo("2.0") >= 0);

   867      * </pre>

   868      *

   869      * <p>A remote MBean Server might be running an earlier version of the

   870      * JMX API, and in that case <a href="package-summary.html#interop">certain

   871      * features</a> might not be available in it.</p>

   872      *

   873      * <p>The version of the MBean Server {@code mbsc} is not necessarily

   874      * the version of all namespaces within that MBean Server, for example

   875      * if some of them use {@link javax.management.namespace.JMXRemoteNamespace

   876      * JMXRemoteNamespace}.  To determine the version of the namespace

   877      * that a particular MBean is in, give its name as the {@code mbeanName}

   878      * parameter.</p>

   879      *

   880      * @param mbsc a connection to an MBean Server.

   881      *

   882      * @param mbeanName the name of an MBean within that MBean Server, or null.

   883      * If non-null, the namespace of this name, as determined by

   884      * {@link JMXNamespaces#getContainingNamespace

   885      * JMXNamespaces.getContainingNamespace}, is the one whose specification

   886      * version will be returned.

   887      *

   888      * @return the JMX specification version reported by that MBean Server.

   889      *

   890      * @throws IllegalArgumentException if {@code mbsc} is null, or if

   891      * {@code mbeanName} includes a wildcard character ({@code *} or {@code ?})

   892      * in its namespace.

   893      *

   894      * @throws IOException if the version cannot be obtained, either because

   895      * there is a communication problem or because the remote MBean Server

   896      * does not have the appropriate {@linkplain

   897      * MBeanServerDelegateMBean#getSpecificationVersion() attribute}.

   898      *

   899      * @see <a href="package-summary.html#interop">Interoperability between

   900      * versions of the JMX specification</a>

   901      * @see MBeanServerDelegateMBean#getSpecificationVersion

   902      */

   903     public static String getSpecificationVersion(

   904             MBeanServerConnection mbsc, ObjectName mbeanName)

   905             throws IOException {

   906         if (mbsc == null)

   907             throw new IllegalArgumentException("Null MBeanServerConnection");

   908 

   909         String namespace;

   910         if (mbeanName == null)

   911             namespace = "";

   912         else

   913             namespace = JMXNamespaces.getContainingNamespace(mbeanName);

   914         if (namespace.contains("*") || namespace.contains("?")) {

   915             throw new IllegalArgumentException(

   916                     "ObjectName contains namespace wildcard: " + mbeanName);

   917         }

   918 

   919         try {

   920             if (namespace.length() > 0)

   921                 mbsc = JMXNamespaces.narrowToNamespace(mbsc, namespace);

   922             return (String) mbsc.getAttribute(

   923                     MBeanServerDelegate.DELEGATE_NAME, "SpecificationVersion");

   924         } catch (IOException e) {

   925             throw e;

   926         } catch (Exception e) {

   927             throw new IOException(e);

   928         }

   929     }