2006-07-22 Andrew John Hughes <gnu_andrew@member.fsf.org>

	* doc/vmintegration.texinfo:
	Mention callback methods.
	* gnu/java/lang/management/MemoryMXBeanImpl.java:
	(fireNotification(String,String,long,long,long,long,long)):
	Made package-private.
	(fireThresholdExceededNotification(String,long,long,long,
	long,long)): Likewise.
	(fireCollectionThresholdExceededNotification(String,long,
	long,long,long,long)): Likewise.
	* java/lang/management/MemoryMXBean.java:
	Document notifications.

4 files changed, 72 insertions, 11 deletions

diff --git a/ChangeLog b/ChangeLog
index 1a7def879..3199399a5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,19 @@
 2006-07-22  Andrew John Hughes  <gnu_andrew@member.fsf.org>
 
+	* doc/vmintegration.texinfo:
+	Mention callback methods.
+	* gnu/java/lang/management/MemoryMXBeanImpl.java:
+	(fireNotification(String,String,long,long,long,long,long)):
+	Made package-private.
+	(fireThresholdExceededNotification(String,long,long,long,
+	long,long)): Likewise.
+	(fireCollectionThresholdExceededNotification(String,long,
+	long,long,long,long)): Likewise.
+	* java/lang/management/MemoryMXBean.java:
+	Document notifications.
+
+2006-07-22  Andrew John Hughes  <gnu_andrew@member.fsf.org>
+
 	* gnu/java/lang/management/MemoryMXBeanImpl.java:
 	(fireNotification(String,String,long,long,long,long,long)):
 	Implemented.
diff --git a/doc/vmintegration.texinfo b/doc/vmintegration.texinfo
index bd7464e49..d6f327310 100644
--- a/doc/vmintegration.texinfo
+++ b/doc/vmintegration.texinfo
@@ -1651,6 +1651,25 @@ the group.
 Call this method from @code{Thread} when a @code{Thread} is stopped or destroyed.
 @end itemize
 
+@item @code{gnu.java.lang.management.MemoryMXBeanImpl.fireThresholdExceededNotification(String, long, long, long, long)}
+If the monitoring of memory usage thresholds is supported, this method
+should be called when the normal usage of a memory pool crosses the
+threshold, in order to emit a notification.  Another notification
+should not be emitted until there is an intermittent period where the
+usage is again below the threshold.  The parameters are the memory
+pool name, the usage levels (init, used, committed and max) and the
+number of times the threshold has been crossed.
+
+@item @code{gnu.java.lang.management.MemoryMXBeanImpl.fireCollectionThresholdExceededNotification(String, long, long, long, long)}
+If the monitoring of memory usage thresholds is supported, this method
+should be called when the usage of a memory pool after a garbage
+collection cycle crosses the threshold, in order to emit a
+notification.  Another notification should not be emitted until there
+is an intermittent period where the usage is again below the
+threshold.  The parameters are the memory pool name, the usage levels
+(init, used, committed and max) and the number of times the threshold
+has been crossed.
+
 @node VM Hooks, JNI Implementation, Classpath Hooks, Top
 @comment node-name, next, previous, up
 @chapter VM Hooks
diff --git a/gnu/java/lang/management/MemoryMXBeanImpl.java b/gnu/java/lang/management/MemoryMXBeanImpl.java
index 1fa1a5954..6890130d4 100644
--- a/gnu/java/lang/management/MemoryMXBeanImpl.java
+++ b/gnu/java/lang/management/MemoryMXBeanImpl.java
@@ -257,8 +257,8 @@ public final class MemoryMXBeanImpl
       }
   }
 
-  public void fireNotification(String type, String poolName, long init, long used,
-			       long committed, long max, long count)
+  void fireNotification(String type, String poolName, long init, long used,
+			long committed, long max, long count)
   {
     Notification notif = new Notification(type, this, notificationCount);
     MemoryUsage usage = new MemoryUsage(init, used, committed, max);
@@ -290,20 +290,20 @@ public final class MemoryMXBeanImpl
     ++notificationCount;
   }
 
-  public void fireThresholdExceededNotification(String poolName, long init,
-						long used, long committed,
-						long max, long count)
+  void fireThresholdExceededNotification(String poolName, long init,
+					 long used, long committed,
+					 long max, long count)
   {
     fireNotification(MemoryNotificationInfo.MEMORY_THRESHOLD_EXCEEDED,
 		     poolName, init, used, committed, max, count);
   }
 
-  public void fireCollectionThresholdExceededNotification(String poolName,
-							  long init,
-							  long used,
-							  long committed,
-							  long max,
-							  long count)
+  void fireCollectionThresholdExceededNotification(String poolName,
+						   long init,
+						   long used,
+						   long committed,
+						   long max,
+						   long count)
   {
     fireNotification(MemoryNotificationInfo.MEMORY_COLLECTION_THRESHOLD_EXCEEDED,
 		     poolName, init, used, committed, max, count);
diff --git a/java/lang/management/MemoryMXBean.java b/java/lang/management/MemoryMXBean.java
index 33d211c9b..4d9e5ff1c 100644
--- a/java/lang/management/MemoryMXBean.java
+++ b/java/lang/management/MemoryMXBean.java
@@ -70,6 +70,34 @@ package java.lang.management;
  * either change (either expanding or contracting) or stay
  * the same.
  * </p>
+ * <h2>Notifications</h2>
+ * <p>
+ * Implementations of this interface also conform to the
+ * {@link javax.management.NotificationEmitter} interface,
+ * and supply two notifications reflecting memory usage.
+ * These notifications occur when a usage threshold is
+ * exceeded; for more details of these, see the documentation
+ * of {@link MemoryPoolMXBean}.  If threshold monitoring
+ * is supported, then a notification will be emitted each time
+ * the threshold is crossed.  Another notification will not
+ * be emitted unless the usage level has dropped below the
+ * threshold again in the meantime.
+ * </p>
+ * <p>
+ * The emitted notifications are instances of
+ * {@link javax.management.Notification}, with a type of
+ * either
+ * {@link java.lang.management.MemoryNotificationInfo#MEMORY_THRESHOLD_EXCEEDED}
+ * or
+ * {@link java.lang.management.MemoryNotificationInfo#MEMORY_COLLECTION_THRESHOLD_EXCEEDED}
+ * (depending on whether the notification refers to the general
+ * usage threshold or the garbage collection threshold) and an instance
+ * of {@link java.lang.management.MemoryNotificationInfo} contained
+ * in the user data section.  This is wrapped inside an instance
+ * of {@link javax.management.openmbean.CompositeData}, as explained
+ * in the documentation for
+ * {@link java.lang.management.MemoryNotificationInfo}.
+ * </p>
  *
  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  * @since 1.5