MBeanRegistrationSupport (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.jmx.support

## Class MBeanRegistrationSupport

- java.lang.Object
- - org.springframework.jmx.support.MBeanRegistrationSupport

- Direct Known Subclasses:
    ConnectorServerFactoryBean, MBeanExporter

      public class MBeanRegistrationSupport
      extends Object

  Provides supporting infrastructure for registering MBeans with an `MBeanServer`. The behavior when encountering an existing MBean at a given `ObjectName` is fully configurable allowing for flexible registration settings.

  All registered MBeans are tracked and can be unregistered by calling the #`unregisterBeans()` method.

  Sub-classes can receive notifications when an MBean is registered or unregistered by overriding the `onRegister(ObjectName)` and `onUnregister(ObjectName)` methods respectively.

  By default, the registration process will fail if attempting to register an MBean using a `ObjectName` that is already used.

  By setting the `registrationPolicy` property to `RegistrationPolicy.IGNORE_EXISTING` the registration process will simply ignore existing MBeans leaving them registered. This is useful in settings where multiple applications want to share a common MBean in a shared `MBeanServer`.

  Setting `registrationPolicy` property to `RegistrationPolicy.REPLACE_EXISTING` will cause existing MBeans to be replaced during registration if necessary. This is useful in situations where you can't guarantee the state of your `MBeanServer`.

  Since:
    2.0
  Author:
    Rob Harrop, Juergen Hoeller, Phillip Webb
  See Also:
    `setServer(javax.management.MBeanServer)`, `setRegistrationPolicy(org.springframework.jmx.support.RegistrationPolicy)`, `MBeanExporter`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Log` | `logger` `Log` instance for this class.
    `static int` | `REGISTRATION_FAIL_ON_EXISTING` Deprecated. since Spring 3.2, in favor of `RegistrationPolicy.FAIL_ON_EXISTING`
    `static int` | `REGISTRATION_IGNORE_EXISTING` Deprecated. since Spring 3.2, in favor of `RegistrationPolicy.IGNORE_EXISTING`
    `static int` | `REGISTRATION_REPLACE_EXISTING` Deprecated. since Spring 3.2, in favor of `RegistrationPolicy.REPLACE_EXISTING`
    `protected MBeanServer` | `server` The `MBeanServer` instance being used to register beans.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MBeanRegistrationSupport()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `doRegister(Object mbean, ObjectName objectName)` Actually register the MBean with the server.
    `protected void` | `doUnregister(ObjectName objectName)` Actually unregister the specified MBean from the server.
    `protected ObjectName[]` | `getRegisteredObjectNames()` Return the `ObjectNames` of all registered beans.
    `MBeanServer` | `getServer()` Return the `MBeanServer` that the beans will be registered with.
    `protected void` | `onRegister(ObjectName objectName)` Called when an MBean is registered under the given `ObjectName`.
    `protected void` | `onRegister(ObjectName objectName, Object mbean)` Called when an MBean is registered under the given `ObjectName`.
    `protected void` | `onUnregister(ObjectName objectName)` Called when an MBean is unregistered under the given `ObjectName`.
    `void` | `setRegistrationBehavior(int registrationBehavior)` Deprecated. since Spring 3.2, in favor of `setRegistrationPolicy(RegistrationPolicy)`
    `void` | `setRegistrationBehaviorName(String registrationBehavior)` Deprecated. since Spring 3.2, in favor of `setRegistrationPolicy(RegistrationPolicy)`
    `void` | `setRegistrationPolicy(RegistrationPolicy registrationPolicy)` The policy to use when attempting to register an MBean under an `ObjectName` that already exists.
    `void` | `setServer(MBeanServer server)` Specify the `MBeanServer` instance with which all beans should be registered.
    `protected void` | `unregisterBeans()` Unregisters all beans that have been registered by an instance of this class.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### REGISTRATION_FAIL_ON_EXISTING

          @Deprecated
          public static final int REGISTRATION_FAIL_ON_EXISTING

      Deprecated. since Spring 3.2, in favor of `RegistrationPolicy.FAIL_ON_EXISTING`
      Constant indicating that registration should fail when attempting to register an MBean under a name that already exists.

      This is the default registration behavior.

      See Also:
        Constant Field Values

    - #### REGISTRATION_IGNORE_EXISTING

          @Deprecated
          public static final int REGISTRATION_IGNORE_EXISTING

      Deprecated. since Spring 3.2, in favor of `RegistrationPolicy.IGNORE_EXISTING`
      Constant indicating that registration should ignore the affected MBean when attempting to register an MBean under a name that already exists.
      See Also:
        Constant Field Values

    - #### REGISTRATION_REPLACE_EXISTING

          @Deprecated
          public static final int REGISTRATION_REPLACE_EXISTING

      Deprecated. since Spring 3.2, in favor of `RegistrationPolicy.REPLACE_EXISTING`
      Constant indicating that registration should replace the affected MBean when attempting to register an MBean under a name that already exists.
      See Also:
        Constant Field Values

    - #### logger

          protected final Log logger

      `Log` instance for this class.

    - #### server

          protected MBeanServer server

      The `MBeanServer` instance being used to register beans.

  - ### Constructor Detail

    - #### MBeanRegistrationSupport

          public MBeanRegistrationSupport()

  - ### Method Detail

    - #### setServer

          public void setServer(MBeanServer server)

      Specify the `MBeanServer` instance with which all beans should be registered. The `MBeanExporter` will attempt to locate an existing `MBeanServer` if none is supplied.

    - #### getServer

          public final MBeanServer getServer()

      Return the `MBeanServer` that the beans will be registered with.

    - #### setRegistrationBehaviorName

          @Deprecated
          public void setRegistrationBehaviorName(String registrationBehavior)

      Deprecated. since Spring 3.2, in favor of `setRegistrationPolicy(RegistrationPolicy)`
      Set the registration behavior by the name of the corresponding constant, e.g. "REGISTRATION_IGNORE_EXISTING".
      See Also:
        `setRegistrationBehavior(int)`, `REGISTRATION_FAIL_ON_EXISTING`, `REGISTRATION_IGNORE_EXISTING`, `REGISTRATION_REPLACE_EXISTING`

    - #### setRegistrationBehavior

          @Deprecated
          public void setRegistrationBehavior(int registrationBehavior)

      Deprecated. since Spring 3.2, in favor of `setRegistrationPolicy(RegistrationPolicy)`
      Specify what action should be taken when attempting to register an MBean under an `ObjectName` that already exists.

      Default is REGISTRATION_FAIL_ON_EXISTING.

      See Also:
        `setRegistrationBehaviorName(String)`, `REGISTRATION_FAIL_ON_EXISTING`, `REGISTRATION_IGNORE_EXISTING`, `REGISTRATION_REPLACE_EXISTING`

    - #### setRegistrationPolicy

          public void setRegistrationPolicy(RegistrationPolicy registrationPolicy)

      The policy to use when attempting to register an MBean under an `ObjectName` that already exists.
      Parameters:
        `registrationPolicy` - the policy to use
      Since:
        3.2

    - #### doRegister

          protected void doRegister(Object mbean,
                        ObjectName objectName)
                             throws JMException

      Actually register the MBean with the server. The behavior when encountering an existing MBean can be configured using the `setRegistrationBehavior(int)` and `setRegistrationBehaviorName(String)` methods.
      Parameters:
        `mbean` - the MBean instance
        `objectName` - the suggested ObjectName for the MBean
      Throws:
        `JMException` - if the registration failed

    - #### unregisterBeans

          protected void unregisterBeans()

      Unregisters all beans that have been registered by an instance of this class.

    - #### doUnregister

          protected void doUnregister(ObjectName objectName)

      Actually unregister the specified MBean from the server.
      Parameters:
        `objectName` - the suggested ObjectName for the MBean

    - #### getRegisteredObjectNames

          protected final ObjectName[] getRegisteredObjectNames()

      Return the `ObjectNames` of all registered beans.

    - #### onRegister

          protected void onRegister(ObjectName objectName,
                        Object mbean)

      Called when an MBean is registered under the given `ObjectName`. Allows subclasses to perform additional processing when an MBean is registered.

      The default implementation delegates to `onRegister(ObjectName)`.

      Parameters:
        `objectName` - the actual `ObjectName` that the MBean was registered with
        `mbean` - the registered MBean instance

    - #### onRegister

          protected void onRegister(ObjectName objectName)

      Called when an MBean is registered under the given `ObjectName`. Allows subclasses to perform additional processing when an MBean is registered.

      The default implementation is empty. Can be overridden in subclasses.

      Parameters:
        `objectName` - the actual `ObjectName` that the MBean was registered with

    - #### onUnregister

          protected void onUnregister(ObjectName objectName)

      Called when an MBean is unregistered under the given `ObjectName`. Allows subclasses to perform additional processing when an MBean is unregistered.

      The default implementation is empty. Can be overridden in subclasses.

      Parameters:
        `objectName` - the `ObjectName` that the MBean was registered with