2007-12-31 Andrew John Hughes <gnu_andrew@member.fsf.org>

	* javax/management/remote/rmi/RMIConnection.java:
	Partial implementation.
	* javax/management/remote/rmi/RMIServer.java:
	Implemented.

2 files changed, 302 insertions, 0 deletions

diff --git a/javax/management/remote/rmi/RMIConnection.java b/javax/management/remote/rmi/RMIConnection.java
new file mode 100644
index 000000000..e5cf23e4b
--- /dev/null
+++ b/javax/management/remote/rmi/RMIConnection.java
@@ -0,0 +1,213 @@
+/* RMIConnection.java -- RMI object representing a MBean server connection.
+   Copyright (C) 2007 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.rmi;
+
+import java.io.Closeable;
+import java.io.IOException;
+
+import java.rmi.MarshalledObject;
+import java.rmi.Remote;
+
+import javax.management.InstanceNotFoundException;
+import javax.management.ObjectName;
+
+import javax.security.auth.Subject;
+
+/**
+ * <p>
+ * RMI interface for forwarding requests to a remote
+ * {@link javax.management.MBeanServer}.  This interface
+ * parallels the {@link javax.management.MBeanServerConnection}
+ * interface, providing a way of invoking those methods using
+ * the RMI protocol.  When a client wishes to call a method
+ * of an MBean server using RMI, the method is called on the stub
+ * on the client side, which serializes the object parameters
+ * and sends them to the server where they are deserialized and
+ * an implementation of this interface forwards them to the
+ * appropriate MBean server.  Return values follow the same
+ * process, only in reverse.  Each client obtains its own
+ * implementation of this interface from an {@link RMIServer}
+ * instance.
+ * </p>
+ * <p>
+ * Implementations of this interface do more than simply
+ * forward requests directly to the server.  The arguments
+ * of the server methods are wrapped in {@link MarshalledObject}
+ * instances, so that the correct classloader can be used to
+ * deserialize the arguments.  When a method is called, the
+ * implementation must first retrieve the appropriate classloader
+ * and then use it to deserialize the marshalled object.  Unless
+ * explicitly specified in the documentation for the method,
+ * a parameter of the type {@link MarshalledObject} or an array
+ * of that type should not be {@code null}.
+ * </p>
+ * <p>
+ * Security is also handled by this interface, as the methods
+ * use an additional {@link javax.security.auth.Subject} parameter
+ * for role delegation.
+ * </p>
+ *
+ * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
+ * @since 1.5
+ */
+public interface RMIConnection
+  extends Closeable, Remote
+{
+
+  /**
+   * Handles {@link
+   * MBeanServerConnection#addNotificationListener(ObjectName,
+   * ObjectName, NotificationFilter, Object)} by
+   * registering the supplied listener with the specified management
+   * bean.  Notifications emitted by the management bean are forwarded
+   * to the listener via the server, which will convert any MBean
+   * references in the source to portable {@link ObjectName}
+   * instances.  The notification is otherwise unchanged.  The filter
+   * and handback object are wrapped in a {@link MarshalledObject}
+   * so that they are deserialised using the bean's classloader.
+   *
+   * @param name the name of the management bean with which the listener
+   *             should be registered.
+   * @param listener the listener which will handle notifications from
+   *                 the bean.
+   * @param filter a wrapper containing a filter to apply to incoming
+   *               notifications, or <code>null</code> if no filtering
+   *               should be applied.
+   * @param passback a wrapper containing an object to be passed to the
+   *                 listener when a notification is emitted.
+   * @param delegationSubject a {@link javax.security.auth.Subject} instance
+   *                          containing the delegation principles or
+   *                          {@code null} if authentication is used.
+   * @throws InstanceNotFoundException if the name of the management bean
+   *                                   could not be resolved.
+   * @throws RuntimeOperationsException if the bean associated with the given
+   *                                    object name is not a
+   *                                    {@link NotificationListener}.  This
+   *                                    exception wraps an
+   *                                    {@link IllegalArgumentException}.
+   * @throws SecurityException if the client or delegated subject (if any)
+   *                           does not have permission to invoke this operation.
+   * @throws IOException if an I/O error occurred in communicating with
+   *                     the bean server.
+   * @see #removeNotificationListener(ObjectName, ObjectName,
+   *                                  javax.security.auth.Subject)
+   * @see #removeNotificationListener(ObjectName, ObjectName,
+   *                                  java.rmi.MarshalledObject,
+   *                                  java.rmi.MarshalledObject,
+   *                                  javax.security.auth.Subject)
+   * @see #removeNotificationListeners(ObjectName, Integer[],
+   *                                  javax.security.auth.Subject)
+   * @see NotificationBroadcaster#addNotificationListener(NotificationListener,
+   *                                                      NotificationFilter,
+   *                                                      Object)
+   */
+  void addNotificationListener(ObjectName name, ObjectName listener,
+			       MarshalledObject filter, MarshalledObject passback,
+			       Subject delegationSubject)
+    throws InstanceNotFoundException, IOException;
+
+  /**
+   * Handles {@link
+   * MBeanServerConnection#addNotificationListener(ObjectName,
+   * NotificationListener, NotificationFilter, Object)} by
+   * registering for notifications from the specified management
+   * beans.  The array of filters is assumed to be aligned with
+   * the array of bean names, so that the notifications from each
+   * bean are matched against the appropriate filter (or left as
+   * is if the filter is {@code null}.  Notifications emitted by
+   * the management beans are forwarded to a local listener created
+   * by this method, via the server, which converts any MBean
+   * references in the source to portable {@link ObjectName}
+   * instances.  The notification is otherwise unchanged.
+   * </p>
+   * <p>
+   * This local listener buffers the notifications for retrieval by
+   * {@link #fetchNotifications(long,int,long).  This method returns
+   * an array of listener identifiers which aligns with the supplied
+   * array of beans so that the appropriate listener can be identified
+   * by the client, which retains its own listener and handback object.
+   * The filters are wrapped in {@link MarshalledObject}s so that they are
+   * deserialised using the bean's classloader.
+   * </p>
+   *
+   * @param names the names of the management bean whose notifications
+   *              should be recorded.
+   * @param filters an array of wrappers containing filters to apply to
+   *                incoming notifications.  An element may be <code>null</code>
+   *                if no filtering should be applied to a bean's notifications.
+   * @param delegationSubjects an array of {@link javax.security.auth.Subject}
+   *                          instances containing the delegation principles for
+   *                          each listener.  An element may be {@code null} if
+   *                          authentication is used instead, or the entire
+   *                          argument itself may be {@code null}.  In the latter
+   *                          case, this is treated as an array of {@code null}
+   *                          values.
+   * @return an array of integers which act as listener identifiers, so that
+   *         notifications retrieved from {@link #fetchNotifications(long,int,long)
+   *         can be matched to the beans they were emitted from.  The array is
+   *         aligned against the array of beans supplied to this methods, so that
+   *         the identifier in position 0 represents the bean in position 0 of the
+   *         input array.
+   * @throws IllegalArgumentException if the {@code names} or {@code filters} array
+   *                                  is {@code null}, the {@code names} array contains
+   *                                  a {@code null} value or the three arrays are not
+   *                                  of the same size.
+   * @throws ClassCastException if an element of the {@code filters} array unmarshalls
+   *                            as a non-null object that is not a {@link NotificationFilter}.
+   * @throws InstanceNotFoundException if the name of one of the management beans
+   *                                   could not be resolved.
+   * @throws SecurityException if, for one of the beans, the client or delegated subject
+   *                           (if any) does not have permission to invoke this operation.
+   * @throws IOException if an I/O error occurred in communicating with
+   *                     the bean server.
+   * @see #removeNotificationListener(ObjectName, ObjectName,
+   *                                  javax.security.auth.Subject)
+   * @see #removeNotificationListener(ObjectName, ObjectName,
+   *                                  java.rmi.MarshalledObject,
+   *                                  java.rmi.MarshalledObject,
+   *                                  javax.security.auth.Subject)
+   * @see #removeNotificationListeners(ObjectName, Integer[],
+   *                                  javax.security.auth.Subject)
+   * @see NotificationBroadcaster#addNotificationListener(NotificationListener,
+   *                                                      NotificationFilter,
+   *                                                      Object)
+   */
+  void addNotificationListeners(ObjectName[] names, MarshalledObject[] filters,
+				Subject[] delegationSubjects)
+    throws InstanceNotFoundException, IOException;
+}
diff --git a/javax/management/remote/rmi/RMIServer.java b/javax/management/remote/rmi/RMIServer.java
new file mode 100644
index 000000000..d862372ac
--- /dev/null
+++ b/javax/management/remote/rmi/RMIServer.java
@@ -0,0 +1,89 @@
+/* RMIServer.java -- RMI object for connecting to an RMI JMX connector.
+   Copyright (C) 2007 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.rmi;
+
+import java.io.IOException;
+
+import java.rmi.Remote;
+import java.rmi.RemoteException;
+
+/**
+ * RMI interface for obtaining an instance of an
+ * {@link RMIConnection}.  An implementation of this
+ * interface exists for each RMI connector.
+ *
+ * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
+ * @since 1.5
+ */
+public interface RMIServer
+  extends Remote
+{
+
+  /**
+   * Returns the version of the RMI connection protocol used
+   * by this server.  The returned string takes the form of
+   * <emph>protocol-version implementation-name</emph> where
+   * <emph>protocol-version</emph> is a series of two or more
+   * non-negative integers, separated by a decimal point (.)
+   * (currently {@code 1.0}) and <emph>implementation-name</emph>
+   * is the string {@code "GNU Classpath"} followed by the version
+   * of GNU Classpath in use.
+   *
+   * @return the string specified above.
+   * @throws RemoteException if there is a problem with the transfer
+   *                         of the string via RMI.
+   */
+  String getVersion()
+    throws RemoteException;
+
+  /**
+   * Constructs and returns a new RMI connection using the specified
+   * authentication credentials.  Each client calls this method to
+   * obtain a connection to the server.
+   *
+   * @param credentials a user-defined object passed to the server
+   *                    to authenticate the client.  May be {@code null}.
+   * @return the new connection.
+   * @throws IOException if the new connection can not be created or
+   *                     exported, or an error occurs in the RMI transmission.
+   * @throws SecurityException if the client could not be authenticated
+   *                           correctly using the supplied credientials.
+   */
+  RMIConnection newClient(Object credentials)
+    throws IOException;
+}