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/05/02 10:09:57 UTC
svn commit: r770909 [4/10] - in
/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang: ./
ref/ reflect/
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IllegalThreadStateException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IllegalThreadStateException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IllegalThreadStateException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IllegalThreadStateException.java Sat May 2 08:09:50 2009
@@ -17,30 +17,30 @@
package java.lang;
-
/**
- * This runtime exception is thrown when an operation is attempted which is not
- * possible given the state that the executing thread is in.
+ * Thrown when an operation is attempted which is not possible given the state
+ * that the executing thread is in.
*/
public class IllegalThreadStateException extends IllegalArgumentException {
private static final long serialVersionUID = -7626246362397460174L;
/**
- * Constructs a new instance of this class with its walkback filled in.
- */
- public IllegalThreadStateException() {
- super();
- }
+ * Constructs a new {@code IllegalThreadStateException} that includes the
+ * current stack trace.
+ */
+ public IllegalThreadStateException() {
+ super();
+ }
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- * @param detailMessage
- * String The detail message for the exception.
- */
- public IllegalThreadStateException(String detailMessage) {
- super(detailMessage);
- }
+ /**
+ * Constructs a new {@code IllegalThreadStateException} with the current
+ * stack trace and the specified detail message.
+ *
+ * @param detailMessage
+ * the detail message for this exception.
+ */
+ public IllegalThreadStateException(String detailMessage) {
+ super(detailMessage);
+ }
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IncompatibleClassChangeError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IncompatibleClassChangeError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IncompatibleClassChangeError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IncompatibleClassChangeError.java Sat May 2 08:09:50 2009
@@ -19,8 +19,9 @@
/**
- * This class is the superclass of all classes which represent errors which
- * occur when inconsistant class files are loaded into the same running image.
+ * {@code IncompatibleClassChangeError} is the superclass of all classes which
+ * represent errors that occur when inconsistent class files are loaded into
+ * the same running image.
*
* @see Error
*/
@@ -29,20 +30,21 @@
private static final long serialVersionUID = -4914975503642802119L;
/**
- * Constructs a new instance of this class with its walkback filled in.
- */
- public IncompatibleClassChangeError() {
- super();
- }
+ * Constructs a new {@code IncompatibleClassChangeError} that includes the
+ * current stack trace.
+ */
+ public IncompatibleClassChangeError() {
+ super();
+ }
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- * @param detailMessage
- * String The detail message for the exception.
- */
- public IncompatibleClassChangeError(String detailMessage) {
- super(detailMessage);
- }
+ /**
+ * Constructs a new {@code IncompatibleClassChangeError} with the current
+ * stack trace and the specified detail message.
+ *
+ * @param detailMessage
+ * the detail message for this error.
+ */
+ public IncompatibleClassChangeError(String detailMessage) {
+ super(detailMessage);
+ }
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IndexOutOfBoundsException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IndexOutOfBoundsException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IndexOutOfBoundsException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IndexOutOfBoundsException.java Sat May 2 08:09:50 2009
@@ -17,31 +17,30 @@
package java.lang;
-
/**
- * This runtime exception is thrown when a program attempts to access a value in
- * an indexable collection using a value which is outside the possible range of
- * indices.
+ * Thrown when a program attempts to access a value in an indexable collection
+ * using a value which is outside of the range of valid indices.
*/
public class IndexOutOfBoundsException extends RuntimeException {
private static final long serialVersionUID = 234122996006267687L;
/**
- * Constructs a new instance of this class with its walkback filled in.
- */
- public IndexOutOfBoundsException() {
- super();
- }
+ * Constructs a new {@code IndexOutOfBoundsException} that includes the
+ * current stack trace.
+ */
+ public IndexOutOfBoundsException() {
+ super();
+ }
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- * @param detailMessage
- * String The detail message for the exception.
- */
- public IndexOutOfBoundsException(String detailMessage) {
- super(detailMessage);
- }
+ /**
+ * Constructs a new {@code IndexOutOfBoundsException} with the current stack
+ * trace and the specified detail message.
+ *
+ * @param detailMessage
+ * the detail message for this exception.
+ */
+ public IndexOutOfBoundsException(String detailMessage) {
+ super(detailMessage);
+ }
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InheritableThreadLocal.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InheritableThreadLocal.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InheritableThreadLocal.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InheritableThreadLocal.java Sat May 2 08:09:50 2009
@@ -19,26 +19,33 @@
/**
- * An InheritableThreadLocal is very similar to a ThreadLocal, with the added
- * functionality that a child Thread inherits all InheritableThreadLocal from
- * its parent Thread upon Thread creation time.
+ * A thread-local variable whose value is passed from parent to child thread. By
+ * default, the value of an inheritable thread-local variable of a child thread
+ * is initialized with the value of the parent thread's variable at thread
+ * creation time. However, subclasses may override {code #childValue(Object)}
+ * to provide an arbitrary function for passing the value of a parent's
+ * thread-local variable to the child's thread-local variable.
*
* @see java.lang.Thread
* @see java.lang.ThreadLocal
*/
-
public class InheritableThreadLocal<T> extends ThreadLocal<T> {
/**
- * Constructs a new InheritableThreadLocal object
+ * Creates a new inheritable thread-local variable.
*/
public InheritableThreadLocal() {
super();
}
/**
- * Computes the created Thread's initial value for this
- * InheritableThreadLocal based on the current value of the same local on
- * the creator Thread.
+ * Computes the initial value of this thread-local variable for the child
+ * thread given the parent thread's value. Called from the parent thread
+ * when creating a child thread. The default implementation returns the
+ * parent thread's value.
+ *
+ * @param parentValue
+ * the value of the variable in the parent thread.
+ * @return the initial value of the variable for the child thread.
*/
protected T childValue(T parentValue) {
return parentValue;
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationError.java Sat May 2 08:09:50 2009
@@ -17,46 +17,44 @@
package java.lang;
-
/**
- * This error is thrown when the VM notices that a an attempt is being made to
- * create a new instance of a class which has no visible constructors from the
- * location where new is invoked.
+ * Thrown when the virtual machine notices that a program tries to create a new
+ * instance of a class which has no visible constructors from the location where
+ * {@code new} is invoked.
* <p>
* Note that this can only occur when inconsistent class files are being loaded.
- *
*/
public class InstantiationError extends IncompatibleClassChangeError {
- private static final long serialVersionUID = -4885810657349421204L;
+ private static final long serialVersionUID = -4885810657349421204L;
- /**
- * Constructs a new instance of this class with its walkback filled in.
- *
- */
- public InstantiationError() {
- super();
- }
-
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- * @param detailMessage
- * String The detail message for the exception.
- */
- public InstantiationError(String detailMessage) {
- super(detailMessage);
- }
-
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- * @param clazz
- * Class The class which cannot be instantiated.
- */
- InstantiationError(Class<?> clazz) {
- super(clazz.getName());
- }
+ /**
+ * Constructs a new {@code InstantiationError} that includes the current
+ * stack trace.
+ */
+ public InstantiationError() {
+ super();
+ }
+
+ /**
+ * Constructs a new {@code InstantiationError} with the current stack trace
+ * and the specified detail message.
+ *
+ * @param detailMessage
+ * the detail message for this error.
+ */
+ public InstantiationError(String detailMessage) {
+ super(detailMessage);
+ }
+
+ /**
+ * Constructs a new {@code InstantiationError} with the current stack trace
+ * and the class that caused this error.
+ *
+ * @param clazz
+ * the class that can not be instantiated.
+ */
+ InstantiationError(Class<?> clazz) {
+ super(clazz.getName());
+ }
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationException.java Sat May 2 08:09:50 2009
@@ -17,42 +17,40 @@
package java.lang;
-
/**
- * This exception is thrown when a program attempts to access a constructor
- * which is not accessible from the location where the reference is made.
- *
+ * Thrown when a program attempts to access a constructor which is not
+ * accessible from the location where the reference is made.
*/
public class InstantiationException extends Exception {
- private static final long serialVersionUID = -8441929162975509110L;
-
- /**
- * Constructs a new instance of this class with its walkback filled in.
- *
- */
- public InstantiationException() {
- super();
- }
-
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- * @param detailMessage
- * String The detail message for the exception.
- */
- public InstantiationException(String detailMessage) {
- super(detailMessage);
- }
+ private static final long serialVersionUID = -8441929162975509110L;
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- * @param clazz
- * Class The class which cannot be instantiated.
- */
- InstantiationException(Class<?> clazz) {
- super(clazz.getName());
- }
+ /**
+ * Constructs a new {@code InstantiationException} that includes the current
+ * stack trace.
+ */
+ public InstantiationException() {
+ super();
+ }
+
+ /**
+ * Constructs a new {@code InstantiationException} with the current stack
+ * trace and the specified detail message.
+ *
+ * @param detailMessage
+ * the detail message for this exception.
+ */
+ public InstantiationException(String detailMessage) {
+ super(detailMessage);
+ }
+
+ /**
+ * Constructs a new {@code InstantiationException} with the current stack
+ * trace and the class that caused this exception.
+ *
+ * @param clazz
+ * the class that can not be instantiated.
+ */
+ InstantiationException(Class<?> clazz) {
+ super(clazz.getName());
+ }
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Integer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Integer.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Integer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Integer.java Sat May 2 08:09:50 2009
@@ -18,17 +18,13 @@
package java.lang;
/**
+ * The wrapper for the primitive type {@code int}.
* <p>
- * Integer is the wrapper for the primitive type <code>int</code>.
- * </p>
- *
- * <p>
- * As with the specification, this implementation relied on code laid out in <a
+ * As with the specification, this implementation relies on code laid out in <a
* href="http://www.hackersdelight.org/">Henry S. Warren, Jr.'s Hacker's
* Delight, (Addison Wesley, 2002)</a> as well as <a
* href="http://aggregate.org/MAGIC/">The Aggregate's Magic Algorithms</a>.
- * </p>
- *
+ *
* @see java.lang.Number
* @since 1.1
*/
@@ -42,25 +38,19 @@
private final int value;
/**
- * <p>
- * Constant for the maximum <code>int</code> value, 2<sup>31</sup>-1.
- * </p>
+ * Constant for the maximum {@code int} value, 2<sup>31</sup>-1.
*/
public static final int MAX_VALUE = 0x7FFFFFFF;
/**
- * <p>
- * Constant for the minimum <code>int</code> value, -2<sup>31</sup>.
- * </p>
+ * Constant for the minimum {@code int} value, -2<sup>31</sup>.
*/
public static final int MIN_VALUE = 0x80000000;
/**
- * <p>
- * Constant for the number of bits to represent an <code>int</code> in
- * two's compliment form.
- * </p>
- *
+ * Constant for the number of bits needed to represent an {@code int} in
+ * two's complement form.
+ *
* @since 1.5
*/
public static final int SIZE = 32;
@@ -74,7 +64,7 @@
10000000, 1000000, 100000, 10000, 1000, 100, 10, 1 };
/**
- * The java.lang.Class that represents this class.
+ * The {@link Class} object that represents the primitive type {@code int}.
*/
@SuppressWarnings("unchecked")
public static final Class<Integer> TYPE = (Class<Integer>) new int[0]
@@ -84,52 +74,45 @@
// defined to be "java.lang.Integer.TYPE";
/**
- * Constructs a new instance of the receiver which represents the int valued
- * argument.
+ * Constructs a new {@code Integer} with the specified primitive integer
+ * value.
*
* @param value
- * the int to store in the new instance.
+ * the primitive integer value to store in the new instance.
*/
public Integer(int value) {
this.value = value;
}
/**
- * Constructs a new instance of this class given a string.
+ * Constructs a new {@code Integer} from the specified string.
*
* @param string
- * a string representation of an int quantity.
- * @exception NumberFormatException
- * if the argument could not be parsed as an int quantity.
+ * the string representation of an integer value.
+ * @throws NumberFormatException
+ * if {@code string} can not be decoded into an integer value.
+ * @see #parseInt(String)
*/
public Integer(String string) throws NumberFormatException {
this(parseInt(string));
}
- /**
- * Answers the byte value which the receiver represents
- *
- * @return byte the value of the receiver.
- */
@Override
public byte byteValue() {
return (byte) value;
}
/**
- * <p>
- * Compares this <code>Integer</code> to the <code>Integer</code>
- * passed. If this instance's value is equal to the value of the instance
- * passed, then 0 is returned. If this instance's value is less than the
- * value of the instance passed, then a negative value is returned. If this
- * instance's value is greater than the value of the instance passed, then a
- * positive value is returned.
- * </p>
+ * Compares this object to the specified integer object to determine their
+ * relative order.
*
* @param object
- * The instance to compare to.
- * @throws NullPointerException
- * if <code>object</code> is <code>null</code>.
+ * the integer object to compare this object to.
+ * @return a negative value if the value of this integer is less than the
+ * value of {@code object}; 0 if the value of this integer and the
+ * value of {@code object} are equal; a positive value if the value
+ * of this integer is greater than the value of {@code object}.
+ * @see java.lang.Comparable
* @since 1.2
*/
public int compareTo(Integer object) {
@@ -137,16 +120,17 @@
}
/**
- * Parses the string argument as if it was an int value and returns the
- * result. Throws NumberFormatException if the string does not represent an
- * int quantity. The string may be a hexadecimal ("0x..."), octal ("0..."),
- * or decimal ("...") representation of an integer
+ * Parses the specified string and returns a {@code Integer} instance if the
+ * string can be decoded into an integer value. The string may be an
+ * optional minus sign "-" followed by a hexadecimal ("0x..." or "#..."),
+ * octal ("0..."), or decimal ("...") representation of an integer.
*
* @param string
- * a string representation of an int quantity.
- * @return Integer the value represented by the argument
- * @exception NumberFormatException
- * if the argument could not be parsed as an int quantity.
+ * a string representation of an integer value.
+ * @return an {@code Integer} containing the value represented by
+ * {@code string}.
+ * @throws NumberFormatException
+ * if {@code string} can not be parsed as an integer value.
*/
public static Integer decode(String string) throws NumberFormatException {
int length = string.length(), i = 0;
@@ -186,28 +170,20 @@
return valueOf(result);
}
- /**
- * Answers the double value which the receiver represents
- *
- * @return double the value of the receiver.
- */
@Override
public double doubleValue() {
return value;
}
/**
- * Compares the argument to the receiver, and answers true if they represent
- * the <em>same</em> object using a class specific comparison.
- * <p>
- * In this case, the argument must also be an Integer, and the receiver and
- * argument must represent the same int value.
+ * Compares this instance with the specified object and indicates if they
+ * are equal. In order to be equal, {@code o} must be an instance of
+ * {@code Integer} and have the same integer value as this object.
*
* @param o
- * the object to compare with this object
- * @return <code>true</code> if the object is the same as this object
- * <code>false</code> if it is different from this object
- * @see #hashCode
+ * the object to compare this integer with.
+ * @return {@code true} if the specified object is equal to this
+ * {@code Integer}; {@code false} otherwise.
*/
@Override
public boolean equals(Object o) {
@@ -215,24 +191,21 @@
&& (value == ((Integer) o).value);
}
- /**
- * Answers the float value which the receiver represents
- *
- * @return float the value of the receiver.
- */
@Override
public float floatValue() {
return value;
}
/**
- * Answers an Integer representing the integer value of the property named
- * by the argument. If the property could not be found, or its value could
- * not be parsed as an integer, answer null.
+ * Returns the {@code Integer} value of the system property identified by
+ * {@code string}. Returns {@code null} if {@code string} is {@code null}
+ * or empty, if the property can not be found or if its value can not be
+ * parsed as an integer.
*
* @param string
- * The name of the desired integer property.
- * @return Integer An Integer representing the value of the property.
+ * the name of the requested system property.
+ * @return the requested property's value as an {@code Integer} or
+ * {@code null}.
*/
public static Integer getInteger(String string) {
if (string == null || string.length() == 0) {
@@ -250,14 +223,18 @@
}
/**
- * Answers an Integer representing the integer value of the property named
- * by the argument. If the property could not be found, or its value could
- * not be parsed as an integer, answer an Integer representing the second
- * argument.
+ * Returns the {@code Integer} value of the system property identified by
+ * {@code string}. Returns the specified default value if {@code string} is
+ * {@code null} or empty, if the property can not be found or if its value
+ * can not be parsed as an integer.
*
* @param string
- * The name of the desired integer property.
- * @return Integer An Integer representing the value of the property.
+ * the name of the requested system property.
+ * @param defaultValue
+ * the default value that is returned if there is no integer
+ * system property with the requested name.
+ * @return the requested property's value as an {@code Integer} or the
+ * default value.
*/
public static Integer getInteger(String string, int defaultValue) {
if (string == null || string.length() == 0) {
@@ -275,13 +252,18 @@
}
/**
- * Answers an Integer representing the integer value of the property named
- * by the argument. If the property could not be found, or its value could
- * not be parsed as an integer, answer the second argument.
+ * Returns the {@code Integer} value of the system property identified by
+ * {@code string}. Returns the specified default value if {@code string} is
+ * {@code null} or empty, if the property can not be found or if its value
+ * can not be parsed as an integer.
*
* @param string
- * The name of the desired integer property.
- * @return Integer An Integer representing the value of the property.
+ * the name of the requested system property.
+ * @param defaultValue
+ * the default value that is returned if there is no integer
+ * system property with the requested name.
+ * @return the requested property's value as an {@code Integer} or the
+ * default value.
*/
public static Integer getInteger(String string, Integer defaultValue) {
if (string == null || string.length() == 0) {
@@ -298,68 +280,56 @@
}
}
- /**
- * Answers an integer hash code for the receiver. Any two objects which
- * answer <code>true</code> when passed to <code>equals</code> must
- * answer the same value for this method.
- *
- * @return the receiver's hash
- *
- * @see #equals
- */
@Override
public int hashCode() {
return value;
}
/**
- * Answers the int value which the receiver represents
+ * Gets the primitive value of this int.
*
- * @return int the value of the receiver.
+ * @return this object's primitive value.
*/
@Override
public int intValue() {
return value;
}
- /**
- * Answers the long value which the receiver represents
- *
- * @return long the value of the receiver.
- */
@Override
public long longValue() {
return value;
}
/**
- * Parses the string argument as if it was an int value and returns the
- * result. Throws NumberFormatException if the string does not represent an
- * int quantity.
+ * Parses the specified string as a signed decimal integer value. The ASCII
+ * character \u002d ('-') is recognized as the minus sign.
*
* @param string
- * a string representation of an int quantity.
- * @return int the value represented by the argument
- * @exception NumberFormatException
- * if the argument could not be parsed as an int quantity.
+ * the string representation of an integer value.
+ * @return the primitive integer value represented by {@code string}.
+ * @throws NumberFormatException
+ * if {@code string} is {@code null}, has a length of zero or
+ * can not be parsed as an integer value.
*/
public static int parseInt(String string) throws NumberFormatException {
return parseInt(string, 10);
}
/**
- * Parses the string argument as if it was an int value and returns the
- * result. Throws NumberFormatException if the string does not represent an
- * int quantity. The second argument specifies the radix to use when parsing
- * the value.
+ * Parses the specified string as a signed integer value using the specified
+ * radix. The ASCII character \u002d ('-') is recognized as the minus sign.
*
* @param string
- * a string representation of an int quantity.
+ * the string representation of an integer value.
* @param radix
- * the base to use for conversion.
- * @return int the value represented by the argument
- * @exception NumberFormatException
- * if the argument could not be parsed as an int quantity.
+ * the radix to use when parsing.
+ * @return the primitive integer value represented by {@code string} using
+ * {@code radix}.
+ * @throws NumberFormatException
+ * if {@code string} is {@code null} or has a length of zero,
+ * {@code radix < Character.MIN_RADIX},
+ * {@code radix > Character.MAX_RADIX}, or if {@code string}
+ * can not be parsed as an integer value.
*/
public static int parseInt(String string, int radix)
throws NumberFormatException {
@@ -406,23 +376,18 @@
return result;
}
- /**
- * Answers the short value which the receiver represents
- *
- * @return short the value of the receiver.
- */
@Override
public short shortValue() {
return (short) value;
}
/**
- * Answers a string containing '0' and '1' characters which describe the
- * binary representation of the argument.
+ * Converts the specified integer into its binary string representation. The
+ * returned string is a concatenation of '0' and '1' characters.
*
* @param i
- * an int to get the binary representation of
- * @return String the binary representation of the argument
+ * the integer to convert.
+ * @return the binary string representation of {@code i}.
*/
public static String toBinaryString(int i) {
int count = 1, j = i;
@@ -444,12 +409,13 @@
}
/**
- * Answers a string containing characters in the range 0..9, a..f which
- * describe the hexadecimal representation of the argument.
+ * Converts the specified integer into its hexadecimal string
+ * representation. The returned string is a concatenation of characters from
+ * '0' to '9' and 'a' to 'f'.
*
* @param i
- * an int to get the hex representation of
- * @return String the hex representation of the argument
+ * the integer to convert.
+ * @return the hexadecimal string representation of {@code i}.
*/
public static String toHexString(int i) {
int count = 1, j = i;
@@ -477,12 +443,12 @@
}
/**
- * Answers a string containing characters in the range 0..7 which describe
- * the octal representation of the argument.
+ * Converts the specified integer into its octal string representation. The
+ * returned string is a concatenation of characters from '0' to '7'.
*
* @param i
- * an int to get the octal representation of
- * @return String the hex representation of the argument
+ * the integer to convert.
+ * @return the octal string representation of {@code i}.
*/
public static String toOctalString(int i) {
int count = 1, j = i;
@@ -503,24 +469,19 @@
return new String(0, buffer.length, buffer);
}
- /**
- * Answers a string containing a concise, human-readable description of the
- * receiver.
- *
- * @return a printable representation for the receiver.
- */
@Override
public String toString() {
return Integer.toString(value);
}
/**
- * Answers a string containing characters in the range 0..9 which describe
- * the decimal representation of the argument.
+ * Converts the specified integer into its decimal string representation.
+ * The returned string is a concatenation of a minus sign if the number is
+ * negative and characters from '0' to '9'.
*
* @param value
- * an int to get the representation of
- * @return String the representation of the argument
+ * the integer to convert.
+ * @return the decimal string representation of {@code value}.
*/
public static String toString(int value) {
if (value == 0) {
@@ -613,15 +574,18 @@
}
/**
- * Answers a string containing characters in the range 0..9, a..z (depending
- * on the radix) which describe the representation of the argument in that
- * radix.
+ * Converts the specified integer into a string representation based on the
+ * specified radix. The returned string is a concatenation of a minus sign
+ * if the number is negative and characters from '0' to '9' and 'a' to 'z',
+ * depending on the radix. If {@code radix} is not in the interval defined
+ * by {@code Character.MIN_RADIX} and {@code Character.MAX_RADIX} then 10 is
+ * used as the base for the conversion.
*
* @param i
- * an int to get the representation of
+ * the integer to convert.
* @param radix
- * the base to use for conversion.
- * @return String the representation of the argument
+ * the base to use for the conversion.
+ * @return the string representation of {@code i}.
*/
public static String toString(int i, int radix) {
if (radix < Character.MIN_RADIX || radix > Character.MAX_RADIX) {
@@ -658,33 +622,37 @@
}
/**
- * Parses the string argument as if it was an int value and returns the
- * result. Throws NumberFormatException if the string does not represent an
- * int quantity.
+ * Parses the specified string as a signed decimal integer value.
*
* @param string
- * a string representation of an int quantity.
- * @return Integer the value represented by the argument
- * @exception NumberFormatException
- * if the argument could not be parsed as an int quantity.
+ * the string representation of an integer value.
+ * @return an {@code Integer} instance containing the integer value
+ * represented by {@code string}.
+ * @throws NumberFormatException
+ * if {@code string} is {@code null}, has a length of zero or
+ * can not be parsed as an integer value.
+ * @see #parseInt(String)
*/
public static Integer valueOf(String string) throws NumberFormatException {
return valueOf(parseInt(string));
}
/**
- * Parses the string argument as if it was an int value and returns the
- * result. Throws NumberFormatException if the string does not represent an
- * int quantity. The second argument specifies the radix to use when parsing
- * the value.
+ * Parses the specified string as a signed integer value using the specified
+ * radix.
*
* @param string
- * a string representation of an int quantity.
+ * the string representation of an integer value.
* @param radix
- * the base to use for conversion.
- * @return Integer the value represented by the argument
- * @exception NumberFormatException
- * if the argument could not be parsed as an int quantity.
+ * the radix to use when parsing.
+ * @return an {@code Integer} instance containing the integer value
+ * represented by {@code string} using {@code radix}.
+ * @throws NumberFormatException
+ * if {@code string} is {@code null} or has a length of zero,
+ * {@code radix < Character.MIN_RADIX},
+ * {@code radix > Character.MAX_RADIX}, or if {@code string}
+ * can not be parsed as an integer value.
+ * @see #parseInt(String, int)
*/
public static Integer valueOf(String string, int radix)
throws NumberFormatException {
@@ -692,15 +660,14 @@
}
/**
- * <p>
- * Determines the highest (leftmost) bit that is 1 and returns the value
- * that is the bit mask for that bit. This is sometimes referred to as the
- * Most Significant 1 Bit.
- * </p>
+ * Determines the highest (leftmost) bit of the specified integer that is 1
+ * and returns the bit mask value for that bit. This is also referred to as
+ * the Most Significant 1 Bit. Returns zero if the specified integer is
+ * zero.
*
* @param i
- * The <code>int</code> to interrogate.
- * @return The bit mask indicating the highest 1 bit.
+ * the integer to examine.
+ * @return the bit mask indicating the highest 1 bit in {@code i}.
* @since 1.5
*/
public static int highestOneBit(int i) {
@@ -713,15 +680,14 @@
}
/**
- * <p>
- * Determines the lowest (rightmost) bit that is 1 and returns the value
- * that is the bit mask for that bit. This is sometimes referred to as the
- * Least Significant 1 Bit.
- * </p>
+ * Determines the lowest (rightmost) bit of the specified integer that is 1
+ * and returns the bit mask value for that bit. This is also referred
+ * to as the Least Significant 1 Bit. Returns zero if the specified integer
+ * is zero.
*
* @param i
- * The <code>int</code> to interrogate.
- * @return The bit mask indicating the lowest 1 bit.
+ * the integer to examine.
+ * @return the bit mask indicating the lowest 1 bit in {@code i}.
* @since 1.5
*/
public static int lowestOneBit(int i) {
@@ -729,14 +695,12 @@
}
/**
- * <p>
- * Determines the number of leading zeros in the <code>int</code> passed
- * prior to the {@link #highestOneBit(int) highest one bit}.
- * </p>
- *
+ * Determines the number of leading zeros in the specified integer prior to
+ * the {@link #highestOneBit(int) highest one bit}.
+ *
* @param i
- * The <code>int</code> to process.
- * @return The number of leading zeros.
+ * the integer to examine.
+ * @return the number of leading zeros in {@code i}.
* @since 1.5
*/
public static int numberOfLeadingZeros(int i) {
@@ -749,14 +713,12 @@
}
/**
- * <p>
- * Determines the number of trailing zeros in the <code>int</code> passed
- * after the {@link #lowestOneBit(int) lowest one bit}.
- * </p>
- *
+ * Determines the number of trailing zeros in the specified integer after
+ * the {@link #lowestOneBit(int) lowest one bit}.
+ *
* @param i
- * The <code>int</code> to process.
- * @return The number of trailing zeros.
+ * the integer to examine.
+ * @return the number of trailing zeros in {@code i}.
* @since 1.5
*/
public static int numberOfTrailingZeros(int i) {
@@ -764,14 +726,12 @@
}
/**
- * <p>
- * Counts the number of 1 bits in the <code>int</code> value passed; this
- * is sometimes referred to as a population count.
- * </p>
- *
+ * Counts the number of 1 bits in the specified integer; this is also
+ * referred to as population count.
+ *
* @param i
- * The <code>int</code> value to process.
- * @return The number of 1 bits.
+ * the integer to examine.
+ * @return the number of 1 bits in {@code i}.
* @since 1.5
*/
public static int bitCount(int i) {
@@ -784,16 +744,14 @@
}
/**
- * <p>
- * Rotates the bits of <code>i</code> to the left by the
- * <code>distance</code> bits.
- * </p>
- *
+ * Rotates the bits of the specified integer to the left by the specified
+ * number of bits.
+ *
* @param i
- * The <code>int</code> value to rotate left.
+ * the integer value to rotate left.
* @param distance
- * The number of bits to rotate.
- * @return The rotated value.
+ * the number of bits to rotate.
+ * @return the rotated value.
* @since 1.5
*/
public static int rotateLeft(int i, int distance) {
@@ -809,16 +767,14 @@
}
/**
- * <p>
- * Rotates the bits of <code>i</code> to the right by the
- * <code>distance</code> bits.
- * </p>
- *
+ * Rotates the bits of the specified integer to the right by the specified
+ * number of bits.
+ *
* @param i
- * The <code>int</code> value to rotate right.
+ * the integer value to rotate right.
* @param distance
- * The number of bits to rotate.
- * @return The rotated value.
+ * the number of bits to rotate.
+ * @return the rotated value.
* @since 1.5
*/
public static int rotateRight(int i, int distance) {
@@ -834,13 +790,11 @@
}
/**
- * <p>
- * Reverses the bytes of a <code>int</code>.
- * </p>
+ * Reverses the order of the bytes of the specified integer.
*
* @param i
- * The <code>int</code> to reverse.
- * @return The reversed value.
+ * the integer value for which to reverse the byte order.
+ * @return the reversed value.
* @since 1.5
*/
public static int reverseBytes(int i) {
@@ -852,13 +806,11 @@
}
/**
- * <p>
- * Reverses the bytes of a <code>int</code>.
- * </p>
+ * Reverses the order of the bits of the specified integer.
*
* @param i
- * The <code>int</code> to reverse.
- * @return The reversed value.
+ * the integer value for which to reverse the bit order.
+ * @return the reversed value.
* @since 1.5
*/
public static int reverse(int i) {
@@ -870,15 +822,13 @@
}
/**
- * <p>
- * The <code>signum</code> function for <code>int</code> values. This
- * method returns -1 for negative values, 1 for positive values and 0 for
- * the value 0.
- * </p>
+ * Returns the value of the {@code signum} function for the specified
+ * integer.
*
* @param i
- * The <code>int</code> value.
- * @return -1 if negative, 1 if positive otherwise 0.
+ * the integer value to check.
+ * @return -1 if {@code i} is negative, 1 if {@code i} is positive, 0 if
+ * {@code i} is zero.
* @since 1.5
*/
public static int signum(int i) {
@@ -886,15 +836,15 @@
}
/**
+ * Returns a {@code Integer} instance for the specified integer value.
* <p>
- * Returns a <code>Integer</code> instance for the <code>int</code>
- * value passed. This method is preferred over the constructor, as this
- * method may maintain a cache of instances.
- * </p>
- *
+ * If it is not necessary to get a new {@code Integer} instance, it is
+ * recommended to use this method instead of the constructor, since it
+ * maintains a cache of instances which may result in better performance.
+ *
* @param i
- * The int value.
- * @return A <code>Integer</code> instance.
+ * the integer value to store in the instance.
+ * @return a {@code Integer} instance containing {@code i}.
* @since 1.5
*/
public static Integer valueOf(int i) {
@@ -909,7 +859,6 @@
/**
* <p>
* A cache of instances used by {@link Integer#valueOf(int)} and auto-boxing.
- * </p>
*/
static final Integer[] CACHE = new Integer[256];
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InternalError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InternalError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InternalError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InternalError.java Sat May 2 08:09:50 2009
@@ -17,30 +17,30 @@
package java.lang;
-
/**
- * This error is thrown when the VM notices that it has gotten into a state
- * which it does not understand.
+ * Thrown when the virtual machine notices that it has gotten into an undefined
+ * state.
*/
public class InternalError extends VirtualMachineError {
private static final long serialVersionUID = -9062593416125562365L;
/**
- * Constructs a new instance of this class with its walkback filled in.
- */
- public InternalError() {
- super();
- }
+ * Constructs a new {@code InternalError} that includes the current stack
+ * trace.
+ */
+ public InternalError() {
+ super();
+ }
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- * @param detailMessage
- * String The detail message for the exception.
- */
- public InternalError(String detailMessage) {
- super(detailMessage);
- }
+ /**
+ * Constructs a new {@code InternalError} with the current stack trace and
+ * the specified detail message.
+ *
+ * @param detailMessage
+ * the detail message for this error.
+ */
+ public InternalError(String detailMessage) {
+ super(detailMessage);
+ }
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InterruptedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InterruptedException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InterruptedException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InterruptedException.java Sat May 2 08:09:50 2009
@@ -17,30 +17,30 @@
package java.lang;
-
/**
- * This exception is thrown when a waiting thread is activated before the
- * condition it was waiting on has been satisfied.
+ * Thrown when a waiting thread is activated before the condition it was waiting
+ * for has been satisfied.
*/
public class InterruptedException extends Exception {
private static final long serialVersionUID = 6700697376100628473L;
/**
- * Constructs a new instance of this class with its walkback filled in.
- */
- public InterruptedException() {
- super();
- }
+ * Constructs a new {@code InterruptedException} that includes the current
+ * stack trace.
+ */
+ public InterruptedException() {
+ super();
+ }
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- * @param detailMessage
- * String The detail message for the exception.
- */
- public InterruptedException(String detailMessage) {
- super(detailMessage);
- }
+ /**
+ * Constructs a new {@code InterruptedException} with the current stack
+ * trace and the specified detail message.
+ *
+ * @param detailMessage
+ * the detail message for this exception.
+ */
+ public InterruptedException(String detailMessage) {
+ super(detailMessage);
+ }
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Iterable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Iterable.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Iterable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Iterable.java Sat May 2 08:09:50 2009
@@ -19,16 +19,17 @@
import java.util.Iterator;
/**
- * <p>Implementations of this interface can be used within a <code>foreach</code>
- * statement.</p>
+ * Objects of classes that implement this interface can be used within a
+ * {@code foreach} statement.
+ *
* @since 1.5
*/
public interface Iterable<T> {
/**
- * <p>Returns an {@link Iterator} for the elements in this object.</p>
+ * Returns an {@link Iterator} for the elements in this object.
*
- * @return An <code>Iterator</code> instance.
+ * @return An {@code Iterator} instance.
*/
Iterator<T> iterator();
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/LinkageError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/LinkageError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/LinkageError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/LinkageError.java Sat May 2 08:09:50 2009
@@ -19,8 +19,8 @@
/**
- * This class is the superclass of all classes which represent errors that occur
- * when loading and linking class files.
+ * {@code LinkageError} is the superclass of all error classes that occur when
+ * loading and linking class files.
*
* @see Error
*/
@@ -29,20 +29,21 @@
private static final long serialVersionUID = 3579600108157160122L;
/**
- * Constructs a new instance of this class with its walkback filled in.
- */
- public LinkageError() {
- super();
- }
+ * Constructs a new {@code LinkageError} that includes the current stack
+ * trace.
+ */
+ public LinkageError() {
+ super();
+ }
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- * @param detailMessage
- * String The detail message for the exception.
- */
- public LinkageError(String detailMessage) {
- super(detailMessage);
- }
+ /**
+ * Constructs a new {@code LinkageError} with the current stack trace and
+ * the specified detail message.
+ *
+ * @param detailMessage
+ * the detail message for this error.
+ */
+ public LinkageError(String detailMessage) {
+ super(detailMessage);
+ }
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Long.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Long.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Long.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Long.java Sat May 2 08:09:50 2009
@@ -18,17 +18,13 @@
package java.lang;
/**
+ * The wrapper for the primitive type {@code long}.
* <p>
- * Long is the wrapper for the primitive type <code>long</code>.
- * </p>
- *
- * <p>
- * As with the specification, this implementation relied on code laid out in <a
+ * As with the specification, this implementation relies on code laid out in <a
* href="http://www.hackersdelight.org/">Henry S. Warren, Jr.'s Hacker's
* Delight, (Addison Wesley, 2002)</a> as well as <a
* href="http://aggregate.org/MAGIC/">The Aggregate's Magic Algorithms</a>.
- * </p>
- *
+ *
* @see java.lang.Number
* @since 1.0
*/
@@ -42,21 +38,17 @@
private final long value;
/**
- * <p>
- * Constant for the maximum <code>long</code> value, 2<sup>63</sup>-1.
- * </p>
+ * Constant for the maximum {@code long} value, 2<sup>63</sup>-1.
*/
public static final long MAX_VALUE = 0x7FFFFFFFFFFFFFFFL;
/**
- * <p>
- * Constant for the minimum <code>long</code> value, -2<sup>31</sup>.
- * </p>
+ * Constant for the minimum {@code long} value, -2<sup>63</sup>.
*/
public static final long MIN_VALUE = 0x8000000000000000L;
/**
- * The java.lang.Class that represents this class.
+ * The {@link Class} object that represents the primitive type {@code long}.
*/
@SuppressWarnings("unchecked")
public static final Class<Long> TYPE = (Class<Long>) new long[0].getClass()
@@ -66,63 +58,53 @@
// defined to be "java.lang.Long.TYPE";
/**
- * <p>
- * Constant for the number of bits to represent a <code>long</code> in
- * two's compliment form.
- * </p>
- *
+ * Constant for the number of bits needed to represent a {@code long} in
+ * two's complement form.
+ *
* @since 1.5
*/
public static final int SIZE = 64;
/**
- * Constructs a new instance of the receiver which represents the long
- * valued argument.
+ * Constructs a new {@code Long} with the specified primitive long value.
*
* @param value
- * the long to store in the new instance.
+ * the primitive long value to store in the new instance.
*/
public Long(long value) {
this.value = value;
}
/**
- * Constructs a new instance of this class given a string.
+ * Constructs a new {@code Long} from the specified string.
*
* @param string
- * a string representation of an long quantity.
- * @exception NumberFormatException
- * if the argument could not be parsed as a long quantity.
+ * the string representation of a long value.
+ * @throws NumberFormatException
+ * if {@code string} can not be decoded into a long value.
+ * @see #parseLong(String)
*/
public Long(String string) throws NumberFormatException {
this(parseLong(string));
}
- /**
- * Answers the byte value which the receiver represents
- *
- * @return byte the value of the receiver.
- */
@Override
public byte byteValue() {
return (byte) value;
}
/**
- * <p>
- * Compares this <code>Long</code> to the <code>Long</code> passed. If
- * this instance's value is equal to the value of the instance passed, then
- * 0 is returned. If this instance's value is less than the value of the
- * instance passed, then a negative value is returned. If this instance's
- * value is greater than the value of the instance passed, then a positive
- * value is returned.
- * </p>
+ * Compares this object to the specified long object to determine their
+ * relative order.
*
* @param object
- * The instance to compare to.
- * @throws NullPointerException
- * if <code>object</code> is <code>null</code>.
+ * the long object to compare this object to.
+ * @return a negative value if the value of this long is less than the value
+ * of {@code object}; 0 if the value of this long and the value of
+ * {@code object} are equal; a positive value if the value of this
+ * long is greater than the value of {@code object}.
+ * @see java.lang.Comparable
* @since 1.2
*/
public int compareTo(Long object) {
@@ -130,16 +112,16 @@
}
/**
- * Parses the string argument as if it was a long value and returns the
- * result. Throws NumberFormatException if the string does not represent a
- * long quantity. The string may be a hexadecimal ("0x..."), octal ("0..."),
- * or decimal ("...") representation of a long.
+ * Parses the specified string and returns a {@code Long} instance if the
+ * string can be decoded into a long value. The string may be an optional
+ * minus sign "-" followed by a hexadecimal ("0x..." or "#..."), octal
+ * ("0..."), or decimal ("...") representation of a long.
*
* @param string
- * a string representation of an long quantity.
- * @return Long the value represented by the argument
- * @exception NumberFormatException
- * if the argument could not be parsed as an long quantity.
+ * a string representation of a long value.
+ * @return a {@code Long} containing the value represented by {@code string}.
+ * @throws NumberFormatException
+ * if {@code string} can not be parsed as a long value.
*/
public static Long decode(String string) throws NumberFormatException {
int length = string.length(), i = 0;
@@ -181,28 +163,20 @@
return valueOf(result);
}
- /**
- * Answers the double value which the receiver represents
- *
- * @return double the value of the receiver.
- */
@Override
public double doubleValue() {
return value;
}
/**
- * Compares the argument to the receiver, and answers true if they represent
- * the <em>same</em> object using a class specific comparison.
- * <p>
- * In this case, the argument must also be an Long, and the receiver and
- * argument must represent the same long value.
+ * Compares this instance with the specified object and indicates if they
+ * are equal. In order to be equal, {@code o} must be an instance of
+ * {@code Long} and have the same long value as this object.
*
* @param o
- * the object to compare with this object
- * @return <code>true</code> if the object is the same as this object
- * <code>false</code> if it is different from this object
- * @see #hashCode
+ * the object to compare this long with.
+ * @return {@code true} if the specified object is equal to this
+ * {@code Long}; {@code false} otherwise.
*/
@Override
public boolean equals(Object o) {
@@ -210,24 +184,20 @@
&& (value == ((Long) o).value);
}
- /**
- * Answers the float value which the receiver represents
- *
- * @return float the value of the receiver.
- */
@Override
public float floatValue() {
return value;
}
/**
- * Answers a Long representing the long value of the property named by the
- * argument. If the property could not be found, or its value could not be
- * parsed as a long, answer null.
+ * Returns the {@code Long} value of the system property identified by
+ * {@code string}. Returns {@code null} if {@code string} is {@code null}
+ * or empty, if the property can not be found or if its value can not be
+ * parsed as a long.
*
* @param string
- * The name of the desired integer property.
- * @return Long A Long representing the value of the property.
+ * the name of the requested system property.
+ * @return the requested property's value as a {@code Long} or {@code null}.
*/
public static Long getLong(String string) {
if (string == null || string.length() == 0) {
@@ -245,13 +215,18 @@
}
/**
- * Answers a Long representing the long value of the property named by the
- * argument. If the property could not be found, or its value could not be
- * parsed as a long, answer a Long representing the second argument.
+ * Returns the {@code Long} value of the system property identified by
+ * {@code string}. Returns the specified default value if {@code string} is
+ * {@code null} or empty, if the property can not be found or if its value
+ * can not be parsed as a long.
*
* @param string
- * The name of the desired long property.
- * @return Long An Long representing the value of the property.
+ * the name of the requested system property.
+ * @param defaultValue
+ * the default value that is returned if there is no long system
+ * property with the requested name.
+ * @return the requested property's value as a {@code Long} or the default
+ * value.
*/
public static Long getLong(String string, long defaultValue) {
if (string == null || string.length() == 0) {
@@ -269,13 +244,18 @@
}
/**
- * Answers an Long representing the long value of the property named by the
- * argument. If the property could not be found, or its value could not be
- * parsed as an long, answer the second argument.
+ * Returns the {@code Long} value of the system property identified by
+ * {@code string}. Returns the specified default value if {@code string} is
+ * {@code null} or empty, if the property can not be found or if its value
+ * can not be parsed as a long.
*
* @param string
- * The name of the desired long property.
- * @return Long An Long representing the value of the property.
+ * the name of the requested system property.
+ * @param defaultValue
+ * the default value that is returned if there is no long system
+ * property with the requested name.
+ * @return the requested property's value as a {@code Long} or the default
+ * value.
*/
public static Long getLong(String string, Long defaultValue) {
if (string == null || string.length() == 0) {
@@ -292,34 +272,20 @@
}
}
- /**
- * Answers an integer hash code for the receiver. Any two objects which
- * answer <code>true</code> when passed to <code>equals</code> must
- * answer the same value for this method.
- *
- * @return the receiver's hash
- *
- * @see #equals
- */
@Override
public int hashCode() {
return (int) (value ^ (value >>> 32));
}
- /**
- * Answers the int value which the receiver represents
- *
- * @return int the value of the receiver.
- */
@Override
public int intValue() {
return (int) value;
}
/**
- * Answers the long value which the receiver represents
+ * Gets the primitive value of this long.
*
- * @return long the value of the receiver.
+ * @return this object's primitive value.
*/
@Override
public long longValue() {
@@ -327,33 +293,35 @@
}
/**
- * Parses the string argument as if it was a long value and returns the
- * result. Throws NumberFormatException if the string does not represent a
- * long quantity.
+ * Parses the specified string as a signed decimal long value. The ASCII
+ * character \u002d ('-') is recognized as the minus sign.
*
* @param string
- * a string representation of a long quantity.
- * @return long the value represented by the argument
- * @exception NumberFormatException
- * if the argument could not be parsed as a long quantity.
+ * the string representation of a long value.
+ * @return the primitive long value represented by {@code string}.
+ * @throws NumberFormatException
+ * if {@code string} is {@code null}, has a length of zero or
+ * can not be parsed as a long value.
*/
public static long parseLong(String string) throws NumberFormatException {
return parseLong(string, 10);
}
/**
- * Parses the string argument as if it was an long value and returns the
- * result. Throws NumberFormatException if the string does not represent an
- * long quantity. The second argument specifies the radix to use when
- * parsing the value.
+ * Parses the specified string as a signed long value using the specified
+ * radix. The ASCII character \u002d ('-') is recognized as the minus sign.
*
* @param string
- * a string representation of an long quantity.
+ * the string representation of a long value.
* @param radix
- * the base to use for conversion.
- * @return long the value represented by the argument
- * @exception NumberFormatException
- * if the argument could not be parsed as an long quantity.
+ * the radix to use when parsing.
+ * @return the primitive long value represented by {@code string} using
+ * {@code radix}.
+ * @throws NumberFormatException
+ * if {@code string} is {@code null} or has a length of zero,
+ * {@code radix < Character.MIN_RADIX},
+ * {@code radix > Character.MAX_RADIX}, or if {@code string}
+ * can not be parsed as a long value.
*/
public static long parseLong(String string, int radix)
throws NumberFormatException {
@@ -400,23 +368,18 @@
return result;
}
- /**
- * Answers the short value which the receiver represents
- *
- * @return short the value of the receiver.
- */
@Override
public short shortValue() {
return (short) value;
}
/**
- * Answers a string containing '0' and '1' characters which describe the
- * binary representation of the argument.
+ * Converts the specified long value into its binary string representation.
+ * The returned string is a concatenation of '0' and '1' characters.
*
* @param l
- * a long to get the binary representation of
- * @return String the binary representation of the argument
+ * the long value to convert.
+ * @return the binary string representation of {@code l}.
*/
public static String toBinaryString(long l) {
int count = 1;
@@ -439,12 +402,13 @@
}
/**
- * Answers a string containing characters in the range 0..7, a..f which
- * describe the hexadecimal representation of the argument.
+ * Converts the specified long value into its hexadecimal string
+ * representation. The returned string is a concatenation of characters from
+ * '0' to '9' and 'a' to 'f'.
*
* @param l
- * a long to get the hex representation of
- * @return String the hex representation of the argument
+ * the long value to convert.
+ * @return the hexadecimal string representation of {@code l}.
*/
public static String toHexString(long l) {
int count = 1;
@@ -473,12 +437,12 @@
}
/**
- * Answers a string containing characters in the range 0..7 which describe
- * the octal representation of the argument.
+ * Converts the specified long value into its octal string representation.
+ * The returned string is a concatenation of characters from '0' to '7'.
*
* @param l
- * a long to get the octal representation of
- * @return String the octal representation of the argument
+ * the long value to convert.
+ * @return the octal string representation of {@code l}.
*/
public static String toOctalString(long l) {
int count = 1;
@@ -500,39 +464,37 @@
return new String(0, buffer.length, buffer);
}
- /**
- * Answers a string containing a concise, human-readable description of the
- * receiver.
- *
- * @return a printable representation for the receiver.
- */
@Override
public String toString() {
return Long.toString(value);
}
/**
- * Answers a string containing characters in the range 0..9 which describe
- * the decimal representation of the argument.
+ * Converts the specified long value into its decimal string representation.
+ * The returned string is a concatenation of a minus sign if the number is
+ * negative and characters from '0' to '9'.
*
* @param l
- * a long to get the representation of
- * @return String the representation of the argument
+ * the long to convert.
+ * @return the decimal string representation of {@code l}.
*/
public static String toString(long l) {
return toString(l, 10);
}
/**
- * Answers a string containing characters in the range 0..9, a..z (depending
- * on the radix) which describe the representation of the argument in that
- * radix.
+ * Converts the specified long value into a string representation based on
+ * the specified radix. The returned string is a concatenation of a minus
+ * sign if the number is negative and characters from '0' to '9' and 'a' to
+ * 'z', depending on the radix. If {@code radix} is not in the interval
+ * defined by {@code Character.MIN_RADIX} and {@code Character.MAX_RADIX}
+ * then 10 is used as the base for the conversion.
*
* @param l
- * a long to get the representation of
+ * the long to convert.
* @param radix
- * the base to use for conversion.
- * @return String the representation of the argument
+ * the base to use for the conversion.
+ * @return the string representation of {@code l}.
*/
public static String toString(long l, int radix) {
if (radix < Character.MIN_RADIX || radix > Character.MAX_RADIX) {
@@ -570,33 +532,37 @@
}
/**
- * Parses the string argument as if it was an long value and returns the
- * result. Throws NumberFormatException if the string does not represent an
- * long quantity.
+ * Parses the specified string as a signed decimal long value.
*
* @param string
- * a string representation of an long quantity.
- * @return Long the value represented by the argument
- * @exception NumberFormatException
- * if the argument could not be parsed as an long quantity.
+ * the string representation of a long value.
+ * @return a {@code Long} instance containing the long value represented by
+ * {@code string}.
+ * @throws NumberFormatException
+ * if {@code string} is {@code null}, has a length of zero or
+ * can not be parsed as a long value.
+ * @see #parseLong(String)
*/
public static Long valueOf(String string) throws NumberFormatException {
return valueOf(parseLong(string));
}
/**
- * Parses the string argument as if it was an long value and returns the
- * result. Throws NumberFormatException if the string does not represent an
- * long quantity. The second argument specifies the radix to use when
- * parsing the value.
+ * Parses the specified string as a signed long value using the specified
+ * radix.
*
* @param string
- * a string representation of an long quantity.
+ * the string representation of a long value.
* @param radix
- * the base to use for conversion.
- * @return Long the value represented by the argument
- * @exception NumberFormatException
- * if the argument could not be parsed as an long quantity.
+ * the radix to use when parsing.
+ * @return a {@code Long} instance containing the long value represented by
+ * {@code string} using {@code radix}.
+ * @throws NumberFormatException
+ * if {@code string} is {@code null} or has a length of zero,
+ * {@code radix < Character.MIN_RADIX},
+ * {@code radix > Character.MAX_RADIX}, or if {@code string}
+ * can not be parsed as a long value.
+ * @see #parseLong(String, int)
*/
public static Long valueOf(String string, int radix)
throws NumberFormatException {
@@ -604,15 +570,14 @@
}
/**
- * <p>
- * Determines the highest (leftmost) bit that is 1 and returns the value
- * that is the bit mask for that bit. This is sometimes referred to as the
- * Most Significant 1 Bit.
- * </p>
+ * Determines the highest (leftmost) bit of the specified long value that is
+ * 1 and returns the bit mask value for that bit. This is also referred to
+ * as the Most Significant 1 Bit. Returns zero if the specified long is
+ * zero.
*
* @param lng
- * The <code>long</code> to interrogate.
- * @return The bit mask indicating the highest 1 bit.
+ * the long to examine.
+ * @return the bit mask indicating the highest 1 bit in {@code lng}.
* @since 1.5
*/
public static long highestOneBit(long lng) {
@@ -626,15 +591,14 @@
}
/**
- * <p>
- * Determines the lowest (rightmost) bit that is 1 and returns the value
- * that is the bit mask for that bit. This is sometimes referred to as the
- * Least Significant 1 Bit.
- * </p>
+ * Determines the lowest (rightmost) bit of the specified long value that is
+ * 1 and returns the bit mask value for that bit. This is also referred to
+ * as the Least Significant 1 Bit. Returns zero if the specified long is
+ * zero.
*
* @param lng
- * The <code>long</code> to interrogate.
- * @return The bit mask indicating the lowest 1 bit.
+ * the long to examine.
+ * @return the bit mask indicating the lowest 1 bit in {@code lng}.
* @since 1.5
*/
public static long lowestOneBit(long lng) {
@@ -642,14 +606,12 @@
}
/**
- * <p>
- * Determines the number of leading zeros in the <code>long</code> passed
- * prior to the {@link #highestOneBit(long) highest one bit}.
- * </p>
- *
+ * Determines the number of leading zeros in the specified long value prior
+ * to the {@link #highestOneBit(long) highest one bit}.
+ *
* @param lng
- * The <code>long</code> to process.
- * @return The number of leading zeros.
+ * the long to examine.
+ * @return the number of leading zeros in {@code lng}.
* @since 1.5
*/
public static int numberOfLeadingZeros(long lng) {
@@ -663,14 +625,12 @@
}
/**
- * <p>
- * Determines the number of trailing zeros in the <code>long</code> passed
- * after the {@link #lowestOneBit(long) lowest one bit}.
- * </p>
- *
+ * Determines the number of trailing zeros in the specified long value after
+ * the {@link #lowestOneBit(long) lowest one bit}.
+ *
* @param lng
- * The <code>long</code> to process.
- * @return The number of trailing zeros.
+ * the long to examine.
+ * @return the number of trailing zeros in {@code lng}.
* @since 1.5
*/
public static int numberOfTrailingZeros(long lng) {
@@ -678,14 +638,12 @@
}
/**
- * <p>
- * Counts the number of 1 bits in the <code>long</code> value passed; this
- * is sometimes referred to as a population count.
- * </p>
- *
+ * Counts the number of 1 bits in the specified long value; this is also
+ * referred to as population count.
+ *
* @param lng
- * The <code>long</code> value to process.
- * @return The number of 1 bits.
+ * the long to examine.
+ * @return the number of 1 bits in {@code lng}.
* @since 1.5
*/
public static int bitCount(long lng) {
@@ -700,16 +658,14 @@
}
/**
- * <p>
- * Rotates the bits of <code>lng</code> to the left by the
- * <code>distance</code> bits.
- * </p>
- *
+ * Rotates the bits of the specified long value to the left by the specified
+ * number of bits.
+ *
* @param lng
- * The <code>long</code> value to rotate left.
+ * the long value to rotate left.
* @param distance
- * The number of bits to rotate.
- * @return The rotated value.
+ * the number of bits to rotate.
+ * @return the rotated value.
* @since 1.5
*/
public static long rotateLeft(long lng, int distance) {
@@ -726,15 +682,14 @@
/**
* <p>
- * Rotates the bits of <code>lng</code> to the right by the
- * <code>distance</code> bits.
- * </p>
- *
+ * Rotates the bits of the specified long value to the right by the
+ * specified number of bits.
+ *
* @param lng
- * The <code>long</code> value to rotate right.
+ * the long value to rotate right.
* @param distance
- * The number of bits to rotate.
- * @return The rotated value.
+ * the number of bits to rotate.
+ * @return the rotated value.
* @since 1.5
*/
public static long rotateRight(long lng, int distance) {
@@ -750,13 +705,11 @@
}
/**
- * <p>
- * Reverses the bytes of a <code>long</code>.
- * </p>
+ * Reverses the order of the bytes of the specified long value.
*
* @param lng
- * The <code>long</code> to reverse.
- * @return The reversed value.
+ * the long value for which to reverse the byte order.
+ * @return the reversed value.
* @since 1.5
*/
public static long reverseBytes(long lng) {
@@ -772,13 +725,11 @@
}
/**
- * <p>
- * Reverses the bytes of a <code>long</code>.
- * </p>
+ * Reverses the order of the bits of the specified long value.
*
* @param lng
- * The <code>long</code> to reverse.
- * @return The reversed value.
+ * the long value for which to reverse the bit order.
+ * @return the reversed value.
* @since 1.5
*/
public static long reverse(long lng) {
@@ -793,15 +744,13 @@
}
/**
- * <p>
- * The <code>signum</code> function for <code>long</code> values. This
- * method returns -1 for negative values, 1 for positive values and 0 for
- * the value 0.
- * </p>
+ * Returns the value of the {@code signum} function for the specified long
+ * value.
*
* @param lng
- * The <code>long</code> value.
- * @return -1 if negative, 1 if positive otherwise 0.
+ * the long value to check.
+ * @return -1 if {@code lng} is negative, 1 if {@code lng} is positive, 0 if
+ * {@code lng} is zero.
* @since 1.5
*/
public static int signum(long lng) {
@@ -809,15 +758,15 @@
}
/**
+ * Returns a {@code Long} instance for the specified long value.
* <p>
- * Returns a <code>Long</code> instance for the <code>long</code> value
- * passed. This method is preferred over the constructor, as this method may
- * maintain a cache of instances.
- * </p>
- *
+ * If it is not necessary to get a new {@code Long} instance, it is
+ * recommended to use this method instead of the constructor, since it
+ * maintains a cache of instances which may result in better performance.
+ *
* @param lng
- * The long value.
- * @return A <code>Long</code> instance.
+ * the long value to store in the instance.
+ * @return a {@code Long} instance containing {@code lng}.
* @since 1.5
*/
public static Long valueOf(long lng) {
@@ -831,7 +780,6 @@
/**
* <p>
* A cache of instances used by {@link Long#valueOf(long)} and auto-boxing.
- * </p>
*/
static final Long[] CACHE = new Long[256];