2006-03-10 Audrius Meskauskas <AudriusA@Bioinformatics.org>

	* java/rmi/activation/ActivationDesc.java,
	java/rmi/activation/ActivationGroupID.java,
	java/rmi/activation/Activator.java,
	java/rmi/server/Operation.java,
	java/rmi/server/RemoteServer.java: Documented and formatted.

6 files changed, 353 insertions, 120 deletions

diff --git a/ChangeLog b/ChangeLog
index 5c30a77dc..945fc5fc6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2006-03-10  Audrius Meskauskas  <AudriusA@Bioinformatics.org>
+
+	* java/rmi/activation/ActivationDesc.java,
+	java/rmi/activation/ActivationGroupID.java,
+	java/rmi/activation/Activator.java,
+	java/rmi/server/Operation.java,
+	java/rmi/server/RemoteServer.java: Documented and formatted.
+
 2006-03-10  David Gilbert  <david.gilbert@object-refinery.com>
 
 	* javax/swing/JToggleButton.java: Fixed API doc tags,
diff --git a/java/rmi/activation/ActivationDesc.java b/java/rmi/activation/ActivationDesc.java
index 65894f808..07e119bfb 100644
--- a/java/rmi/activation/ActivationDesc.java
+++ b/java/rmi/activation/ActivationDesc.java
@@ -1,6 +1,6 @@
 /* ActivationDecc.java --
    Copyright (c) 1996, 1997, 1998, 1999 Free Software Foundation, Inc.
-
+   
 This file is part of GNU Classpath.
 
 GNU Classpath is free software; you can redistribute it and/or modify
@@ -40,74 +40,193 @@ package java.rmi.activation;
 import java.io.Serializable;
 import java.rmi.MarshalledObject;
 
-public final class ActivationDesc implements Serializable
+/**
+ * Contains the information, necessary to activate the object. This information
+ * includes:
+ * <ul>
+ * <li>the object class name</li>
+ * <li>the object group identifier</li>
+ * <li>the code location (codebase URL) that can be used to load the class
+ * remotely</li>
+ * <li>the object restart mode</li>
+ * <li>the object specific intialization information</li>
+ * </ul>
+ */
+public final class ActivationDesc
+    implements Serializable
 {
+  /**
+   * Use SVUID for interoperability.
+   */
   static final long serialVersionUID = 7455834104417690957L;
 
-private ActivationGroupID groupid;
-private String classname;
-private String location;
-private MarshalledObject data;
-private boolean restart;
-
-public ActivationDesc(String className, String location, MarshalledObject data) throws ActivationException {
-	this(ActivationGroup.currentGroupID(), className, location, data, false);
-}
-
-public ActivationDesc(String className, String location, MarshalledObject data, boolean restart) throws ActivationException {
-	this(ActivationGroup.currentGroupID(), className, location, data, restart);
-}
-
-public ActivationDesc(ActivationGroupID groupID, String className, String location, MarshalledObject data) {
-	this(groupID, className, location, data, false);
-}
-
-public ActivationDesc(ActivationGroupID groupID, String className, String location, MarshalledObject data, boolean restart) {
-	this.groupid = groupID;
-	this.classname = className;
-	this.location = location;
-	this.data = data;
-	this.restart = restart;
-}
-
-public ActivationGroupID getGroupID() {
-	return (groupid);
-}
-
-public String getClassName() {
-	return (classname);
-}
-
-public String getLocation() {
-	return (location);
-}
-
-public MarshalledObject getData() {
-	return (data);
-}
-
-public boolean getRestartMode() {
-	return (restart);
-}
-
-public boolean equals(Object obj) {
-	if (!(obj instanceof ActivationDesc)) {
-		return (false);
-	}
-	ActivationDesc that = (ActivationDesc)obj;
-
-	if (this.groupid.equals(that.groupid) &&
-	    this.classname.equals(that.classname) &&
-	    this.location.equals(that.location) &&
-	    this.data.equals(that.data) &&
-	    this.restart == that.restart) {
-		return (true);
-	}
-	return (false);
-}
-
-public int hashCode() {
-	return (groupid.hashCode() ^ classname.hashCode() ^ location.hashCode() ^ data.hashCode());
-}
-
+  /**
+   * The group id.
+   */
+  private ActivationGroupID groupid;
+
+  /**
+   * The class name.
+   */
+  private String classname;
+
+  /**
+   * The code location URL.
+   */
+  private String location;
+
+  /**
+   * The object specific intitalization data.
+   */
+  private MarshalledObject data;
+
+  /**
+   * The start mode.
+   */
+  private boolean restart;
+
+  /**
+   * Create the new activation description, assuming the object group is the
+   * {@link ActivationGroup#currentGroupID()}. 
+   * 
+   * @param className the object fully qualified class name
+   * @param location the code base URL
+   * @param data the object initialization data, contained in a marshalled form
+   */
+  public ActivationDesc(String className, String location, MarshalledObject data)
+      throws ActivationException
+  {
+    this(ActivationGroup.currentGroupID(), className, location, data, false);
+  }
+
+  /**
+   * Create the new activation description, assuming the object group is the
+   * {@link ActivationGroup#currentGroupID()}. 
+   * 
+   * @param className the object fully qualified class name
+   * @param location the code base URL
+   * @param data the object initialization data, contained in a marshalled form
+   * @param restart specifies reactivation mode after crash. If true, the object
+   *          is activated when activator is restarted or the activation group
+   *          is restarted. If false, the object is only activated on demand.
+   *          This flag does has no effect during the normal operation (the
+   *          object is normally activated on demand).
+   */
+  public ActivationDesc(String className, String location,
+                        MarshalledObject data, boolean restart)
+      throws ActivationException
+  {
+    this(ActivationGroup.currentGroupID(), className, location, data, restart);
+  }
+
+  /**
+   * Create the new activation description. Under crash, the object will only
+   * be reactivated on demand.
+   * 
+   * @param groupID the object group id.
+   * @param className the object fully qualified class name
+   * @param location the code base URL
+   * @param data the object initialization data, contained in a marshalled form
+   */
+  public ActivationDesc(ActivationGroupID groupID, String className,
+                        String location, MarshalledObject data)
+  {
+    this(groupID, className, location, data, false);
+  }
+
+  /**
+   * Create the new activation description, providing full information.
+   * 
+   * @param groupID the object group id.
+   * @param className the object fully qualified class name
+   * @param location the code base URL
+   * @param data the object initialization data, contained in a marshalled form
+   * @param restart specifies reactivation mode after crash. If true, the object
+   *          is activated when activator is restarted or the activation group
+   *          is restarted. If false, the object is only activated on demand.
+   *          This flag does has no effect during the normal operation (the
+   *          object is normally activated on demand).
+   */
+  public ActivationDesc(ActivationGroupID groupID, String className,
+                        String location, MarshalledObject data, boolean restart)
+  {
+    this.groupid = groupID;
+    this.classname = className;
+    this.location = location;
+    this.data = data;
+    this.restart = restart;
+  }
+
+  public ActivationGroupID getGroupID()
+  {
+    return groupid;
+  }
+
+  /**
+   * Get the class name of the object being activated
+   * 
+   * @return the fully qualified class name of the object being activated
+   */
+  public String getClassName()
+  {
+    return classname;
+  }
+
+  /**
+   * Get the code location URL ("codebase") of the object being activated.
+   * 
+   * @return the codebase of the object being activated.
+   */
+  public String getLocation()
+  {
+    return location;
+  }
+
+  public MarshalledObject getData()
+  {
+    return data;
+  }
+
+  /**
+   * Get the object reactivation strategy after crash.
+   * 
+   * @return true ir the object is activated when activator is restarted or the
+   *         activation group is restarted. False if the object is only
+   *         activated on demand. This flag does has no effect during the normal
+   *         operation (the object is normally activated on demand).
+   */
+  public boolean getRestartMode()
+  {
+    return restart;
+  }
+  
+  /**
+   * Compare this object with another activation description for equality.
+   * 
+   * @return true if all fields have the equal values, false otherwise.
+   */
+  public boolean equals(Object obj)
+  {
+    if (obj instanceof ActivationDesc)
+      {
+        ActivationDesc that = (ActivationDesc) obj;
+        return groupid.equals(that.groupid) &&
+               classname.equals(that.classname) && 
+               location.equals(that.location) && 
+               data.equals(that.data)
+               && restart == that.restart;
+      }
+    else
+      return false;
+  }
+  
+  /**
+   * Get the hash code of this object (overridden to make the returned value
+   * consistent with .equals(..).
+   */
+  public int hashCode()
+  {
+    return groupid.hashCode() ^ classname.hashCode() ^ 
+      location.hashCode() ^ data.hashCode();
+  }
 }
