1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/emul/src/main/java/java/lang/reflect/Array.java Fri Jan 18 12:07:11 2013 +0100
1.3 @@ -0,0 +1,485 @@
1.4 +/*
1.5 + * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package java.lang.reflect;
1.30 +
1.31 +/**
1.32 + * The {@code Array} class provides static methods to dynamically create and
1.33 + * access Java arrays.
1.34 + *
1.35 + * <p>{@code Array} permits widening conversions to occur during a get or set
1.36 + * operation, but throws an {@code IllegalArgumentException} if a narrowing
1.37 + * conversion would occur.
1.38 + *
1.39 + * @author Nakul Saraiya
1.40 + */
1.41 +public final
1.42 +class Array {
1.43 +
1.44 + /**
1.45 + * Constructor. Class Array is not instantiable.
1.46 + */
1.47 + private Array() {}
1.48 +
1.49 + /**
1.50 + * Creates a new array with the specified component type and
1.51 + * length.
1.52 + * Invoking this method is equivalent to creating an array
1.53 + * as follows:
1.54 + * <blockquote>
1.55 + * <pre>
1.56 + * int[] x = {length};
1.57 + * Array.newInstance(componentType, x);
1.58 + * </pre>
1.59 + * </blockquote>
1.60 + *
1.61 + * @param componentType the {@code Class} object representing the
1.62 + * component type of the new array
1.63 + * @param length the length of the new array
1.64 + * @return the new array
1.65 + * @exception NullPointerException if the specified
1.66 + * {@code componentType} parameter is null
1.67 + * @exception IllegalArgumentException if componentType is {@link Void#TYPE}
1.68 + * @exception NegativeArraySizeException if the specified {@code length}
1.69 + * is negative
1.70 + */
1.71 + public static Object newInstance(Class<?> componentType, int length)
1.72 + throws NegativeArraySizeException {
1.73 + return newArray(componentType, length);
1.74 + }
1.75 +
1.76 + /**
1.77 + * Creates a new array
1.78 + * with the specified component type and dimensions.
1.79 + * If {@code componentType}
1.80 + * represents a non-array class or interface, the new array
1.81 + * has {@code dimensions.length} dimensions and
1.82 + * {@code componentType} as its component type. If
1.83 + * {@code componentType} represents an array class, the
1.84 + * number of dimensions of the new array is equal to the sum
1.85 + * of {@code dimensions.length} and the number of
1.86 + * dimensions of {@code componentType}. In this case, the
1.87 + * component type of the new array is the component type of
1.88 + * {@code componentType}.
1.89 + *
1.90 + * <p>The number of dimensions of the new array must not
1.91 + * exceed the number of array dimensions supported by the
1.92 + * implementation (typically 255).
1.93 + *
1.94 + * @param componentType the {@code Class} object representing the component
1.95 + * type of the new array
1.96 + * @param dimensions an array of {@code int} representing the dimensions of
1.97 + * the new array
1.98 + * @return the new array
1.99 + * @exception NullPointerException if the specified
1.100 + * {@code componentType} argument is null
1.101 + * @exception IllegalArgumentException if the specified {@code dimensions}
1.102 + * argument is a zero-dimensional array, or if the number of
1.103 + * requested dimensions exceeds the limit on the number of array dimensions
1.104 + * supported by the implementation (typically 255), or if componentType
1.105 + * is {@link Void#TYPE}.
1.106 + * @exception NegativeArraySizeException if any of the components in
1.107 + * the specified {@code dimensions} argument is negative.
1.108 + */
1.109 + public static Object newInstance(Class<?> componentType, int... dimensions)
1.110 + throws IllegalArgumentException, NegativeArraySizeException {
1.111 + return multiNewArray(componentType, dimensions);
1.112 + }
1.113 +
1.114 + /**
1.115 + * Returns the length of the specified array object, as an {@code int}.
1.116 + *
1.117 + * @param array the array
1.118 + * @return the length of the array
1.119 + * @exception IllegalArgumentException if the object argument is not
1.120 + * an array
1.121 + */
1.122 + public static native int getLength(Object array)
1.123 + throws IllegalArgumentException;
1.124 +
1.125 + /**
1.126 + * Returns the value of the indexed component in the specified
1.127 + * array object. The value is automatically wrapped in an object
1.128 + * if it has a primitive type.
1.129 + *
1.130 + * @param array the array
1.131 + * @param index the index
1.132 + * @return the (possibly wrapped) value of the indexed component in
1.133 + * the specified array
1.134 + * @exception NullPointerException If the specified object is null
1.135 + * @exception IllegalArgumentException If the specified object is not
1.136 + * an array
1.137 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.138 + * argument is negative, or if it is greater than or equal to the
1.139 + * length of the specified array
1.140 + */
1.141 + public static native Object get(Object array, int index)
1.142 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.143 +
1.144 + /**
1.145 + * Returns the value of the indexed component in the specified
1.146 + * array object, as a {@code boolean}.
1.147 + *
1.148 + * @param array the array
1.149 + * @param index the index
1.150 + * @return the value of the indexed component in the specified array
1.151 + * @exception NullPointerException If the specified object is null
1.152 + * @exception IllegalArgumentException If the specified object is not
1.153 + * an array, or if the indexed element cannot be converted to the
1.154 + * return type by an identity or widening conversion
1.155 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.156 + * argument is negative, or if it is greater than or equal to the
1.157 + * length of the specified array
1.158 + * @see Array#get
1.159 + */
1.160 + public static native boolean getBoolean(Object array, int index)
1.161 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.162 +
1.163 + /**
1.164 + * Returns the value of the indexed component in the specified
1.165 + * array object, as a {@code byte}.
1.166 + *
1.167 + * @param array the array
1.168 + * @param index the index
1.169 + * @return the value of the indexed component in the specified array
1.170 + * @exception NullPointerException If the specified object is null
1.171 + * @exception IllegalArgumentException If the specified object is not
1.172 + * an array, or if the indexed element cannot be converted to the
1.173 + * return type by an identity or widening conversion
1.174 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.175 + * argument is negative, or if it is greater than or equal to the
1.176 + * length of the specified array
1.177 + * @see Array#get
1.178 + */
1.179 + public static native byte getByte(Object array, int index)
1.180 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.181 +
1.182 + /**
1.183 + * Returns the value of the indexed component in the specified
1.184 + * array object, as a {@code char}.
1.185 + *
1.186 + * @param array the array
1.187 + * @param index the index
1.188 + * @return the value of the indexed component in the specified array
1.189 + * @exception NullPointerException If the specified object is null
1.190 + * @exception IllegalArgumentException If the specified object is not
1.191 + * an array, or if the indexed element cannot be converted to the
1.192 + * return type by an identity or widening conversion
1.193 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.194 + * argument is negative, or if it is greater than or equal to the
1.195 + * length of the specified array
1.196 + * @see Array#get
1.197 + */
1.198 + public static native char getChar(Object array, int index)
1.199 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.200 +
1.201 + /**
1.202 + * Returns the value of the indexed component in the specified
1.203 + * array object, as a {@code short}.
1.204 + *
1.205 + * @param array the array
1.206 + * @param index the index
1.207 + * @return the value of the indexed component in the specified array
1.208 + * @exception NullPointerException If the specified object is null
1.209 + * @exception IllegalArgumentException If the specified object is not
1.210 + * an array, or if the indexed element cannot be converted to the
1.211 + * return type by an identity or widening conversion
1.212 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.213 + * argument is negative, or if it is greater than or equal to the
1.214 + * length of the specified array
1.215 + * @see Array#get
1.216 + */
1.217 + public static native short getShort(Object array, int index)
1.218 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.219 +
1.220 + /**
1.221 + * Returns the value of the indexed component in the specified
1.222 + * array object, as an {@code int}.
1.223 + *
1.224 + * @param array the array
1.225 + * @param index the index
1.226 + * @return the value of the indexed component in the specified array
1.227 + * @exception NullPointerException If the specified object is null
1.228 + * @exception IllegalArgumentException If the specified object is not
1.229 + * an array, or if the indexed element cannot be converted to the
1.230 + * return type by an identity or widening conversion
1.231 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.232 + * argument is negative, or if it is greater than or equal to the
1.233 + * length of the specified array
1.234 + * @see Array#get
1.235 + */
1.236 + public static native int getInt(Object array, int index)
1.237 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.238 +
1.239 + /**
1.240 + * Returns the value of the indexed component in the specified
1.241 + * array object, as a {@code long}.
1.242 + *
1.243 + * @param array the array
1.244 + * @param index the index
1.245 + * @return the value of the indexed component in the specified array
1.246 + * @exception NullPointerException If the specified object is null
1.247 + * @exception IllegalArgumentException If the specified object is not
1.248 + * an array, or if the indexed element cannot be converted to the
1.249 + * return type by an identity or widening conversion
1.250 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.251 + * argument is negative, or if it is greater than or equal to the
1.252 + * length of the specified array
1.253 + * @see Array#get
1.254 + */
1.255 + public static native long getLong(Object array, int index)
1.256 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.257 +
1.258 + /**
1.259 + * Returns the value of the indexed component in the specified
1.260 + * array object, as a {@code float}.
1.261 + *
1.262 + * @param array the array
1.263 + * @param index the index
1.264 + * @return the value of the indexed component in the specified array
1.265 + * @exception NullPointerException If the specified object is null
1.266 + * @exception IllegalArgumentException If the specified object is not
1.267 + * an array, or if the indexed element cannot be converted to the
1.268 + * return type by an identity or widening conversion
1.269 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.270 + * argument is negative, or if it is greater than or equal to the
1.271 + * length of the specified array
1.272 + * @see Array#get
1.273 + */
1.274 + public static native float getFloat(Object array, int index)
1.275 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.276 +
1.277 + /**
1.278 + * Returns the value of the indexed component in the specified
1.279 + * array object, as a {@code double}.
1.280 + *
1.281 + * @param array the array
1.282 + * @param index the index
1.283 + * @return the value of the indexed component in the specified array
1.284 + * @exception NullPointerException If the specified object is null
1.285 + * @exception IllegalArgumentException If the specified object is not
1.286 + * an array, or if the indexed element cannot be converted to the
1.287 + * return type by an identity or widening conversion
1.288 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.289 + * argument is negative, or if it is greater than or equal to the
1.290 + * length of the specified array
1.291 + * @see Array#get
1.292 + */
1.293 + public static native double getDouble(Object array, int index)
1.294 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.295 +
1.296 + /**
1.297 + * Sets the value of the indexed component of the specified array
1.298 + * object to the specified new value. The new value is first
1.299 + * automatically unwrapped if the array has a primitive component
1.300 + * type.
1.301 + * @param array the array
1.302 + * @param index the index into the array
1.303 + * @param value the new value of the indexed component
1.304 + * @exception NullPointerException If the specified object argument
1.305 + * is null
1.306 + * @exception IllegalArgumentException If the specified object argument
1.307 + * is not an array, or if the array component type is primitive and
1.308 + * an unwrapping conversion fails
1.309 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.310 + * argument is negative, or if it is greater than or equal to
1.311 + * the length of the specified array
1.312 + */
1.313 + public static native void set(Object array, int index, Object value)
1.314 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.315 +
1.316 + /**
1.317 + * Sets the value of the indexed component of the specified array
1.318 + * object to the specified {@code boolean} value.
1.319 + * @param array the array
1.320 + * @param index the index into the array
1.321 + * @param z the new value of the indexed component
1.322 + * @exception NullPointerException If the specified object argument
1.323 + * is null
1.324 + * @exception IllegalArgumentException If the specified object argument
1.325 + * is not an array, or if the specified value cannot be converted
1.326 + * to the underlying array's component type by an identity or a
1.327 + * primitive widening conversion
1.328 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.329 + * argument is negative, or if it is greater than or equal to
1.330 + * the length of the specified array
1.331 + * @see Array#set
1.332 + */
1.333 + public static native void setBoolean(Object array, int index, boolean z)
1.334 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.335 +
1.336 + /**
1.337 + * Sets the value of the indexed component of the specified array
1.338 + * object to the specified {@code byte} value.
1.339 + * @param array the array
1.340 + * @param index the index into the array
1.341 + * @param b the new value of the indexed component
1.342 + * @exception NullPointerException If the specified object argument
1.343 + * is null
1.344 + * @exception IllegalArgumentException If the specified object argument
1.345 + * is not an array, or if the specified value cannot be converted
1.346 + * to the underlying array's component type by an identity or a
1.347 + * primitive widening conversion
1.348 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.349 + * argument is negative, or if it is greater than or equal to
1.350 + * the length of the specified array
1.351 + * @see Array#set
1.352 + */
1.353 + public static native void setByte(Object array, int index, byte b)
1.354 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.355 +
1.356 + /**
1.357 + * Sets the value of the indexed component of the specified array
1.358 + * object to the specified {@code char} value.
1.359 + * @param array the array
1.360 + * @param index the index into the array
1.361 + * @param c the new value of the indexed component
1.362 + * @exception NullPointerException If the specified object argument
1.363 + * is null
1.364 + * @exception IllegalArgumentException If the specified object argument
1.365 + * is not an array, or if the specified value cannot be converted
1.366 + * to the underlying array's component type by an identity or a
1.367 + * primitive widening conversion
1.368 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.369 + * argument is negative, or if it is greater than or equal to
1.370 + * the length of the specified array
1.371 + * @see Array#set
1.372 + */
1.373 + public static native void setChar(Object array, int index, char c)
1.374 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.375 +
1.376 + /**
1.377 + * Sets the value of the indexed component of the specified array
1.378 + * object to the specified {@code short} value.
1.379 + * @param array the array
1.380 + * @param index the index into the array
1.381 + * @param s the new value of the indexed component
1.382 + * @exception NullPointerException If the specified object argument
1.383 + * is null
1.384 + * @exception IllegalArgumentException If the specified object argument
1.385 + * is not an array, or if the specified value cannot be converted
1.386 + * to the underlying array's component type by an identity or a
1.387 + * primitive widening conversion
1.388 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.389 + * argument is negative, or if it is greater than or equal to
1.390 + * the length of the specified array
1.391 + * @see Array#set
1.392 + */
1.393 + public static native void setShort(Object array, int index, short s)
1.394 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.395 +
1.396 + /**
1.397 + * Sets the value of the indexed component of the specified array
1.398 + * object to the specified {@code int} value.
1.399 + * @param array the array
1.400 + * @param index the index into the array
1.401 + * @param i the new value of the indexed component
1.402 + * @exception NullPointerException If the specified object argument
1.403 + * is null
1.404 + * @exception IllegalArgumentException If the specified object argument
1.405 + * is not an array, or if the specified value cannot be converted
1.406 + * to the underlying array's component type by an identity or a
1.407 + * primitive widening conversion
1.408 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.409 + * argument is negative, or if it is greater than or equal to
1.410 + * the length of the specified array
1.411 + * @see Array#set
1.412 + */
1.413 + public static native void setInt(Object array, int index, int i)
1.414 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.415 +
1.416 + /**
1.417 + * Sets the value of the indexed component of the specified array
1.418 + * object to the specified {@code long} value.
1.419 + * @param array the array
1.420 + * @param index the index into the array
1.421 + * @param l the new value of the indexed component
1.422 + * @exception NullPointerException If the specified object argument
1.423 + * is null
1.424 + * @exception IllegalArgumentException If the specified object argument
1.425 + * is not an array, or if the specified value cannot be converted
1.426 + * to the underlying array's component type by an identity or a
1.427 + * primitive widening conversion
1.428 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.429 + * argument is negative, or if it is greater than or equal to
1.430 + * the length of the specified array
1.431 + * @see Array#set
1.432 + */
1.433 + public static native void setLong(Object array, int index, long l)
1.434 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.435 +
1.436 + /**
1.437 + * Sets the value of the indexed component of the specified array
1.438 + * object to the specified {@code float} value.
1.439 + * @param array the array
1.440 + * @param index the index into the array
1.441 + * @param f the new value of the indexed component
1.442 + * @exception NullPointerException If the specified object argument
1.443 + * is null
1.444 + * @exception IllegalArgumentException If the specified object argument
1.445 + * is not an array, or if the specified value cannot be converted
1.446 + * to the underlying array's component type by an identity or a
1.447 + * primitive widening conversion
1.448 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.449 + * argument is negative, or if it is greater than or equal to
1.450 + * the length of the specified array
1.451 + * @see Array#set
1.452 + */
1.453 + public static native void setFloat(Object array, int index, float f)
1.454 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.455 +
1.456 + /**
1.457 + * Sets the value of the indexed component of the specified array
1.458 + * object to the specified {@code double} value.
1.459 + * @param array the array
1.460 + * @param index the index into the array
1.461 + * @param d the new value of the indexed component
1.462 + * @exception NullPointerException If the specified object argument
1.463 + * is null
1.464 + * @exception IllegalArgumentException If the specified object argument
1.465 + * is not an array, or if the specified value cannot be converted
1.466 + * to the underlying array's component type by an identity or a
1.467 + * primitive widening conversion
1.468 + * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
1.469 + * argument is negative, or if it is greater than or equal to
1.470 + * the length of the specified array
1.471 + * @see Array#set
1.472 + */
1.473 + public static native void setDouble(Object array, int index, double d)
1.474 + throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
1.475 +
1.476 + /*
1.477 + * Private
1.478 + */
1.479 +
1.480 + private static native Object newArray(Class componentType, int length)
1.481 + throws NegativeArraySizeException;
1.482 +
1.483 + private static native Object multiNewArray(Class componentType,
1.484 + int[] dimensions)
1.485 + throws IllegalArgumentException, NegativeArraySizeException;
1.486 +
1.487 +
1.488 +}