Module org.apache.derby.engine

# 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.

- Interface Summary
  Interface | 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.
  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.

- Class Summary
  Class | Description
  --- | ---
  Management | Management MBean to allow applications to dynamically control visibility of Derby's MBeans.