List<BufferPoolMXBean> pools = ManagementFactory.getPlatformMXBeans(BufferPoolMXBean.class);

java.nio:type=BufferPool,name=pool name

The management interface for a buffer pool, for example a pool of
direct or mapped buffers.

 A class implementing this interface is an
MXBean. A Java
virtual machine has one or more implementations of this interface. The getPlatformMXBeans
method can be used to obtain the list of BufferPoolMXBean objects
representing the management interfaces for pools of buffers as follows:


    List<BufferPoolMXBean> pools = ManagementFactory.getPlatformMXBeans(BufferPoolMXBean.class);

 The management interfaces are also registered with the platform MBeanServer. The ObjectName that uniquely identifies the
management interface within the MBeanServer takes the form:


    java.nio:type=BufferPool,name=pool name
where pool name is the name of the buffer pool.

The management interface for the class loading system of
the Java virtual machine.

 A Java virtual machine has a single instance of the implementation
class of this interface.  This instance implementing this interface is
an MXBean
that can be obtained by calling
the ManagementFactory.getClassLoadingMXBean() method or
from the platform MBeanServer.

The ObjectName for uniquely identifying the MXBean for
the class loading system within an MBeanServer is:

java.lang:type=ClassLoading


It can be obtained by calling the
PlatformManagedObject.getObjectName() method.

The management interface for the compilation system of
the Java virtual machine.

 A Java virtual machine has a single instance of the implementation
class of this interface.  This instance implementing this interface is
an MXBean
that can be obtained by calling
the ManagementFactory.getCompilationMXBean() method or
from the platform MBeanServer method.

The ObjectName for uniquely identifying the MXBean for
the compilation system within an MBeanServer is:

 java.lang:type=Compilation


It can be obtained by calling the
PlatformManagedObject.getObjectName() method.

The management interface for the garbage collection of
the Java virtual machine.  Garbage collection is the process
that the Java virtual machine uses to find and reclaim unreachable
objects to free up memory space.  A garbage collector is one type of
memory manager.

 A Java virtual machine may have one or more instances of
the implementation class of this interface.
An instance implementing this interface is
an MXBean
that can be obtained by calling
the ManagementFactory.getGarbageCollectorMXBeans() method or
from the platform MBeanServer method.

The ObjectName for uniquely identifying the MXBean for
a garbage collector within an MBeanServer is:

  java.lang:type=GarbageCollector,name=collector's name


It can be obtained by calling the
PlatformManagedObject.getObjectName() method.

A platform usually includes additional platform-dependent information
specific to a garbage collection algorithm for monitoring.

Information about a lock.  A lock can be a built-in object monitor,
an ownable synchronizer, or the Condition
object associated with synchronizers.

An ownable synchronizer is
a synchronizer that may be exclusively owned by a thread and uses
AbstractOwnableSynchronizer
(or its subclass) to implement its synchronization property.
ReentrantLock and
ReentrantReadWriteLock are
two examples of ownable synchronizers provided by the platform.

MXBean Mapping
LockInfo is mapped to a CompositeData
as specified in the from method.

The ManagementFactory class is a factory class for getting
managed beans for the Java platform.
This class consists of static methods each of which returns
one or more platform MXBeans representing
the management interface of a component of the Java virtual
machine.

Platform MXBeans

A platform MXBean is a managed bean that
conforms to the JMX
Instrumentation Specification and only uses a set of basic data types.
A JMX management application and the platform MBeanServer
can interoperate without requiring classes for MXBean specific
data types.
The data types being transmitted between the JMX connector
server and the connector client are
javax.management.openmbean.open types
and this allows interoperation across versions.
See
the specification of MXBeans for details.


Each platform MXBean is a PlatformManagedObject
and it has a unique
ObjectName for
registration in the platform MBeanServer as returned by
by the getObjectName
method.


An application can access a platform MXBean in the following ways:
1. Direct access to an MXBean interface


    Get an MXBean instance by calling the
        getPlatformMXBean or
        getPlatformMXBeans method
        and access the MXBean locally in the running
        virtual machine.

    Construct an MXBean proxy instance that forwards the
        method calls to a given MBeanServer by calling
        the getPlatformMXBean(MBeanServerConnection, Class) or
        getPlatformMXBeans(MBeanServerConnection, Class) method.
        The newPlatformMXBeanProxy method
        can also be used to construct an MXBean proxy instance of
        a given ObjectName.
        A proxy is typically constructed to remotely access
        an MXBean of another running virtual machine.


2. Indirect access to an MXBean interface via MBeanServer

    Go through the platform MBeanServer to access MXBeans
        locally or a specific MBeanServerConnection to access
        MXBeans remotely.
        The attributes and operations of an MXBean use only
        JMX open types which include basic data types,
        CompositeData,
        and TabularData
        defined in
        OpenType.
        The mapping is specified in
        the javax.management.MXBean specification
        for details.





