Package io.hekate.core.jmx

Interface JmxService

  • All Superinterfaces:
    Service
    @DefaultServiceFactory(JmxServiceFactory.class)
public interface JmxService
extends Service
    « start hereJava Management Extensions service.

    Overview

    The JmxService is the utility service that provides an abstraction layer on top of JMX facilities that are provided by the JMV. This service is primarily intended to be used by the Hekate's internal components and services.

    Service Configuration

    JmxService can be registered and configured in HekateBootstrap with the help of JmxServiceFactory as shown in the example below: 

    
// Prepare service factory and configure some options.
JmxServiceFactory factory = new JmxServiceFactory();

// (optional) explicitly specify MBean server.
factory.setServer(ManagementFactory.getPlatformMBeanServer());

// ...other options...

// Start node.
Hekate hekate = new HekateBootstrap()
    .withService(factory)
    .join();
    Note: This example requires Spring Framework integration (see HekateSpringBootstrap). 
    
<beans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:h="http://www.hekate.io/spring/hekate-core"
    xmlns="http://www.springframework.org/schema/beans"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.hekate.io/spring/hekate-core
        http://www.hekate.io/spring/hekate-core.xsd">

    <h:node id="hekate">
        <!-- JMX service. -->
        <h:jmx>
            <!-- ...JMX configuration options... -->
        </h:jmx>

        <!-- ...other services... -->
    </h:node>
</beans>
    Note: This example requires Spring Framework integration (see HekateSpringBootstrap). 
    
<beans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://www.springframework.org/schema/beans"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd">

    <bean id="hekate" class="io.hekate.spring.bean.HekateSpringBootstrap">
        <property name="services">
            <list>
                <!-- JMX service. -->
                <bean class="io.hekate.core.jmx.JmxServiceFactory">
                    <!-- ...JMX configuration options... -->
                </bean>

                <!-- ...other services... -->
            </list>
        </property>
    </bean>
</beans>

    Accessing the Service

    JmxService is an optional service that is available only if application registers an instance of JmxServiceFactory within the HekateBootstrap. Availability of this service can be checked at runtime via the Hekate.has(Class) method. If service is available then it can be accessed via the Hekate.get(Class) method as shown in the example below: 

    
JmxService jmx = hekate.get(JmxService.class);

    Registering MXBeans

    JMX objects can be registered to the JmxService via register(Object) method. Such objects must implement exactly one MXBean-annotated interface (i.e. 'MXBean' suffix in interface name is not supported). Alternatively, instead of implementing such interface directly, objects can implement JmxSupport interface. In such case the object that is returned by the JmxSupport.jmx() method will be registered as an MX bean.

    JMX Object Names

    ObjectNames of all registered beans are constructed as follows:

    [domain]:type=[simple_class_name],name=[name_attribute]

    • Method Detail

      • names

        List<ObjectName> names()
        Returns the list of names of all MBeans that are registered to this service.
        Returns:
        List of all registered MBean names or an empty list if none are registered.

      • nameFor

        ObjectName nameFor​(Class<?> jmxInterface)
        Constructs a new object name for the specified JMX interface.
        Parameters:
        jmxInterface - JMX interface.
        Returns:
        Object name.

      • nameFor

        ObjectName nameFor​(Class<?> jmxInterface,
                   String nameAttribute)
        Constructs a new object name for the specified JMX interface and an additional 'name' attribute.
        Parameters:
        jmxInterface - JMX interface.
        nameAttribute - Optional value for the 'name' attribute of the resulting object name. If omitted then 'name' attribute will not be added to the object name.
        Returns:
        Object name.

      • register

        Optional<ObjectName> register​(Object mxBean)
                       throws JmxServiceException
        Registers the specified object as MXBean.

        The specified object is expected to implement exactly one interface that is marked with @MXBean annotation or implement the JmxSupport interface. If object doesn't implement any of those interfaces then nothing will happen and registration operation will be ignored.

        Parameters:
        mxBean - JMX bean.
        Returns:
        Object name if registration took place.
        Throws:
        JmxServiceException - Signals that JMX registration failed.

      • register

        Optional<ObjectName> register​(Object mxBean,
                              String nameAttribute)
                       throws JmxServiceException
        Registers the specified object as MXBean.

        The specified object is expected to implement exactly one interface that is marked with @MXBean annotation or implement the JmxSupport interface. If object doesn't implement any of those interfaces then nothing will happen and registration operation will be ignored.

        Parameters:
        mxBean - JMX bean.
        nameAttribute - Optional value for the 'name' attribute of the resulting object name. If omitted then 'name' attribute will not be added to the object name.
        Returns:
        Object name if registration took place.
        Throws:
        JmxServiceException - Signals that JMX registration failed.