You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/04/22 14:04:11 UTC
svn commit: r767477 [4/5] - in
/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang:
./ ref/ reflect/
Modified: harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ThreadGroup.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ThreadGroup.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ThreadGroup.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ThreadGroup.java Wed Apr 22 12:04:10 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/trunk/modules/luni-kernel/src/main/java/java/lang/Throwable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Throwable.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Throwable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Throwable.java Wed Apr 22 12:04:10 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/trunk/modules/luni-kernel/src/main/java/java/lang/ref/PhantomReference.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/PhantomReference.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/PhantomReference.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/PhantomReference.java Wed Apr 22 12:04:10 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/trunk/modules/luni-kernel/src/main/java/java/lang/ref/Reference.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/Reference.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/Reference.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/Reference.java Wed Apr 22 12:04:10 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/trunk/modules/luni-kernel/src/main/java/java/lang/ref/SoftReference.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/SoftReference.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/SoftReference.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/SoftReference.java Wed Apr 22 12:04:10 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/trunk/modules/luni-kernel/src/main/java/java/lang/ref/WeakReference.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/WeakReference.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/WeakReference.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/WeakReference.java Wed Apr 22 12:04:10 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/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/AccessibleObject.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/AccessibleObject.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/AccessibleObject.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/AccessibleObject.java Wed Apr 22 12:04:10 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/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Array.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Array.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Array.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Array.java Wed Apr 22 12:04:10 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;