The getPlatformManagementInterfaces
method returns all management interfaces supported in the Java virtual machine
including the standard management interfaces listed in the tables
below as well as the management interfaces extended by the JDK implementation.

A Java virtual machine has a single instance of the following management
interfaces:




Management Interface
ObjectName


 ClassLoadingMXBean
 java.lang:type=ClassLoading


 MemoryMXBean
 java.lang:type=Memory


 ThreadMXBean
 java.lang:type=Threading


 RuntimeMXBean
 java.lang:type=Runtime


 OperatingSystemMXBean
 java.lang:type=OperatingSystem


 PlatformLoggingMXBean
 java.util.logging:type=Logging





A Java virtual machine has zero or a single instance of
the following management interfaces.




Management Interface
ObjectName


 CompilationMXBean
 java.lang:type=Compilation





A Java virtual machine may have one or more instances of the following
management interfaces.



Management Interface
ObjectName


 GarbageCollectorMXBean
 java.lang:type=GarbageCollector,name=collector's name


 MemoryManagerMXBean
 java.lang:type=MemoryManager,name=manager's name


 MemoryPoolMXBean
 java.lang:type=MemoryPool,name=pool's name


 BufferPoolMXBean
 java.nio:type=BufferPool,name=pool name

The permission which the SecurityManager will check when code
that is running with a SecurityManager calls methods defined
in the management interface for the Java platform.

The following table
provides a summary description of what the permission allows,
and discusses the risks of granting code the permission.



Permission Target Name
What the Permission Allows
Risks of Allowing this Permission



  control
  Ability to control the runtime characteristics of the Java virtual
      machine, for example, enabling and disabling the verbose output for
      the class loading or memory system, setting the threshold of a memory
      pool, and enabling and disabling the thread contention monitoring
      support. Some actions controlled by this permission can disclose
      information about the running application, like the -verbose:class
      flag.

  This allows an attacker to control the runtime characteristics
      of the Java virtual machine and cause the system to misbehave. An
      attacker can also access some information related to the running
      application.



  monitor
  Ability to retrieve runtime information about
      the Java virtual machine such as thread
      stack trace, a list of all loaded class names, and input arguments
      to the Java virtual machine.
  This allows malicious code to monitor runtime information and
      uncover vulnerabilities.





Programmers do not normally create ManagementPermission objects directly.
Instead they are created by the security policy code based on reading
the security policy file.

The management interface for a memory manager.
A memory manager manages one or more memory pools of the
Java virtual machine.

 A Java virtual machine has one or more memory managers.
An instance implementing this interface is
an MXBean
that can be obtained by calling
the ManagementFactory.getMemoryManagerMXBeans() method or
from the platform MBeanServer method.

The ObjectName for uniquely identifying the MXBean for
a memory manager within an MBeanServer is:

  java.lang:type=MemoryManager,name=manager's name


It can be obtained by calling the
PlatformManagedObject.getObjectName() method.

  collection usage threshold after the Java virtual machine
  has expended effort in recycling unused objects in that
  memory pool.

The management interface for the memory system of
the Java virtual machine.

 A Java virtual machine has a single instance of the implementation
class of this interface.  This instance implementing this interface is
an MXBean
that can be obtained by calling
the ManagementFactory.getMemoryMXBean() method or
from the platform MBeanServer method.

The ObjectName for uniquely identifying the MXBean for
the memory system within an MBeanServer is:

   java.lang:type=Memory


It can be obtained by calling the
PlatformManagedObject.getObjectName() method.

 Memory
The memory system of the Java virtual machine manages
the following kinds of memory:

 1. Heap
The Java virtual machine has a heap that is the runtime
data area from which memory for all class instances and arrays
are allocated.  It is created at the Java virtual machine start-up.
Heap memory for objects is reclaimed by an automatic memory management
system which is known as a garbage collector.

The heap may be of a fixed size or may be expanded and shrunk.
The memory for the heap does not need to be contiguous.

 2. Non-Heap Memory
The Java virtual machine manages memory other than the heap
(referred as non-heap memory).

 The Java virtual machine has a method area that is shared
among all threads.
The method area belongs to non-heap memory.  It stores per-class structures
such as a runtime constant pool, field and method data, and the code for
methods and constructors.  It is created at the Java virtual machine
start-up.

 The method area is logically part of the heap but a Java virtual
machine implementation may choose not to either garbage collect
or compact it.  Similar to the heap, the method area may be of a
fixed size or may be expanded and shrunk.  The memory for the
method area does not need to be contiguous.

In addition to the method area, a Java virtual machine
implementation may require memory for internal processing or
optimization which also belongs to non-heap memory.
For example, the JIT compiler requires memory for storing the native
machine code translated from the Java virtual machine code for
high performance.

