GERONIMO-4120 Sun API specification information appears directly in some of the javamail classes.
git-svn-id: https://svn.apache.org/repos/asf/geronimo/javamail/trunk@668614 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/geronimo-javamail_1.4/geronimo-javamail_1.4_provider/src/main/java/org/apache/geronimo/javamail/store/imap/ACL.java b/geronimo-javamail_1.4/geronimo-javamail_1.4_provider/src/main/java/org/apache/geronimo/javamail/store/imap/ACL.java
index 382ef48..ba9a179 100644
--- a/geronimo-javamail_1.4/geronimo-javamail_1.4_provider/src/main/java/org/apache/geronimo/javamail/store/imap/ACL.java
+++ b/geronimo-javamail_1.4/geronimo-javamail_1.4_provider/src/main/java/org/apache/geronimo/javamail/store/imap/ACL.java
@@ -80,65 +80,12 @@
}
-
/**
- * Creates and returns a copy of this object. The precise meaning
- * of "copy" may depend on the class of the object. The general
- * intent is that, for any object <tt>x</tt>, the expression:
- * <blockquote>
- * <pre>
- * x.clone() != x</pre></blockquote>
- * will be true, and that the expression:
- * <blockquote>
- * <pre>
- * x.clone().getClass() == x.getClass()</pre></blockquote>
- * will be <tt>true</tt>, but these are not absolute requirements.
- * While it is typically the case that:
- * <blockquote>
- * <pre>
- * x.clone().equals(x)</pre></blockquote>
- * will be <tt>true</tt>, this is not an absolute requirement.
- * <p>
- * By convention, the returned object should be obtained by calling
- * <tt>super.clone</tt>. If a class and all of its superclasses (except
- * <tt>Object</tt>) obey this convention, it will be the case that
- * <tt>x.clone().getClass() == x.getClass()</tt>.
- * <p>
- * By convention, the object returned by this method should be independent
- * of this object (which is being cloned). To achieve this independence,
- * it may be necessary to modify one or more fields of the object returned
- * by <tt>super.clone</tt> before returning it. Typically, this means
- * copying any mutable objects that comprise the internal "deep structure"
- * of the object being cloned and replacing the references to these
- * objects with references to the copies. If a class contains only
- * primitive fields or references to immutable objects, then it is usually
- * the case that no fields in the object returned by <tt>super.clone</tt>
- * need to be modified.
- * <p>
- * The method <tt>clone</tt> for class <tt>Object</tt> performs a
- * specific cloning operation. First, if the class of this object does
- * not implement the interface <tt>Cloneable</tt>, then a
- * <tt>CloneNotSupportedException</tt> is thrown. Note that all arrays
- * are considered to implement the interface <tt>Cloneable</tt>.
- * Otherwise, this method creates a new instance of the class of this
- * object and initializes all its fields with exactly the contents of
- * the corresponding fields of this object, as if by assignment; the
- * contents of the fields are not themselves cloned. Thus, this method
- * performs a "shallow copy" of this object, not a "deep copy" operation.
- * <p>
- * The class <tt>Object</tt> does not itself implement the interface
- * <tt>Cloneable</tt>, so calling the <tt>clone</tt> method on an object
- * whose class is <tt>Object</tt> will result in throwing an
- * exception at run time.
+ * Creates and returns a copy of this object.
*
- * @return a clone of this instance.
+ * @return A cloned copy of this object. This is a deep
+ * copy, given that a new Rights set is also created.
* @exception CloneNotSupportedException
- * if the object's class does not
- * support the <code>Cloneable</code> interface. Subclasses
- * that override the <code>clone</code> method can also
- * throw this exception to indicate that an instance cannot
- * be cloned.
- * @see java.lang.Cloneable
*/
protected Object clone() throws CloneNotSupportedException {
return new ACL(name, new Rights(rights));
diff --git a/geronimo-javamail_1.4/geronimo-javamail_1.4_provider/src/main/java/org/apache/geronimo/javamail/store/imap/Rights.java b/geronimo-javamail_1.4/geronimo-javamail_1.4_provider/src/main/java/org/apache/geronimo/javamail/store/imap/Rights.java
index 5445020..c08ef0f 100644
--- a/geronimo-javamail_1.4/geronimo-javamail_1.4_provider/src/main/java/org/apache/geronimo/javamail/store/imap/Rights.java
+++ b/geronimo-javamail_1.4/geronimo-javamail_1.4_provider/src/main/java/org/apache/geronimo/javamail/store/imap/Rights.java
@@ -284,36 +284,14 @@
class RightComparator implements Comparator {
/**
- * Compares its two arguments for order. Returns a negative integer,
- * zero, or a positive integer as the first argument is less than, equal
- * to, or greater than the second.<p>
- *
- * The implementor must ensure that <tt>sgn(compare(x, y)) ==
- * -sgn(compare(y, x))</tt> for all <tt>x</tt> and <tt>y</tt>. (This
- * implies that <tt>compare(x, y)</tt> must throw an exception if and only
- * if <tt>compare(y, x)</tt> throws an exception.)<p>
- *
- * The implementor must also ensure that the relation is transitive:
- * <tt>((compare(x, y)>0) && (compare(y, z)>0))</tt> implies
- * <tt>compare(x, z)>0</tt>.<p>
- *
- * Finally, the implementer must ensure that <tt>compare(x, y)==0</tt>
- * implies that <tt>sgn(compare(x, z))==sgn(compare(y, z))</tt> for all
- * <tt>z</tt>.<p>
- *
- * It is generally the case, but <i>not</i> strictly required that
- * <tt>(compare(x, y)==0) == (x.equals(y))</tt>. Generally speaking,
- * any comparator that violates this condition should clearly indicate
- * this fact. The recommended language is "Note: this comparator
- * imposes orderings that are inconsistent with equals."
- *
- * @param o1 the first object to be compared.
- * @param o2 the second object to be compared.
- * @return a negative integer, zero, or a positive integer as the
- * first argument is less than, equal to, or greater than the
- * second.
- * @throws ClassCastException if the arguments' types prevent them from
- * being compared by this Comparator.
+ * Perform a sort comparison to order two Right objects.
+ * The sort is performed using the string value.
+ *
+ * @param o1 The left comparator
+ * @param o2 The right comparator.
+ *
+ * @return 0 if the two items have equal ordering, -1 if the
+ * left item is lower, 1 if the left item is greater.
*/
public int compare(Object o1, Object o2) {
// compare on the string value
diff --git a/geronimo-javamail_1.4/geronimo-javamail_1.4_provider/src/main/java/org/apache/geronimo/javamail/util/TraceInputStream.java b/geronimo-javamail_1.4/geronimo-javamail_1.4_provider/src/main/java/org/apache/geronimo/javamail/util/TraceInputStream.java
index 39ee6dd..05ef8c0 100644
--- a/geronimo-javamail_1.4/geronimo-javamail_1.4_provider/src/main/java/org/apache/geronimo/javamail/util/TraceInputStream.java
+++ b/geronimo-javamail_1.4/geronimo-javamail_1.4_provider/src/main/java/org/apache/geronimo/javamail/util/TraceInputStream.java
@@ -67,24 +67,15 @@
}
/**
- * Reads up to <code>len</code> bytes of data from this input stream into
- * an array of bytes. This method blocks until some input is available.
- * <p>
- * This method simply performs <code>in.read(b, off, len)</code> and
- * returns the result.
+ * Reads up to len bytes of data from this input stream, placing them directly
+ * into the provided byte array.
*
- * @param b
- * the buffer into which the data is read.
- * @param off
- * the start offset of the data.
- * @param len
- * the maximum number of bytes read.
- * @return the total number of bytes read into the buffer, or
- * <code>-1</code> if there is no more data because the end of the
- * stream has been reached.
- * @exception IOException
- * if an I/O error occurs.
- * @see java.io.FilterInputStream#in
+ * @param b the provided data buffer.
+ * @param off the starting offset within the buffer for placing the data.
+ * @param len the maximum number of bytes to read.
+ * @return that number of bytes that have been read and copied into the
+ * buffer or -1 if an end of stream occurs.
+ * @exception IOException for any I/O errors.
*/
public int read(byte b[], int off, int len) throws IOException {
int count = in.read(b, off, len);
@@ -95,21 +86,11 @@
}
/**
- * Reads the next byte of data from this input stream. The value byte is
- * returned as an <code>int</code> in the range <code>0</code> to
- * <code>255</code>. If no byte is available because the end of the
- * stream has been reached, the value <code>-1</code> is returned. This
- * method blocks until input data is available, the end of the stream is
- * detected, or an exception is thrown.
- * <p>
- * This method simply performs <code>in.read()</code> and returns the
- * result.
+ * Read the next byte of data from the input stream, returning it as an
+ * int value. Returns -1 if the end of stream is detected.
*
- * @return the next byte of data, or <code>-1</code> if the end of the
- * stream is reached.
- * @exception IOException
- * if an I/O error occurs.
- * @see java.io.FilterInputStream#in
+ * @return The next byte of data or -1 to indicate end-of-stream.
+ * @exception IOException for any I/O errors
*/
public int read() throws IOException {
int b = in.read();
