harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From qi...@apache.org
Subject svn commit: r768698 [12/18] - in /harmony/enhanced/classlib/branches/java6: ./ modules/annotation/src/main/java/java/lang/annotation/ modules/archive/src/main/java/java/util/jar/ modules/archive/src/main/java/java/util/zip/ modules/auth/src/main/java/c...
Date Sun, 26 Apr 2009 12:30:06 GMT
Modified: harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ThreadGroup.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ThreadGroup.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ThreadGroup.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ThreadGroup.java Sun Apr 26 12:30:01 2009
@@ -18,22 +18,31 @@
 package java.lang;
 
 /**
- * An implementation of this class is provided, but the documented constructors
- * are used by the vm specific implementation to create the required "system"
- * and "main" ThreadGroups. The documented methods are used by java.lang.Thread
- * to add and remove Threads from their ThreadGroups.
- * 
- * ThreadGroups are containers of Threads and ThreadGroups, therefore providing
- * a tree-like structure to organize Threads. The root ThreadGroup name is
- * "system" and it has no parent ThreadGroup. All other ThreadGroups have
- * exactly one parent ThreadGroup. All Threads belong to exactly one
- * ThreadGroup.
- * 
+ * A {@code ThreadGroup} is a means of organizing {@link Thread}s into a
+ * hierarchical structure. A {@code ThreadGroup} can contain zero or more
+ * {@code Thread}s and zero or more other {@code ThreadGroup}s. Each {@code
+ * Thread} and each {@code ThreadGroup} (except the root group) has a unique
+ * parent {@code ThreadGroup}. The result is a tree whose inner nodes are
+ * {@code ThreadGroup}s and whose leaf nodes are {@code Threads}. The unique
+ * root of the tree is a {@code ThreadGroup} that is created at VM startup and
+ * has the name "system". The benefit of using {@code ThreadGroup}s, in addition
+ * to the mere housekeeping aspect, is that all {@code Thread}s in a {@code
+ * ThreadGroup} can be manipulated together, that is, the {@code ThreadGroup}
+ * has methods that delegate to all its all {@code Thread}s.
+ *
  * @see Thread
  * @see SecurityManager
  */
 public class ThreadGroup implements Thread.UncaughtExceptionHandler {
 
+    /*
+     * An implementation of this class is provided, but the documented
+     * constructors are used by the vm specific implementation to create the
+     * required "system" and "main" ThreadGroups. The documented methods are
+     * used by java.lang.Thread to add and remove Threads from their
+     * ThreadGroups.
+     */
+
     // Name of this ThreadGroup
     private String name;
 
@@ -135,11 +144,10 @@
 
     /**
      * Returns the number of Threads which are children of the receiver,
-     * directly or indirectly.
-     * 
-     * @return Number of children Threads
+     * directly or indirectly and are running.
+     *
+     * @return the number of children Threads
      */
-
     public int activeCount() {
         int count = numThreads;
         // Lock this subpart of the tree as we walk
@@ -155,7 +163,7 @@
      * Returns the number of ThreadGroups which are children of the receiver,
      * directly or indirectly.
      * 
-     * @return Number of children ThreadGroups
+     * @return the number of children ThreadGroups
      */
     public int activeGroupCount() {
         int count = 0;
@@ -224,11 +232,13 @@
     }
 
     /**
-     * The definition of this method depends on the deprecated method
-     * <code>suspend()</code>. The behavior of this call was never specified.
+     * Does nothing. The definition of this method depends on the deprecated
+     * method {@link #suspend()}. The exact behavior of this call was never
+     * specified.
      * 
      * @param b Used to control low memory implicit suspension
-     * 
+     * @return {@code true} (always)
+     *
      * @deprecated Required deprecated method suspend().
      */
     @Deprecated
@@ -238,8 +248,10 @@
     }
 
     /**
-     * If there is a SecurityManager installed, call <code>checkAccess</code>
-     * in it passing the receiver as parameter, otherwise do nothing.
+     * Checks the accessibility of the ThreadGroup from the perspective of the
+     * caller. If there is a SecurityManager installed, calls
+     * {@code checkAccess} with the receiver as a parameter, otherwise does
+     * nothing.
      */
     public final void checkAccess() {
         // Forwards the message to the SecurityManager (if there's one) passing
@@ -252,13 +264,14 @@
 
     /**
      * Destroys the receiver and recursively all its subgroups. It is only legal
-     * to destroy a ThreadGroup that has no Threads. Any daemon ThreadGroup is
-     * destroyed automatically when it becomes empty (no Threads and no
-     * ThreadGroups in it).
+     * to destroy a ThreadGroup that has no Threads in it. Any daemon
+     * ThreadGroup is destroyed automatically when it becomes empty (no Threads
+     * and no ThreadGroups in it).
      * 
      * @throws IllegalThreadStateException if the receiver or any of its
-     *         subgroups has been destroyed already
-     * @throws SecurityException if <code>this.checkAccess()</code> fails with
+     *         subgroups has been destroyed already or if it still contains
+     *         threads.
+     * @throws SecurityException if {@code this.checkAccess()} fails with
      *         a SecurityException
      */
 
@@ -310,46 +323,38 @@
     }
 
     /**
-     * Copies an array with all Threads which are children of the receiver
-     * (directly or indirectly) into the array <code>threads</code> passed as
-     * parameters. If the array passed as parameter is too small no exception is
-     * thrown - the extra elements are simply not copied.
-     * 
-     * @param threads Thread array into which the Threads will be copied
-     * @return How many Threads were copied over
+     * Iterates over all active threads in this group (and its sub-groups) and
+     * stores the threads in the given array. Returns when the array is full or
+     * no more threads remain, whichever happens first.
      * 
+     * @param threads the array into which the Threads will be copied
+     * @return the number of Threads that were copied
      */
     public int enumerate(Thread[] threads) {
         return enumerate(threads, true);
     }
 
     /**
-     * Copies an array with all Threads which are children of the receiver into
-     * the array <code>threads</code> passed as parameter. Children Threads of
-     * subgroups are recursively copied as well if parameter
-     * <code>recurse</code> is <code>true</code>.
-     * 
-     * If the array passed as parameter is too small no exception is thrown -
-     * the extra elements are simply not copied.
-     * 
-     * @param threads array into which the Threads will be copied
-     * @param recurse Indicates whether Threads in subgroups should be
-     *        recursively copied as well or not
-     * @return How many Threads were copied over
-     * 
+     * Iterates over all active threads in this group (and, optionally, its
+     * sub-groups) and stores the threads in the given array. Returns when the
+     * array is full or no more threads remain, whichever happens first.
+     * 
+     * @param threads the array into which the Threads will be copied
+     * @param recurse indicates whether Threads in subgroups should be
+     *        recursively copied as well
+     * @return the number of Threads that were copied
      */
     public int enumerate(Thread[] threads, boolean recurse) {
         return enumerateGeneric(threads, recurse, 0, true);
     }
 
     /**
-     * Copies an array with all ThreadGroups which are children of the receiver
-     * (directly or indirectly) into the array <code>groups</code> passed as
-     * parameters. If the array passed as parameter is too small no exception is
-     * thrown - the extra elements are simply not copied.
+     * Iterates over all thread groups in this group (and its sub-groups) and
+     * and stores the groups in the given array. Returns when the array is full
+     * or no more groups remain, whichever happens first.
      * 
-     * @param groups array into which the ThreadGroups will be copied
-     * @return How many ThreadGroups were copied over
+     * @param groups the array into which the ThreadGroups will be copied
+     * @return the number of ThreadGroups that were copied
      * 
      */
     public int enumerate(ThreadGroup[] groups) {
@@ -357,18 +362,14 @@
     }
 
     /**
-     * Copies an array with all ThreadGroups which are children of the receiver
-     * into the array <code>groups</code> passed as parameter. Children
-     * ThreadGroups of subgroups are recursively copied as well if parameter
-     * <code>recurse</code> is <code>true</code>.
+     * Iterates over all thread groups in this group (and, optionally, its
+     * sub-groups) and and stores the groups in the given array. Returns when
+     * the array is full or no more groups remain, whichever happens first.
      * 
-     * If the array passed as parameter is too small no exception is thrown -
-     * the extra elements are simply not copied.
-     * 
-     * @param groups array into which the ThreadGroups will be copied
-     * @param recurse Indicates whether ThreadGroups in subgroups should be
+     * @param groups the array into which the ThreadGroups will be copied
+     * @param recurse indicates whether ThreadGroups in subgroups should be
      *        recursively copied as well or not
-     * @return How many ThreadGroups were copied over
+     * @return the number of ThreadGroups that were copied
      * 
      */
     public int enumerate(ThreadGroup[] groups, boolean recurse) {
@@ -426,9 +427,9 @@
     }
 
     /**
-     * Answers the maximum allowed priority for a Thread in the receiver.
+     * Returns the maximum allowed priority for a Thread in the receiver.
      * 
-     * @return the maximum priority (an <code>int</code>)
+     * @return the maximum priority
      * 
      * @see #setMaxPriority
      */
@@ -437,17 +438,17 @@
     }
 
     /**
-     * Answers the name of the receiver.
+     * Returns the name of the receiver.
      * 
-     * @return the receiver's name (a java.lang.String)
+     * @return the receiver's name
      */
     public final String getName() {
         return name;
     }
 
     /**
-     * Answers the receiver's parent ThreadGroup. It can be null if the receiver
-     * is the the root ThreadGroup.
+     * Returns the receiver's parent ThreadGroup. It can be {@code null}  if the
+     * receiver is the the root ThreadGroup.
      * 
      * @return the parent ThreadGroup
      * 
@@ -463,7 +464,7 @@
      * Interrupts every Thread in the receiver and recursively in all its
      * subgroups.
      * 
-     * @throws SecurityException if <code>this.checkAccess()</code> fails with
+     * @throws SecurityException if {@code this.checkAccess()} fails with
      *         a SecurityException
      * 
      * @see Thread#interrupt
@@ -485,9 +486,9 @@
     }
 
     /**
-     * Answers true if the receiver is a daemon ThreadGroup, false otherwise.
+     * Checks whether the receiver is a daemon ThreadGroup.
      * 
-     * @return if the receiver is a daemon ThreadGroup
+     * @return true if (and only if) the receiver is a daemon ThreadGroup
      * 
      * @see #setDaemon
      * @see #destroy
@@ -497,9 +498,9 @@
     }
 
     /**
-     * Answers true if the receiver has been destroyed already, false otherwise.
+     * Checks whether the receiver has already been destroyed.
      * 
-     * @return if the receiver has been destroyed already
+     * @return true if (and only if) the receiver has already been destroyed
      * 
      * @see #destroy
      */