Memory Pools and Memory Managers
Memory pools and
memory managers are the abstract entities
that monitor and manage the memory system
of the Java virtual machine.

A memory pool represents a memory area that the Java virtual machine
manages.  The Java virtual machine has at least one memory pool
and it may create or remove memory pools during execution.
A memory pool can belong to either the heap or the non-heap memory.

A memory manager is responsible for managing one or more memory pools.
The garbage collector is one type of memory manager responsible
for reclaiming memory occupied by unreachable objects.  A Java virtual
machine may have one or more memory managers.   It may
add or remove memory managers during execution.
A memory pool can be managed by more than one memory manager.

Memory Usage Monitoring

Memory usage is a very important monitoring attribute for the memory system.
The memory usage, for example, could indicate:

  the memory usage of an application,
  the workload being imposed on the automatic memory management system,
  potential memory leakage.



The memory usage can be monitored in three ways:

  Polling
  Usage Threshold Notification
  Collection Usage Threshold Notification


Details are specified in the MemoryPoolMXBean interface.

The memory usage monitoring mechanism is intended for load-balancing
or workload distribution use.  For example, an application would stop
receiving any new workload when its memory usage exceeds a
certain threshold. It is not intended for an application to detect
and recover from a low memory condition.

Notifications

This MemoryMXBean is a
NotificationEmitter
that emits two types of memory notifications if any one of the memory pools
supports a usage threshold
or a collection usage
threshold which can be determined by calling the
MemoryPoolMXBean.isUsageThresholdSupported() and
MemoryPoolMXBean.isCollectionUsageThresholdSupported() methods.

  usage threshold exceeded notification - for notifying that
      the memory usage of a memory pool is increased and has reached
      or exceeded its
       usage threshold value.

  collection usage threshold exceeded notification - for notifying that
      the memory usage of a memory pool is greater than or equal to its

      collection usage threshold after the Java virtual machine
      has expended effort in recycling unused objects in that
      memory pool.



The notification emitted is a Notification
instance whose user data is set to a CompositeData
that represents a MemoryNotificationInfo object
containing information about the memory pool when the notification
was constructed. The CompositeData contains the attributes
as described in MemoryNotificationInfo.


NotificationEmitter
The MemoryMXBean object returned by
ManagementFactory.getMemoryMXBean() implements
the NotificationEmitter
interface that allows a listener to be registered within the
MemoryMXBean as a notification listener.

Below is an example code that registers a MyListener to handle
notification emitted by the MemoryMXBean.



class MyListener implements javax.management.NotificationListener {
    public void handleNotification(Notification notif, Object handback) {
        // handle notification
        ....
    }
}

MemoryMXBean mbean = ManagementFactory.getMemoryMXBean();
NotificationEmitter emitter = (NotificationEmitter) mbean;
MyListener listener = new MyListener();
emitter.addNotificationListener(listener, null, null);

 Notification notif;

 // receive the notification emitted by MemoryMXBean and set to notif
 ...

 String notifType = notif.getType();
 if (notifType.equals(MemoryNotificationInfo.MEMORY_THRESHOLD_EXCEEDED) ||
     notifType.equals(MemoryNotificationInfo.MEMORY_COLLECTION_THRESHOLD_EXCEEDED)) {
     // retrieve the memory notification information
     CompositeData cd = (CompositeData) notif.getUserData();
     MemoryNotificationInfo info = MemoryNotificationInfo.from(cd);
     ....
 }

  collection usage threshold after the Java virtual machine
  has expended effort in recycling unused objects in that
  memory pool.

The information about a memory notification.


A memory notification is emitted by MemoryMXBean
when the Java virtual machine detects that the memory usage
of a memory pool is exceeding a threshold value.
The notification emitted will contain the memory notification
information about the detected condition:

  The name of the memory pool.
  The memory usage of the memory pool when the notification
      was constructed.
  The number of times that the memory usage has crossed
      a threshold when the notification was constructed.
      For usage threshold notifications, this count will be the
      usage threshold
      count.  For collection threshold notifications,
      this count will be the
      collection usage threshold count.




A CompositeData representing
the MemoryNotificationInfo object
is stored in the
user data
of a notification.
The from method is provided to convert from
a CompositeData to a MemoryNotificationInfo
object. For example:



     Notification notif;

     // receive the notification emitted by MemoryMXBean and set to notif
     ...

     String notifType = notif.getType();
     if (notifType.equals(MemoryNotificationInfo.MEMORY_THRESHOLD_EXCEEDED) ||
         notifType.equals(MemoryNotificationInfo.MEMORY_COLLECTION_THRESHOLD_EXCEEDED)) {
         // retrieve the memory notification information
         CompositeData cd = (CompositeData) notif.getUserData();
         MemoryNotificationInfo info = MemoryNotificationInfo.from(cd);
         ....
     }