diff --git a/java/rmi/activation/ActivationGroupID.java b/java/rmi/activation/ActivationGroupID.java
index 5e0b96442..941499aa8 100644
--- a/java/rmi/activation/ActivationGroupID.java
+++ b/java/rmi/activation/ActivationGroupID.java
@@ -1,5 +1,5 @@
 /* ActivationGroupID.java --
-   Copyright (c) 1996, 1997, 1998, 1999 Free Software Foundation, Inc.
+   Copyright (c) 1996, 1997, 1998, 1999, 2006 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -35,36 +35,73 @@ 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 java.rmi.activation;
 
 import java.io.Serializable;
 
-public class ActivationGroupID implements Serializable
+/**
+ * This identifier identifies the activation group inside the scope of its
+ * activation system. It also contains (and can provide) the reference to the
+ * groups activation system.
+ * 
+ * @see ActivationSystem#registerGroup(ActivationGroupDesc)
+ */
+public class ActivationGroupID
+    implements Serializable
 {
-  static final long serialVersionUID = -1648432278909740833L;
+  /**
+   * Use SVUID for interoperability.
+   */
+  static final long serialVersionUID = - 1648432278909740833L;
 
-private ActivationSystem system;
+  /**
+   * The associated activation system.
+   */
+  private ActivationSystem system;
 
-public ActivationGroupID(ActivationSystem system) {
-	this.system = system;
-}
+  /**
+   * Create the new activation group id in the scope of the given activation
+   * system
+   * 
+   * @param system the activation system
+   */
+  public ActivationGroupID(ActivationSystem system)
+  {
+    this.system = system;
+  }
 
-public ActivationSystem getSystem() {
-	return (system);
-}
+  /**
+   * Get the associated activation system
+   * 
+   * @return the associated activation system
+   */
+  public ActivationSystem getSystem()
+  {
+    return system;
+  }
 
-public int hashCode() {
-	return (system.hashCode());
-}
+  /**
+   * Get the hash code of the associated activation system.
+   */
+  public int hashCode()
+  {
+    return system.hashCode();
+  }
 
-public boolean equals(Object obj) {
-	if (obj instanceof ActivationGroupID) {
-		ActivationGroupID that = (ActivationGroupID)obj;
-		if (this.system.equals(that.system)) {
-			return (true);
-		}
-	}
-	return (false);
-}
+  /**
+   * Copmare for equality, returns true if the passed object is also the
+   * activation group id and its activation system is the same.
+   */
+  public boolean equals(Object obj)
+  {
+    if (obj instanceof ActivationGroupID)
+      {
+        ActivationGroupID that = (ActivationGroupID) obj;
+        return system.equals(that.system);
+      }
+    else
+      return false;
+  }
 
 }
