1 /*
2 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. 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. 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.
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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * 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 * <p>The number of dimensions of the new array must not
59 * exceed 255.
60 *
61 * @param componentType the {@code Class} object representing the
62 * component type of the new array
63 * @param length the length of the new array
64 * @return the new array
65 * @exception NullPointerException if the specified
66 * {@code componentType} parameter is null
67 * @exception IllegalArgumentException if componentType is {@link
68 * Void#TYPE} or if the number of dimensions of the requested array
69 * instance exceed 255.
70 * @exception NegativeArraySizeException if the specified {@code length}
71 * is negative
72 */
73 public static Object newInstance(Class<?> componentType, int length)
74 throws NegativeArraySizeException {
75 return newArray(componentType, length);
76 }
77
78 /**
79 * Creates a new array
80 * with the specified component type and dimensions.
81 * If {@code componentType}
82 * represents a non-array class or interface, the new array
83 * has {@code dimensions.length} dimensions and
84 * {@code componentType} as its component type. If
85 * {@code componentType} represents an array class, the
86 * number of dimensions of the new array is equal to the sum
87 * of {@code dimensions.length} and the number of
88 * dimensions of {@code componentType}. In this case, the
89 * component type of the new array is the component type of
90 * {@code componentType}.
91 *
92 * <p>The number of dimensions of the new array must not
93 * exceed 255.
94 *
95 * @param componentType the {@code Class} object representing the component
96 * type of the new array
97 * @param dimensions an array of {@code int} representing the dimensions of
98 * the new array
99 * @return the new array
100 * @exception NullPointerException if the specified
101 * {@code componentType} argument is null
102 * @exception IllegalArgumentException if the specified {@code dimensions}
103 * argument is a zero-dimensional array, if componentType is {@link
104 * Void#TYPE}, or if the number of dimensions of the requested array
105 * instance exceed 255.
106 * @exception NegativeArraySizeException if any of the components in
107 * the specified {@code dimensions} argument is negative.
108 */
109 public static Object newInstance(Class<?> componentType, int... dimensions)
110 throws IllegalArgumentException, NegativeArraySizeException {
111 return multiNewArray(componentType, dimensions);
112 }
113
114 /**
115 * Returns the length of the specified array object, as an {@code int}.
116 *
117 * @param array the array
118 * @return the length of the array
119 * @exception IllegalArgumentException if the object argument is not
120 * an array
121 */
122 public static native int getLength(Object array)
123 throws IllegalArgumentException;
124
125 /**
126 * Returns the value of the indexed component in the specified
127 * array object. The value is automatically wrapped in an object
128 * if it has a primitive type.
129 *
130 * @param array the array
131 * @param index the index
132 * @return the (possibly wrapped) value of the indexed component in
133 * the specified array
134 * @exception NullPointerException If the specified object is null
135 * @exception IllegalArgumentException If the specified object is not
136 * an array
137 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
138 * argument is negative, or if it is greater than or equal to the
139 * length of the specified array
140 */
141 public static native Object get(Object array, int index)
142 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
143
144 /**
145 * Returns the value of the indexed component in the specified
146 * array object, as a {@code boolean}.
147 *
148 * @param array the array
149 * @param index the index
150 * @return the value of the indexed component in the specified array
151 * @exception NullPointerException If the specified object is null
152 * @exception IllegalArgumentException If the specified object is not
153 * an array, or if the indexed element cannot be converted to the
154 * return type by an identity or widening conversion
155 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
156 * argument is negative, or if it is greater than or equal to the
157 * length of the specified array
158 * @see Array#get
159 */
160 public static native boolean getBoolean(Object array, int index)
161 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
162
163 /**
164 * Returns the value of the indexed component in the specified
165 * array object, as a {@code byte}.
166 *
167 * @param array the array
168 * @param index the index
169 * @return the value of the indexed component in the specified array
170 * @exception NullPointerException If the specified object is null
171 * @exception IllegalArgumentException If the specified object is not
172 * an array, or if the indexed element cannot be converted to the
173 * return type by an identity or widening conversion
174 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
175 * argument is negative, or if it is greater than or equal to the
176 * length of the specified array
177 * @see Array#get
178 */
179 public static native byte getByte(Object array, int index)
180 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
181
182 /**
183 * Returns the value of the indexed component in the specified
184 * array object, as a {@code char}.
185 *
186 * @param array the array
187 * @param index the index
188 * @return the value of the indexed component in the specified array
189 * @exception NullPointerException If the specified object is null
190 * @exception IllegalArgumentException If the specified object is not
191 * an array, or if the indexed element cannot be converted to the
192 * return type by an identity or widening conversion
193 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
194 * argument is negative, or if it is greater than or equal to the
195 * length of the specified array
196 * @see Array#get
197 */
198 public static native char getChar(Object array, int index)
199 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
200
201 /**
202 * Returns the value of the indexed component in the specified
203 * array object, as a {@code short}.
204 *
205 * @param array the array
206 * @param index the index
207 * @return the value of the indexed component in the specified array
208 * @exception NullPointerException If the specified object is null
209 * @exception IllegalArgumentException If the specified object is not
210 * an array, or if the indexed element cannot be converted to the
211 * return type by an identity or widening conversion
212 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
213 * argument is negative, or if it is greater than or equal to the
214 * length of the specified array
215 * @see Array#get
216 */
217 public static native short getShort(Object array, int index)
218 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
219
220 /**
221 * Returns the value of the indexed component in the specified
222 * array object, as an {@code int}.
223 *
224 * @param array the array
225 * @param index the index
226 * @return the value of the indexed component in the specified array
227 * @exception NullPointerException If the specified object is null
228 * @exception IllegalArgumentException If the specified object is not
229 * an array, or if the indexed element cannot be converted to the
230 * return type by an identity or widening conversion
231 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
232 * argument is negative, or if it is greater than or equal to the
233 * length of the specified array
234 * @see Array#get
235 */
236 public static native int getInt(Object array, int index)
237 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
238
239 /**
240 * Returns the value of the indexed component in the specified
241 * array object, as a {@code long}.
242 *
243 * @param array the array
244 * @param index the index
245 * @return the value of the indexed component in the specified array
246 * @exception NullPointerException If the specified object is null
247 * @exception IllegalArgumentException If the specified object is not
248 * an array, or if the indexed element cannot be converted to the
249 * return type by an identity or widening conversion
250 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
251 * argument is negative, or if it is greater than or equal to the
252 * length of the specified array
253 * @see Array#get
254 */
255 public static native long getLong(Object array, int index)
256 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
257
258 /**
259 * Returns the value of the indexed component in the specified
260 * array object, as a {@code float}.
261 *
262 * @param array the array
263 * @param index the index
264 * @return the value of the indexed component in the specified array
265 * @exception NullPointerException If the specified object is null
266 * @exception IllegalArgumentException If the specified object is not
267 * an array, or if the indexed element cannot be converted to the
268 * return type by an identity or widening conversion
269 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
270 * argument is negative, or if it is greater than or equal to the
271 * length of the specified array
272 * @see Array#get
273 */
274 public static native float getFloat(Object array, int index)
275 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
276
277 /**
278 * Returns the value of the indexed component in the specified
279 * array object, as a {@code double}.
280 *
281 * @param array the array
282 * @param index the index
283 * @return the value of the indexed component in the specified array
284 * @exception NullPointerException If the specified object is null
285 * @exception IllegalArgumentException If the specified object is not
286 * an array, or if the indexed element cannot be converted to the
287 * return type by an identity or widening conversion
288 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
289 * argument is negative, or if it is greater than or equal to the
290 * length of the specified array
291 * @see Array#get
292 */
293 public static native double getDouble(Object array, int index)
294 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
295
296 /**
297 * Sets the value of the indexed component of the specified array
298 * object to the specified new value. The new value is first
299 * automatically unwrapped if the array has a primitive component
300 * type.
301 * @param array the array
302 * @param index the index into the array
303 * @param value the new value of the indexed component
304 * @exception NullPointerException If the specified object argument
305 * is null
306 * @exception IllegalArgumentException If the specified object argument
307 * is not an array, or if the array component type is primitive and
308 * an unwrapping conversion fails
309 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
310 * argument is negative, or if it is greater than or equal to
311 * the length of the specified array
312 */
313 public static native void set(Object array, int index, Object value)
314 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
315
316 /**
317 * Sets the value of the indexed component of the specified array
318 * object to the specified {@code boolean} value.
319 * @param array the array
320 * @param index the index into the array
321 * @param z the new value of the indexed component
322 * @exception NullPointerException If the specified object argument
323 * is null
324 * @exception IllegalArgumentException If the specified object argument
325 * is not an array, or if the specified value cannot be converted
326 * to the underlying array's component type by an identity or a
327 * primitive widening conversion
328 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
329 * argument is negative, or if it is greater than or equal to
330 * the length of the specified array
331 * @see Array#set
332 */
333 public static native void setBoolean(Object array, int index, boolean z)
334 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
335
336 /**
337 * Sets the value of the indexed component of the specified array
338 * object to the specified {@code byte} value.
339 * @param array the array
340 * @param index the index into the array
341 * @param b the new value of the indexed component
342 * @exception NullPointerException If the specified object argument
343 * is null
344 * @exception IllegalArgumentException If the specified object argument
345 * is not an array, or if the specified value cannot be converted
346 * to the underlying array's component type by an identity or a
347 * primitive widening conversion
348 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
349 * argument is negative, or if it is greater than or equal to
350 * the length of the specified array
351 * @see Array#set
352 */
353 public static native void setByte(Object array, int index, byte b)
354 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
355
356 /**
357 * Sets the value of the indexed component of the specified array
358 * object to the specified {@code char} value.
359 * @param array the array
360 * @param index the index into the array
361 * @param c the new value of the indexed component
362 * @exception NullPointerException If the specified object argument
363 * is null
364 * @exception IllegalArgumentException If the specified object argument
365 * is not an array, or if the specified value cannot be converted
366 * to the underlying array's component type by an identity or a
367 * primitive widening conversion
368 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
369 * argument is negative, or if it is greater than or equal to
370 * the length of the specified array
371 * @see Array#set
372 */
373 public static native void setChar(Object array, int index, char c)
374 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
375
376 /**
377 * Sets the value of the indexed component of the specified array
378 * object to the specified {@code short} value.
379 * @param array the array
380 * @param index the index into the array
381 * @param s the new value of the indexed component
382 * @exception NullPointerException If the specified object argument
383 * is null
384 * @exception IllegalArgumentException If the specified object argument
385 * is not an array, or if the specified value cannot be converted
386 * to the underlying array's component type by an identity or a
387 * primitive widening conversion
388 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
389 * argument is negative, or if it is greater than or equal to
390 * the length of the specified array
391 * @see Array#set
392 */
393 public static native void setShort(Object array, int index, short s)
394 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
395
396 /**
397 * Sets the value of the indexed component of the specified array
398 * object to the specified {@code int} value.
399 * @param array the array
400 * @param index the index into the array
401 * @param i the new value of the indexed component
402 * @exception NullPointerException If the specified object argument
403 * is null
404 * @exception IllegalArgumentException If the specified object argument
405 * is not an array, or if the specified value cannot be converted
406 * to the underlying array's component type by an identity or a
407 * primitive widening conversion
408 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
409 * argument is negative, or if it is greater than or equal to
410 * the length of the specified array
411 * @see Array#set
412 */
413 public static native void setInt(Object array, int index, int i)
414 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
415
416 /**
417 * Sets the value of the indexed component of the specified array
418 * object to the specified {@code long} value.
419 * @param array the array
420 * @param index the index into the array
421 * @param l the new value of the indexed component
422 * @exception NullPointerException If the specified object argument
423 * is null
424 * @exception IllegalArgumentException If the specified object argument
425 * is not an array, or if the specified value cannot be converted
426 * to the underlying array's component type by an identity or a
427 * primitive widening conversion
428 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
429 * argument is negative, or if it is greater than or equal to
430 * the length of the specified array
431 * @see Array#set
432 */
433 public static native void setLong(Object array, int index, long l)
434 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
435
436 /**
437 * Sets the value of the indexed component of the specified array
438 * object to the specified {@code float} value.
439 * @param array the array
440 * @param index the index into the array
441 * @param f the new value of the indexed component
442 * @exception NullPointerException If the specified object argument
443 * is null
444 * @exception IllegalArgumentException If the specified object argument
445 * is not an array, or if the specified value cannot be converted
446 * to the underlying array's component type by an identity or a
447 * primitive widening conversion
448 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
449 * argument is negative, or if it is greater than or equal to
450 * the length of the specified array
451 * @see Array#set
452 */
453 public static native void setFloat(Object array, int index, float f)
454 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
455
456 /**
457 * Sets the value of the indexed component of the specified array
458 * object to the specified {@code double} value.
459 * @param array the array
460 * @param index the index into the array
461 * @param d the new value of the indexed component
462 * @exception NullPointerException If the specified object argument
463 * is null
464 * @exception IllegalArgumentException If the specified object argument
465 * is not an array, or if the specified value cannot be converted
466 * to the underlying array's component type by an identity or a
467 * primitive widening conversion
468 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
469 * argument is negative, or if it is greater than or equal to
470 * the length of the specified array
471 * @see Array#set
472 */
473 public static native void setDouble(Object array, int index, double d)
474 throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
475
476 /*
477 * Private
478 */
479
480 private static native Object newArray(Class<?> componentType, int length)
481 throws NegativeArraySizeException;
482
483 private static native Object multiNewArray(Class<?> componentType,
484 int[] dimensions)
485 throws IllegalArgumentException, NegativeArraySizeException;
486
487
488 }