35  *

    36  * <h4 id="injection">Resource injection</h4>

    37  *

    38  * <p>As an alternative to implementing {@code MBeanRegistration}, if all that

    39  * is needed is the MBean Server or ObjectName then an MBean can use

    40  * <em>resource injection</em>.</p>

    41  *

    42  * <p>If a field in the MBean object has type {@link ObjectName} and has

    43  * the {@link javax.annotation.Resource @Resource} annotation,

    44  * then the {@code ObjectName} under which the MBean is registered is

    45  * assigned to that field during registration.  Likewise, if a field has type

    46  * {@link MBeanServer} and the <code>&#64;Resource</code> annotation, then it will

    47  * be set to the {@code MBeanServer} in which the MBean is registered.</p>

    48  *

    49  * <p>For example:</p>

    50  *

    51  * <pre>

    52  * public Configuration implements ConfigurationMBean {

    53  *     @Resource

    54  *     private volatile MBeanServer mbeanServer;

    55  *     @Resource

    56  *     private volatile ObjectName objectName;

    57  *     ...

    58  *     void unregisterSelf() throws Exception {

    59  *         mbeanServer.unregisterMBean(objectName);

    60  *     }

    61  * }

    62  * </pre>

    63  *

    64  * <p>Resource injection can also be used on fields of type

    65  * {@link SendNotification} to simplify notification sending.  Such a field

    66  * will get a reference to an object of type {@code SendNotification} when

    67  * the MBean is registered, and it can use this reference to send notifications.

    68  * For example:</p>

    69  *

    70  * <pre>

    71  * public Configuration implements ConfigurationMBean {

    72  *     @Resource

    73  *     private volatile SendNotification sender;

    74  *     ...

    75  *     private void updated() {

    76  *         Notification n = new Notification(...);

    77  *         sender.sendNotification(n);

    78  *     }

    79  * }

    80  * </pre>

    81  *

    82  * <p>(Listeners may be invoked in the same thread as the caller of

    83  * {@code sender.sendNotification}.)</p>

    84  *

    85  * <p>A field to be injected must not be static.  It is recommended that

    86  * such fields be declared {@code volatile}.</p>

    87  *

    88  * <p>It is also possible to use the <code>&#64;Resource</code> annotation on

    89  * methods. Such a method must have a {@code void} return type and a single

    90  * argument of the appropriate type, for example {@code ObjectName}.</p>

    91  *

    92  * <p>Any number of fields and methods may have the <code>&#64;Resource</code>

    93  * annotation.  All fields and methods with type {@code ObjectName}

    94  * (for example) will receive the same {@code ObjectName} value.</p>

    95  *

    96  * <p>Resource injection is available for all types of MBeans, not just

    97  * Standard MBeans.</p>

    98  *

    99  * <p>If an MBean implements the {@link DynamicWrapperMBean} interface then

   100  * resource injection happens on the object returned by that interface's

   101  * {@link DynamicWrapperMBean#getWrappedObject() getWrappedObject()} method

   102  * rather than on the MBean object itself.

   103  *

   104  * <p>Resource injection happens after the {@link #preRegister preRegister}

   105  * method is called (if any), and before the MBean is actually registered

   106  * in the MBean Server. If a <code>&#64;Resource</code> method throws

   107  * an exception, the effect is the same as if {@code preRegister} had

   108  * thrown the exception. In particular it will prevent the MBean from being

   109  * registered.</p>

   110  *

   111  * <p>Resource injection can be used on a field or method where the type

   112  * is a parent of the injected type, if the injected type is explicitly

   113  * specified in the <code>&#64;Resource</code> annotation.  For example:</p>

   114  *

   115  * <pre>

   116  *     @Resource(type = MBeanServer.class)

   117  *     private volatile MBeanServerConnection mbsc;

   118  * </pre>

   119  *

   120  * <p>Formally, suppose <em>R</em> is the type in the <code>&#64;Resource</code>

   121  * annotation and <em>T</em> is the type of the method parameter or field.

   122  * Then one of <em>R</em> and <em>T</em> must be a subtype of the other

   123  * (or they must be the same type).  Injection happens if this subtype

   124  * is {@code MBeanServer}, {@code ObjectName}, or {@code SendNotification}.

   125  * Otherwise the <code>&#64;Resource</code> annotation is ignored.</p>

   126  *

   127  * <p>Resource injection in MBeans is new in version 2.0 of the JMX API.</p>