The types of notifications emitted by MemoryMXBean are:

  A usage threshold exceeded notification.
      This notification will be emitted when
      the memory usage of a memory pool is increased and has reached
      or exceeded its
       usage threshold value.
      Subsequent crossing of the usage threshold value does not cause
      further notification until the memory usage has returned
      to become less than the usage threshold value.

  A collection usage threshold exceeded notification.
      This notification will be emitted when
      the memory usage of a memory pool is greater than or equal to its

      collection usage threshold after the Java virtual machine
      has expended effort in recycling unused objects in that
      memory pool.

  An application can continuously monitor its memory usage
  by calling either the getUsage() method for all
  memory pools or the isUsageThresholdExceeded() method
  for those memory pools that support a usage threshold.
  Below is example code that has a thread dedicated for
  task distribution and processing.  At every interval,
  it will determine if it should receive and process new tasks based
  on its memory usage.  If the memory usage exceeds its usage threshold,
  it will redistribute all outstanding tasks to other VMs and
  stop receiving new tasks until the memory usage returns
  below its usage threshold.



  // Assume the usage threshold is supported for this pool.
  // Set the threshold to myThreshold above which no new tasks
  // should be taken.
  pool.setUsageThreshold(myThreshold);
  ....

  boolean lowMemory = false;
  while (true) {
     if (pool.isUsageThresholdExceeded()) {
         // potential low memory, so redistribute tasks to other VMs
         lowMemory = true;
         redistributeTasks();
         // stop receiving new tasks
         stopReceivingTasks();
     } else {
         if (lowMemory) {
             // resume receiving tasks
             lowMemory = false;
             resumeReceivingTasks();
         }
         // processing outstanding task
         ...
     }
     // sleep for sometime
     try {
         Thread.sleep(sometime);
     } catch (InterruptedException e) {
         ...
     }
  }


  The above example does not differentiate the case where
  the memory usage has temporarily dropped below the usage threshold
  from the case where the memory usage remains above the threshold
  between two iterations.  The usage threshold count returned by
  the getUsageThresholdCount() method
  can be used to determine
  if the memory usage has returned below the threshold
  between two polls.

  Below shows another example that takes some action if a
  memory pool is under low memory and ignores the memory usage
  changes during the action processing time.



  // Assume the usage threshold is supported for this pool.
  // Set the threshold to myThreshold which determines if
  // the application will take some action under low memory condition.
  pool.setUsageThreshold(myThreshold);

  int prevCrossingCount = 0;
  while (true) {
      // A busy loop to detect when the memory usage
      // has exceeded the threshold.
      while (!pool.isUsageThresholdExceeded() ||
             pool.getUsageThresholdCount() == prevCrossingCount) {
          try {
              Thread.sleep(sometime)
          } catch (InterruptException e) {
              ....
          }
      }

      // Do some processing such as check for memory usage
      // and issue a warning
      ....

      // Gets the current threshold count. The busy loop will then
      // ignore any crossing of threshold happens during the processing.
      prevCrossingCount = pool.getUsageThresholdCount();
  }

  Usage threshold notification will be emitted by MemoryMXBean.
  When the Java virtual machine detects that the memory usage of
  a memory pool has reached or exceeded the usage threshold
  the virtual machine will trigger the MemoryMXBean to emit an
  usage threshold exceeded notification.
  Another usage threshold exceeded notification will not be
  generated until the usage has fallen below the threshold and
  then exceeded it again.

  Below is an example code implementing the same logic as the
  first example above but using the usage threshold notification
  mechanism to detect low memory conditions instead of polling.
  In this example code, upon receiving notification, the notification
  listener notifies another thread to perform the actual action
  such as to redistribute outstanding tasks, stop receiving tasks,
  or resume receiving tasks.
  The handleNotification method should be designed to
  do a very minimal amount of work and return without delay to avoid
  causing delay in delivering subsequent notifications.  Time-consuming
  actions should be performed by a separate thread.
  The notification listener may be invoked by multiple threads
  concurrently; so the tasks performed by the listener
  should be properly synchronized.



  class MyListener implements javax.management.NotificationListener {
       public void handleNotification(Notification notification, Object handback)  {
           String notifType = notification.getType();
           if (notifType.equals(MemoryNotificationInfo.MEMORY_THRESHOLD_EXCEEDED)) {
               // potential low memory, notify another thread
               // to redistribute outstanding tasks to other VMs
               // and stop receiving new tasks.
               lowMemory = true;
               notifyAnotherThread(lowMemory);
           }
       }
  }

  // Register MyListener with MemoryMXBean
  MemoryMXBean mbean = ManagementFactory.getMemoryMXBean();
  NotificationEmitter emitter = (NotificationEmitter) mbean;
  MyListener listener = new MyListener();
  emitter.addNotificationListener(listener, null, null);

  // Assume this pool supports a usage threshold.
  // Set the threshold to myThreshold above which no new tasks
  // should be taken.
  pool.setUsageThreshold(myThreshold);

  // Usage threshold detection is enabled and notification will be
  // handled by MyListener.  Continue for other processing.
  ....


  There is no guarantee about when the MemoryMXBean will emit
  a threshold notification and when the notification will be delivered.
  When a notification listener is invoked, the memory usage of
  the memory pool may have crossed the usage threshold more
  than once.
  The MemoryNotificationInfo.getCount() method returns the number
  of times that the memory usage has crossed the usage threshold
  at the point in time when the notification was constructed.
  It can be compared with the current usage threshold count returned
  by the getUsageThresholdCount() method to determine if
  such situation has occurred.

