Java Array源码总结 Array源码注释翻译和解析中英文对照版

版本
JDK8(JDK1.8)

Array final类（无法被继承）源码重点
1.Array类提供静态方法来动态创建和访问Java数组。

2.Array允许在get或set操作期间进行加宽转换，但如果发生缩小转换，则抛出IllegalArgumentException，这里的加宽指的是字节范围加宽，如int->double是合法的，而不是指数组长度加宽

3.Array类内部有两个私有原生方法用于创建数组，newArray和multiNewArray, 分别对应创建一维数组和创建多维数组

4.Array类的部分方法

方法名	作用
Object newInstance(Class<?> componentType, int length)	创建特定类型，长度为length的一维数组，底层调用newArray(.)方法
Object newInstance(Class<?> componentType, int… dimensions)	创建特定类型的多维数组，底层调用multiNewArray(.)方法
Object newArray(Class<?> componentType, int length)	创建长度为length的一维数组
Object multiNewArray(Class<?> componentType, int[] dimensions)	根据dimensions数组中的值创建特定维度长度的多维数组
int getLength(Object array)	以int形式返回指定数组对象的长度
Object get(Object array, int index)	返回指定数组对象中索引元素的值
boolean getBoolean(Object array, int index)	以boolean形式返回指定数组对象中索引元素的值
byte getByte(Object array, int index)	以byte的形式返回指定数组对象中索引组件的值
char getChar(Object array, int index)	以char的形式返回指定数组对象中索引组件的值
short getShort(Object array, int index)	以short的形式返回指定数组对象中索引组件的值
int getInt(Object array, int index)	以int的形式返回指定数组对象中索引组件的值
long getLong(Object array, int index)	以long的形式返回指定数组对象中索引组件的值
float getFloat(Object array, int index)	以float的形式返回指定数组对象中索引组件的值
double getDouble(Object array, int index)	以double的形式返回指定数组对象中索引组件的值
void set(Object array, int index, Object value)	将指定数组对象的索引组件的值设置为指定的新值
void setBoolean(Object array, int index, boolean z)	将指定数组对象的索引组件的值设置为指定的boolean值
void setByte(Object array, int index, byte b)	将指定数组对象的索引组件的值设置为指定的byte值
void setChar(Object array, int index, char c)	将指定数组对象的索引组件的值设置为指定的char值
void setShort(Object array, int index, short s)	将指定数组对象的索引组件的值设置为指定的short值
void setInt(Object array, int index, int i)	将指定数组对象的索引组件的值设置为指定的int值
void setLong(Object array, int index, long l)	将指定数组对象的索引组件的值设置为指定的long值
void setFloat(Object array, int index, float f)	将指定数组对象的索引组件的值设置为指定的float值
void setDouble(Object array, int index, double d)	将指定数组对象的索引组件的值设置为指定的double值

Array final类源码

package java.lang.reflect;

import jdk.internal.HotSpotIntrinsicCandidate;

/**
 * The {@code Array} class provides static methods to dynamically create and
 * access Java arrays.
 * Array类提供静态方法来动态创建和访问Java数组。
 *
 * <p>{@code Array} permits widening conversions to occur during a get or set
 * operation, but throws an {@code IllegalArgumentException} if a narrowing
 * conversion would occur.
 * 
 * Array允许在get或set操作期间进行加宽转换，但如果发生缩小转换，则抛出IllegalArgumentException
 *
 * @author Nakul Saraiya
 * @since 1.1
 */
public final
class Array {

    /**
     * Constructor.  Class Array is not instantiable.
     * 构造器。类数组不可实例化。
     */
    private Array() {}

    /**
     * Creates a new array with the specified component type and
     * length.
     * 创建具有指定组件类型和长度的新数组
     * Invoking this method is equivalent to creating an array
     * 调用此方法相当于创建一个数组
     * as follows:
     * 详情如下:
     * <blockquote>
     * <pre>
     * int[] x = {length};
     * Array.newInstance(componentType, x);
     * </pre>
     * </blockquote>
     *
     * <p>The number of dimensions of the new array must not
     * exceed 255.
     * 新数组的维数不得超过255。
     *
     * @param componentType the {@code Class} object representing the
     * component type of the new array 表示新数组的组件类型的Class对象
     * @param length the length of the new array 新数组的长度
     * @return the new array 新数组
     * @exception NullPointerException if the specified
     * {@code componentType} parameter is null 如果指定的componentType参数为null
     * @exception IllegalArgumentException if componentType is {@link
     * Void#TYPE} or if the number of dimensions of the requested array
     * instance exceed 255. 
     * 如果componentType为Void.TYPE，或者请求的数组实例的维数超过255。
     * @exception NegativeArraySizeException if the specified {@code length}
     * is negative
     * 如果指定的length为负
     */
    public static Object newInstance(Class<?> componentType, int length)
        throws NegativeArraySizeException {
        return newArray(componentType, length);
    }

