Hi,
I had some javadoc fixes in my local tree and expanded them today
to cover the whole package.
2006-02-12 Wolfgang Baer <[EMAIL PROTECTED]>
* java/rmi/MarshalledObject.java: Added api docs to the class.
* java/rmi/Remote.java: Added interface api docs.
* java/rmi/package.html: Added package description.
* java/rmi/AccessException.java: Minor api doc fixes.
* java/rmi/NoSuchObjectException.java: Likewise.
* java/rmi/AlreadyBoundException.java: Likewise.
* java/rmi/RemoteException.java: Likewise.
* java/rmi/NotBoundException.java: Likewise.
* java/rmi/RMISecurityException.java: Likewise.
* java/rmi/StubNotFoundException.java: Likewise.
Wolfgang
Index: java/rmi/AccessException.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/rmi/AccessException.java,v
retrieving revision 1.4
diff -u -r1.4 AccessException.java
--- java/rmi/AccessException.java 2 Jul 2005 20:32:40 -0000 1.4
+++ java/rmi/AccessException.java 12 Feb 2006 12:23:08 -0000
@@ -1,5 +1,6 @@
/* AccessException.java -- thrown if the caller does not have access
- Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+ Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006
+ Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -43,7 +44,7 @@
*
* @author unknown
* @see Naming
- * @see ActivationSystem
+ * @see java.rmi.activation.ActivationSystem
* @since 1.1
*/
public class AccessException extends RemoteException
Index: java/rmi/AlreadyBoundException.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/rmi/AlreadyBoundException.java,v
retrieving revision 1.4
diff -u -r1.4 AlreadyBoundException.java
--- java/rmi/AlreadyBoundException.java 2 Jul 2005 20:32:40 -0000 1.4
+++ java/rmi/AlreadyBoundException.java 12 Feb 2006 12:23:08 -0000
@@ -1,5 +1,6 @@
/* AlreadyBoundException.java -- thrown if a binding is already bound
- Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+ Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006
+ Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -42,8 +43,8 @@
* bound.
*
* @author unknown
- * @see Naming#bind(String, Remote)
- * @see Registry#bind(String, Remote)
+ * @see java.rmi.Naming#bind(String, Remote)
+ * @see java.rmi.registry.Registry#bind(String, Remote)
* @since 1.1
* @status updated to 1.4
*/
Index: java/rmi/NoSuchObjectException.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/rmi/NoSuchObjectException.java,v
retrieving revision 1.4
diff -u -r1.4 NoSuchObjectException.java
--- java/rmi/NoSuchObjectException.java 2 Jul 2005 20:32:40 -0000 1.4
+++ java/rmi/NoSuchObjectException.java 12 Feb 2006 12:23:08 -0000
@@ -1,5 +1,6 @@
/* NoSuchObjectException.java -- thrown if the remote object no longer exists
- Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+ Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006
+ Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -43,9 +44,9 @@
* obey the semantics of "at most once".
*
* @author unknown
- * @see RemoteObject#toStub(Remote)
- * @see UnicastRemoteObject#unexportObject(Remote, boolean)
- * @see Activatable#unexportObject(Remote, boolean)
+ * @see java.rmi.server.RemoteObject#toStub(Remote)
+ * @see java.rmi.server.UnicastRemoteObject#unexportObject(Remote, boolean)
+ * @see java.rmi.activation.Activatable#unexportObject(Remote, boolean)
* @since 1.1
* @status updated to 1.4
*/
Index: java/rmi/NotBoundException.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/rmi/NotBoundException.java,v
retrieving revision 1.4
diff -u -r1.4 NotBoundException.java
--- java/rmi/NotBoundException.java 2 Jul 2005 20:32:40 -0000 1.4
+++ java/rmi/NotBoundException.java 12 Feb 2006 12:23:08 -0000
@@ -1,5 +1,6 @@
/* NotBoundException.java -- attempt to use a registry name with no binding
- Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+ Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006
+ Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -42,10 +43,10 @@
* associated binding.
*
* @author unknown
- * @see Naming#lookup(String)
- * @see Naming#unbind(String)
- * @see Registry#lookup(String)
- * @see Registry#unbind(String)
+ * @see java.rmi.Naming#lookup(String)
+ * @see java.rmi.Naming#unbind(String)
+ * @see java.rmi.registry.Registry#lookup(String)
+ * @see java.rmi.registry.Registry#unbind(String)
* @since 1.1
* @status updated to 1.4
*/
Index: java/rmi/RemoteException.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/rmi/RemoteException.java,v
retrieving revision 1.5
diff -u -r1.5 RemoteException.java
--- java/rmi/RemoteException.java 2 Jul 2005 20:32:40 -0000 1.5
+++ java/rmi/RemoteException.java 12 Feb 2006 12:23:08 -0000
@@ -1,5 +1,6 @@
/* RemoteException.java -- common superclass for exceptions in java.rmi
- Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+ Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006
+ Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -86,7 +87,7 @@
* Create an exception with the given message and cause.
*
* @param s the message
- * @param ex the cause
+ * @param e the cause
*/
public RemoteException(String s, Throwable e)
{
Index: java/rmi/RMISecurityException.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/rmi/RMISecurityException.java,v
retrieving revision 1.4
diff -u -r1.4 RMISecurityException.java
--- java/rmi/RMISecurityException.java 2 Jul 2005 20:32:40 -0000 1.4
+++ java/rmi/RMISecurityException.java 12 Feb 2006 12:23:08 -0000
@@ -1,5 +1,6 @@
/* RMISecurityException.java -- deprecated version of SecurityException
- Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+ Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006
+ Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -38,11 +39,12 @@
package java.rmi;
/**
- * Never thrown, but originally intended to wrap a java.lang.SecurityException.
+ * Never thrown, but originally intended to wrap a
+ * [EMAIL PROTECTED] java.lang.SecurityException} in the case of RMI.
*
* @author unknown
* @since 1.1
- * @deprecated use [EMAIL PROTECTED] SecurityException} instead
+ * @deprecated use [EMAIL PROTECTED] java.lang.SecurityException} instead
* @status updated to 1.4
*/
public class RMISecurityException extends SecurityException
@@ -55,7 +57,7 @@
/**
* Create an exception with a message.
*
- * @param s the message
+ * @param n the message
* @deprecated no longer needed
*/
public RMISecurityException(String n)
@@ -66,8 +68,8 @@
/**
* Create an exception with a message and a cause.
*
- * @param s the message
- * @param e the cause
+ * @param n the message
+ * @param a the cause (ignored)
* @deprecated no longer needed
*/
public RMISecurityException(String n, String a)
Index: java/rmi/StubNotFoundException.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/rmi/StubNotFoundException.java,v
retrieving revision 1.4
diff -u -r1.4 StubNotFoundException.java
--- java/rmi/StubNotFoundException.java 2 Jul 2005 20:32:40 -0000 1.4
+++ java/rmi/StubNotFoundException.java 12 Feb 2006 12:23:08 -0000
@@ -1,5 +1,6 @@
/* StubNotFoundException.java -- thrown if a valid stub is not found
- Copyright (c) 1996, 1997, 1998, 1999, 2002 Free Software Foundation, Inc.
+ Copyright (c) 1996, 1997, 1998, 1999, 2002, 2006
+ Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -41,8 +42,8 @@
* Thrown if a valid stub class is not found for an object when it is exported.
*
* @author unknown
- * @see UnicastRemoteObject
- * @see Activatable
+ * @see java.rmi.server.UnicastRemoteObject
+ * @see java.rmi.activation.Activatable
* @since 1.1
* @status updated to 1.4
*/
Index: java/rmi/Remote.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/rmi/Remote.java,v
retrieving revision 1.4
diff -u -r1.4 Remote.java
--- java/rmi/Remote.java 2 Jul 2005 20:32:40 -0000 1.4
+++ java/rmi/Remote.java 12 Feb 2006 12:23:08 -0000
@@ -1,5 +1,5 @@
/* Remote.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.
@@ -37,5 +37,22 @@
package java.rmi;
+/**
+ * Marker interface for interfaces which methods are invokable
+ * from outside of this virtual machine through remote method calls.
+ * <p>
+ * Remote invokable methods of remote object implementations are specified
+ * as the methods defined in the implemented remote interfaces. Typically
+ * remote object implementations are subclasses of the convenience classes
+ * [EMAIL PROTECTED] java.rmi.server.UnicastRemoteObject} or
+ * [EMAIL PROTECTED] java.rmi.activation.Activatable} implementing one or more remote
+ * interfaces indicating their remotely accessible methods. The convenience
+ * classes provide implementations for correct remote object creation,
+ * hash, equals and toString methods.
+ * </p>
+ *
+ * @author unknown
+ */
public interface Remote {
+ // marker interface
}
Index: java/rmi/MarshalledObject.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/rmi/MarshalledObject.java,v
retrieving revision 1.10
diff -u -r1.10 MarshalledObject.java
--- java/rmi/MarshalledObject.java 12 Feb 2006 11:36:48 -0000 1.10
+++ java/rmi/MarshalledObject.java 12 Feb 2006 12:23:08 -0000
@@ -47,7 +47,16 @@
import java.io.Serializable;
/**
- * FIXME - doc missing
+ * A <code>MarshalledObject</code> consists of a serialized object which is
+ * marshalled according to the RMI specification.
+ * <p>
+ * An object passed to the constructor is serialized and tagged with the needed
+ * URL to retrieve its class definition for remote usage. If the object is a
+ * remote reference its stub is serialized instead. The instance of this
+ * marshalled object can be later retrieved by its <code>get()</code> method.
+ * </p>
+ *
+ * @author unknown
*/
public final class MarshalledObject
implements Serializable
@@ -59,7 +68,13 @@
byte[] locBytes;
int hash;
- public MarshalledObject(Object obj) throws java.io.IOException
+ /**
+ * Constructs a <code>MarshalledObject</code> from the given object.
+ *
+ * @param obj the object to marshal
+ * @throws IOException if an I/O error during serialization occurs.
+ */
+ public MarshalledObject(Object obj) throws IOException
{
ByteArrayOutputStream objStream = new ByteArrayOutputStream();
RMIMarshalledObjectOutputStream stream =
@@ -79,6 +94,16 @@
hash = hash * 31 + locBytes[i];
}
+ /**
+ * Checks if the given object is equal to this marshalled object.
+ *
+ * <p>Marshalled objects are considered equal if they contain the
+ * same serialized object. Codebase annotations where the class
+ * definition can be downloaded are ignored in the equals test.</p>
+ *
+ * @param obj the object to compare.
+ * @return <code>true</code> if equal, <code>false</code> otherwise.
+ */
public boolean equals(Object obj)
{
if (! (obj instanceof MarshalledObject))
@@ -102,6 +127,15 @@
return true;
}
+ /**
+ * Constructs and returns a copy of the internal serialized object.
+ *
+ * @return The deserialized object.
+ *
+ * @throws IOException if an I/O exception occurs during deserialization.
+ * @throws ClassNotFoundException if the class of the deserialized object
+ * cannot be found.
+ */
public Object get() throws IOException, ClassNotFoundException
{
if (objBytes == null)
Index: java/rmi/package.html
===================================================================
RCS file: /cvsroot/classpath/classpath/java/rmi/package.html,v
retrieving revision 1.2
diff -u -r1.2 package.html
--- java/rmi/package.html 2 Jul 2005 20:32:40 -0000 1.2
+++ java/rmi/package.html 12 Feb 2006 12:23:08 -0000
@@ -40,7 +40,7 @@
<head><title>GNU Classpath - java.rmi</title></head>
<body>
-<p></p>
+<p>Provides basic Remote Method Invocation (RMI) interfaces, classes and exceptions.</p>
</body>
</html>
