001 /*
002 * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.lang.reflect;
027
028 /**
029 * The {@code Array} class provides static methods to dynamically create and
030 * access Java arrays.
031 *
032 * <p>{@code Array} permits widening conversions to occur during a get or set
033 * operation, but throws an {@code IllegalArgumentException} if a narrowing
034 * conversion would occur.
035 *
036 * @author Nakul Saraiya
037 */
038 public final class Array {
039
040 /**
041 * Constructor. Class Array is not instantiable.
042 */
043 private Array() {
044 }
045
046 /**
047 * Creates a new array with the specified component type and
048 * length.
049 * Invoking this method is equivalent to creating an array
050 * as follows:
051 * <blockquote>
052 * <pre>
053 * int[] x = {length};
054 * Array.newInstance(componentType, x);
055 * </pre>
056 * </blockquote>
057 *
058 * @param componentType the {@code Class} object representing the
059 * component type of the new array
060 * @param length the length of the new array
061 * @return the new array
062 * @exception NullPointerException if the specified
063 * {@code componentType} parameter is null
064 * @exception IllegalArgumentException if componentType is {@link Void#TYPE}
065 * @exception NegativeArraySizeException if the specified {@code length}
066 * is negative
067 */
068 public static Object newInstance(Class<?> componentType, int length)
069 throws NegativeArraySizeException {
070 return newArray(componentType, length);
071 }
072
073 /**
074 * Creates a new array
075 * with the specified component type and dimensions.
076 * If {@code componentType}
077 * represents a non-array class or interface, the new array
078 * has {@code dimensions.length} dimensions and
079 * {@code componentType} as its component type. If
080 * {@code componentType} represents an array class, the
081 * number of dimensions of the new array is equal to the sum
082 * of {@code dimensions.length} and the number of
083 * dimensions of {@code componentType}. In this case, the
084 * component type of the new array is the component type of
085 * {@code componentType}.
086 *
087 * <p>The number of dimensions of the new array must not
088 * exceed the number of array dimensions supported by the
089 * implementation (typically 255).
090 *
091 * @param componentType the {@code Class} object representing the component
092 * type of the new array
093 * @param dimensions an array of {@code int} representing the dimensions of
094 * the new array
095 * @return the new array
096 * @exception NullPointerException if the specified
097 * {@code componentType} argument is null
098 * @exception IllegalArgumentException if the specified {@code dimensions}
099 * 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,
107 int... dimensions) throws IllegalArgumentException,
108 NegativeArraySizeException {
109 return multiNewArray(componentType, dimensions);
110 }
111
112 /**
113 * Returns the length of the specified array object, as an {@code int}.
114 *
115 * @param array the array
116 * @return the length of the array
117 * @exception IllegalArgumentException if the object argument is not
118 * an array
119 */
120 public static native int getLength(Object array)
121 throws IllegalArgumentException;
122
123 /**
124 * Returns the value of the indexed component in the specified
125 * array object. The value is automatically wrapped in an object
126 * if it has a primitive type.
127 *
128 * @param array the array
129 * @param index the index
130 * @return the (possibly wrapped) value of the indexed component in
131 * the specified array
132 * @exception NullPointerException If the specified object is null
133 * @exception IllegalArgumentException If the specified object is not
134 * an array
135 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
136 * argument is negative, or if it is greater than or equal to the
137 * length of the specified array
138 */
139 public static native Object get(Object array, int index)
140 throws IllegalArgumentException,
141 ArrayIndexOutOfBoundsException;
142
143 /**
144 * Returns the value of the indexed component in the specified
145 * array object, as a {@code boolean}.
146 *
147 * @param array the array
148 * @param index the index
149 * @return the value of the indexed component in the specified array
150 * @exception NullPointerException If the specified object is null
151 * @exception IllegalArgumentException If the specified object is not
152 * an array, or if the indexed element cannot be converted to the
153 * return type by an identity or widening conversion
154 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
155 * argument is negative, or if it is greater than or equal to the
156 * length of the specified array
157 * @see Array#get
158 */
159 public static native boolean getBoolean(Object array, int index)
160 throws IllegalArgumentException,
161 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,
181 ArrayIndexOutOfBoundsException;
182
183 /**
184 * Returns the value of the indexed component in the specified
185 * array object, as a {@code char}.
186 *
187 * @param array the array
188 * @param index the index
189 * @return the value of the indexed component in the specified array
190 * @exception NullPointerException If the specified object is null
191 * @exception IllegalArgumentException If the specified object is not
192 * an array, or if the indexed element cannot be converted to the
193 * return type by an identity or widening conversion
194 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
195 * argument is negative, or if it is greater than or equal to the
196 * length of the specified array
197 * @see Array#get
198 */
199 public static native char getChar(Object array, int index)
200 throws IllegalArgumentException,
201 ArrayIndexOutOfBoundsException;
202
203 /**
204 * Returns the value of the indexed component in the specified
205 * array object, as a {@code short}.
206 *
207 * @param array the array
208 * @param index the index
209 * @return the value of the indexed component in the specified array
210 * @exception NullPointerException If the specified object is null
211 * @exception IllegalArgumentException If the specified object is not
212 * an array, or if the indexed element cannot be converted to the
213 * return type by an identity or widening conversion
214 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
215 * argument is negative, or if it is greater than or equal to the
216 * length of the specified array
217 * @see Array#get
218 */
219 public static native short getShort(Object array, int index)
220 throws IllegalArgumentException,
221 ArrayIndexOutOfBoundsException;
222
223 /**
224 * Returns the value of the indexed component in the specified
225 * array object, as an {@code int}.
226 *
227 * @param array the array
228 * @param index the index
229 * @return the value of the indexed component in the specified array
230 * @exception NullPointerException If the specified object is null
231 * @exception IllegalArgumentException If the specified object is not
232 * an array, or if the indexed element cannot be converted to the
233 * return type by an identity or widening conversion
234 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
235 * argument is negative, or if it is greater than or equal to the
236 * length of the specified array
237 * @see Array#get
238 */
239 public static native int getInt(Object array, int index)
240 throws IllegalArgumentException,
241 ArrayIndexOutOfBoundsException;
242
243 /**
244 * Returns the value of the indexed component in the specified
245 * array object, as a {@code long}.
246 *
247 * @param array the array
248 * @param index the index
249 * @return the value of the indexed component in the specified array
250 * @exception NullPointerException If the specified object is null
251 * @exception IllegalArgumentException If the specified object is not
252 * an array, or if the indexed element cannot be converted to the
253 * return type by an identity or widening conversion
254 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
255 * argument is negative, or if it is greater than or equal to the
256 * length of the specified array
257 * @see Array#get
258 */
259 public static native long getLong(Object array, int index)
260 throws IllegalArgumentException,
261 ArrayIndexOutOfBoundsException;
262
263 /**
264 * Returns the value of the indexed component in the specified
265 * array object, as a {@code float}.
266 *
267 * @param array the array
268 * @param index the index
269 * @return the value of the indexed component in the specified array
270 * @exception NullPointerException If the specified object is null
271 * @exception IllegalArgumentException If the specified object is not
272 * an array, or if the indexed element cannot be converted to the
273 * return type by an identity or widening conversion
274 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
275 * argument is negative, or if it is greater than or equal to the
276 * length of the specified array
277 * @see Array#get
278 */
279 public static native float getFloat(Object array, int index)
280 throws IllegalArgumentException,
281 ArrayIndexOutOfBoundsException;
282
283 /**
284 * Returns the value of the indexed component in the specified
285 * array object, as a {@code double}.
286 *
287 * @param array the array
288 * @param index the index
289 * @return the value of the indexed component in the specified array
290 * @exception NullPointerException If the specified object is null
291 * @exception IllegalArgumentException If the specified object is not
292 * an array, or if the indexed element cannot be converted to the
293 * return type by an identity or widening conversion
294 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
295 * argument is negative, or if it is greater than or equal to the
296 * length of the specified array
297 * @see Array#get
298 */
299 public static native double getDouble(Object array, int index)
300 throws IllegalArgumentException,
301 ArrayIndexOutOfBoundsException;
302
303 /**
304 * Sets the value of the indexed component of the specified array
305 * object to the specified new value. The new value is first
306 * automatically unwrapped if the array has a primitive component
307 * type.
308 * @param array the array
309 * @param index the index into the array
310 * @param value the new value of the indexed component
311 * @exception NullPointerException If the specified object argument
312 * is null
313 * @exception IllegalArgumentException If the specified object argument
314 * is not an array, or if the array component type is primitive and
315 * an unwrapping conversion fails
316 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
317 * argument is negative, or if it is greater than or equal to
318 * the length of the specified array
319 */
320 public static native void set(Object array, int index, Object value)
321 throws IllegalArgumentException,
322 ArrayIndexOutOfBoundsException;
323
324 /**
325 * Sets the value of the indexed component of the specified array
326 * object to the specified {@code boolean} value.
327 * @param array the array
328 * @param index the index into the array
329 * @param z the new value of the indexed component
330 * @exception NullPointerException If the specified object argument
331 * is null
332 * @exception IllegalArgumentException If the specified object argument
333 * is not an array, or if the specified value cannot be converted
334 * to the underlying array's component type by an identity or a
335 * primitive widening conversion
336 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
337 * argument is negative, or if it is greater than or equal to
338 * the length of the specified array
339 * @see Array#set
340 */
341 public static native void setBoolean(Object array, int index,
342 boolean z) throws IllegalArgumentException,
343 ArrayIndexOutOfBoundsException;
344
345 /**
346 * Sets the value of the indexed component of the specified array
347 * object to the specified {@code byte} value.
348 * @param array the array
349 * @param index the index into the array
350 * @param b the new value of the indexed component
351 * @exception NullPointerException If the specified object argument
352 * is null
353 * @exception IllegalArgumentException If the specified object argument
354 * is not an array, or if the specified value cannot be converted
355 * to the underlying array's component type by an identity or a
356 * primitive widening conversion
357 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
358 * argument is negative, or if it is greater than or equal to
359 * the length of the specified array
360 * @see Array#set
361 */
362 public static native void setByte(Object array, int index, byte b)
363 throws IllegalArgumentException,
364 ArrayIndexOutOfBoundsException;
365
366 /**
367 * Sets the value of the indexed component of the specified array
368 * object to the specified {@code char} value.
369 * @param array the array
370 * @param index the index into the array
371 * @param c the new value of the indexed component
372 * @exception NullPointerException If the specified object argument
373 * is null
374 * @exception IllegalArgumentException If the specified object argument
375 * is not an array, or if the specified value cannot be converted
376 * to the underlying array's component type by an identity or a
377 * primitive widening conversion
378 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
379 * argument is negative, or if it is greater than or equal to
380 * the length of the specified array
381 * @see Array#set
382 */
383 public static native void setChar(Object array, int index, char c)
384 throws IllegalArgumentException,
385 ArrayIndexOutOfBoundsException;
386
387 /**
388 * Sets the value of the indexed component of the specified array
389 * object to the specified {@code short} value.
390 * @param array the array
391 * @param index the index into the array
392 * @param s the new value of the indexed component
393 * @exception NullPointerException If the specified object argument
394 * is null
395 * @exception IllegalArgumentException If the specified object argument
396 * is not an array, or if the specified value cannot be converted
397 * to the underlying array's component type by an identity or a
398 * primitive widening conversion
399 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
400 * argument is negative, or if it is greater than or equal to
401 * the length of the specified array
402 * @see Array#set
403 */
404 public static native void setShort(Object array, int index, short s)
405 throws IllegalArgumentException,
406 ArrayIndexOutOfBoundsException;
407
408 /**
409 * Sets the value of the indexed component of the specified array
410 * object to the specified {@code int} value.
411 * @param array the array
412 * @param index the index into the array
413 * @param i the new value of the indexed component
414 * @exception NullPointerException If the specified object argument
415 * is null
416 * @exception IllegalArgumentException If the specified object argument
417 * is not an array, or if the specified value cannot be converted
418 * to the underlying array's component type by an identity or a
419 * primitive widening conversion
420 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
421 * argument is negative, or if it is greater than or equal to
422 * the length of the specified array
423 * @see Array#set
424 */
425 public static native void setInt(Object array, int index, int i)
426 throws IllegalArgumentException,
427 ArrayIndexOutOfBoundsException;
428
429 /**
430 * Sets the value of the indexed component of the specified array
431 * object to the specified {@code long} value.
432 * @param array the array
433 * @param index the index into the array
434 * @param l the new value of the indexed component
435 * @exception NullPointerException If the specified object argument
436 * is null
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
444 * @see Array#set
445 */
446 public static native void setLong(Object array, int index, long l)
447 throws IllegalArgumentException,
448 ArrayIndexOutOfBoundsException;
449
450 /**
451 * Sets the value of the indexed component of the specified array
452 * object to the specified {@code float} value.
453 * @param array the array
454 * @param index the index into the array
455 * @param f the new value of the indexed component
456 * @exception NullPointerException If the specified object argument
457 * is null
458 * @exception IllegalArgumentException If the specified object argument
459 * is not an array, or if the specified value cannot be converted
460 * to the underlying array's component type by an identity or a
461 * primitive widening conversion
462 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
463 * argument is negative, or if it is greater than or equal to
464 * the length of the specified array
465 * @see Array#set
466 */
467 public static native void setFloat(Object array, int index, float f)
468 throws IllegalArgumentException,
469 ArrayIndexOutOfBoundsException;
470
471 /**
472 * Sets the value of the indexed component of the specified array
473 * object to the specified {@code double} value.
474 * @param array the array
475 * @param index the index into the array
476 * @param d the new value of the indexed component
477 * @exception NullPointerException If the specified object argument
478 * is null
479 * @exception IllegalArgumentException If the specified object argument
480 * is not an array, or if the specified value cannot be converted
481 * to the underlying array's component type by an identity or a
482 * primitive widening conversion
483 * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
484 * argument is negative, or if it is greater than or equal to
485 * the length of the specified array
486 * @see Array#set
487 */
488 public static native void setDouble(Object array, int index,
489 double d) throws IllegalArgumentException,
490 ArrayIndexOutOfBoundsException;
491
492 /*
493 * Private
494 */
495
496 private static native Object newArray(Class componentType,
497 int length) throws NegativeArraySizeException;
498
499 private static native Object multiNewArray(Class componentType,
500 int[] dimensions) throws IllegalArgumentException,
501 NegativeArraySizeException;
502
503 }
|