The management interface for a memory pool.  A memory pool
represents the memory resource managed by the Java virtual machine
and is managed by one or more memory managers.

 A Java virtual machine has one or more instances of the
implementation class of this interface.  An instance
implementing this interface is
an MXBean
that can be obtained by calling
the ManagementFactory.getMemoryPoolMXBeans() method or
from the platform MBeanServer method.

The ObjectName for uniquely identifying the MXBean for
a memory pool within an MBeanServer is:

   java.lang:type=MemoryPool,name=pool's name


It can be obtained by calling the
PlatformManagedObject.getObjectName() method.

Memory Type
The Java virtual machine has a heap for object allocation and also
maintains non-heap memory for the method area and the Java virtual
machine execution.  The Java virtual machine can have one or more
memory pools.  Each memory pool represents a memory area
of one of the following types:

  heap
  non-heap


Memory Usage Monitoring

A memory pool has the following attributes:

  Memory usage
  Peak memory usage
  Usage Threshold
  Collection Usage Threshold
      (only supported by some garbage-collected memory pools)


1. Memory Usage

The getUsage() method provides an estimate
of the current usage of a memory pool.
For a garbage-collected memory pool, the amount of used memory
includes the memory occupied by all objects in the pool
including both reachable and unreachable objects.

In general, this method is a lightweight operation for getting
an approximate memory usage.  For some memory pools, for example,
when objects are not packed contiguously, this method may be
an expensive operation that requires some computation to determine
the current memory usage.  An implementation should document when
this is the case.

2. Peak Memory Usage

The Java virtual machine maintains the peak memory usage of a memory
pool since the virtual machine was started or the peak was reset.
The peak memory usage is returned by the getPeakUsage() method
and reset by calling the resetPeakUsage() method.

3. Usage Threshold

Each memory pool has a manageable attribute
called the usage threshold which has a default value supplied
by the Java virtual machine.  The default value is platform-dependent.
The usage threshold can be set via the
setUsageThreshold method.
If the threshold is set to a positive value, the usage threshold crossing
checking is enabled in this memory pool.
If the usage threshold is set to zero, usage
threshold crossing checking on this memory pool is disabled.
The isUsageThresholdSupported() method can
be used to determine if this functionality is supported.

A Java virtual machine performs usage threshold crossing checking on a
memory pool basis at its best appropriate time, typically,
at garbage collection time.
Each memory pool maintains a usage threshold count that will get incremented
every time when the Java virtual machine
detects that the memory pool usage is crossing the threshold.

This manageable usage threshold attribute is designed for monitoring the
increasing trend of memory usage with low overhead.
Usage threshold may not be appropriate for some memory pools.
For example, a generational garbage collector, a common garbage collection
algorithm used in many Java virtual machine implementations,
manages two or more generations segregating objects by age.
Most of the objects are allocated in
the youngest generation (say a nursery memory pool).
The nursery memory pool is designed to be filled up and
collecting the nursery memory pool will free most of its memory space
since it is expected to contain mostly short-lived objects
and mostly are unreachable at garbage collection time.
In this case, it is more appropriate for the nursery memory pool
not to support a usage threshold.  In addition,
if the cost of an object allocation
in one memory pool is very low (for example, just atomic pointer exchange),
the Java virtual machine would probably not support the usage threshold
for that memory pool since the overhead in comparing the usage with
the threshold is higher than the cost of object allocation.


