[cp-patches] FYI: Documenting UnicastRemoteObject

[Audrius Meskauskas]

This patch adds some documentation fo the UnicastRemoteObject

2006-02-19  Audrius Meskauskas  <[EMAIL PROTECTED]>

* java/rmi/server/UnicastRemoteObject.java: Documenting.


Index: UnicastRemoteObject.java
===================================================================
RCS file: /sources/classpath/classpath/java/rmi/server/UnicastRemoteObject.java,v
retrieving revision 1.12
diff -u -r1.12 UnicastRemoteObject.java
--- UnicastRemoteObject.java	13 Feb 2006 17:15:09 -0000	1.12
+++ UnicastRemoteObject.java	19 Feb 2006 13:34:43 -0000
@@ -1,5 +1,6 @@
 /* UnicastRemoteObject.java --
-   Copyright (c) 1996, 1997, 1998, 1999, 2002, 2003 Free Software Foundation, Inc.
+   Copyright (c) 1996, 1997, 1998, 1999, 2002, 2003, 2006 
+   Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -44,22 +45,57 @@
 import java.rmi.Remote;
 import java.rmi.RemoteException;
 
+/**
+ * This class obtains stub that communicates with the remote object. 
+ */
 public class UnicastRemoteObject extends RemoteServer
 {
+  /**
+   * Use SVUID for interoperability.
+   */
   private static final long serialVersionUID = 4974527148936298033L;
 
   //The following serialized fields are from Java API Documentation
   // "Serialized form"
-  private int port = 0;
-  private RMIClientSocketFactory csf = null;
-  private RMIServerSocketFactory ssf = null;
+  
+  /**
+   * The port, on that the created remote object becomes available,
+   * zero meaning the anonymous port.
+   */
+  private int port;
+  
+  /**
+   * The client socket factory for producing client sockets, used by this
+   * object.
+   */
+  private RMIClientSocketFactory csf;
+  
+  /**
+   * The server socket factory for producing server sockets, used by this
+   * object.
+   */
+  private RMIServerSocketFactory ssf;
 
+  /**
+   * Create and export new remote object without specifying the port value.
+   * 
+   * @throws RemoteException if the attempt to export the object failed.
+   */
   protected UnicastRemoteObject()
     throws RemoteException
   {
 	this(0);
   }
-
+  
+  /**
+   * Create and export the new remote object, making it available at the
+   * given port, local host.
+   * 
+   * @param port the port, on that the object should become available.
+   * Zero means anonymous port.
+   * 
+   * @throws RemoteException if the attempt to export the object failed.
+   */
   protected UnicastRemoteObject(int port)
     throws RemoteException
   {
@@ -67,15 +103,28 @@
          RMISocketFactory.getSocketFactory());
   }
 
-  protected UnicastRemoteObject(int port, RMIClientSocketFactory csf,
-                                RMIServerSocketFactory ssf)
+  /**
+   * Create and export the new remote object, making it available at the
+   * given port, using sockets, produced by the specified factories.
+   * 
+   * @param port the port, on that the object should become available.
+   * Zero means anonymous port.
+   * 
+   * @param clientSocketFactory the client socket factory
+   * @param serverSocketFactory the server socket factory
+   * 
+   * @throws RemoteException if the attempt to export the object failed.
+   */
+  protected UnicastRemoteObject(int port, 
+                                RMIClientSocketFactory clientSocketFactory,
+                                RMIServerSocketFactory serverSocketFactory)
     throws RemoteException
   {
     this.port = port;
     //Is RMIXXXSocketFactory serializable
     //this.csf = csf;
     //this.ssf = ssf;
-    this.ref = new UnicastServerRef(new ObjID(), port, ssf);
+    this.ref = new UnicastServerRef(new ObjID(), port, serverSocketFactory);
     exportObject(this);
   }
 
@@ -91,20 +140,51 @@
   {
 	throw new Error("Not implemented");
   }
-
+  
+  /**
+   * Export object, making it available for the remote calls at the 
+   * anonymous port.
+   * 
+   * @param obj the object being exported.
+   * 
+   * @return the remote object stub
+   * 
+   * @throws RemoteException if the attempt to export the object failed.
+   */
   public static RemoteStub exportObject(Remote obj)
     throws RemoteException
   {
 	return (RemoteStub) exportObject(obj, 0);
   }
 
+  /**
+   * Export object, making it available for the remote calls at the 
+   * specified port.
+   * 
+   * @param obj the object being exported.
+   * @param port the remote object port
+   * 
+   * @return the remote object stub
+   * 
+   * @throws RemoteException if the attempt to export the object failed.
+   */
   public static Remote exportObject(Remote obj, int port)
     throws RemoteException
   {
     return exportObject(obj, port, null);
   }
 
-  static Remote exportObject(Remote obj, int port, RMIServerSocketFactory ssf) 
+  /**
+   * Create and export the new remote object, making it available at the
+   * given port, using sockets, produced by the specified factories.
+   * 
+   * @param port the port, on that the object should become available.
+   * Zero means anonymous port.
+   * 
+   * @param serverSocketFactory the server socket factory
+   */ 
+  static Remote exportObject(Remote obj, int port, 
+                             RMIServerSocketFactory serverSocketFactory) 
     throws RemoteException
   {
     UnicastServerRef sref = null;
@@ -112,7 +192,7 @@
       sref = (UnicastServerRef) ((RemoteObject) obj).getRef();
 
     if (sref == null)
-      sref = new UnicastServerRef(new ObjID(), port, ssf);
+      sref = new UnicastServerRef(new ObjID(), port, serverSocketFactory);
 
     Remote stub = sref.exportObject(obj);
     addStub(obj, stub);