@@ -508,7 +509,7 @@
     }
 
     /**
-     * Outputs to <code>System.out</code> a text representation of the
+     * Outputs to {@code System.out} a text representation of the
      * hierarchy of Threads and ThreadGroups in the receiver (and recursively).
      * Proper indentation is done to suggest the nesting of groups inside groups
      * and threads inside groups.
@@ -520,7 +521,7 @@
     }
 
     /*
-     * Outputs to <code>System.out</code>a text representation of the
+     * Outputs to {@code System.out}a text representation of the
      * hierarchy of Threads and ThreadGroups in the receiver (and recursively).
      * The indentation will be four spaces per level of nesting.
      * 
@@ -553,12 +554,12 @@
     }
 
     /**
-     * Answers true if the receiver is a direct or indirect parent group of
-     * ThreadGroup <code>g</code>, false otherwise.
+     * Checks whether the receiver is a direct or indirect parent group of a
+     * given ThreadGroup.
      * 
-     * @param g ThreadGroup to test
+     * @param g the potential child ThreadGroup
      * 
-     * @return if the receiver is parent of the ThreadGroup passed as parameter
+     * @return true if (and only if) the receiver is parent of {@code g}
      * 
      */
     public final boolean parentOf(ThreadGroup g) {
@@ -598,7 +599,7 @@
     /**
      * Removes an immediate subgroup from the receiver.
      * 
-     * @param g Threadgroup to remove from the receiver
+     * @param g ThreadGroup to remove from the receiver
      * 
      * @see #add(Thread)
      * @see #add(ThreadGroup)
@@ -621,7 +622,7 @@
      * Resumes every Thread in the receiver and recursively in all its
      * subgroups.
      * 
-     * @throws SecurityException if <code>this.checkAccess()</code> fails with
+     * @throws SecurityException if {@code this.checkAccess()} fails with
      *         a SecurityException
      * 
      * @see Thread#resume
@@ -651,9 +652,10 @@
      * Configures the receiver to be a daemon ThreadGroup or not. Daemon
      * ThreadGroups are automatically destroyed when they become empty.
      * 
-     * @param isDaemon new value defining if receiver should be daemon or not
+     * @param isDaemon the new value defining if receiver should be daemon or
+     *                 not
      * 
-     * @throws SecurityException if <code>checkAccess()</code> for the parent
+     * @throws SecurityException if {@code checkAccess()} for the parent
      *         group fails with a SecurityException
      * 
      * @see #isDaemon
@@ -674,7 +676,7 @@
      * 
      * @param newMax the new maximum priority to be set
      * 
-     * @throws SecurityException if <code>checkAccess()</code> fails with a
+     * @throws SecurityException if {@code checkAccess()} fails with a
      *         SecurityException
      * @throws IllegalArgumentException if the new priority is greater than
      *         Thread.MAX_PRIORITY or less than Thread.MIN_PRIORITY
@@ -703,8 +705,8 @@
 
     /**
      * Sets the parent ThreadGroup of the receiver, and adds the receiver to the
-     * parent's collection of immediate children (if <code>parent</code> is
-     * not <code>null</code>).
+     * parent's collection of immediate children (if {@code parent} is
+     * not {@code null}).
      * 
      * @param parent The parent ThreadGroup, or null if the receiver is to be
      *        the root ThreadGroup
@@ -722,7 +724,7 @@
     /**
      * Stops every Thread in the receiver and recursively in all its subgroups.
      * 
-     * @throws SecurityException if <code>this.checkAccess()</code> fails with
+     * @throws SecurityException if {@code this.checkAccess()} fails with
      *         a SecurityException
      * 
      * @see Thread#stop()
@@ -772,7 +774,7 @@
      * Suspends every Thread in the receiver and recursively in all its
      * subgroups.
      * 
-     * @throws SecurityException if <code>this.checkAccess()</code> fails with
+     * @throws SecurityException if {@code this.checkAccess()} fails with
      *         a SecurityException
      * 
      * @see Thread#suspend
@@ -818,10 +820,10 @@
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
+     * Returns a string containing a concise, human-readable description of the
      * receiver.
      * 
-     * @return a printable representation for the receiver.
+     * @return a printable representation of the ThreadGroup
      */
     @Override
     public String toString() {
@@ -830,14 +832,14 @@
     }
 
     /**
-     * Any uncaught exception in any Thread has to be forwarded (by the VM) to
-     * the Thread's ThreadGroup by sending this message (uncaughtException).
-     * This allows users to define custom ThreadGroup classes and custom
-     * behavior for when a Thread has an uncaughtException or when it does
-     * (ThreadDeath).
+     * Handles uncaught exceptions. Any uncaught exception in any Thread
+     * is forwarded (by the VM) to the Thread's ThreadGroup by sending this
+     * message (uncaughtException). This allows users to define custom
+     * ThreadGroup classes and custom behavior for when a Thread has an
+     * uncaughtException or when it does (ThreadDeath).
      * 
-     * @param t Thread with an uncaught exception
-     * @param e The uncaught exception itself
+     * @param t the Thread that terminated with an uncaught exception
+     * @param e the uncaught exception itself
      * 
      * @see Thread#stop()
      * @see Thread#stop(Throwable)

Modified: harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Throwable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Throwable.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Throwable.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/Throwable.java Sun Apr 26 12:30:01 2009
@@ -23,22 +23,32 @@
 import java.io.PrintWriter;
 
 /**
- * This class must be implemented by the VM vendor, or the reference
- * implementation can be used if the documented natives are implemented.
- * 
- * This class is the superclass of all classes which can be thrown by the
- * virtual machine. The two direct subclasses represent recoverable exceptions
- * (Exception) and unrecoverable errors (Error). This class provides common
- * methods for accessing a string message which provides extra information about
- * the circumstances in which the throwable was created, and for filling in a
- * walkback (i.e. a record of the call stack at a particular point in time)
- * which can be printed later.
- * 
+ * The superclass of all classes which can be thrown by the virtual machine. The
+ * two direct subclasses are recoverable exceptions ({@code Exception}) and
+ * unrecoverable errors ({@code Error}). This class provides common methods for
+ * accessing a string message which provides extra information about the
+ * circumstances in which the {@code Throwable} was created (basically an error
+ * message in most cases), and for saving a stack trace (that is, a record of
+ * the call stack at a particular point in time) which can be printed later.
+ * <p>
+ * A {@code Throwable} can also include a cause, which is a nested {@code
+ * Throwable} that represents the original problem that led to this {@code
+ * Throwable}. It is often used for wrapping various types of errors into a
+ * common {@code Throwable} without losing the detailed original error
+ * information. When printing the stack trace, the trace of the cause is
+ * included.
+ *
  * @see Error
  * @see Exception
  * @see RuntimeException
  */
 public class Throwable implements java.io.Serializable {
+
+    /*
+     * This class must be implemented by the VM vendor, or the reference
+     * implementation can be used if the documented natives are implemented.
+     */
+
     private static final long serialVersionUID = -3042686055658047285L;
 
     /**
@@ -51,10 +61,13 @@
      */
     private Throwable cause = this;
 
+    /**
+     * A fully-expanded representation of the stack trace.
+     */
     private StackTraceElement[] stackTrace;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code Throwable} that includes the current stack trace.
      */
     public Throwable() {
         super();
@@ -62,10 +75,11 @@
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
-     * 
-     * @param detailMessage String The detail message for the exception.
+     * Constructs a new {@code Throwable} with the current stack trace and the
+     * specified detail message.
+     *
+     * @param detailMessage
+     *            the detail message for this {@code Throwable}.
      */
     public Throwable(String detailMessage) {
         this();
@@ -73,11 +87,13 @@
     }
 
     /**
-     * Constructs a new instance of this class with its walkback, message and
-     * cause filled in.
+     * Constructs a new {@code Throwable} with the current stack trace, the
+     * specified detail message and the specified cause.
      * 
-     * @param detailMessage String The detail message for the exception.
-     * @param throwable The cause of this Throwable
+     * @param detailMessage
+     *            the detail message for this {@code Throwable}.
+     * @param throwable
+     *            the cause of this {@code Throwable}.
      */
     public Throwable(String detailMessage, Throwable throwable) {
         this();
@@ -86,10 +102,11 @@
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and cause
-     * filled in.
-     * 
-     * @param throwable The cause of this Throwable
+     * Constructs a new {@code Throwable} with the current stack trace and the
+     * specified cause.
+     *
+     * @param throwable
+     *            the cause of this {@code Throwable}.
      */
     public Throwable(Throwable throwable) {
         this();
@@ -97,37 +114,39 @@
         cause = throwable;
     }
 
-    /**
+    /*
      * This native must be implemented to use the reference implementation of
      * this class.
-     * 
-     * Record in the receiver a walkback from the point where this message was
-     * sent. The message is public so that code which catches a throwable and
-     * then <em>re-throws</em> it can adjust the walkback to represent the
-     * location where the exception was re-thrown.
-     * 
-     * @return the receiver
+     */
+    /**
+     * Records the stack trace from the point where this method has been called
+     * to this {@code Throwable}. The method is public so that code which
+     * catches a {@code Throwable} and then re-throws it can adjust the stack
+     * trace to represent the location where the exception was re-thrown.
+     *
+     * @return this {@code Throwable} instance.
      */
     public native Throwable fillInStackTrace();
 
     /**
-     * Answers the extra information message which was provided when the
-     * throwable was created. If no message was provided at creation time, then
-     * answer null.
-     * 
-     * @return String The receiver's message.
+     * Returns the extra information message which was provided when this
+     * {@code Throwable} was created. Returns {@code null} if no message was
+     * provided at creation time.
+     *
+     * @return this {@code Throwable}'s detail message.
      */
     public String getMessage() {
         return detailMessage;
     }
 
     /**
-     * Answers the extra information message which was provided when the
-     * throwable was created. If no message was provided at creation time, then
-     * answer null. Subclasses may override this method to answer localized text
-     * for the message.
+     * Returns the extra information message which was provided when this
+     * {@code Throwable} was created. Returns {@code null} if no message was
+     * provided at creation time. Subclasses may override this method to return
+     * localized text for the message. The Android reference implementation
+     * returns the unlocalized detail message.
      * 
-     * @return String The receiver's message.
+     * @return this {@code Throwable}'s localized detail message.
      */
     public String getLocalizedMessage() {
         return getMessage();
@@ -137,7 +156,7 @@
      * This native must be implemented to use the reference implementation of
      * this class. The result of this native is cloned, and returned from the
      * public API getStackTrace().
-     * 
+     *
      * Answers an array of StackTraceElement. Each StackTraceElement represents
      * a entry on the stack.
      * 
@@ -146,21 +165,34 @@
     private native StackTraceElement[] getStackTraceImpl();
 
     /**
-     * Answers an array of StackTraceElement. Each StackTraceElement represents
-     * a entry on the stack.
-     * 
-     * @return an array of StackTraceElement representing the stack
+     * Returns the array of stack trace elements of this {@code Throwable}. Each
+     * {@code StackTraceElement} represents an entry in the call stack. The
+     * element at position 0 is the top of the stack, that is, the stack frame
+     * where this {@code Throwable} is thrown.
+     *
+     * @return a copy of the array of {@code StackTraceElement}s representing
+     *         the call stack. Changes in the array obtained from this call will
+     *         not change the call stack stored in this {@code Throwable}.
+     * @see #printStackTrace()
      */
     public StackTraceElement[] getStackTrace() {
         return getInternalStackTrace().clone();
     }
 
     /**
-     * Sets the array of StackTraceElements. Each StackTraceElement represents a
-     * entry on the stack. A copy of this array will be returned by
-     * getStackTrace() and printed by printStackTrace().
-     * 
-     * @param trace The array of StackTraceElement
+     * Sets the array of stack trace elements. Each {@code StackTraceElement}
+     * represents an entry in the call stack. A copy of the specified array is
+     * stored in this {@code Throwable}. will be returned by {@code
+     * getStackTrace()} and printed by {@code printStackTrace()}.
+     *
+     * @param trace
+     *            the new array of {@code StackTraceElement}s. A copy of the
+     *            array is stored in this {@code Throwable}, so subsequent
+     *            changes to {@code trace} will not change the call stack stored
+     *            in this {@code Throwable}.
+     * @throws NullPointerException
+     *             if any element in {@code trace} is {@code null}.
+     * @see #printStackTrace()
      */
     public void setStackTrace(StackTraceElement[] trace) {
         StackTraceElement[] newTrace = trace.clone();
@@ -173,16 +205,16 @@
     }
 
     /**
-     * Outputs a printable representation of the receiver's walkback on the
-     * System.err stream.
+     * Writes a printable representation of this {@code Throwable}'s stack trace
+     * to the {@code System.err} stream.
      */
     public void printStackTrace() {
         printStackTrace(System.err);
     }
 
     /**
-     * Count the number of duplicate stack frames, starting from the end of the
-     * stack.
+     * Counts the number of duplicate stack frames, starting from the
+     * end of the stack.
      * 
      * @param currentStack a stack to compare
      * @param parentStack a stack to compare
@@ -205,7 +237,7 @@
     }
 
     /**
-     * Answers an array of StackTraceElement. Each StackTraceElement represents
+     * Returns an array of StackTraceElements. Each StackTraceElement represents
      * a entry on the stack. Cache the stack trace in the stackTrace field,
      * returning the cached field when it has already been initialized.
      * 
@@ -219,10 +251,13 @@
     }
 
     /**
-     * Outputs a printable representation of the receiver's walkback on the
-     * stream specified by the argument.
+     * Writes a printable representation of this {@code Throwable}'s stack trace
+     * to the specified print stream. If the {@code Throwable} contains a
+     * {@link #getCause() cause}, the method will be invoked recursively for
+     * the nested {@code Throwable}.
      * 
-     * @param err PrintStream The stream to write the walkback on.
+     * @param err
+     *            the stream to write the stack trace on.
      */
     public void printStackTrace(PrintStream err) {
         err.println(toString());
@@ -252,10 +287,13 @@
     }
 
     /**
-     * Outputs a printable representation of the receiver's walkback on the
-     * writer specified by the argument.
+     * Writes a printable representation of this {@code Throwable}'s stack trace
+     * to the specified print writer. If the {@code Throwable} contains a
+     * {@link #getCause() cause}, the method will be invoked recursively for the
+     * nested {@code Throwable}.
      * 
-     * @param err PrintWriter The writer to write the walkback on.
+     * @param err
+     *            the writer to write the stack trace on.
      */
     public void printStackTrace(PrintWriter err) {
         err.println(toString());
@@ -284,12 +322,6 @@
         }
     }
 
-    /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
-     * 
-     * @return String a printable representation for the receiver.
-     */
     @Override
     public String toString() {
         String msg = getLocalizedMessage();
@@ -302,15 +334,16 @@
     }
 
     /**
-     * Initialize the cause of the receiver. The cause cannot be reassigned.
-     * 
-     * @param throwable The cause of this Throwable
-     * 
-     * @exception IllegalArgumentException when the cause is the receiver
-     * @exception IllegalStateException when the cause has already been
-     *            initialized
-     * 
-     * @return the receiver.
+     * Initializes the cause of this {@code Throwable}. The cause can only be
+     * initialized once.
+     *
+     * @param throwable
+     *            the cause of this {@code Throwable}.
+     * @return this {@code Throwable} instance.
+     * @throws IllegalArgumentException
+     *             if {@code Throwable} is this object.
+     * @throws IllegalStateException
+     *             if the cause has already been initialized.
      */
     public synchronized Throwable initCause(Throwable throwable) {
         if (cause == this) {
@@ -324,9 +357,10 @@
     }
 
     /**
-     * Answers the cause of this Throwable, or null if there is no cause.
+     * Returns the cause of this {@code Throwable}, or {@code null} if there is
+     * no cause.
      * 
-     * @return Throwable The receiver's cause.
+     * @return Throwable this {@code Throwable}'s cause.
      */
     public Throwable getCause() {
         if (cause == this) {

Modified: harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/PhantomReference.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/PhantomReference.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/PhantomReference.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/PhantomReference.java Sun Apr 26 12:30:01 2009
@@ -18,19 +18,30 @@
 package java.lang.ref;
 
 /**
- * PhantomReference objects are used to detect referents which are no longer
- * visible and are eligible to have their storage reclaimed.
- * 
+ * Implements a phantom reference, which is the weakest of the three types of
+ * references. Once the garbage collector decides that an object {@code obj} is
+ * <a href="package.html#definitions>phantom-reachable</a>, it is being enqueued
+ * on the corresponding queue, but its referent is not cleared. That is, the
+ * reference queue of the phantom reference must explicitly be processed by some
+ * application code. As a consequence, a phantom reference that is not
+ * registered with any reference queue does not make any sense.
+ * <p>
+ * Phantom references are useful for implementing cleanup operations that are
+ * necessary before an object gets garbage-collected. They are sometimes more
+ * flexible than the {@link Object#finalize()} method.
+ *
  * @since 1.2
  */
 public class PhantomReference<T> extends Reference<T> {
 
     /**
-     * Constructs a new instance of this class.
-     * 
-     * 
-     * @param r referent to track.
-     * @param q queue to register to the reference object with.
+     * Constructs a new phantom reference and registers it with the given
+     * reference queue. The reference queue may be {@code null}, but this case
+     * does not make any sense, since the reference will never be enqueued, and
+     * the {@link #get()} method always returns {@code null}.
+     *
+     * @param r the referent to track
+     * @param q the queue to register the phantom reference object with
      */
     public PhantomReference(T r, ReferenceQueue<? super T> q) {
         super();
@@ -38,10 +49,10 @@
     }
 
     /**
-     * Return the referent of the reference object. Phantom reference objects
-     * referents are inaccessible, and so null is returned.
-     * 
-     * @return Object Returns null.
+     * Returns {@code null}.  The referent of a phantom reference is not
+     * accessible.
+     *
+     * @return {@code null} (always)
      */
     @Override
     public T get() {

Modified: harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/Reference.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/Reference.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/Reference.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/Reference.java Sun Apr 26 12:30:01 2009
@@ -18,17 +18,26 @@
 package java.lang.ref;
 
 /**
- * This class must be implemented by the vm vendor. The documented methods must
- * be implemented to support the provided subclass implementations. As the
- * provided subclass implementations are trivial and simply call
- * initReference(Object) and initReference(Object, ReferenceQueue) from their
- * constructors, the vm vendor may elect to implement the subclasses as well.
- * Abstract class which describes behavior common to all reference objects.
- * 
+ * Provides an abstract class which describes behavior common to all reference
+ * objects. It is not possible to create immediate subclasses of
+ * {@code Reference} in addition to the ones provided by this package. It is
+ * also not desirable to do so, since references require very close cooperation
+ * with the system's garbage collector. The existing, specialized reference
+ * classes should be used instead.
+ *
  * @since 1.2
  */
 public abstract class Reference<T> {
 
+  /*
+   * This class must be implemented by the vm vendor. The documented methods must
+   * be implemented to support the provided subclass implementations. As the
+   * provided subclass implementations are trivial and simply call
+   * initReference(Object) and initReference(Object, ReferenceQueue) from their
+   * constructors, the vm vendor may elect to implement the subclasses as well.
+   * Abstract class which describes behavior common to all reference objects.
+   */
+
     /**
      * Constructs a new instance of this class.
      * 
@@ -38,37 +47,39 @@
     }
 
     /**
-     * Make the referent null. This does not force the reference object to be
-     * enqueued.
+     * Makes the referent {@code null}. This does not force the reference
+     * object to be enqueued.
      */
     public void clear() {
         return;
     }
 
     /**
-     * Force the reference object to be enqueued if it has been associated with
+     * Forces the reference object to be enqueued if it has been associated with
      * a queue.
-     * 
-     * @return boolean true if Reference is enqueued. false otherwise.
+     *
+     * @return {@code true} if this call has caused the {@code Reference} to
+     * become enqueued, or {@code false} otherwise
      */
     public boolean enqueue() {
         return false;
     }
 
-    /**
-     * Return the referent of the reference object.
-     * 
-     * @return Referent to which reference refers, or null if object has been
-     *         cleared.
-     */
+  /**
+   * Returns the referent of the reference object.
+   *
+   * @return the referent to which reference refers, or {@code null} if the
+   *         object has been cleared.
+   */
     public T get() {
         return null;
     }
 
     /**
-     * Return whether the reference object has been enqueued.
-     * 
-     * @return boolean true if Reference has been enqueued. false otherwise.
+     * Checks whether the reference object has been enqueued.
+     *
+     * @return {@code true} if the {@code Reference} has been enqueued, {@code
+     *         false} otherwise
      */
     public boolean isEnqueued() {
         return false;

Modified: harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/SoftReference.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/SoftReference.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/SoftReference.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/SoftReference.java Sun Apr 26 12:30:01 2009
@@ -18,28 +18,80 @@
 package java.lang.ref;
 
 /**
- * SoftReference objects are used to detect referents which are no longer
- * visible and who's memory is to be reclaimed.
- * 
+ * Implements a soft reference, which is the least-weak of the three types of
+ * references. Once the garbage collector has decided that an object {@code obj}
+ * is <a href="package.html#definitions>softly-reachable</a>, the following
+ * may happen, either immediately or at a later point:
+ *
+ * <ul>
+ *   <li>
+ *     A set {@code ref} of references is determined. {@code ref} contains the
+ *     following elements:
+ *     <ul>
+ *       <li>
+ *         All soft references pointing to {@code obj}.
+ *       </li>
+ *       <li>
+ *         All soft references pointing to objects from which {@code obj} is
+ *         strongly reachable.
+ *       </li>
+ *     </ul>
+ *   </li>
+ *   <li>
+ *     All references in {@code ref} are atomically cleared.
+ *   </li>
+ *   <li>
+ *     At the same time or some time in the future, all references in {@code
+ *     ref} will be enqueued with their corresponding reference queues, if any.
+ *   </li>
+ * </ul>
+ *
+ * The system may decide not to clear and enqueue soft references until a later
+ * time, yet all {@code SoftReference}s pointing to softly reachable objects are
+ * guaranteed to be cleared before the VM will throw an {@link
+ * java.lang.OutOfMemoryError}.
+ *
+ * Soft references are useful for caches that should automatically have
+ * their entries removed once they are not referenced any more (from outside),
+ * and there is a need for memory. The difference between a {@code
+ * SoftReference} and a {@code WeakReference} is the point of time at which the
+ * decision is made to clear and enqueue the reference:
+ *
+ * <ul>
+ *   <li>
+ *     A {@code SoftReference} should be cleared and enqueued <em>as late as
+ *     possible</em>, that is, in case the VM is in danger of running out of
+ *     memory.
+ *   </li>
+ *   <li>
+ *     A {@code WeakReference} may be cleared and enqueued as soon as is
+ *     known to be weakly-referenced.
+ *   </li>
+ * </ul>
+ *
  * @since 1.2
  */
 public class SoftReference<T> extends Reference<T> {
 
     /**
-     * Constructs a new instance of this class.
-     * 
-     * @param r referent to track.
+     * Constructs a new soft reference to the given referent. The newly created
+     * reference is not registered with any reference queue.
+     *
+     * @param r the referent to track
      */
     public SoftReference(T r) {
         super();
         initReference(r);
     }
-    
+
     /**
-     * Constructs a new instance of this class.
-     * 
-     * @param r referent to track.
-     * @param q queue to register to the reference object with.
+     * Constructs a new soft reference to the given referent. The newly created
+     * reference is registered with the given reference queue.
+     *
+     * @param r the referent to track
+     * @param q the queue to register to the reference object with. A null value
+     *          results in a weak reference that is not associated with any
+     *          queue.
      */
     public SoftReference(T r, ReferenceQueue<? super T> q) {
         super();
@@ -48,9 +100,9 @@
 
     /**
      * Return the referent of the reference object.
-     * 
-     * @return Object Referent to which reference refers, or null if object has
-     *         been cleared.
+     *
+     * @return the referent to which reference refers, or {@code null} if the
+     *         referent has been cleared.
      */
     @Override
     public T get() {

Modified: harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/WeakReference.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/WeakReference.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/WeakReference.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/ref/WeakReference.java Sun Apr 26 12:30:01 2009
@@ -18,17 +18,65 @@
 package java.lang.ref;
 
 /**
- * WeakReference objects are used to detect referents which are no longer
- * visible.
- * 
+ * Implements a weak reference, which is the middle of the three types of
+ * references. Once the garbage collector decides that an object {@code obj} is
+ * is <a href="package.html#definitions>weakly-reachable</a>, the following
+ * happens:
+ *
+ * <ul>
+ *   <li>
+ *     A set {@code ref} of references is determined. {@code ref} contains the
+ *     following elements:
+ *     <ul>
+ *       <li>
+ *         All weak references pointing to {@code obj}.
+ *       </li>
+ *       <li>
+ *         All weak references pointing to objects from which {@code obj} is
+ *         either strongly or softly reachable.
+ *       </li>
+ *     </ul>
+ *   </li>
+ *   <li>
+ *     All references in {@code ref} are atomically cleared.
+ *   </li>
+ *   <li>
+ *     All objects formerly being referenced by {@code ref} become eligible for
+ *     finalization.
+ *   </li>
+ *   <li>
+ *     At some future point, all references in {@code ref} will be enqueued
+ *     with their corresponding reference queues, if any.
+ *   </li>
+ * </ul>
+ *
+ * Weak references are useful for mappings that should have their entries
+ * removed automatically once they are not referenced any more (from outside).
+ * The difference between a {@code SoftReference} and a {@code WeakReference} is
+ * the point of time at which the decision is made to clear and enqueue the
+ * reference:
+ *
+ * <ul>
+ *   <li>
+ *     A {@code SoftReference} should be cleared and enqueued <em>as late as
+ *     possible</em>, that is, in case the VM is in danger of running out of
+ *     memory.
+ *   </li>
+ *   <li>
+ *     A {@code WeakReference} may be cleared and enqueued as soon as is
+ *     known to be weakly-referenced.
+ *   </li>
+ * </ul>
+ *
  * @since 1.2
  */
 public class WeakReference<T> extends Reference<T> {
 
     /**
-     * Constructs a new instance of this class.
-     * 
-     * @param r referent to track.
+     * Constructs a new weak reference to the given referent. The newly created
+     * reference is not registered with any reference queue.
+     *
+     * @param r the referent to track
      */
     public WeakReference(T r) {
         super();
@@ -36,10 +84,13 @@
     }
 
     /**
-     * Constructs a new instance of this class.
-     * 
-     * @param r referent to track.
-     * @param q queue to register to the reference object with.
+     * Constructs a new weak reference to the given referent. The newly created
+     * reference is registered with the given reference queue.
+     *
+     * @param r the referent to track
+     * @param q the queue to register to the reference object with. A null value
+     *          results in a weak reference that is not associated with any
+     *          queue.
      */
     public WeakReference(T r, ReferenceQueue<? super T> q) {
         super();

Modified: harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/reflect/AccessibleObject.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/reflect/AccessibleObject.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/reflect/AccessibleObject.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/reflect/AccessibleObject.java Sun Apr 26 12:30:01 2009
@@ -20,24 +20,28 @@
 import java.lang.annotation.Annotation;
 
 /**
- * This class must be implemented by the VM vendor. This class is the superclass
- * of all member reflect classes (Field, Constructor, Method). AccessibleObject
- * provides the ability to toggle access checks for these objects. By default
- * accessing a member (for example, setting a field or invoking a method) checks
- * the validity of the access (for example, invoking a private method from
- * outside the defining class is prohibited) and throws IllegalAccessException
- * if the operation is not permitted. If the accessible flag is set to true,
- * these checks are omitted. This allows privileged applications such as Java
- * Object Serialization, inspectors, and debuggers to have complete access to
+ * {@code AccessibleObject} is the superclass of all member reflection classes
+ * (Field, Constructor, Method). AccessibleObject provides the ability to toggle
+ * a flag controlling access checks for these objects. By default, accessing a
+ * member (for example, setting a field or invoking a method) checks the
+ * validity of the access (for example, invoking a private method from outside
+ * the defining class is prohibited) and throws IllegalAccessException if the
+ * operation is not permitted. If the accessible flag is set to true, these
+ * checks are omitted. This allows privileged code, such as Java object
+ * serialization, object inspectors, and debuggers to have complete access to
  * objects.
- * 
+ *
  * @see Field
  * @see Constructor
  * @see Method
  * @see ReflectPermission
- * @since 1.2
  */
 public class AccessibleObject implements AnnotatedElement {
+
+    /*
+     * This class must be implemented by the VM vendor.
+     */
+
     /**
      * TODO Is this necessary?
      */
@@ -46,15 +50,18 @@
     /**
      * Attempts to set the value of the accessible flag for all the objects in
      * the array provided. Only one security check is performed. Setting this
-     * flag to false will enable access checks, setting to true will disable
-     * them. If there is a security manager, checkPermission is called with a
-     * ReflectPermission("suppressAccessChecks").
-     * 
-     * @param objects the accessible objects
-     * @param flag the new value for the accessible flag
+     * flag to {@code false} will enable access checks, setting to {@code true}
+     * will disable them. If there is a security manager, checkPermission is
+     * called with a {@code ReflectPermission("suppressAccessChecks")}.
+     *
+     * @param objects
+     *            the accessible objects
+     * @param flag
+     *            the new value for the accessible flag
+     * @throws SecurityException
+     *             if the request is denied
      * @see #setAccessible(boolean)
      * @see ReflectPermission
-     * @throws SecurityException if the request is denied
      */
     public static void setAccessible(AccessibleObject[] objects, boolean flag)
             throws SecurityException {
@@ -93,8 +100,9 @@
     static final native Class<?> getStackClass(int depth);
 
     /**
-     * AccessibleObject constructor. AccessibleObjects can only be created by
-     * the Virtual Machine.
+     * Constructs a new {@code AccessibleObject} instance. {@code
+     * AccessibleObject} instances can only be constructed by the virtual
+     * machine.
      */
     protected AccessibleObject() {
         super();
@@ -148,10 +156,11 @@
     native boolean checkAccessibility(Class<?> senderClass, Object receiver);
 
     /**
-     * Returns the value of the accessible flag. This is false if access checks
-     * are performed, true if they are skipped.
-     * 
-     * @return the value of the accessible flag
+     * Indicates whether this object is accessible without security checks being
+     * performed. Returns the accessible flag.
+     *
+     * @return {@code true} if this object is accessible without security
+     *         checks, {@code false} otherwise
      */
     public boolean isAccessible() {
         return false;

Modified: harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/reflect/Array.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/reflect/Array.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/reflect/Array.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/luni-kernel/src/main/java/java/lang/reflect/Array.java Sun Apr 26 12:30:01 2009
@@ -18,13 +18,12 @@
 package java.lang.reflect;
 
 /**
- * This class must be implemented by the VM vendor. This class provides methods
- * to dynamically create and access arrays.
+ * This class provides static methods to create and access arrays dynamically.
  */
 public final class Array {
     
     /**
-     * Prevent this class from being instantiated
+     * Prevent this class from being instantiated.
      */
     private Array(){
         //do nothing
@@ -49,455 +48,443 @@
      */
     @SuppressWarnings("unused")
     private static native Object newArrayImpl(Class<?> componentType, int dimension);
-    
-	/**
-	 * Return the element of the array at the specified index. This reproduces
-	 * the effect of <code>array[index]</code> If the array component is a
-	 * base type, the result is automatically wrapped.
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @return the requested element, possibly wrapped
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+
+    /**
+     * Returns the element of the array at the specified index. This reproduces
+     * the effect of {@code array[index]}. If the array component is a primitive
+     * type, the result is automatically wrapped.
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @return the requested element, possibly wrapped
+     * @throws NullPointerException
+     *             if the array is null
+     * @throws IllegalArgumentException
+     *             if {@code array} is not an array
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code  index < 0 || index >= array.length}
+     */
 	public static native Object get(Object array, int index)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Return the element of the array at the specified index, converted to a
-	 * boolean if possible. This reproduces the effect of
-	 * <code>array[index]</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @return the requested element
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the element cannot be
-	 *                converted to the requested type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Returns the element of the array at the specified index, converted to a
+     * {@code boolean}, if possible. This reproduces the effect of {@code
+     * array[index]}
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @return the requested element
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if {@code array} is not an array or the element at the
+     *             index position can not be converted to the return type
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code index < 0 || index >= array.length}
+     */
 	public static native boolean getBoolean(Object array, int index)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Return the element of the array at the specified index, converted to a
-	 * byte if possible. This reproduces the effect of <code>array[index]</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @return the requested element
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the element cannot be
-	 *                converted to the requested type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Returns the element of the array at the specified index, converted to a
+     * {@code byte}, if possible. This reproduces the effect of {@code
+     * array[index]}
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @return the requested element
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if {@code array} is not an array or the element at the
+     *             index position can not be converted to the return type
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code index < 0 || index >= array.length}
+     */
 	public static native byte getByte(Object array, int index)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Return the element of the array at the specified index, converted to a
-	 * char if possible. This reproduces the effect of <code>array[index]</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @return the requested element
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the element cannot be
-	 *                converted to the requested type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Returns the element of the array at the specified index, converted to a
+     * {@code char}, if possible. This reproduces the effect of {@code
+     * array[index]}
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @return the requested element
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if {@code array} is not an array or the element at the
+     *             index position can not be converted to the return type
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code index < 0 || index >= array.length}
+     */
 	public static native char getChar(Object array, int index)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Return the element of the array at the specified index, converted to a
-	 * double if possible. This reproduces the effect of
-	 * <code>array[index]</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @return the requested element
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the element cannot be
-	 *                converted to the requested type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Returns the element of the array at the specified index, converted to a
+     * {@code double}, if possible. This reproduces the effect of {@code
+     * array[index]}
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @return the requested element
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if {@code array} is not an array or the element at the
+     *             index position can not be converted to the return type
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code index < 0 || index >= array.length}
+     */
 	public static native double getDouble(Object array, int index)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Return the element of the array at the specified index, converted to a
-	 * float if possible. This reproduces the effect of
-	 * <code>array[index]</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @return the requested element
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the element cannot be
-	 *                converted to the requested type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Returns the element of the array at the specified index, converted to a
+     * {@code float}, if possible. This reproduces the effect of {@code
+     * array[index]}
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @return the requested element
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if {@code array} is not an array or the element at the
+     *             index position can not be converted to the return type
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code index < 0 || index >= array.length}
+     */
 	public static native float getFloat(Object array, int index)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Return the element of the array at the specified index, converted to an
-	 * int if possible. This reproduces the effect of <code>array[index]</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @return the requested element
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the element cannot be
-	 *                converted to the requested type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Returns the element of the array at the specified index, converted to an
+     * {@code int}, if possible. This reproduces the effect of {@code
+     * array[index]}
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @return the requested element
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if {@code array} is not an array or the element at the
+     *             index position can not be converted to the return type
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code index < 0 || index >= array.length}
+     */
 	public static native int getInt(Object array, int index)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Return the length of the array. This reproduces the effect of
-	 * <code>array.length</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @return the length
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array
-	 */
+    /**
+     * Returns the length of the array. This reproduces the effect of {@code
+     * array.length}
+     *
+     * @param array
+     *            the array
+     * @return the length of the array
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if {@code array} is not an array
+     */
 	public static native int getLength(Object array)
 			throws IllegalArgumentException;
 
-	/**
-	 * Return the element of the array at the specified index, converted to a
-	 * long if possible. This reproduces the effect of <code>array[index]</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @return the requested element
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the element cannot be
-	 *                converted to the requested type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Returns the element of the array at the specified index, converted to a
+     * {@code long}, if possible. This reproduces the effect of {@code
+     * array[index]}
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @return the requested element
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if {@code array} is not an array or the element at the
+     *             index position can not be converted to the return type
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code index < 0 || index >= array.length}
+     */
 	public static native long getLong(Object array, int index)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Return the element of the array at the specified index, converted to a
-	 * short if possible. This reproduces the effect of
-	 * <code>array[index]</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @return the requested element
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the element cannot be
-	 *                converted to the requested type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Returns the element of the array at the specified index, converted to a
+     * {@code short}, if possible. This reproduces the effect of {@code
+     * array[index]}
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @return the requested element
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if {@code array} is not an array or the element at the
+     *             index position can not be converted to the return type
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code index < 0 || index >= array.length}
+     */
 	public static native short getShort(Object array, int index)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Return a new multidimensional array of the specified component type and
-	 * dimensions. This reproduces the effect of
-	 * <code>new componentType[d0][d1]...[dn]</code> for a dimensions array of {
-	 * d0, d1, ... , dn }
-	 * 
-	 * @param componentType
-	 *            the component type of the new array
-	 * @param dimensions
-	 *            the dimensions of the new array
-	 * @return the new array
-	 * @throws java.lang.NullPointerException
-	 *                if the component type is null
-	 * @throws java.lang.NegativeArraySizeException
-	 *                if any of the dimensions are negative
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array of dimensions is of size zero, or exceeds the
-	 *                limit of the number of dimension for an array (currently
-	 *                255)
-	 */
+    /**
+     * Returns a new multidimensional array of the specified component type and
+     * dimensions. This reproduces the effect of {@code new
+     * componentType[d0][d1]...[dn]} for a dimensions array of { d0, d1, ... ,
+     * dn }.
+     *
+     * @param componentType
+     *            the component type of the new array
+     * @param dimensions
+     *            the dimensions of the new array
+     * @return the new array
+     * @throws NullPointerException
+     *             if the component type is {@code null}
+     * @throws NegativeArraySizeException
+     *             if any of the dimensions are negative
+     * @throws IllegalArgumentException
+     *             if the array of dimensions is of size zero, or exceeds the
+     *             limit of the number of dimension for an array (currently 255)
+     */
 	public static Object newInstance(Class<?> componentType, int[] dimensions)
 			throws NegativeArraySizeException, IllegalArgumentException {
 		return null;
 	}
 
-	/**
-	 * Return a new array of the specified component type and length. This
-	 * reproduces the effect of <code>new componentType[size]</code>
-	 * 
-	 * @param componentType
-	 *            the component type of the new array
-	 * @param size
-	 *            the length of the new array
-	 * @return the new array
-	 * @throws java.lang.NullPointerException
-	 *                if the component type is null
-	 * @throws java.lang.NegativeArraySizeException
-	 *                if the size if negative
-	 */
+    /**
+     * Returns a new array of the specified component type and length. This
+     * reproduces the effect of {@code new componentType[size]}.
+     *
+     * @param componentType
+     *            the component type of the new array
+     * @param size
+     *            the length of the new array
+     * @return the new array
+     * @throws NullPointerException
+     *             if the component type is null
+     * @throws NegativeArraySizeException
+     *             if {@code size < 0}
+     */
 	public static Object newInstance(Class<?> componentType, int size)
 			throws NegativeArraySizeException {
 		return null;
 	}
 
-	/**
-	 * Set the element of the array at the specified index to the value. This
-	 * reproduces the effect of <code>array[index] = value</code> If the array
-	 * component is a base type, the value is automatically unwrapped
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @param value
-	 *            the new value
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the value cannot be
-	 *                converted to the array type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Sets the element of the array at the specified index to the value. This
+     * reproduces the effect of {@code array[index] = value}. If the array
+     * component is a primitive type, the value is automatically unwrapped.
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @param value
+     *            the new value
+     *
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if {@code array} is not an array or the value cannot be
+     *             converted to the array type by a widening conversion
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code  index < 0 || index >= array.length}
+     */
 	public static native void set(Object array, int index, Object value)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Set the element of the array at the specified index to the boolean value.
-	 * This reproduces the effect of <code>array[index] = value</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @param value
-	 *            the new value
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the value cannot be
-	 *                converted to the array type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Sets the element of the array at the specified index to the {@code
+     * boolean} value. This reproduces the effect of {@code array[index] =
+     * value}.
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @param value
+     *            the new value
+     *
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if the {@code array} is not an array or the value cannot be
+     *             converted to the array type by a widening conversion
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code  index < 0 || index >= array.length}
+     */
 	public static native void setBoolean(Object array, int index, boolean value)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Set the element of the array at the specified index to the byte value.
-	 * This reproduces the effect of <code>array[index] = value</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @param value
-	 *            the new value
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the value cannot be
-	 *                converted to the array type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Sets the element of the array at the specified index to the {@code byte}
+     * value. This reproduces the effect of {@code array[index] = value}.
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if the {@code array} is not an array or the value cannot be
+     *             converted to the array type by a widening conversion
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code  index < 0 || index >= array.length}
+     */
 	public static native void setByte(Object array, int index, byte value)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Set the element of the array at the specified index to the char value.
-	 * This reproduces the effect of <code>array[index] = value</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @param value
-	 *            the new value
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the value cannot be
-	 *                converted to the array type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Set the element of the array at the specified index to the {@code char}
+     * value. This reproduces the effect of {@code array[index] = value}.
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if the {@code array} is not an array or the value cannot be
+     *             converted to the array type by a widening conversion
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code  index < 0 || index >= array.length}
+     */
 	public static native void setChar(Object array, int index, char value)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Set the element of the array at the specified index to the double value.
-	 * This reproduces the effect of <code>array[index] = value</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @param value
-	 *            the new value
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the value cannot be
-	 *                converted to the array type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Set the element of the array at the specified index to the {@code double}
+     * value. This reproduces the effect of {@code array[index] = value}.
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if the {@code array} is not an array or the value cannot be
+     *             converted to the array type by a widening conversion
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code  index < 0 || index >= array.length}
+     */
 	public static native void setDouble(Object array, int index, double value)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Set the element of the array at the specified index to the float value.
-	 * This reproduces the effect of <code>array[index] = value</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @param value
-	 *            the new value
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the value cannot be
-	 *                converted to the array type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Set the element of the array at the specified index to the {@code float}
+     * value. This reproduces the effect of {@code array[index] = value}.
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if the {@code array} is not an array or the value cannot be
+     *             converted to the array type by a widening conversion
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code  index < 0 || index >= array.length}
+     */
 	public static native void setFloat(Object array, int index, float value)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Set the element of the array at the specified index to the int value.
-	 * This reproduces the effect of <code>array[index] = value</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @param value
-	 *            the new value
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the value cannot be
-	 *                converted to the array type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Set the element of the array at the specified index to the {@code int}
+     * value. This reproduces the effect of {@code array[index] = value}.
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if the {@code array} is not an array or the value cannot be
+     *             converted to the array type by a widening conversion
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code  index < 0 || index >= array.length}
+     */
 	public static native void setInt(Object array, int index, int value)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Set the element of the array at the specified index to the long value.
-	 * This reproduces the effect of <code>array[index] = value</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @param value
-	 *            the new value
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the value cannot be
-	 *                converted to the array type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Set the element of the array at the specified index to the {@code long}
+     * value. This reproduces the effect of {@code array[index] = value}.
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if the {@code array} is not an array or the value cannot be
+     *             converted to the array type by a widening conversion
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code  index < 0 || index >= array.length}
+     */
 	public static native void setLong(Object array, int index, long value)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 
-	/**
-	 * Set the element of the array at the specified index to the short value.
-	 * This reproduces the effect of <code>array[index] = value</code>
-	 * 
-	 * @param array
-	 *            the array
-	 * @param index
-	 *            the index
-	 * @param value
-	 *            the new value
-	 * @throws java.lang.NullPointerException
-	 *                if the array is null
-	 * @throws java.lang.IllegalArgumentException
-	 *                if the array is not an array or the value cannot be
-	 *                converted to the array type by a widening conversion
-	 * @throws java.lang.ArrayIndexOutOfBoundsException
-	 *                if the index is out of bounds -- negative or greater than
-	 *                or equal to the array length
-	 */
+    /**
+     * Set the element of the array at the specified index to the {@code short}
+     * value. This reproduces the effect of {@code array[index] = value}.
+     *
+     * @param array
+     *            the array
+     * @param index
+     *            the index
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the {@code array} is {@code null}
+     * @throws IllegalArgumentException
+     *             if the {@code array} is not an array or the value cannot be
+     *             converted to the array type by a widening conversion
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code  index < 0 || index >= array.length}
+     */
 	public static native void setShort(Object array, int index, short value)
 			throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
 



Mime
View raw message