Java Core Reflection

The class java.lang.reflect.Array

    package java.lang.reflect;

    public final class Array extends Object

The Array class is an uninstantiable class that exports static methods to create Java arrays with primitive or class component types, and to get and set array component values.

Methods

newInstance

    public static Object newInstance(Class componentType, int length)

        throws NullPointerException, NegativeArraySizeException

Returns a new array with the specified component type and length. The array is created as if by the equivalent array creation expression, namely:

new componentType[length] The method throws a NullPointerException if the specified componentType argument is null.

The method throws a NegativeArraySizeException if the specified length argument is negative.

newInstance

    public static Object newInstance(Class componentType,

                                 int[] dimensions)

        throws NullPointerException, IllegalArgumentException,

            NegativeArraySizeException

Returns a new array with the specified component type and dimensions. The array is created as if by the equivalent array creation expression, namely:

new componentType[dimensions[0]][dimensions[1]]... The method throws a NullPointerException if either the componentType argument or the dimensions argument is null.

The method throws an IllegalArgumentException if the specified dimensions argument is a zero-dimensional array, or if the number of requested dimensions exceeds the limit on the number of array dimensions supported by the implementation (typically 255).

The method throws a NegativeArraySizeException if any of the elements of the specified dimensions array is negative.

getLength

    public static int getLength(Object array)

        throws NullPointerException, IllegalArgumentException

Returns the length of the specified array.

Throws a NullPointerException if the specified object argument is null.

Throws an IllegalArgumentException if the specified object argument is not an array.

get

    public static Object get(Object array, int index)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Returns the value of the indexed component of the specified array object. The value is automatically wrapped in an object if it has a primitive type.

The operation proceeds as follows:

If the specified object is null, the method throws a NullPointerException.
If the specified object is not an array, the method throws an IllegalArgumentException.
If the specified index argument is negative, or if it is greater than or equal to the length of the specified array, the method throws an ArrayIndexOutOfBoundsException.
The value of the indexed component is fetched. If the array's component type is primitive, the value is wrapped in an object. The possibly wrapped value is returned.

Primitive variants of Array.get are also provided for efficiency; these avoid the final wrapping conversion. They are described below.

getBoolean

    public static boolean getBoolean(Object array, int index)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Returns the value of the indexed element in the specified array object, as a boolean. See Array.get for the detailed procedure.

If the indexed value is not of type boolean, the method throws an IllegalArgumentException.

getByte

    public static byte getByte(Object array, int index)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Returns the value of the indexed element in the specified array object, as a byte. See Array.get for the detailed procedure.

If the indexed value is not of type byte, the method throws an IllegalArgumentException.

getChar

    public static char getChar(Object array, int index)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Returns the value of the indexed element in the specified array object, as a char. See Array.get for the detailed procedure.

If the indexed value is not of type char, the method throws an IllegalArgumentException.

getShort

    public static short getShort(Object array, int index)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Returns the value of the indexed element in the specified array object, as a short. See Array.get for the detailed procedure.

If the indexed value cannot be converted to a short by an identity or widening conversion, the method throws an IllegalArgumentException.

getInt

    public static int getInt(Object array, int index)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Returns the value of the indexed element in the specified array object, as an int. See Array.get for the detailed procedure.

If the indexed value cannot be converted to an int by an identity conversion or a widening conversion, the method throws an IllegalArgumentException.

getLong

    public static long getLong(Object array, int index)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Returns the value of the indexed element in the specified array object, as a long. See Array.get for the detailed procedure.

If the indexed value cannot be converted to a long by an identity conversion or a widening conversion, the method throws an IllegalArgumentException.

getFloat

    public static float getFloat(Object array, int index)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Returns the value of the indexed element in the specified array object, as a float. See Array.get for the detailed procedure.

If the indexed value cannot be converted to a float by an identity conversion or a widening conversion, the method throws an IllegalArgumentException.

getDouble

    public static double getDouble(Object array, int index)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Returns the value of the indexed element in the specified array object, as a double. See Array.get for the detailed procedure.

If the indexed value cannot be converted to a double by an identity conversion or a widening conversion, the method throws an IllegalArgumentException.

set

    public static void set(Object array, int index, Object value)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Sets the indexed component of the specified array object to the specified new value. The new value is first automatically unwrapped if the array has a primitive component type.

The operation proceeds as follows:

If the specified object argument is null, the method throws a NullPointerException.
If the specified object argument is not an array, the method throws an IllegalArgumentException.
If the specified index argument is negative, or if it is greater than or equal to the length of the specified array, the method throws an ArrayIndexOutOfBoundsException.
If the array has a primitive component type, an unwrapping conversion is attempted to convert the new object value to a value of a primitive type. If the object parameter is null, the conversion fails by throwing a NullPointerException. If the object parameter is not an instance of a standard Java wrapper class, the conversion fails by throwing an IllegalArgumentException.
If, after possible unwrapping, the new value cannot be converted to a value of the array component type by an identity conversion or a widening conversion, the method throws an IllegalArgumentException.
The indexed array component is set to the possibly unwrapped and widened new value.

Primitive variants of Array.set are also provided for efficiency; these let user code avoid having to wrap the new value. They are described below.

setBoolean

    public static void setBoolean(Object array, int index, boolean z)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Sets the indexed element of the specified array object to the specified boolean value. See Array.set for the detailed procedure.

setByte

    public static void setByte(Object array, int index, byte b)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Sets the indexed element of the specified array object to the specified byte value. See Array.set for the detailed procedure.

setChar

    public static void setChar(Object array, int index, char c)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Sets the indexed element of the specified array object to the specified char value. See Array.set for the detailed procedure.

setShort

    public static void setShort(Object array, int index, short s)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Sets the indexed component of the specified array object to the specified short value. See Array.set for the detailed procedure.

setInt

    public static void setInt(Object array, int index, int i)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Sets the indexed component of the specified array object to the specified int value. See Array.set for the detailed procedure.

setLong

    public static void setLong(Object array, int index, long l)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Sets the indexed component of the specified array object to the specified long value. See Array.set for the detailed procedure.

setFloat

    public static void setFloat(Object array, int index, float f)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Sets the indexed component of the specified array object to the specified float value. See Array.set for the detailed procedure.

setDouble

    public static void setDouble(Object array, int index, double d)

        throws NullPointerException, IllegalArgumentException,

            ArrayIndexOutOfBoundsException

Sets the indexed component of the specified array object to the specified double value. See Array.set for the detailed procedure.

Contents | Prev | Next