1 files changed, 59 insertions, 5 deletions
diff --git a/libjava/classpath/java/rmi/server/RemoteRef.java b/libjava/classpath/java/rmi/server/RemoteRef.java
index f33f9d374c3..8bdb6633040 100644
--- a/libjava/classpath/java/rmi/server/RemoteRef.java
+++ b/libjava/classpath/java/rmi/server/RemoteRef.java
@@ -1,5 +1,6 @@
 /* RemoteRef.java --
-   Copyright (c) 1996, 1997, 1998, 1999, 2004  Free Software Foundation, Inc.
+   Copyright (c) 1996, 1997, 1998, 1999, 2004, 2006  
+   Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -44,8 +45,16 @@ import java.lang.reflect.Method;
 import java.rmi.Remote;
 import java.rmi.RemoteException;
 
+/**
+ * Represents a handler to the remote object. Each instance of the
+ * {@link RemoteStub} contains such handler and uses it to invoke remote
+ * methods via {@link #invoke(Remote, Method, Object[], long)}.
+ */
 public interface RemoteRef extends Externalizable
 {
+  /**
+   *  Indicates compatibility with JDK 1.1.*
+   */
   long serialVersionUID = 3632638527362204081L;
   
   /**
@@ -55,29 +64,74 @@ public interface RemoteRef extends Externalizable
   String packagePrefix = "sun.rmi.server";
 
   /**
-   * @deprecated
+   * @deprecated use {@link #invoke(Remote, Method, Object[], long)} instead.
    */
   void invoke (RemoteCall call) throws Exception;
   
-  Object invoke (Remote obj, Method method, Object[] params, long opnum)
+  /**
+   * Invoke a method. This method either returns the result of remote invocation
+   * or throws RemoteException if the remote call failed. Other exceptions may
+   * be thrown if some problem has occured in the application level.
+   * 
+   * @param obj the object, containing the remote reference (for instance,
+   *          remote stub, generated by rmic).
+   * @param method the method to invoke
+   * @param params the method parameters
+   * @param methodHash a persistent hash code that can be used to represent a
+   *          method
+   * @return the result of the remote invocation
+   * @throws RemoteException if the remote call has failed
+   * @throws Exception if one is raised at the application level
+   */
+  Object invoke (Remote obj, Method method, Object[] params, long methodHash)
     throws Exception;
   
   /**
-   * @deprecated
+   * @deprecated use {@link #invoke(Remote, Method, Object[], long)} instead.
    */
   RemoteCall newCall (RemoteObject obj, Operation[] op, int opnum, long hash)
     throws RemoteException;
 
   /**
-   * @deprecated
+   * @deprecated use {@link #invoke(Remote, Method, Object[], long)} instead.
    */
   void done (RemoteCall call) throws RemoteException;
   
+  /**
+   * Compare two remote objects for equality. The references are equal if
+   * they point to the same remote object.
+   * 
+   * @param ref the reference to compare.
+   * 
+   * @return true if this and passed references both point to the same remote
+   * object, false otherwise.
+   */
   boolean remoteEquals (RemoteRef ref);
   
+  /**
+   * Get the hashcode for a remote object. Two remote object stubs, referring
+   * to the same remote object, have the same hash code.
+   * 
+   * @return the hashcode of the remote object
+   */
   int remoteHashCode();
   
+  
+  /**
+   * Returns the class name of the reference type that must be written to the
+   * given stream. When writing, this returned name is passed first, and
+   * the reference.writeExternal(out) writes the reference specific data.
+   * 
+   * @param out the stream, where the data must be written 
+   * 
+   * @return the class name. 
+   */
   String getRefClass (ObjectOutput out);
   
+  /**
+   * Get the string representation of this remote reference.
+   * 
+   * @return the string representation.
+   */
   String remoteToString();
 }