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

org.springframework.jmx.access

## Class MBeanClientInterceptor

- java.lang.Object
- - org.springframework.jmx.access.MBeanClientInterceptor

- All Implemented Interfaces:
    Advice, Interceptor, MethodInterceptor, Aware, BeanClassLoaderAware, DisposableBean, InitializingBean
  Direct Known Subclasses:
    MBeanProxyFactoryBean

      public class MBeanClientInterceptor
      extends Object
      implements MethodInterceptor, BeanClassLoaderAware, InitializingBean, DisposableBean

  `MethodInterceptor` that routes calls to an MBean running on the supplied `MBeanServerConnection`. Works for both local and remote `MBeanServerConnection`s.

  By default, the `MBeanClientInterceptor` will connect to the `MBeanServer` and cache MBean metadata at startup. This can be undesirable when running against a remote `MBeanServer` that may not be running when the application starts. Through setting the `connectOnStartup` property to "false", you can defer this process until the first invocation against the proxy.

  This functionality is usually used through `MBeanProxyFactoryBean`. See the javadoc of that class for more information.

  Since:
    1.2
  Author:
    Rob Harrop, Juergen Hoeller
  See Also:
    `MBeanProxyFactoryBean`, `setConnectOnStartup(boolean)`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Log` | `logger` Logger available to subclasses

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MBeanClientInterceptor()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterPropertiesSet()` Prepares the `MBeanServerConnection` if the "connectOnStartup" is turned on (which it is by default).
    `protected Object` | `convertResultValueIfNecessary(Object result, MethodParameter parameter)` Convert the given result object (from attribute access or operation invocation) to the specified target class for returning from the proxy method.
    `void` | `destroy()` Invoked by a BeanFactory on destruction of a singleton.
    `protected Object` | `doInvoke(MethodInvocation invocation)` Route the invocation to the configured managed resource.
    `Map<String,?>` | `getEnvironment()` Allow Map access to the environment to be set for the connector, with the option to add or override specific entries.
    `protected Class` | `getManagementInterface()` Return the management interface of the target MBean, or `null` if none specified.
    `protected Object` | `handleConnectFailure(MethodInvocation invocation, Exception ex)` Refresh the connection and retry the MBean invocation if possible.
    `Object` | `invoke(MethodInvocation invocation)` Route the invocation to the configured managed resource..
    `protected boolean` | `isPrepared()` Return whether this client interceptor has already been prepared, i.e.
    `void` | `prepare()` Ensures that an `MBeanServerConnection` is configured and attempts to detect a local connection if one is not supplied.
    `void` | `setAgentId(String agentId)` Set the agent id of the `MBeanServer` to locate.
    `void` | `setBeanClassLoader(ClassLoader beanClassLoader)` Callback that supplies the bean `class loader` to a bean instance.
    `void` | `setConnectOnStartup(boolean connectOnStartup)` Set whether or not the proxy should connect to the `MBeanServer` at creation time ("true") or the first time it is invoked ("false").
    `void` | `setEnvironment(Map<String,?> environment)` Specify the environment for the JMX connector.
    `void` | `setManagementInterface(Class managementInterface)` Set the management interface of the target MBean, exposing bean property setters and getters for MBean attributes and conventional Java methods for MBean operations.
    `void` | `setObjectName(Object objectName)` Set the `ObjectName` of the MBean which calls are routed to, as `ObjectName` instance or as `String`.
    `void` | `setRefreshOnConnectFailure(boolean refreshOnConnectFailure)` Set whether to refresh the MBeanServer connection on connect failure.
    `void` | `setServer(MBeanServerConnection server)` Set the `MBeanServerConnection` used to connect to the MBean which all invocations are routed to.
    `void` | `setServiceUrl(String url)` Set the service URL of the remote `MBeanServer`.
    `void` | `setUseStrictCasing(boolean useStrictCasing)` Set whether to use strict casing for attributes.

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

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