diff --git a/java/rmi/activation/Activator.java b/java/rmi/activation/Activator.java
index 2fb5a5810..4da6dfd5d 100644
--- a/java/rmi/activation/Activator.java
+++ b/java/rmi/activation/Activator.java
@@ -42,9 +42,31 @@ import java.rmi.MarshalledObject;
 import java.rmi.Remote;
 import java.rmi.RemoteException;
 
+/**
+ * Activates remote object, providing the live reference to the activable remote
+ * object.  
+ *
+ * @see ActivationSystem
+ * @see ActivationMonitor
+ */
 public interface Activator
   extends Remote
 {
+  /**
+   * Activate the object, associated with the given activation identifier. The
+   * activator looks for the {@link ActivationDesc}riptor for the passed
+   * identifier, determines the object activation group and initiates object
+   * recreation either via {@link ActivationInstantiator} or via
+   * {@link Class#newInstance()}.
+   * 
+   * @param id the identifier of the object to activate.
+   * @param force if true, the activator always contacts the group to obtain the
+   *          reference. If false, it may return the cached value.
+   * @return the activated remote object (its stub).
+   * @throws UnknownObjectException if the object with this id is unknown
+   * @throws ActivationException if the activation has failed due other reason
+   * @throws RemoteException if the remote call has failed.
+   */
   MarshalledObject activate (ActivationID id, boolean force)
     throws ActivationException, UnknownObjectException, RemoteException;
 }