The memory usage of the system can be monitored using
polling or
threshold notification mechanisms.


  Polling

      An application can continuously monitor its memory usage
      by calling either the getUsage() method for all
      memory pools or the isUsageThresholdExceeded() method
      for those memory pools that support a usage threshold.
      Below is example code that has a thread dedicated for
      task distribution and processing.  At every interval,
      it will determine if it should receive and process new tasks based
      on its memory usage.  If the memory usage exceeds its usage threshold,
      it will redistribute all outstanding tasks to other VMs and
      stop receiving new tasks until the memory usage returns
      below its usage threshold.



      // Assume the usage threshold is supported for this pool.
      // Set the threshold to myThreshold above which no new tasks
      // should be taken.
      pool.setUsageThreshold(myThreshold);
      ....

      boolean lowMemory = false;
      while (true) {
         if (pool.isUsageThresholdExceeded()) {
             // potential low memory, so redistribute tasks to other VMs
             lowMemory = true;
             redistributeTasks();
             // stop receiving new tasks
             stopReceivingTasks();
         } else {
             if (lowMemory) {
                 // resume receiving tasks
                 lowMemory = false;
                 resumeReceivingTasks();
             }
             // processing outstanding task
             ...
         }
         // sleep for sometime
         try {
             Thread.sleep(sometime);
         } catch (InterruptedException e) {
             ...
         }
      }


      The above example does not differentiate the case where
      the memory usage has temporarily dropped below the usage threshold
      from the case where the memory usage remains above the threshold
      between two iterations.  The usage threshold count returned by
      the getUsageThresholdCount() method
      can be used to determine
      if the memory usage has returned below the threshold
      between two polls.

      Below shows another example that takes some action if a
      memory pool is under low memory and ignores the memory usage
      changes during the action processing time.



      // Assume the usage threshold is supported for this pool.
      // Set the threshold to myThreshold which determines if
      // the application will take some action under low memory condition.
      pool.setUsageThreshold(myThreshold);

      int prevCrossingCount = 0;
      while (true) {
          // A busy loop to detect when the memory usage
          // has exceeded the threshold.
          while (!pool.isUsageThresholdExceeded() ||
                 pool.getUsageThresholdCount() == prevCrossingCount) {
              try {
                  Thread.sleep(sometime)
              } catch (InterruptException e) {
                  ....
              }
          }

          // Do some processing such as check for memory usage
          // and issue a warning
          ....

          // Gets the current threshold count. The busy loop will then
          // ignore any crossing of threshold happens during the processing.
          prevCrossingCount = pool.getUsageThresholdCount();
      }

  Usage Threshold Notifications

      Usage threshold notification will be emitted by MemoryMXBean.
      When the Java virtual machine detects that the memory usage of
      a memory pool has reached or exceeded the usage threshold
      the virtual machine will trigger the MemoryMXBean to emit an
      usage threshold exceeded notification.
      Another usage threshold exceeded notification will not be
      generated until the usage has fallen below the threshold and
      then exceeded it again.

      Below is an example code implementing the same logic as the
      first example above but using the usage threshold notification
      mechanism to detect low memory conditions instead of polling.
      In this example code, upon receiving notification, the notification
      listener notifies another thread to perform the actual action
      such as to redistribute outstanding tasks, stop receiving tasks,
      or resume receiving tasks.
      The handleNotification method should be designed to
      do a very minimal amount of work and return without delay to avoid
      causing delay in delivering subsequent notifications.  Time-consuming
      actions should be performed by a separate thread.
      The notification listener may be invoked by multiple threads
      concurrently; so the tasks performed by the listener
      should be properly synchronized.



      class MyListener implements javax.management.NotificationListener {
           public void handleNotification(Notification notification, Object handback)  {
               String notifType = notification.getType();
               if (notifType.equals(MemoryNotificationInfo.MEMORY_THRESHOLD_EXCEEDED)) {
                   // potential low memory, notify another thread
                   // to redistribute outstanding tasks to other VMs
                   // and stop receiving new tasks.
                   lowMemory = true;
                   notifyAnotherThread(lowMemory);
               }
           }
      }

      // Register MyListener with MemoryMXBean
      MemoryMXBean mbean = ManagementFactory.getMemoryMXBean();
      NotificationEmitter emitter = (NotificationEmitter) mbean;
      MyListener listener = new MyListener();
      emitter.addNotificationListener(listener, null, null);

      // Assume this pool supports a usage threshold.
      // Set the threshold to myThreshold above which no new tasks
      // should be taken.
      pool.setUsageThreshold(myThreshold);

      // Usage threshold detection is enabled and notification will be
      // handled by MyListener.  Continue for other processing.
      ....


      There is no guarantee about when the MemoryMXBean will emit
      a threshold notification and when the notification will be delivered.
      When a notification listener is invoked, the memory usage of
      the memory pool may have crossed the usage threshold more
      than once.
      The MemoryNotificationInfo.getCount() method returns the number
      of times that the memory usage has crossed the usage threshold
      at the point in time when the notification was constructed.
      It can be compared with the current usage threshold count returned
      by the getUsageThresholdCount() method to determine if
      such situation has occurred.



4. Collection Usage Threshold

Collection usage threshold is a manageable attribute only applicable
to some garbage-collected memory pools.
After a Java virtual machine has expended effort in reclaiming memory
space by recycling unused objects in a memory pool at garbage collection
time, some number of bytes in the memory pools that are garbaged
collected will still be in use.  The collection usage threshold
allows a value to be set for this number of bytes such
that if the threshold is exceeded,
a collection usage threshold exceeded notification
will be emitted by the MemoryMXBean.
In addition, the collection usage threshold count will then be incremented.


