Contents | Prev | Next | 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

Copyright © 1996, 1997 Sun Microsystems, Inc. All rights reserved.