Module org.apache.derby.engine

# Package org.apache.derby.mbeans

package org.apache.derby.mbeans

## JMX MBeans.

When Derby (the embedded engine) is booted it will attempt to connect to the PlatformMBeanServer and register a number of MBeans to monitor and manage Derby.

Derby registers its JMX MBeans in the `org.apache.derby` domain and always includes values for `type` and `system` in the MBean's ObjectName's key properties. Other key properties are described in the interface class for the MBean.

- `type` Set to the class name of the MBean's interface class without the package and without `MBean`. E.g. for `org.apache.derby.mbeans.VersionMBean` the key property `type` will be set to `Version`. The javadoc for each MBean also indicates what `type` will be set to.
- `system` Set to a runtime identifier that allows Derby and applications to disambiguate multiple Derby systems in the same virtual machine but different class loaders. Currently a new value is created each time Derby is booted. An application may discover the value of the identifier by registering the MBean `org.apache.derby.mbeans.Management` and accessing the `SystemIdentifier`. This application created `ManagementMBean` must be running in the same class loader as Derby.

Derby registers the class name for any MBean to be the interface class for the MBean (i.e. `org.apache.derby.mbeans.*MBean`) to hide the implementation class (which is subject to change). Permissions in policy files therefore need to use the MBean interface to define fine grained access. E.g. the permission to allow a invoking the `startManagement` of the `ManagementMBean` may be written as:

    permission javax.management.MBeanPermission
        "org.apache.derby.mbeans.ManagementMBean#startManagement[org.apache.derby:*]",
        "invoke";

If Derby cannot connect to the PlatformMBeanServer then no MBeans will be registered. Applications may use the `org.apache.derby.mbeans.Management` MBean to later enable Derby's JMX management.

If Derby cannot register a specific MBean (e.g. due to no permission to register that MBean) then it will simply be ignored. Subsequent re-starts of Derby's management service through `org.apache.derby.mbeans.ManagementMBean` will attempt to register such an MBean again (assuming it is still valid), in case the security policy has been updated.

- Related Packages
  Module
  Package
  Description
  org.apache.derby.server
  org.apache.derby.mbeans.drda
  This package contains JMX MBeans that are intended to provide monitoring and management capabilities of the Derby Network Server.
- Class
  Description
  CacheManagerMBean
  This is an MBean that provides information about one of Derby's cache managers.
  JDBCMBean
  Management and information for the embedded JDBC driver.
  Management
  Management MBean to allow applications to dynamically control visibility of Derby's MBeans.
  ManagementMBean
  JMX MBean inteface to control visibility of Derby's MBeans.
  VersionMBean
  This interface defines a Standard MBean for exposing the version information of a running Derby component.