Imported GNU Classpath 0.19 + gcj-import-20051115.

* sources.am: Regenerated.
       * Makefile.in: Likewise.
       * scripts/makemake.tcl: Use glob -nocomplain.

From-SVN: r107049

libjava/classpath/javax/rmi/CORBA/PortableRemoteObjectDelegate.java

@@ -1,5 +1,5 @@
 /* PortableRemoteObjectDelegate.java -- Interface supporting PortableRemoteObject
-   Copyright (C) 2002, 2004 Free Software Foundation, Inc.
+   Copyright (C) 2002, 2004, 2005 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -43,23 +43,95 @@ import java.rmi.Remote;
 import java.rmi.RemoteException;
 
 /**
- * A delegate is a singleton class that support delegation for method
- * implementation in PortableRemoteObject.
+ * A delegate, implementing the functionality, provided by the
+ * {@link PortableRemoteObject}.
+ * 
+ * The default delegate can be altered by setting the system property
+ * "javax.rmi.CORBA.PortableRemoteObjectClass" to the name of the alternative
+ * class that must implement {@link PortableRemoteObjectDelegate}.
+ * 
+ * @author Audrius Meskauskas (AudriusA@Bioinformatics.org)
  */
 public interface PortableRemoteObjectDelegate
 {
+  /**
+   * <p>
+   * Makes the remote object <code>target</code> ready for remote
+   * communication using the same communications runtime as for the passed
+   * <code>source</code> parameter. Connection normally happens implicitly
+   * when the object is sent or received as an argument on a remote method call.
+   * </p>
+   * <p>
+   * The target object is connected to the same ORB as source by calling the
+   * {@link Stub#connect} if it is a stub or by associating its tie with an ORB
+   * if it is an implementation object.
+   * </p>
+   * 
+   * @param target the target object that may be either an RMI/IDL stub or an
+   * exported RMI/IDL implementation object
+   * @param source the source object may also be either an RMI/IDL stub or an
+   * exported RMI/IDL implementation object.
+   * 
+   * @throws RemoteException if the target is already connected to another ORB.
+   */
   void connect(Remote target, Remote source)
     throws RemoteException;
-        
+
+  /**
+   * Register the passed object with the ORB runtimes, making it remotely
+   * accessible. When called on jre with no objects exported, creates a
+   * non-daemon thread that prevents jre from terminating until all objects are
+   * unexported. Also, such object cannot be collected by garbage collector.
+   * This is usually impemented via {@link Util#unexportObject}
+   * 
+   * @param object the object to export.
+   * 
+   * @throws RemoteException
+   */
   void exportObject(Remote obj)
     throws RemoteException;
 
+  /**
+   * Narrows the passed object to conform to the given interface or IDL type.
+   * This method may return different instance and cannot be replaced by the
+   * direct cast.
+   * 
+   * @param narrowFrom an object to narrow.
+   * @param narrowTo a type to that the object must be narrowed.
+   * 
+   * @return On success, an object of type narrowTo or null, if narrowFrom =
+   * null.
+   * 
+   * @throws ClassCastException if no narrowing is possible.
+   */
   Object narrow(Object narrowFrom, Class narrowTo)
     throws ClassCastException;
-        
+
+  /**
+   * Takes a server implementation object and returns a stub object that can be
+   * used to access that server object (target). If the target is connected, the
+   * returned stub is also connected to the same ORB. If the target is
+   * unconnected, the returned stub is unconnected.
+   * 
+   * @param target a server side object.
+   * @return a stub object that can be used to access that server object.
+   * 
+   * @throws NoSuchObjectException if a stub cannot be located for the given
+   * target.
+   */
   Remote toStub(Remote obj)
     throws NoSuchObjectException;
-  
+
+  /**
+   * Deregister a currently exported server object from the ORB runtimes. The
+   * object to becomes available for garbage collection. This is usually
+   * impemented via {@link Util#unexportObject}
+   * 
+   * @param object the object to unexport.
+   * 
+   * @throws NoSuchObjectException if the passed object is not currently
+   * exported.
+   */
   void unexportObject(Remote obj)
     throws NoSuchObjectException;
 }