- - ### Field Detail

    - #### logger

          protected final Log logger

      Logger available to subclasses

  - ### Constructor Detail

    - #### MBeanClientInterceptor

          public MBeanClientInterceptor()

  - ### Method Detail

    - #### setServer

          public void setServer(MBeanServerConnection server)

      Set the `MBeanServerConnection` used to connect to the MBean which all invocations are routed to.

    - #### setServiceUrl

          public void setServiceUrl(String url)
                             throws MalformedURLException

      Set the service URL of the remote `MBeanServer`.
      Throws:
        `MalformedURLException`

    - #### setEnvironment

          public void setEnvironment(Map<String,?> environment)

      Specify the environment for the JMX connector.
      See Also:
        `JMXConnectorFactory.connect(javax.management.remote.JMXServiceURL, java.util.Map)`

    - #### getEnvironment

          public Map<String,?> getEnvironment()

      Allow Map access to the environment to be set for the connector, with the option to add or override specific entries.

      Useful for specifying entries directly, for example via "environment[myKey]". This is particularly useful for adding or overriding entries in child bean definitions.

    - #### setAgentId

          public void setAgentId(String agentId)

      Set the agent id of the `MBeanServer` to locate.

      Default is none. If specified, this will result in an attempt being made to locate the attendant MBeanServer, unless the `"serviceUrl"` property has been set.

      See Also:
        `

        Specifying the empty String indicates the platform MBeanServer.

        `

    - #### setConnectOnStartup

          public void setConnectOnStartup(boolean connectOnStartup)

      Set whether or not the proxy should connect to the `MBeanServer` at creation time ("true") or the first time it is invoked ("false"). Default is "true".

    - #### setRefreshOnConnectFailure

          public void setRefreshOnConnectFailure(boolean refreshOnConnectFailure)

      Set whether to refresh the MBeanServer connection on connect failure. Default is "false".

      Can be turned on to allow for hot restart of the JMX server, automatically reconnecting and retrying in case of an IOException.

    - #### setObjectName

          public void setObjectName(Object objectName)
                             throws MalformedObjectNameException

      Set the `ObjectName` of the MBean which calls are routed to, as `ObjectName` instance or as `String`.
      Throws:
        `MalformedObjectNameException`

    - #### setUseStrictCasing

          public void setUseStrictCasing(boolean useStrictCasing)

      Set whether to use strict casing for attributes. Enabled by default.

      When using strict casing, a JavaBean property with a getter such as `getFoo()` translates to an attribute called `Foo`. With strict casing disabled, `getFoo()` would translate to just `foo`.

    - #### setManagementInterface

          public void setManagementInterface(Class managementInterface)

      Set the management interface of the target MBean, exposing bean property setters and getters for MBean attributes and conventional Java methods for MBean operations.

    - #### getManagementInterface

          protected final Class getManagementInterface()

      Return the management interface of the target MBean, or `null` if none specified.

    - #### setBeanClassLoader

          public void setBeanClassLoader(ClassLoader beanClassLoader)

      Description copied from interface: `BeanClassLoaderAware`
      Callback that supplies the bean `class loader` to a bean instance.

      Invoked after the population of normal bean properties but before an initialization callback such as `InitializingBean's` `InitializingBean.afterPropertiesSet()` method or a custom init-method.

      Specified by:
        `setBeanClassLoader` in interface `BeanClassLoaderAware`
      Parameters:
        `beanClassLoader` - the owning class loader; may be `null` in which case a default `ClassLoader` must be used, for example the `ClassLoader` obtained via `ClassUtils.getDefaultClassLoader()`

    - #### afterPropertiesSet

          public void afterPropertiesSet()

      Prepares the `MBeanServerConnection` if the "connectOnStartup" is turned on (which it is by default).
      Specified by:
        `afterPropertiesSet` in interface `InitializingBean`

    - #### prepare

          public void prepare()

      Ensures that an `MBeanServerConnection` is configured and attempts to detect a local connection if one is not supplied.

    - #### isPrepared

          protected boolean isPrepared()

      Return whether this client interceptor has already been prepared, i.e. has already looked up the server and cached all metadata.

    - #### invoke

          public Object invoke(MethodInvocation invocation)
                        throws Throwable

      Route the invocation to the configured managed resource..
      Specified by:
        `invoke` in interface `MethodInterceptor`
      Parameters:
        `invocation` - the `MethodInvocation` to re-route
      Returns:
        the value returned as a result of the re-routed invocation
      Throws:
        `Throwable` - an invocation error propagated to the user
      See Also:
        `doInvoke(org.aopalliance.intercept.MethodInvocation)`, `handleConnectFailure(org.aopalliance.intercept.MethodInvocation, java.lang.Exception)`

    - #### handleConnectFailure

          protected Object handleConnectFailure(MethodInvocation invocation,
                                    Exception ex)
                                         throws Throwable

      Refresh the connection and retry the MBean invocation if possible.

      If not configured to refresh on connect failure, this method simply rethrows the original exception.

      Parameters:
        `invocation` - the invocation that failed
        `ex` - the exception raised on remote invocation
      Returns:
        the result value of the new invocation, if succeeded
      Throws:
        `Throwable` - an exception raised by the new invocation, if it failed as well
      See Also:
        `setRefreshOnConnectFailure(boolean)`, `doInvoke(org.aopalliance.intercept.MethodInvocation)`

    - #### doInvoke

          protected Object doInvoke(MethodInvocation invocation)
                             throws Throwable

      Route the invocation to the configured managed resource. Correctly routes JavaBean property access to `MBeanServerConnection.get/setAttribute` and method invocation to `MBeanServerConnection.invoke`.
      Parameters:
        `invocation` - the `MethodInvocation` to re-route
      Returns:
        the value returned as a result of the re-routed invocation
      Throws:
        `Throwable` - an invocation error propagated to the user

    - #### convertResultValueIfNecessary

          protected Object convertResultValueIfNecessary(Object result,
                                             MethodParameter parameter)

      Convert the given result object (from attribute access or operation invocation) to the specified target class for returning from the proxy method.
      Parameters:
        `result` - the result object as returned by the `MBeanServer`
        `parameter` - the method parameter of the proxy method that's been invoked
      Returns:
        the converted result object, or the passed-in object if no conversion is necessary

    - #### destroy

          public void destroy()

      Description copied from interface: `DisposableBean`
      Invoked by a BeanFactory on destruction of a singleton.
      Specified by:
        `destroy` in interface `DisposableBean`