    /**
     * Creates a new array
     * with the specified component type and dimensions.
     * 使用指定的元素类型和大小创建新数组。（创建多维数组）
     * If {@code componentType}
     * represents a non-array class or interface, the new array
     * has {@code dimensions.length} dimensions and
     * {@code componentType} as its component type. If
     * {@code componentType} represents an array class, the
     * number of dimensions of the new array is equal to the sum
     * of {@code dimensions.length} and the number of
     * dimensions of {@code componentType}. In this case, the
     * component type of the new array is the component type of
     * {@code componentType}.
     * 如果 componentType 表示非数组类或接口，则新数组将dimensions.length维度
     * 和componentType作为其组件类型。
     * 如果componentType表示数组类，则新数组的维数等于dimensions.length和
     * componentType的维数之和。
     * 在本例中，新数组的组件类型是componentType的组件类型。
     * 
     * 
     * 
     * 
     *
     * <p>The number of dimensions of the new array must not
     * exceed 255.
     * 新数组的维数不得超过255。
     *
     * @param componentType the {@code Class} object representing the component
     * type of the new array 表示新数组的组件类型的Class对象
     * @param dimensions an array of {@code int} representing the dimensions of
     * the new array 表示新数组维度的int数组
     * @return the new array 新数组
     * @exception NullPointerException if the specified
     * {@code componentType} argument is null 如果指定的componentType参数为空
     * @exception IllegalArgumentException if the specified {@code dimensions}
     * argument is a zero-dimensional array, if componentType is {@link
     * Void#TYPE}, or if the number of dimensions of the requested array
     * instance exceed 255.
     * 如果指定的dimensions参数是零维数组，如果componentType是Void.TYPE，
     * 或者如果请求的数组实例的维数超过255。
     * 
     * @exception NegativeArraySizeException if any of the components in
     * the specified {@code dimensions} argument is negative.
     * 如果指定的dimensions参数中的任何元素为负。
     * dimensions是一个数组，里面的每一个元素都对应新数组每一个维度上元素个数
     * 
     */
    public static Object newInstance(Class<?> componentType, int... dimensions)
        throws IllegalArgumentException, NegativeArraySizeException {
        return multiNewArray(componentType, dimensions);
    }

    /**
     * Returns the length of the specified array object, as an {@code int}.
     * 以int形式返回指定数组对象的长度。
     * 
     * @param array the array
     * @return the length of the array
     * @exception IllegalArgumentException if the object argument is not
     * an array 如果对象参数不是数组
     */
    @HotSpotIntrinsicCandidate
    public static native int getLength(Object array)
        throws IllegalArgumentException;