diff --git a/java/rmi/server/Operation.java b/java/rmi/server/Operation.java
index 64faf66e2..f7b5f02cc 100644
--- a/java/rmi/server/Operation.java
+++ b/java/rmi/server/Operation.java
@@ -38,6 +38,9 @@ exception statement from your version. */
 package java.rmi.server;
 
 /**
+ * This class was used with jdk 1.1 stubs and skeletons. It is no longer
+ * needed since jdk 1.2 and higher.
+ *  
  * @deprecated
  */
 public class Operation
@@ -45,6 +48,7 @@ public class Operation
   private String operation;
 
   /**
+   * Create operation with the given name.
    * @deprecated
    */
   public Operation (String op)
@@ -53,6 +57,8 @@ public class Operation
   }
 
   /**
+   * Get the name of the operation.
+   * 
    * @deprecated
    */
   public String getOperation ()
@@ -61,6 +67,8 @@ public class Operation
   }
 
   /**
+   * Return the name of the operation.
+   * 
    * @deprecated
    */
   public String toString ()
diff --git a/java/rmi/server/RemoteServer.java b/java/rmi/server/RemoteServer.java
index 9efb12a78..f022b7326 100644
--- a/java/rmi/server/RemoteServer.java
+++ b/java/rmi/server/RemoteServer.java
@@ -1,5 +1,6 @@
 /* RemoteServer.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.
 
@@ -35,6 +36,7 @@ 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 java.rmi.server;
 
 import gnu.java.rmi.server.RMIIncomingThread;
@@ -42,35 +44,72 @@ import gnu.java.rmi.server.RMIIncomingThread;
 import java.io.OutputStream;
 import java.io.PrintStream;
 
-public abstract class RemoteServer extends RemoteObject
+/**
+ * A common superclass for the server implementations.
+ */
+public abstract class RemoteServer
+    extends RemoteObject
 {
-private static final long serialVersionUID = -4100238210092549637L;
-
-protected RemoteServer() {
-	super();
-}
-
-protected RemoteServer(RemoteRef ref) {
-	super(ref);
-}
-
-public static String getClientHost() throws ServerNotActiveException {
-	Thread currThread = Thread.currentThread();
-	if (currThread instanceof RMIIncomingThread) {
-		RMIIncomingThread incomingThread = (RMIIncomingThread) currThread;
-		return incomingThread.getClientHost();
-	} else {
-		throw new ServerNotActiveException(
-			"Unknown client host - current thread not instance of 'RMIIncomingThread'");
-	}
-}
-
-public static void setLog(OutputStream out) {
-	throw new Error("Not implemented");
-}
-
-public static PrintStream getLog() {
-	throw new Error("Not implemented");
-}
+  private static final long serialVersionUID = - 4100238210092549637L;
+  
+  /**
+   * Does nothing, delegates to super().
+   */
+  protected RemoteServer()
+  {
+    super();
+  }
+  
+  /**
+   * Does nothing, delegates to super(ref).
+   */
+  protected RemoteServer(RemoteRef ref)
+  {
+    super(ref);
+  }
+  
+  /**
+   * Get the host of the calling client. The current thread must be an instance
+   * of the {@link RMIIncomingThread}.
+   * 
+   * @return the client host address
+   * 
+   * @throws ServerNotActiveException if the current thread is not an instance
+   * of the RMIIncomingThread.
+   */
+  public static String getClientHost() throws ServerNotActiveException
+  {
+    Thread currThread = Thread.currentThread();
+    if (currThread instanceof RMIIncomingThread)
+      {
+        RMIIncomingThread incomingThread = (RMIIncomingThread) currThread;
+        return incomingThread.getClientHost();
+      }
+    else
+      {
+        throw new ServerNotActiveException(
+          "Unknown client host - current thread not instance of 'RMIIncomingThread'");
+      }
+  }
+  
+  /**
+   * Set the stream for logging RMI calls.
+   * 
+   * @param out the stream to set or null to turn the logging off.
+   */
+  public static void setLog(OutputStream out)
+  {
+    throw new Error("Not implemented");
+  }
+  
+  /**
+   * Get the stream for logging RMI calls.
+   * 
+   * @return the associated stream.
+   */
+  public static PrintStream getLog()
+  {
+    throw new Error("Not implemented");
+  }
 
 }