2 * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
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).
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.
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
26 package java.lang.reflect;
28 import org.apidesign.bck2brwsr.core.JavaScriptBody;
31 * The {@code Array} class provides static methods to dynamically create and
34 * <p>{@code Array} permits widening conversions to occur during a get or set
35 * operation, but throws an {@code IllegalArgumentException} if a narrowing
36 * conversion would occur.
38 * @author Nakul Saraiya
44 * Constructor. Class Array is not instantiable.
49 * Creates a new array with the specified component type and
51 * Invoking this method is equivalent to creating an array
56 * Array.newInstance(componentType, x);
60 * @param componentType the {@code Class} object representing the
61 * component type of the new array
62 * @param length the length of the new array
63 * @return the new array
64 * @exception NullPointerException if the specified
65 * {@code componentType} parameter is null
66 * @exception IllegalArgumentException if componentType is {@link Void#TYPE}
67 * @exception NegativeArraySizeException if the specified {@code length}
70 public static Object newInstance(Class<?> componentType, int length)
71 throws NegativeArraySizeException {
73 throw new NegativeArraySizeException();
75 String sig = findSignature(componentType);
76 return newArray(componentType.isPrimitive(), sig, length);
79 private static String findSignature(Class<?> type) {
80 if (type == Integer.TYPE) {
83 if (type == Long.TYPE) {
86 if (type == Double.TYPE) {
89 if (type == Float.TYPE) {
92 if (type == Byte.TYPE) {
95 if (type == Boolean.TYPE) {
98 if (type == Short.TYPE) {
101 if (type == Character.TYPE) {
104 if (type.getName().equals("void")) {
105 throw new IllegalStateException("Can't create array for " + type);
107 return "[L" + type.getName() + ";";
110 * Creates a new array
111 * with the specified component type and dimensions.
112 * If {@code componentType}
113 * represents a non-array class or interface, the new array
114 * has {@code dimensions.length} dimensions and
115 * {@code componentType} as its component type. If
116 * {@code componentType} represents an array class, the
117 * number of dimensions of the new array is equal to the sum
118 * of {@code dimensions.length} and the number of
119 * dimensions of {@code componentType}. In this case, the
120 * component type of the new array is the component type of
121 * {@code componentType}.
123 * <p>The number of dimensions of the new array must not
124 * exceed the number of array dimensions supported by the
125 * implementation (typically 255).
127 * @param componentType the {@code Class} object representing the component
128 * type of the new array
129 * @param dimensions an array of {@code int} representing the dimensions of
131 * @return the new array
132 * @exception NullPointerException if the specified
133 * {@code componentType} argument is null
134 * @exception IllegalArgumentException if the specified {@code dimensions}
135 * argument is a zero-dimensional array, or if the number of
136 * requested dimensions exceeds the limit on the number of array dimensions
137 * supported by the implementation (typically 255), or if componentType
138 * is {@link Void#TYPE}.
139 * @exception NegativeArraySizeException if any of the components in
140 * the specified {@code dimensions} argument is negative.
142 public static Object newInstance(Class<?> componentType, int... dimensions)
143 throws IllegalArgumentException, NegativeArraySizeException {
144 return multiNewArray(componentType, dimensions);
148 * Returns the length of the specified array object, as an {@code int}.
150 * @param array the array
151 * @return the length of the array
152 * @exception IllegalArgumentException if the object argument is not
155 public static native int getLength(Object array)
156 throws IllegalArgumentException;
159 * Returns the value of the indexed component in the specified
160 * array object. The value is automatically wrapped in an object
161 * if it has a primitive type.
163 * @param array the array
164 * @param index the index
165 * @return the (possibly wrapped) value of the indexed component in
166 * the specified array
167 * @exception NullPointerException If the specified object is null
168 * @exception IllegalArgumentException If the specified object is not
170 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
171 * argument is negative, or if it is greater than or equal to the
172 * length of the specified array
174 public static native Object get(Object array, int index)
175 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
178 * Returns the value of the indexed component in the specified
179 * array object, as a {@code boolean}.
181 * @param array the array
182 * @param index the index
183 * @return the value of the indexed component in the specified array
184 * @exception NullPointerException If the specified object is null
185 * @exception IllegalArgumentException If the specified object is not
186 * an array, or if the indexed element cannot be converted to the
187 * return type by an identity or widening conversion
188 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
189 * argument is negative, or if it is greater than or equal to the
190 * length of the specified array
193 public static native boolean getBoolean(Object array, int index)
194 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
197 * Returns the value of the indexed component in the specified
198 * array object, as a {@code byte}.
200 * @param array the array
201 * @param index the index
202 * @return the value of the indexed component in the specified array
203 * @exception NullPointerException If the specified object is null
204 * @exception IllegalArgumentException If the specified object is not
205 * an array, or if the indexed element cannot be converted to the
206 * return type by an identity or widening conversion
207 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
208 * argument is negative, or if it is greater than or equal to the
209 * length of the specified array
212 public static native byte getByte(Object array, int index)
213 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
216 * Returns the value of the indexed component in the specified
217 * array object, as a {@code char}.
219 * @param array the array
220 * @param index the index
221 * @return the value of the indexed component in the specified array
222 * @exception NullPointerException If the specified object is null
223 * @exception IllegalArgumentException If the specified object is not
224 * an array, or if the indexed element cannot be converted to the
225 * return type by an identity or widening conversion
226 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
227 * argument is negative, or if it is greater than or equal to the
228 * length of the specified array
231 public static native char getChar(Object array, int index)
232 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
235 * Returns the value of the indexed component in the specified
236 * array object, as a {@code short}.
238 * @param array the array
239 * @param index the index
240 * @return the value of the indexed component in the specified array
241 * @exception NullPointerException If the specified object is null
242 * @exception IllegalArgumentException If the specified object is not
243 * an array, or if the indexed element cannot be converted to the
244 * return type by an identity or widening conversion
245 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
246 * argument is negative, or if it is greater than or equal to the
247 * length of the specified array
250 public static native short getShort(Object array, int index)
251 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
254 * Returns the value of the indexed component in the specified
255 * array object, as an {@code int}.
257 * @param array the array
258 * @param index the index
259 * @return the value of the indexed component in the specified array
260 * @exception NullPointerException If the specified object is null
261 * @exception IllegalArgumentException If the specified object is not
262 * an array, or if the indexed element cannot be converted to the
263 * return type by an identity or widening conversion
264 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
265 * argument is negative, or if it is greater than or equal to the
266 * length of the specified array
269 public static native int getInt(Object array, int index)
270 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
273 * Returns the value of the indexed component in the specified
274 * array object, as a {@code long}.
276 * @param array the array
277 * @param index the index
278 * @return the value of the indexed component in the specified array
279 * @exception NullPointerException If the specified object is null
280 * @exception IllegalArgumentException If the specified object is not
281 * an array, or if the indexed element cannot be converted to the
282 * return type by an identity or widening conversion
283 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
284 * argument is negative, or if it is greater than or equal to the
285 * length of the specified array
288 public static native long getLong(Object array, int index)
289 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
292 * Returns the value of the indexed component in the specified
293 * array object, as a {@code float}.
295 * @param array the array
296 * @param index the index
297 * @return the value of the indexed component in the specified array
298 * @exception NullPointerException If the specified object is null
299 * @exception IllegalArgumentException If the specified object is not
300 * an array, or if the indexed element cannot be converted to the
301 * return type by an identity or widening conversion
302 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
303 * argument is negative, or if it is greater than or equal to the
304 * length of the specified array
307 public static native float getFloat(Object array, int index)
308 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
311 * Returns the value of the indexed component in the specified
312 * array object, as a {@code double}.
314 * @param array the array
315 * @param index the index
316 * @return the value of the indexed component in the specified array
317 * @exception NullPointerException If the specified object is null
318 * @exception IllegalArgumentException If the specified object is not
319 * an array, or if the indexed element cannot be converted to the
320 * return type by an identity or widening conversion
321 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
322 * argument is negative, or if it is greater than or equal to the
323 * length of the specified array
326 public static native double getDouble(Object array, int index)
327 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
330 * Sets the value of the indexed component of the specified array
331 * object to the specified new value. The new value is first
332 * automatically unwrapped if the array has a primitive component
334 * @param array the array
335 * @param index the index into the array
336 * @param value the new value of the indexed component
337 * @exception NullPointerException If the specified object argument
339 * @exception IllegalArgumentException If the specified object argument
340 * is not an array, or if the array component type is primitive and
341 * an unwrapping conversion fails
342 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
343 * argument is negative, or if it is greater than or equal to
344 * the length of the specified array
346 public static native void set(Object array, int index, Object value)
347 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
350 * Sets the value of the indexed component of the specified array
351 * object to the specified {@code boolean} value.
352 * @param array the array
353 * @param index the index into the array
354 * @param z the new value of the indexed component
355 * @exception NullPointerException If the specified object argument
357 * @exception IllegalArgumentException If the specified object argument
358 * is not an array, or if the specified value cannot be converted
359 * to the underlying array's component type by an identity or a
360 * primitive widening conversion
361 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
362 * argument is negative, or if it is greater than or equal to
363 * the length of the specified array
366 public static native void setBoolean(Object array, int index, boolean z)
367 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
370 * Sets the value of the indexed component of the specified array
371 * object to the specified {@code byte} value.
372 * @param array the array
373 * @param index the index into the array
374 * @param b the new value of the indexed component
375 * @exception NullPointerException If the specified object argument
377 * @exception IllegalArgumentException If the specified object argument
378 * is not an array, or if the specified value cannot be converted
379 * to the underlying array's component type by an identity or a
380 * primitive widening conversion
381 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
382 * argument is negative, or if it is greater than or equal to
383 * the length of the specified array
386 public static native void setByte(Object array, int index, byte b)
387 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
390 * Sets the value of the indexed component of the specified array
391 * object to the specified {@code char} value.
392 * @param array the array
393 * @param index the index into the array
394 * @param c the new value of the indexed component
395 * @exception NullPointerException If the specified object argument
397 * @exception IllegalArgumentException If the specified object argument
398 * is not an array, or if the specified value cannot be converted
399 * to the underlying array's component type by an identity or a
400 * primitive widening conversion
401 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
402 * argument is negative, or if it is greater than or equal to
403 * the length of the specified array
406 public static native void setChar(Object array, int index, char c)
407 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
410 * Sets the value of the indexed component of the specified array
411 * object to the specified {@code short} value.
412 * @param array the array
413 * @param index the index into the array
414 * @param s the new value of the indexed component
415 * @exception NullPointerException If the specified object argument
417 * @exception IllegalArgumentException If the specified object argument
418 * is not an array, or if the specified value cannot be converted
419 * to the underlying array's component type by an identity or a
420 * primitive widening conversion
421 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
422 * argument is negative, or if it is greater than or equal to
423 * the length of the specified array
426 public static native void setShort(Object array, int index, short s)
427 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
430 * Sets the value of the indexed component of the specified array
431 * object to the specified {@code int} value.
432 * @param array the array
433 * @param index the index into the array
434 * @param i the new value of the indexed component
435 * @exception NullPointerException If the specified object argument
437 * @exception IllegalArgumentException If the specified object argument
438 * is not an array, or if the specified value cannot be converted
439 * to the underlying array's component type by an identity or a
440 * primitive widening conversion
441 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
442 * argument is negative, or if it is greater than or equal to
443 * the length of the specified array
446 public static native void setInt(Object array, int index, int i)
447 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
450 * Sets the value of the indexed component of the specified array
451 * object to the specified {@code long} value.
452 * @param array the array
453 * @param index the index into the array
454 * @param l the new value of the indexed component
455 * @exception NullPointerException If the specified object argument
457 * @exception IllegalArgumentException If the specified object argument
458 * is not an array, or if the specified value cannot be converted
459 * to the underlying array's component type by an identity or a
460 * primitive widening conversion
461 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
462 * argument is negative, or if it is greater than or equal to
463 * the length of the specified array
466 public static native void setLong(Object array, int index, long l)
467 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
470 * Sets the value of the indexed component of the specified array
471 * object to the specified {@code float} value.
472 * @param array the array
473 * @param index the index into the array
474 * @param f the new value of the indexed component
475 * @exception NullPointerException If the specified object argument
477 * @exception IllegalArgumentException If the specified object argument
478 * is not an array, or if the specified value cannot be converted
479 * to the underlying array's component type by an identity or a
480 * primitive widening conversion
481 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
482 * argument is negative, or if it is greater than or equal to
483 * the length of the specified array
486 public static native void setFloat(Object array, int index, float f)
487 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
490 * Sets the value of the indexed component of the specified array
491 * object to the specified {@code double} value.
492 * @param array the array
493 * @param index the index into the array
494 * @param d the new value of the indexed component
495 * @exception NullPointerException If the specified object argument
497 * @exception IllegalArgumentException If the specified object argument
498 * is not an array, or if the specified value cannot be converted
499 * to the underlying array's component type by an identity or a
500 * primitive widening conversion
501 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
502 * argument is negative, or if it is greater than or equal to
503 * the length of the specified array
506 public static native void setDouble(Object array, int index, double d)
507 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
513 @JavaScriptBody(args = { "primitive", "sig", "length" }, body =
514 "var arr = new Array(length);\n"
515 + "var value = primitive ? 0 : null;\n"
516 + "for(var i = 0; i < length; i++) arr[i] = value;\n"
517 + "arr.jvmName = sig;\n"
520 private static native Object newArray(boolean primitive, String sig, int length);
522 private static native Object multiNewArray(Class componentType,
524 throws IllegalArgumentException, NegativeArraySizeException;