    /**
     * Returns the value of the indexed component in the specified
     * array object.  The value is automatically wrapped in an object
     * if it has a primitive type.
     * 返回指定数组对象中索引元素的值。如果对象具有基元类型，则该值将自动包装在对象中。
     * 
     * 
     *
     * @param array the array
     * @param index the index
     * @return the (possibly wrapped) value of the indexed component in
     * the specified array 指定数组中索引元素的（可能已包装）值
     * @exception NullPointerException If the specified object is null 如果指定的对象为空
     * @exception IllegalArgumentException If the specified object is not
     * an array 如果指定的对象不是数组
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to the
     * length of the specified array
     * 如果指定的index参数为负，或者大于或等于指定数组的长度
     * 
     * 
     */
    public static native Object get(Object array, int index)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Returns the value of the indexed component in the specified
     * array object, as a {@code boolean}.
     * 以boolean形式返回指定数组对象中索引元素的值。
     * 
     * 
     * @param array the array
     * @param index the index
     * @return the value of the indexed component in the specified array 指定数组中索引元素的值
     * @exception NullPointerException If the specified object is null
     * @exception IllegalArgumentException If the specified object is not
     * an array, or if the indexed element cannot be converted to the
     * return type by an identity or widening conversion
     * 如果指定的对象不是数组，或者索引元素无法通过标识或加宽转换转换为返回类型
     * 
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to the
     * length of the specified array
     * 如果指定的index参数为负，或者大于或等于指定数组的长度
     * @see Array#get
     */
    public static native boolean getBoolean(Object array, int index)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Returns the value of the indexed component in the specified
     * array object, as a {@code byte}.
     * 以byte的形式返回指定数组对象中索引组件的值。
     * 
     * @param array the array
     * @param index the index
     * @return the value of the indexed component in the specified array
     * @exception NullPointerException If the specified object is null
     * @exception IllegalArgumentException If the specified object is not
     * an array, or if the indexed element cannot be converted to the
     * return type by an identity or widening conversion
     *  如果指定的对象不是数组，或者索引元素无法通过标识或加宽转换转换为返回类型
     * 
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to the
     * length of the specified array
     * 如果指定的index参数为负，或者大于或等于指定数组的长度
     * @see Array#get
     */
    public static native byte getByte(Object array, int index)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Returns the value of the indexed component in the specified
     * array object, as a {@code char}.
     * 以char的形式返回指定数组对象中索引组件的值。
     * 
     * @param array the array
     * @param index the index
     * @return the value of the indexed component in the specified array
     * @exception NullPointerException If the specified object is null
     * @exception IllegalArgumentException If the specified object is not
     * an array, or if the indexed element cannot be converted to the
     * return type by an identity or widening conversion
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to the
     * length of the specified array
     * @see Array#get
     */
    public static native char getChar(Object array, int index)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Returns the value of the indexed component in the specified
     * array object, as a {@code short}.
     * 返回指定数组对象中索引组件的值，格式为short
     *
     * @param array the array
     * @param index the index
     * @return the value of the indexed component in the specified array
     * @exception NullPointerException If the specified object is null
     * @exception IllegalArgumentException If the specified object is not
     * an array, or if the indexed element cannot be converted to the
     * return type by an identity or widening conversion
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to the
     * length of the specified array
     * @see Array#get
     */
    public static native short getShort(Object array, int index)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Returns the value of the indexed component in the specified
     * array object, as an {@code int}.
     * 返回指定数组对象中索引组件的值，格式为int
     * 
     * 
     * @param array the array
     * @param index the index
     * @return the value of the indexed component in the specified array
     * @exception NullPointerException If the specified object is null
     * @exception IllegalArgumentException If the specified object is not
     * an array, or if the indexed element cannot be converted to the
     * return type by an identity or widening conversion
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to the
     * length of the specified array
     * @see Array#get
     */
    public static native int getInt(Object array, int index)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Returns the value of the indexed component in the specified
     * array object, as a {@code long}.
     * 返回指定数组对象中索引组件的值，格式为long
     * 
     * 
     * @param array the array
     * @param index the index
     * @return the value of the indexed component in the specified array
     * @exception NullPointerException If the specified object is null
     * @exception IllegalArgumentException If the specified object is not
     * an array, or if the indexed element cannot be converted to the
     * return type by an identity or widening conversion
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to the
     * length of the specified array
     * @see Array#get
     */
    public static native long getLong(Object array, int index)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Returns the value of the indexed component in the specified
     * array object, as a {@code float}.
     * 返回指定数组对象中索引组件的值，格式为float
     * 
     * @param array the array
     * @param index the index
     * @return the value of the indexed component in the specified array
     * @exception NullPointerException If the specified object is null
     * @exception IllegalArgumentException If the specified object is not
     * an array, or if the indexed element cannot be converted to the
     * return type by an identity or widening conversion
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to the
     * length of the specified array
     * @see Array#get
     */
    public static native float getFloat(Object array, int index)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Returns the value of the indexed component in the specified
     * array object, as a {@code double}.
     * 返回指定数组对象中索引组件的值，格式为double
     * 
     * @param array the array
     * @param index the index
     * @return the value of the indexed component in the specified array
     * @exception NullPointerException If the specified object is null
     * @exception IllegalArgumentException If the specified object is not
     * an array, or if the indexed element cannot be converted to the
     * return type by an identity or widening conversion
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to the
     * length of the specified array
     * @see Array#get
     */
    public static native double getDouble(Object array, int index)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Sets the value of 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.
     * 将指定数组对象的索引组件的值设置为指定的新值。
     * 如果数组具有基元组件类型，则首先自动展开新值。
     * 
     * 
     * @param array the array
     * @param index the index into the array
     * @param value the new value of the indexed component
     * @exception NullPointerException If the specified object argument
     * is null
     * @exception IllegalArgumentException If the specified object argument
     * is not an array, or if the array component type is primitive and
     * an unwrapping conversion fails
     * 如果指定的对象参数不是数组，或者数组组件类型是基元且展开转换失败
     * 
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to
     * the length of the specified array
     */
    public static native void set(Object array, int index, Object value)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Sets the value of the indexed component of the specified array
     * object to the specified {@code boolean} value.
     * 将指定数组对象的索引组件的值设置为指定的boolean值。
     * 
     * @param array the array
     * @param index the index into the array
     * @param z the new value of the indexed component
     * @exception NullPointerException If the specified object argument
     * is null
     * @exception IllegalArgumentException If the specified object argument
     * is not an array, or if the specified value cannot be converted
     * to the underlying array's component type by an identity or a
     * primitive widening conversion
     * 如果指定的对象参数不是数组，或者指定的值无法通过标识或基元转换转换为基础数组的组件类型
     * 
     * 
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to
     * the length of the specified array
     * @see Array#set
     */
    public static native void setBoolean(Object array, int index, boolean z)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Sets the value of the indexed component of the specified array
     * object to the specified {@code byte} value.
     *  将指定数组对象的索引组件的值设置为指定的byte值。
     * @param array the array
     * @param index the index into the array
     * @param b the new value of the indexed component
     * @exception NullPointerException If the specified object argument
     * is null
     * @exception IllegalArgumentException If the specified object argument
     * is not an array, or if the specified value cannot be converted
     * to the underlying array's component type by an identity or a
     * primitive widening conversion
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to
     * the length of the specified array
     * @see Array#set
     */
    public static native void setByte(Object array, int index, byte b)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Sets the value of the indexed component of the specified array
     * object to the specified {@code char} value.
     * 将指定数组对象的索引组件的值设置为指定的char值。
     * @param array the array
     * @param index the index into the array
     * @param c the new value of the indexed component
     * @exception NullPointerException If the specified object argument
     * is null
     * @exception IllegalArgumentException If the specified object argument
     * is not an array, or if the specified value cannot be converted
     * to the underlying array's component type by an identity or a
     * primitive widening conversion
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to
     * the length of the specified array
     * @see Array#set
     */
    public static native void setChar(Object array, int index, char c)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Sets the value of the indexed component of the specified array
     * object to the specified {@code short} value.
     * 将指定数组对象的索引组件的值设置为指定的short值。
     * @param array the array
     * @param index the index into the array
     * @param s the new value of the indexed component
     * @exception NullPointerException If the specified object argument
     * is null
     * @exception IllegalArgumentException If the specified object argument
     * is not an array, or if the specified value cannot be converted
     * to the underlying array's component type by an identity or a
     * primitive widening conversion
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to
     * the length of the specified array
     * @see Array#set
     */
    public static native void setShort(Object array, int index, short s)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Sets the value of the indexed component of the specified array
     * object to the specified {@code int} value.
     * 将指定数组对象的索引组件的值设置为指定的int值。
     * @param array the array
     * @param index the index into the array
     * @param i the new value of the indexed component
     * @exception NullPointerException If the specified object argument
     * is null
     * @exception IllegalArgumentException If the specified object argument
     * is not an array, or if the specified value cannot be converted
     * to the underlying array's component type by an identity or a
     * primitive widening conversion
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to
     * the length of the specified array
     * @see Array#set
     */
    public static native void setInt(Object array, int index, int i)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Sets the value of the indexed component of the specified array
     * object to the specified {@code long} value.
     * 将指定数组对象的索引组件的值设置为指定的long值。
     * @param array the array
     * @param index the index into the array
     * @param l the new value of the indexed component
     * @exception NullPointerException If the specified object argument
     * is null
     * @exception IllegalArgumentException If the specified object argument
     * is not an array, or if the specified value cannot be converted
     * to the underlying array's component type by an identity or a
     * primitive widening conversion
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to
     * the length of the specified array
     * @see Array#set
     */
    public static native void setLong(Object array, int index, long l)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Sets the value of the indexed component of the specified array
     * object to the specified {@code float} value.
     * 将指定数组对象的索引组件的值设置为指定的float值。
     * @param array the array
     * @param index the index into the array
     * @param f the new value of the indexed component
     * @exception NullPointerException If the specified object argument
     * is null
     * @exception IllegalArgumentException If the specified object argument
     * is not an array, or if the specified value cannot be converted
     * to the underlying array's component type by an identity or a
     * primitive widening conversion
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to
     * the length of the specified array
     * @see Array#set
     */
    public static native void setFloat(Object array, int index, float f)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /**
     * Sets the value of the indexed component of the specified array
     * object to the specified {@code double} value.
     * 将指定数组对象的索引组件的值设置为指定的double值。
     * @param array the array
     * @param index the index into the array
     * @param d the new value of the indexed component
     * @exception NullPointerException If the specified object argument
     * is null
     * @exception IllegalArgumentException If the specified object argument
     * is not an array, or if the specified value cannot be converted
     * to the underlying array's component type by an identity or a
     * primitive widening conversion
     * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
     * argument is negative, or if it is greater than or equal to
     * the length of the specified array
     * @see Array#set
     */
    public static native void setDouble(Object array, int index, double d)
        throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

    /*
     * Private
     */

     // 创建一维数组
    @HotSpotIntrinsicCandidate
    private static native Object newArray(Class<?> componentType, int length)
        throws NegativeArraySizeException;

    // 创建多维数组
    private static native Object multiNewArray(Class<?> componentType,
        int[] dimensions)
        throws IllegalArgumentException, NegativeArraySizeException;


}