content/documentation/extensions/mod_management.adoc

:jbake-type: page
:jbake-status: published

= Apache Tamaya - Extension: JMX Management Access

toc::[]


[[ExtModel]]
== Tamaya Management (JMX Support) (Extension Module)
Tamaya _Management_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.

=== What functionality this module provides ?

The Tamaya _Management_ module provides support for registering a JMX management bean for
accessing configuration.

=== Compatibility

The module is based on Java 7, so it will run on Java 7 and beyond.


=== Installation

To use the _management_ extension you only must add the corresponding dependency
to your module:

[source, xml, subs=attributes+]
-----------------------------------------------
<dependency>
  <groupId>org.apache.tamaya.ext</groupId>
  <artifactId>tamaya-management</artifactId>
  <version>{tamaya_version}</version>
</dependency>
-----------------------------------------------


=== The ManagedConfigMBean bean

The management model defines the MBean of type +ManagedConfigMBean+ as follows:


[source,java]
-----------------------------------------------------------------------------
public interface ManagedConfigMBean {
    String getJsonConfigurationInfo();
    String getXmlConfigurationInfo();
    Map<String, String> getConfiguration();
    Map<String, String> getSection(String area, boolean recursive);
    Set<String> getSections();
    Set<String> getTransitiveSections();
    boolean isSectionExisting(String area);
    default boolean isSectionEmpty(String area);
}
-----------------------------------------------------------------------------

* +getJsonConfigurationInfo,getXmlConfigurationInfo+ return a JSON or XML representation of the
current configuration.
* +getConfiguration+ access the current configuration properties.
* +getSection+ allows to extract all entries below a certain subkey. With _recursive_ the query
  will not only return direct children, but also recursively walk down all subsection of the
  given section key.
* +getSections+ returns all current known section names.
* +getTransitiveSections+ return all sections, but also adds all transitive subsection as single
  entries to the set as well.
* +isSectionExisting+ and +isSectionEmpty+ allow for quering if entries are present under the given
  section keys.


=== Registering the ManagedConfigMBean

For registering the current +ManagedConfigMBean+ instance to the current MBean platform server, the
following static methods are available:

[source,java]
-----------------------------------------------------------------------------
public final class ConfigManagementSupport{

    private JMXSupport(){}

    public static ObjectName registerMBean();
    public static ObjectName registerMBean(String context);
    public static ObjectName unregisterMBean();
    public static ObjectName unregisterMBean(String context);
}
-----------------------------------------------------------------------------

* +registerMBean+ creates a new +ManagedConfigMBean+ instance using the +ServiceContextManager+
  and registers it. Optionally an additional _context_ parameter can be passed, which allows
  to register the management bean for different classloaders, e.g. for different
  ears.
* +unregisterMBean+ does the oppsite than registering obviously.

NOTE: The instance of +ManagedConfigMBean+ to be created and registered is evaluated by use og the
      +ServiceContextManager+. So you can replace the bean implementation by registering your
      overriding implementation using the current +ServiceContext+ (by default using
      +java.util.ServiceLoader+ and +@Priority+ annotation.