The isCollectionUsageThresholdSupported() method can
be used to determine if this functionality is supported.


A Java virtual machine performs collection usage threshold checking
on a memory pool basis.  This checking is enabled if the collection
usage threshold is set to a positive value.
If the collection usage threshold is set to zero, this checking
is disabled on this memory pool.  Default value is zero.
The Java virtual machine performs the collection usage threshold
checking at garbage collection time.


Some garbage-collected memory pools may
choose not to support the collection usage threshold.  For example,
a memory pool is only managed by a continuous concurrent garbage
collector.  Objects can be allocated in this memory pool by some thread
while the unused objects are reclaimed by the concurrent garbage
collector simultaneously.  Unless there is a well-defined
garbage collection time which is the best appropriate time
to check the memory usage, the collection usage threshold should not
be supported.


The collection usage threshold is designed for monitoring the memory usage
after the Java virtual machine has expended effort in reclaiming
memory space.  The collection usage could also be monitored
by the polling and threshold notification mechanism
described above for the usage threshold
in a similar fashion.

   ----------------------------------------------+
   ////////////////           |
   ////////////////           |
   ----------------------------------------------+

   |--------|
      init
   |---------------|
          used
   |---------------------------|
             committed
   |----------------------------------------------|
                       max

A MemoryUsage object represents a snapshot of memory usage.
Instances of the MemoryUsage class are usually constructed
by methods that are used to obtain memory usage
information about individual memory pool of the Java virtual machine or
the heap or non-heap memory of the Java virtual machine as a whole.

 A MemoryUsage object contains four values:


 init
 represents the initial amount of memory (in bytes) that
     the Java virtual machine requests from the operating system
     for memory management during startup.  The Java virtual machine
     may request additional memory from the operating system and
     may also release memory to the system over time.
     The value of init may be undefined.



 used
 represents the amount of memory currently used (in bytes).



 committed
 represents the amount of memory (in bytes) that is
     guaranteed to be available for use by the Java virtual machine.
     The amount of committed memory may change over time (increase
     or decrease).  The Java virtual machine may release memory to
     the system and committed could be less than init.
     committed will always be greater than
     or equal to used.



 max
 represents the maximum amount of memory (in bytes)
     that can be used for memory management. Its value may be undefined.
     The maximum amount of memory may change over time if defined.
     The amount of used and committed memory will always be less than
     or equal to max if max is defined.
     A memory allocation may fail if it attempts to increase the
     used memory such that used > committed even
     if used <= max would still be true (for example,
     when the system is low on virtual memory).




Below is a picture showing an example of a memory pool:



       ----------------------------------------------+
       ////////////////           |
       ////////////////           |
       ----------------------------------------------+

       |--------|
          init
       |---------------|
              used
       |---------------------------|
                 committed
       |----------------------------------------------|
                           max

MXBean Mapping
MemoryUsage is mapped to a CompositeData
with attributes as specified in the from method.

Information about an object monitor lock.  An object monitor is locked
when entering a synchronization block or method on that object.

MXBean Mapping
MonitorInfo is mapped to a CompositeData
with attributes as specified in
the from method.

The management interface for the operating system on which
the Java virtual machine is running.

 A Java virtual machine has a single instance of the implementation
class of this interface.  This instance implementing this interface is
an MXBean
that can be obtained by calling
the ManagementFactory.getOperatingSystemMXBean() method or
from the platform MBeanServer method.

The ObjectName for uniquely identifying the MXBean for
the operating system within an MBeanServer is:

   java.lang:type=OperatingSystem


It can be obtained by calling the
PlatformManagedObject.getObjectName() method.

 This interface defines several convenient methods for accessing
system properties about the operating system on which the Java
virtual machine is running.

PlatformLoggingMXBean logging = ManagementFactory.getPlatformMXBean(PlatformLoggingMXBean.class);

 java.util.logging:type=Logging

The management interface for the logging facility.

There is a single global instance of the PlatformLoggingMXBean.
The ManagementFactory.getPlatformMXBean method can be used to obtain
the PlatformLoggingMXBean object as follows:


    PlatformLoggingMXBean logging = ManagementFactory.getPlatformMXBean(PlatformLoggingMXBean.class);
The PlatformLoggingMXBean object is also registered with the
platform MBeanServer.
The ObjectName for uniquely
identifying the PlatformLoggingMXBean within an MBeanServer is:


     java.util.logging:type=Logging

The instance registered in the platform MBeanServer with
this ObjectName implements all attributes defined by
LoggingMXBean.

A platform managed object is a javax.management.JMX MXBean
for monitoring and managing a component in the Java platform.
Each platform managed object has a unique
object name
for the platform MBeanServer access.
All platform MXBeans will implement this interface.


