2008-02-10 Andrew John Hughes <gnu_andrew@member.fsf.org>

	* javax/management/remote/NotificationResult.java:
	New file.
	* javax/management/remote/TargetedNotification.java:
	Likewise.
	* javax/management/remote/rmi/RMIConnection.java:
	(fetchNotifications(long,int,long)): Added.

4 files changed, 361 insertions, 1 deletions

diff --git a/ChangeLog b/ChangeLog
index 8b3f9fe43..7790afe64 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2008-02-10  Andrew John Hughes  <gnu_andrew@member.fsf.org>
+
+	* javax/management/remote/NotificationResult.java:
+	New file.
+	* javax/management/remote/TargetedNotification.java:
+	Likewise.
+	* javax/management/remote/rmi/RMIConnection.java:
+	(fetchNotifications(long,int,long)): Added.
+	
 2008-02-10  Dalibor Topic  <robilad@kaffe.org>
 
 	* lib/Makefile.am (compile_classpath), include/Makefile.am (JAVAH): 
diff --git a/javax/management/remote/NotificationResult.java b/javax/management/remote/NotificationResult.java
new file mode 100644
index 000000000..c0b2d9ba1
--- /dev/null
+++ b/javax/management/remote/NotificationResult.java
@@ -0,0 +1,166 @@
+/* NotificationResult.java -- Wrapper for a series of buffered notifications.
+   Copyright (C) 2008 Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+02110-1301 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+package javax.management.remote;
+
+import java.io.Serializable;
+
+/**
+ * <p>
+ * Wraps the result of a query for buffered notifications.  In a remote
+ * scenario, it may be more practical for the server to buffer individual
+ * notifications from its beans and then return them in bulk on request.
+ * This class contains the notifications returned by such a request.
+ * </p>
+ * <p>
+ * It consists of a series of {@link Notification} and identifier pairs,
+ * wrapped in a {@link TargetedNotification} object.  The identifiers
+ * serve to pair up the notification with the listener that requested
+ * it.  Two positive numbers are also included: the first sequence number
+ * used by the returned notifications, and the sequence number of the
+ * notification which will be returned by the next query.  The first
+ * sequence number may be greater than the next sequence number if some
+ * notifications have been lost.
+ * </p>
+ *
+ * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
+ * @since 1.5
+ */
+public class NotificationResult
+  implements Serializable
+{
+
+  /**
+   * Compatible with JDK 1.6
+   */
+  private static final long serialVersionUID = 1191800228721395279L;
+
+  /**
+   * The sequence number of the first notification.
+   */
+  private long earliestSequenceNumber;
+
+  /**
+   * The sequence number of the next notification to be
+   * returned by a future query.
+   */
+  private long nextSequenceNumber;
+
+  /**
+   * The pairs of notifications and identifiers returned
+   * by the query.
+   */
+  private TargetedNotification[] targetedNotifications;
+
+  /**
+   * Constructs a new {@link NotificationResult} using the specified
+   * sequence numbers and the supplied array of notification pairs.
+   *
+   * @param startSeqNumber the sequence number of the first notification
+   *                       being returned.
+   * @param nextSeqNumber the sequence numbr of the next notification
+   *                      that will be returned from a future query.
+   * @param notifications the notification and identifier pairs.  This
+   *                      may be empty.
+   * @throws IllegalArgumentException if a sequence number is negative
+   *                                  or <code>notifications</code> is
+   *                                  <code>null</code>.
+   */
+  public NotificationResult(long startSeqNumber, long nextSeqNumber,
+			    TargetedNotification[] notifications)
+  {
+    if (startSeqNumber < 0)
+      throw new IllegalArgumentException("Starting sequence number is " +
+					 "less than 0.");
+    if (nextSeqNumber < 0)
+      throw new IllegalArgumentException("Next sequence number is " +
+					 "less than 0.");
+    if (notifications == null)
+      throw new IllegalArgumentException("The array of notifications is null.");
+    earliestSequenceNumber = startSeqNumber;
+    nextSequenceNumber = nextSeqNumber;
+    targetedNotifications = notifications;
+  }
+
+  /**
+   * Returns the sequence number of the earliest notification
+   * in the buffer.
+   *
+   * @return the sequence number of the earliest notification.
+   */
+  public long getEarliestSequenceNumber()
+  {
+    return earliestSequenceNumber;
+  }
+
+  /**
+   * Returns the sequence number of the next notification to
+   * be returned by a future query.
+   *
+   * @return the sequence number of the next notification.
+   */
+  public long getNextSequenceNumber()
+  {
+    return nextSequenceNumber;
+  }
+
+  /**
+   * Returns the notification and identifier pairs returned
+   * by the query.
+   *
+   * @return the notification and identifier pairs.
+   */
+  public TargetedNotification[] getTargetedNotifications()
+  {
+    return targetedNotifications;
+  }
+
+  /**
+   * Returns a textual representation of the object.
+   *
+   * @return a textual representation.
+   */
+  public String toString()
+  {
+    return getClass().getName() +
+      "[earliestSequenceNumber=" + earliestSequenceNumber +
+      ",nextSequenceNumber=" + nextSequenceNumber + 
+      ",targetedNotifications=" + targetedNotifications +
+      "]";
+  }
+
+}
diff --git a/javax/management/remote/TargetedNotification.java b/javax/management/remote/TargetedNotification.java
new file mode 100644
index 000000000..c383c9184
--- /dev/null
+++ b/javax/management/remote/TargetedNotification.java
@@ -0,0 +1,127 @@
+/* TargetedNotificaton.java -- Wrapper for a notification and identifier pair.
+   Copyright (C) 2008 Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+02110-1301 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+package javax.management.remote;
+
+import java.io.Serializable;
+
+import javax.management.Notification;
+
+/**
+ * Wraps a notification with an identifier that specifies
+ * the listener which received it.
+ *
+ * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
+ * @since 1.5
+ */
+public class TargetedNotification
+  implements Serializable
+{
+
+  /**
+   * Compatible with JDK 1.6
+   */
+  private static final long serialVersionUID = 7676132089779300926L;
+
+  /**
+   * The notification that was recieved by the listener.
+   */
+  private Notification notif;
+
+  /**
+   * The identifier for the listener that received the notification;
+   */
+  private Integer id;
+
+  /**
+   * Constructs a new {@link TargetedNotification} which connects
+   * the supplied notification with the specified identifier.  The
+   * identifier matches one of those returned by a previous call
+   * to add a new notification listener.
+   *
+   * @param notif the notification.
+   * @param id the identifier of the listener that received the
+   *           notification.
+   * @throws IllegalArgumentException if either argument is
+   *                                  <code>null</code>.
+   */
+  public TargetedNotification(Notification notif, Integer id)
+  {
+    if (notif == null)
+      throw new IllegalArgumentException("The notification is null.");
+    if (id == null)
+      throw new IllegalArgumentException("The identifier is null.");
+    this.notif = notif;
+    this.id = id;
+  }
+
+  /**
+   * Returns the notification.
+   *
+   * @return the notification.
+   */
+  public Notification getNotification()
+  {
+    return notif;
+  }
+
+  /**
+   * Returns the identifier for the listener
+   * which received the notification.
+   *
+   * @return the identifier.
+   */
+  public Integer getListenerID()
+  {
+    return id;
+  }
+
+  /**
+   * Returns a textual representation of the object.
+   *
+   * @return a textual representation.
+   */
+  public String toString()
+  {
+    return getClass().getName() +
+      "[notif=" + notif +
+      ",id=" + id +
+      "]";
+  }
+
+}
+
diff --git a/javax/management/remote/rmi/RMIConnection.java b/javax/management/remote/rmi/RMIConnection.java
index 647f9a3ad..38fb544fe 100644
--- a/javax/management/remote/rmi/RMIConnection.java
+++ b/javax/management/remote/rmi/RMIConnection.java
@@ -1,5 +1,5 @@
 /* RMIConnection.java -- RMI object representing a MBean server connection.
-   Copyright (C) 2007 Free Software Foundation, Inc.
+   Copyright (C) 2007, 2008 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -60,6 +60,8 @@ import javax.management.ObjectInstance;
 import javax.management.ObjectName;
 import javax.management.ReflectionException;
 
+import javax.management.remote.NotificationResult;
+
 import javax.security.auth.Subject;
 
 /**
@@ -495,6 +497,62 @@ public interface RMIConnection
 	   NotCompliantMBeanException, IOException;
 
   /**
+   * <p>
+   * Retrieves any waiting notifications from the server.  When notifications
+   * are requested using the {@link #addNotificationListeners(ObjectName[],
+   * MarshalledObject[], Subject[])} method, the server sets up an internal
+   * listener to receive notifications from the bean and buffer them.  When
+   * this method is called, these buffered notifications can be retrieved.
+   * </p>
+   * <p>
+   * The blocking behaviour of this method depends on the timeout value specified.
+   * If there are no waiting notifications in the buffer, a value of 0 will cause
+   * the method to return immediately.  Conversely, if the value is
+   * {@link Long#MAX_VALUE}, then it will wait indefinitely until a notification
+   * arrives. For any other value, it waits until a notification arrives or the
+   * number of milliseconds specified by the timeout value is exceeded.  The
+   * behaviour for a negative timeout value is undefined.
+   * </p>
+   * <p>
+   * For a notification to be returned, the following criteria must be fulfilled:
+   * </p>
+   * <ul>
+   * <li>the client must have previously requested notifications from at least
+   * one bean</li>
+   * <li>a bean from which notifications have been requested must have emitted
+   * a notification since the last call to this method</li>
+   * <li>the emitted notification must pass through any filters established
+   * when notifications were requested</li>
+   * <li>the sequence number of the notification must be greater than or equal
+   * to the specified sequence number (if non-negative)</li>
+   * </ul>
+   *
+   * @param sequenceNumber the sequence number of each notification returned
+   *                       must be greater than or equal to this value.  If
+   *                       the number is negative, this is interpreted as
+   *                       meaning the sequence number of the next notification
+   *                       and so all notifications are allowed through.
+   * @param maxNotifications the maximum number of notifications to return.
+   *                         This does not include any duplicates so the
+   *                         number of actual notifications returned may
+   *                         be larger.
+   * @param timeout the number of milliseconds to wait for a notification
+   *                if the buffer is empty.  <code>0</code> causes the
+   *                method to return immediately even if there are no
+   *                notifications available (non-blocking behaviour) while
+   *                a value of {@link Long#MAX_VALUE} causes it to wait
+   *                indefinitely (blocking behaviour).  The response to
+   *                a negative value is undefined.
+   * @return a {@link NotificationResult} object containing the buffered
+   *         notifications.
+   * @throws IOException if an I/O error occurs.
+   */
+  NotificationResult fetchNotifications(long sequenceNumber,
+					int maxNotifications,
+					long timeout)
+    throws IOException;
+
+  /**
    * Handles {@link
    * MBeanServerConnection#getAttribute(ObjectName, String)},
    * returning the value of the supplied attribute from the specified