1 /*

     2  * Copyright 1996-2006 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package java.lang.reflect;

    27 

    28 /**

    29  * The {@code Array} class provides static methods to dynamically create and

    30  * access Java arrays.

    31  *

    32  * <p>{@code Array} permits widening conversions to occur during a get or set

    33  * operation, but throws an {@code IllegalArgumentException} if a narrowing

    34  * conversion would occur.

    35  *

    36  * @author Nakul Saraiya

    37  */

    38 public final

    39 class Array {

    40 

    41     /**

    42      * Constructor.  Class Array is not instantiable.

    43      */

    44     private Array() {}

    45 

    46     /**

    47      * Creates a new array with the specified component type and

    48      * length.

    49      * Invoking this method is equivalent to creating an array

    50      * as follows:

    51      * <blockquote>

    52      * <pre>

    53      * int[] x = {length};

    54      * Array.newInstance(componentType, x);

    55      * </pre>

    56      * </blockquote>

    57      *

    58      * @param componentType the {@code Class} object representing the

    59      * component type of the new array

    60      * @param length the length of the new array

    61      * @return the new array

    62      * @exception NullPointerException if the specified

    63      * {@code componentType} parameter is null

    64      * @exception IllegalArgumentException if componentType is {@link Void#TYPE}

    65      * @exception NegativeArraySizeException if the specified {@code length}

    66      * is negative

    67      */

    68     public static Object newInstance(Class<?> componentType, int length)

    69         throws NegativeArraySizeException {

    70         return newArray(componentType, length);

    71     }

    72 

    73     /**

    74      * Creates a new array

    75      * with the specified component type and dimensions.

    76      * If {@code componentType}

    77      * represents a non-array class or interface, the new array

    78      * has {@code dimensions.length} dimensions and

    79      * {@code componentType} as its component type. If

    80      * {@code componentType} represents an array class, the

    81      * number of dimensions of the new array is equal to the sum

    82      * of {@code dimensions.length} and the number of

    83      * dimensions of {@code componentType}. In this case, the

    84      * component type of the new array is the component type of

    85      * {@code componentType}.

    86      *

    87      * <p>The number of dimensions of the new array must not

    88      * exceed the number of array dimensions supported by the

    89      * implementation (typically 255).

    90      *

    91      * @param componentType the {@code Class} object representing the component

    92      * type of the new array

    93      * @param dimensions an array of {@code int} representing the dimensions of

    94      * the new array

    95      * @return the new array

    96      * @exception NullPointerException if the specified

    97      * {@code componentType} argument is null

    98      * @exception IllegalArgumentException if the specified {@code dimensions}

    99      * argument is a zero-dimensional array, or if the number of

   100      * requested dimensions exceeds the limit on the number of array dimensions

   101      * supported by the implementation (typically 255), or if componentType

   102      * is {@link Void#TYPE}.

   103      * @exception NegativeArraySizeException if any of the components in

   104      * the specified {@code dimensions} argument is negative.

   105      */

   106     public static Object newInstance(Class<?> componentType, int... dimensions)

   107         throws IllegalArgumentException, NegativeArraySizeException {

   108         return multiNewArray(componentType, dimensions);

   109     }

   110 

   111     /**

   112      * Returns the length of the specified array object, as an {@code int}.

   113      *

   114      * @param array the array

   115      * @return the length of the array

   116      * @exception IllegalArgumentException if the object argument is not

   117      * an array

   118      */

   119     public static native int getLength(Object array)

   120         throws IllegalArgumentException;

   121 

   122     /**

   123      * Returns the value of the indexed component in the specified

   124      * array object.  The value is automatically wrapped in an object

   125      * if it has a primitive type.

   126      *

   127      * @param array the array

   128      * @param index the index

   129      * @return the (possibly wrapped) value of the indexed component in

   130      * the specified array

   131      * @exception NullPointerException If the specified object is null

   132      * @exception IllegalArgumentException If the specified object is not

   133      * an array

   134      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   135      * argument is negative, or if it is greater than or equal to the

   136      * length of the specified array

   137      */

   138     public static native Object get(Object array, int index)

   139         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   140 

   141     /**

   142      * Returns the value of the indexed component in the specified

   143      * array object, as a {@code boolean}.

   144      *

   145      * @param array the array

   146      * @param index the index

   147      * @return the value of the indexed component in the specified array

   148      * @exception NullPointerException If the specified object is null

   149      * @exception IllegalArgumentException If the specified object is not

   150      * an array, or if the indexed element cannot be converted to the

   151      * return type by an identity or widening conversion

   152      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   153      * argument is negative, or if it is greater than or equal to the

   154      * length of the specified array

   155      * @see Array#get

   156      */

   157     public static native boolean getBoolean(Object array, int index)

   158         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   159 

   160     /**

   161      * Returns the value of the indexed component in the specified

   162      * array object, as a {@code byte}.

   163      *

   164      * @param array the array

   165      * @param index the index

   166      * @return the value of the indexed component in the specified array

   167      * @exception NullPointerException If the specified object is null

   168      * @exception IllegalArgumentException If the specified object is not

   169      * an array, or if the indexed element cannot be converted to the

   170      * return type by an identity or widening conversion

   171      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   172      * argument is negative, or if it is greater than or equal to the

   173      * length of the specified array

   174      * @see Array#get

   175      */

   176     public static native byte getByte(Object array, int index)

   177         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   178 

   179     /**

   180      * Returns the value of the indexed component in the specified

   181      * array object, as a {@code char}.

   182      *

   183      * @param array the array

   184      * @param index the index

   185      * @return the value of the indexed component in the specified array

   186      * @exception NullPointerException If the specified object is null

   187      * @exception IllegalArgumentException If the specified object is not

   188      * an array, or if the indexed element cannot be converted to the

   189      * return type by an identity or widening conversion

   190      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   191      * argument is negative, or if it is greater than or equal to the

   192      * length of the specified array

   193      * @see Array#get

   194      */

   195     public static native char getChar(Object array, int index)

   196         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   197 

   198     /**

   199      * Returns the value of the indexed component in the specified

   200      * array object, as a {@code short}.

   201      *

   202      * @param array the array

   203      * @param index the index

   204      * @return the value of the indexed component in the specified array

   205      * @exception NullPointerException If the specified object is null

   206      * @exception IllegalArgumentException If the specified object is not

   207      * an array, or if the indexed element cannot be converted to the

   208      * return type by an identity or widening conversion

   209      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   210      * argument is negative, or if it is greater than or equal to the

   211      * length of the specified array

   212      * @see Array#get

   213      */

   214     public static native short getShort(Object array, int index)

   215         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   216 

   217     /**

   218      * Returns the value of the indexed component in the specified

   219      * array object, as an {@code int}.

   220      *

   221      * @param array the array

   222      * @param index the index

   223      * @return the value of the indexed component in the specified array

   224      * @exception NullPointerException If the specified object is null

   225      * @exception IllegalArgumentException If the specified object is not

   226      * an array, or if the indexed element cannot be converted to the

   227      * return type by an identity or widening conversion

   228      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   229      * argument is negative, or if it is greater than or equal to the

   230      * length of the specified array

   231      * @see Array#get

   232      */

   233     public static native int getInt(Object array, int index)

   234         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   235 

   236     /**

   237      * Returns the value of the indexed component in the specified

   238      * array object, as a {@code long}.

   239      *

   240      * @param array the array

   241      * @param index the index

   242      * @return the value of the indexed component in the specified array

   243      * @exception NullPointerException If the specified object is null

   244      * @exception IllegalArgumentException If the specified object is not

   245      * an array, or if the indexed element cannot be converted to the

   246      * return type by an identity or widening conversion

   247      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   248      * argument is negative, or if it is greater than or equal to the

   249      * length of the specified array

   250      * @see Array#get

   251      */

   252     public static native long getLong(Object array, int index)

   253         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   254 

   255     /**

   256      * Returns the value of the indexed component in the specified

   257      * array object, as a {@code float}.

   258      *

   259      * @param array the array

   260      * @param index the index

   261      * @return the value of the indexed component in the specified array

   262      * @exception NullPointerException If the specified object is null

   263      * @exception IllegalArgumentException If the specified object is not

   264      * an array, or if the indexed element cannot be converted to the

   265      * return type by an identity or widening conversion

   266      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   267      * argument is negative, or if it is greater than or equal to the

   268      * length of the specified array

   269      * @see Array#get

   270      */

   271     public static native float getFloat(Object array, int index)

   272         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   273 

   274     /**

   275      * Returns the value of the indexed component in the specified

   276      * array object, as a {@code double}.

   277      *

   278      * @param array the array

   279      * @param index the index

   280      * @return the value of the indexed component in the specified array

   281      * @exception NullPointerException If the specified object is null

   282      * @exception IllegalArgumentException If the specified object is not

   283      * an array, or if the indexed element cannot be converted to the

   284      * return type by an identity or widening conversion

   285      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   286      * argument is negative, or if it is greater than or equal to the

   287      * length of the specified array

   288      * @see Array#get

   289      */

   290     public static native double getDouble(Object array, int index)

   291         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   292 

   293     /**

   294      * Sets the value of the indexed component of the specified array

   295      * object to the specified new value.  The new value is first

   296      * automatically unwrapped if the array has a primitive component

   297      * type.

   298      * @param array the array

   299      * @param index the index into the array

   300      * @param value the new value of the indexed component

   301      * @exception NullPointerException If the specified object argument

   302      * is null

   303      * @exception IllegalArgumentException If the specified object argument

   304      * is not an array, or if the array component type is primitive and

   305      * an unwrapping conversion fails

   306      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   307      * argument is negative, or if it is greater than or equal to

   308      * the length of the specified array

   309      */

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

   311         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   312 

   313     /**

   314      * Sets the value of the indexed component of the specified array

   315      * object to the specified {@code boolean} value.

   316      * @param array the array

   317      * @param index the index into the array

   318      * @param z the new value of the indexed component

   319      * @exception NullPointerException If the specified object argument

   320      * is null

   321      * @exception IllegalArgumentException If the specified object argument

   322      * is not an array, or if the specified value cannot be converted

   323      * to the underlying array's component type by an identity or a

   324      * primitive widening conversion

   325      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   326      * argument is negative, or if it is greater than or equal to

   327      * the length of the specified array

   328      * @see Array#set

   329      */

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

   331         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   332 

   333     /**

   334      * Sets the value of the indexed component of the specified array

   335      * object to the specified {@code byte} value.

   336      * @param array the array

   337      * @param index the index into the array

   338      * @param b the new value of the indexed component

   339      * @exception NullPointerException If the specified object argument

   340      * is null

   341      * @exception IllegalArgumentException If the specified object argument

   342      * is not an array, or if the specified value cannot be converted

   343      * to the underlying array's component type by an identity or a

   344      * primitive widening conversion

   345      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   346      * argument is negative, or if it is greater than or equal to

   347      * the length of the specified array

   348      * @see Array#set

   349      */

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

   351         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   352 

   353     /**

   354      * Sets the value of the indexed component of the specified array

   355      * object to the specified {@code char} value.

   356      * @param array the array

   357      * @param index the index into the array

   358      * @param c the new value of the indexed component

   359      * @exception NullPointerException If the specified object argument

   360      * is null

   361      * @exception IllegalArgumentException If the specified object argument

   362      * is not an array, or if the specified value cannot be converted

   363      * to the underlying array's component type by an identity or a

   364      * primitive widening conversion

   365      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   366      * argument is negative, or if it is greater than or equal to

   367      * the length of the specified array

   368      * @see Array#set

   369      */

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

   371         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   372 

   373     /**

   374      * Sets the value of the indexed component of the specified array

   375      * object to the specified {@code short} value.

   376      * @param array the array

   377      * @param index the index into the array

   378      * @param s the new value of the indexed component

   379      * @exception NullPointerException If the specified object argument

   380      * is null

   381      * @exception IllegalArgumentException If the specified object argument

   382      * is not an array, or if the specified value cannot be converted

   383      * to the underlying array's component type by an identity or a

   384      * primitive widening conversion

   385      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   386      * argument is negative, or if it is greater than or equal to

   387      * the length of the specified array

   388      * @see Array#set

   389      */

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

   391         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   392 

   393     /**

   394      * Sets the value of the indexed component of the specified array

   395      * object to the specified {@code int} value.

   396      * @param array the array

   397      * @param index the index into the array

   398      * @param i the new value of the indexed component

   399      * @exception NullPointerException If the specified object argument

   400      * is null

   401      * @exception IllegalArgumentException If the specified object argument

   402      * is not an array, or if the specified value cannot be converted

   403      * to the underlying array's component type by an identity or a

   404      * primitive widening conversion

   405      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   406      * argument is negative, or if it is greater than or equal to

   407      * the length of the specified array

   408      * @see Array#set

   409      */

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

   411         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   412 

   413     /**

   414      * Sets the value of the indexed component of the specified array

   415      * object to the specified {@code long} value.

   416      * @param array the array

   417      * @param index the index into the array

   418      * @param l the new value of the indexed component

   419      * @exception NullPointerException If the specified object argument

   420      * is null

   421      * @exception IllegalArgumentException If the specified object argument

   422      * is not an array, or if the specified value cannot be converted

   423      * to the underlying array's component type by an identity or a

   424      * primitive widening conversion

   425      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   426      * argument is negative, or if it is greater than or equal to

   427      * the length of the specified array

   428      * @see Array#set

   429      */

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

   431         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   432 

   433     /**

   434      * Sets the value of the indexed component of the specified array

   435      * object to the specified {@code float} value.

   436      * @param array the array

   437      * @param index the index into the array

   438      * @param f the new value of the indexed component

   439      * @exception NullPointerException If the specified object argument

   440      * is null

   441      * @exception IllegalArgumentException If the specified object argument

   442      * is not an array, or if the specified value cannot be converted

   443      * to the underlying array's component type by an identity or a

   444      * primitive widening conversion

   445      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   446      * argument is negative, or if it is greater than or equal to

   447      * the length of the specified array

   448      * @see Array#set

   449      */

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

   451         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   452 

   453     /**

   454      * Sets the value of the indexed component of the specified array

   455      * object to the specified {@code double} value.

   456      * @param array the array

   457      * @param index the index into the array

   458      * @param d the new value of the indexed component

   459      * @exception NullPointerException If the specified object argument

   460      * is null

   461      * @exception IllegalArgumentException If the specified object argument

   462      * is not an array, or if the specified value cannot be converted

   463      * to the underlying array's component type by an identity or a

   464      * primitive widening conversion

   465      * @exception ArrayIndexOutOfBoundsException If the specified {@code index}

   466      * argument is negative, or if it is greater than or equal to

   467      * the length of the specified array

   468      * @see Array#set

   469      */

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

   471         throws IllegalArgumentException, ArrayIndexOutOfBoundsException;

   472 

   473     /*

   474      * Private

   475      */

   476 

   477     private static native Object newArray(Class componentType, int length)

   478         throws NegativeArraySizeException;

   479 

   480     private static native Object multiNewArray(Class componentType,

   481         int[] dimensions)

   482         throws IllegalArgumentException, NegativeArraySizeException;

   483 

   484 

   485 }