Note:
The platform MXBean interfaces (i.e. all subinterfaces
of PlatformManagedObject) are implemented
by the Java platform only.  New methods may be added in these interfaces
in future Java SE releases.
In addition, this PlatformManagedObject interface is only
intended for the management interfaces for the platform to extend but
not for applications.

The management interface for the runtime system of
the Java virtual machine.

 A Java virtual machine has a single instance of the implementation
class of this interface.  This instance implementing this interface is
an MXBean
that can be obtained by calling
the ManagementFactory.getRuntimeMXBean() method or
from the platform MBeanServer method.

The ObjectName for uniquely identifying the MXBean for
the runtime system within an MBeanServer is:

   java.lang:type=Runtime


It can be obtained by calling the
PlatformManagedObject.getObjectName() method.

 This interface defines several convenient methods for accessing
system properties about the Java virtual machine.

  waiting to enter a synchronization block/method, or
  waiting to be notified in a Object.wait method,
      or
  parking due to a LockSupport.park call.

Thread information. ThreadInfo contains the information
about a thread including:
General thread information

  Thread ID.
  Name of the thread.


Execution information

  Thread state.
  The object upon which the thread is blocked due to:

      waiting to enter a synchronization block/method, or
      waiting to be notified in a Object.wait method,
          or
      parking due to a LockSupport.park call.


  The ID of the thread that owns the object
      that the thread is blocked.
  Stack trace of the thread.
  List of object monitors locked by the thread.
  List of
      ownable synchronizers locked by the thread.


Synchronization Statistics

  The number of times that the thread has blocked for
      synchronization or waited for notification.
  The accumulated elapsed time that the thread has blocked
      for synchronization or waited for notification
      since thread contention monitoring
      was enabled. Some Java virtual machine implementation
      may not support this.  The
      ThreadMXBean.isThreadContentionMonitoringSupported()
      method can be used to determine if a Java virtual machine
      supports this.


This thread information class is designed for use in monitoring of
the system, not for synchronization control.

MXBean Mapping
ThreadInfo is mapped to a CompositeData
with attributes as specified in
the from method.

The management interface for the thread system of
the Java virtual machine.

 A Java virtual machine has a single instance of the implementation
class of this interface.  This instance implementing this interface is
an MXBean
that can be obtained by calling
the ManagementFactory.getThreadMXBean() method or
from the platform MBeanServer method.

The ObjectName for uniquely identifying the MXBean for
the thread system within an MBeanServer is:

   java.lang:type=Threading


It can be obtained by calling the
PlatformManagedObject.getObjectName() method.

Thread ID
Thread ID is a positive long value returned by calling the
Thread.getId() method for a thread.
The thread ID is unique during its lifetime.  When a thread
is terminated, this thread ID may be reused.

 Some methods in this interface take a thread ID or an array
of thread IDs as the input parameter and return per-thread information.

Thread CPU time
A Java virtual machine implementation may support measuring
the CPU time for the current thread, for any thread, or for no threads.


The isThreadCpuTimeSupported() method can be used to determine
if a Java virtual machine supports measuring of the CPU time for any
thread.  The isCurrentThreadCpuTimeSupported() method can
be used to determine if a Java virtual machine supports measuring of
the CPU time for the current  thread.
A Java virtual machine implementation that supports CPU time measurement
for any thread will also support that for the current thread.

 The CPU time provided by this interface has nanosecond precision
but not necessarily nanosecond accuracy.


A Java virtual machine may disable CPU time measurement
by default.
The isThreadCpuTimeEnabled() and setThreadCpuTimeEnabled(boolean)
methods can be used to test if CPU time measurement is enabled
and to enable/disable this support respectively.
Enabling thread CPU measurement could be expensive in some
Java virtual machine implementations.

Thread Contention Monitoring
Some Java virtual machines may support thread contention monitoring.
When thread contention monitoring is enabled, the accumulated elapsed
time that the thread has blocked for synchronization or waited for
notification will be collected and returned in the
ThreadInfo object.

The isThreadContentionMonitoringSupported() method can be used to
determine if a Java virtual machine supports thread contention monitoring.
The thread contention monitoring is disabled by default.  The
setThreadContentionMonitoringEnabled(boolean) method can be used to enable
thread contention monitoring.

Synchronization Information and Deadlock Detection
Some Java virtual machines may support monitoring of
object monitor usage and
ownable synchronizer usage.
The getThreadInfo(long[], boolean, boolean) and
dumpAllThreads(boolean, boolean) methods can be used to obtain the thread stack trace
and synchronization information including which
lock a thread is blocked to
acquire or waiting on and which locks the thread currently owns.

The ThreadMXBean interface provides the
findMonitorDeadlockedThreads() and
findDeadlockedThreads() methods to find deadlocks in
the running application.