001 /* java.lang.reflect.Array - manipulate arrays by reflection
002 Copyright (C) 1998, 1999, 2001, 2003, 2005, 2007 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package java.lang.reflect;
040
041 import gnu.classpath.Configuration;
042
043 /**
044 * Array holds static helper functions that allow you to create and
045 * manipulate arrays by reflection. Operations know how to perform widening
046 * conversions, but throw {@link IllegalArgumentException} if you attempt
047 * a narrowing conversion. Also, when accessing primitive arrays, this
048 * class performs object wrapping and unwrapping as necessary.<p>
049 *
050 * <B>Note:</B> This class returns and accepts types as Classes, even
051 * primitive types; there are Class types defined that represent each
052 * different primitive type. They are <code>java.lang.Boolean.TYPE,
053 * java.lang.Byte.TYPE,</code>, also available as <code>boolean.class,
054 * byte.class</code>, etc. These are not to be confused with the
055 * classes <code>java.lang.Boolean, java.lang.Byte</code>, etc., which are
056 * real classes. Note also that the shorthand <code>Object[].class</code>
057 * is a convenient way to get array Classes.<p>
058 *
059 * <B>Performance note:</B> This class performs best when it does not have
060 * to convert primitive types. The further along the chain it has to convert,
061 * the worse performance will be. You're best off using the array as whatever
062 * type it already is, and then converting the result. You will do even
063 * worse if you do this and use the generic set() function.
064 *
065 * @author John Keiser
066 * @author Eric Blake (ebb9@email.byu.edu)
067 * @author Per Bothner (bothner@cygnus.com)
068 * @see java.lang.Boolean#TYPE
069 * @see java.lang.Byte#TYPE
070 * @see java.lang.Short#TYPE
071 * @see java.lang.Character#TYPE
072 * @see java.lang.Integer#TYPE
073 * @see java.lang.Long#TYPE
074 * @see java.lang.Float#TYPE
075 * @see java.lang.Double#TYPE
076 * @since 1.1
077 * @status updated to 1.4
078 */
079 public final class Array
080 {
081 static
082 {
083 if (Configuration.INIT_LOAD_LIBRARY)
084 {
085 System.loadLibrary("javalangreflect");
086 }
087 }
088
089 /**
090 * This class is uninstantiable.
091 */
092 private Array()
093 {
094 }
095
096 /**
097 * Creates a new single-dimensioned array.
098 * @param componentType the type of the array to create
099 * @param length the length of the array to create
100 * @return the created array, cast to an Object
101 * @throws NullPointerException if <code>componentType</code> is null
102 * @throws IllegalArgumentException if <code>componentType</code> is
103 * <code>Void.TYPE</code>
104 * @throws NegativeArraySizeException when length is less than 0
105 * @throws OutOfMemoryError if memory allocation fails
106 */
107 public static native Object newInstance(Class<?> componentType, int length);
108
109 /**
110 * Creates a new multi-dimensioned array. The new array has the same
111 * component type as the argument class, and the number of dimensions
112 * in the new array is the sum of the dimensions of the argument class
113 * and the length of the argument dimensions. Virtual Machine limitations
114 * forbid too many dimensions (usually 255 is the maximum); but even
115 * 50 dimensions of 2 elements in each dimension would exceed your memory
116 * long beforehand!
117 *
118 * @param componentType the type of the array to create.
119 * @param dimensions the dimensions of the array to create. Each element
120 * in <code>dimensions</code> makes another dimension of the new
121 * array. Thus, <code>Array.newInstance(java.lang.Boolean,
122 * new int[]{1,2,3})</code> is the same as
123 * <code>new java.lang.Boolean[1][2][3]</code>
124 * @return the created array, cast to an Object
125 * @throws NullPointerException if componentType or dimension is null
126 * @throws IllegalArgumentException if the the size of
127 * <code>dimensions</code> is 0 or exceeds the maximum number of
128 * array dimensions in the VM; or if componentType is Void.TYPE
129 * @throws NegativeArraySizeException when any of the dimensions is less
130 * than 0
131 * @throws OutOfMemoryError if memory allocation fails
132 */
133 public static native Object newInstance(Class<?> elementType, int[] dimensions);
134
135 /**
136 * Gets the array length.
137 * @param array the array
138 * @return the length of the array
139 * @throws IllegalArgumentException if <code>array</code> is not an array
140 * @throws NullPointerException if <code>array</code> is null
141 */
142 public static native int getLength(Object array);
143
144 /**
145 * Gets an element of an array. Primitive elements will be wrapped in
146 * the corresponding class type.
147 *
148 * @param array the array to access
149 * @param index the array index to access
150 * @return the element at <code>array[index]</code>
151 * @throws IllegalArgumentException if <code>array</code> is not an array
152 * @throws NullPointerException if <code>array</code> is null
153 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
154 * bounds
155 * @see #getBoolean(Object, int)
156 * @see #getByte(Object, int)
157 * @see #getChar(Object, int)
158 * @see #getShort(Object, int)
159 * @see #getInt(Object, int)
160 * @see #getLong(Object, int)
161 * @see #getFloat(Object, int)
162 * @see #getDouble(Object, int)
163 */
164 public static native Object get(Object array, int index);
165
166 /**
167 * Gets an element of a boolean array.
168 *
169 * @param array the array to access
170 * @param index the array index to access
171 * @return the boolean element at <code>array[index]</code>
172 * @throws IllegalArgumentException if <code>array</code> is not a boolean
173 * array
174 * @throws NullPointerException if <code>array</code> is null
175 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
176 * bounds
177 * @see #get(Object, int)
178 */
179 public static native boolean getBoolean(Object array, int index);
180
181 /**
182 * Gets an element of a byte array.
183 *
184 * @param array the array to access
185 * @param index the array index to access
186 * @return the byte element at <code>array[index]</code>
187 * @throws IllegalArgumentException if <code>array</code> is not a byte
188 * array
189 * @throws NullPointerException if <code>array</code> is null
190 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
191 * bounds
192 * @see #get(Object, int)
193 */
194 public static native byte getByte(Object array, int index);
195
196 /**
197 * Gets an element of a char array.
198 *
199 * @param array the array to access
200 * @param index the array index to access
201 * @return the char element at <code>array[index]</code>
202 * @throws IllegalArgumentException if <code>array</code> is not a char
203 * array
204 * @throws NullPointerException if <code>array</code> is null
205 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
206 * bounds
207 * @see #get(Object, int)
208 */
209 public static native char getChar(Object array, int index);
210
211 /**
212 * Gets an element of a short array.
213 *
214 * @param array the array to access
215 * @param index the array index to access
216 * @return the short element at <code>array[index]</code>
217 * @throws IllegalArgumentException if <code>array</code> is not a byte
218 * or char array
219 * @throws NullPointerException if <code>array</code> is null
220 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
221 * bounds
222 * @see #get(Object, int)
223 */
224 public static native short getShort(Object array, int index);
225
226 /**
227 * Gets an element of an int array.
228 *
229 * @param array the array to access
230 * @param index the array index to access
231 * @return the int element at <code>array[index]</code>
232 * @throws IllegalArgumentException if <code>array</code> is not a byte,
233 * char, short, or int array
234 * @throws NullPointerException if <code>array</code> is null
235 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
236 * bounds
237 * @see #get(Object, int)
238 */
239 public static native int getInt(Object array, int index);
240
241 /**
242 * Gets an element of a long array.
243 *
244 * @param array the array to access
245 * @param index the array index to access
246 * @return the long element at <code>array[index]</code>
247 * @throws IllegalArgumentException if <code>array</code> is not a byte,
248 * char, short, int, or long array
249 * @throws NullPointerException if <code>array</code> is null
250 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
251 * bounds
252 * @see #get(Object, int)
253 */
254 public static native long getLong(Object array, int index);
255
256 /**
257 * Gets an element of a float array.
258 *
259 * @param array the array to access
260 * @param index the array index to access
261 * @return the float element at <code>array[index]</code>
262 * @throws IllegalArgumentException if <code>array</code> is not a byte,
263 * char, short, int, long, or float array
264 * @throws NullPointerException if <code>array</code> is null
265 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
266 * bounds
267 * @see #get(Object, int)
268 */
269 public static native float getFloat(Object array, int index);
270
271 /**
272 * Gets an element of a double array.
273 *
274 * @param array the array to access
275 * @param index the array index to access
276 * @return the double element at <code>array[index]</code>
277 * @throws IllegalArgumentException if <code>array</code> is not a byte,
278 * char, short, int, long, float, or double array
279 * @throws NullPointerException if <code>array</code> is null
280 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
281 * bounds
282 * @see #get(Object, int)
283 */
284 public static native double getDouble(Object array, int index);
285
286 private static native Class getElementType(Object array, int index);
287
288 private static native void set(Object array, int index,
289 Object value, Class elType);
290
291 /**
292 * Sets an element of an array. If the array is primitive, then the new
293 * value is unwrapped and widened.
294 *
295 * @param array the array to set a value of
296 * @param index the array index to set the value to
297 * @param value the value to set
298 * @throws IllegalArgumentException if <code>array</code> is not an array,
299 * or the array is primitive and unwrapping value fails, or the
300 * value is not assignable to the array component type
301 * @throws NullPointerException if array is null, or if array is primitive
302 * and value is null
303 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
304 * bounds
305 * @see #setBoolean(Object, int, boolean)
306 * @see #setByte(Object, int, byte)
307 * @see #setChar(Object, int, char)
308 * @see #setShort(Object, int, short)
309 * @see #setInt(Object, int, int)
310 * @see #setLong(Object, int, long)
311 * @see #setFloat(Object, int, float)
312 * @see #setDouble(Object, int, double)
313 */
314 public static void set(Object array, int index, Object value)
315 {
316 Class elType = getElementType(array, index);
317 if (! elType.isPrimitive())
318 set(array, index, value, elType);
319 else if (value instanceof Byte)
320 setByte(array, index, ((Byte) value).byteValue());
321 else if (value instanceof Short)
322 setShort(array, index, ((Short) value).shortValue());
323 else if (value instanceof Integer)
324 setInt(array, index, ((Integer) value).intValue());
325 else if (value instanceof Long)
326 setLong(array, index, ((Long) value).longValue());
327 else if (value instanceof Float)
328 setFloat(array, index, ((Float) value).floatValue());
329 else if (value instanceof Double)
330 setDouble(array, index, ((Double) value).doubleValue());
331 else if (value instanceof Character)
332 setChar(array, index, ((Character) value).charValue());
333 else if (value instanceof Boolean)
334 setBoolean(array, index, ((Boolean) value).booleanValue());
335 else
336 throw new IllegalArgumentException();
337 }
338
339 /**
340 * Sets an element of a boolean array.
341 *
342 * @param array the array to set a value of
343 * @param index the array index to set the value to
344 * @param value the value to set
345 * @throws IllegalArgumentException if <code>array</code> is not a boolean
346 * array
347 * @throws NullPointerException if <code>array</code> is null
348 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
349 * bounds
350 * @see #set(Object, int, Object)
351 */
352 public static native void setBoolean(Object array, int index, boolean value);
353
354 /**
355 * Sets an element of a byte array.
356 *
357 * @param array the array to set a value of
358 * @param index the array index to set the value to
359 * @param value the value to set
360 * @throws IllegalArgumentException if <code>array</code> is not a byte,
361 * short, int, long, float, or double array
362 * @throws NullPointerException if <code>array</code> is null
363 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
364 * bounds
365 * @see #set(Object, int, Object)
366 */
367 public static native void setByte(Object array, int index, byte value);
368
369 /**
370 * Sets an element of a char array.
371 *
372 * @param array the array to set a value of
373 * @param index the array index to set the value to
374 * @param value the value to set
375 * @throws IllegalArgumentException if <code>array</code> is not a char,
376 * int, long, float, or double array
377 * @throws NullPointerException if <code>array</code> is null
378 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
379 * bounds
380 * @see #set(Object, int, Object)
381 */
382 public static native void setChar(Object array, int index, char value);
383
384 /**
385 * Sets an element of a short array.
386 *
387 * @param array the array to set a value of
388 * @param index the array index to set the value to
389 * @param value the value to set
390 * @throws IllegalArgumentException if <code>array</code> is not a short,
391 * int, long, float, or double array
392 * @throws NullPointerException if <code>array</code> is null
393 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
394 * bounds
395 * @see #set(Object, int, Object)
396 */
397 public static native void setShort(Object array, int index, short value);
398
399 /**
400 * Sets an element of an int array.
401 *
402 * @param array the array to set a value of
403 * @param index the array index to set the value to
404 * @param value the value to set
405 * @throws IllegalArgumentException if <code>array</code> is not an int,
406 * long, float, or double array
407 * @throws NullPointerException if <code>array</code> is null
408 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
409 * bounds
410 * @see #set(Object, int, Object)
411 */
412 public static native void setInt(Object array, int index, int value);
413
414 /**
415 * Sets an element of a long array.
416 *
417 * @param array the array to set a value of
418 * @param index the array index to set the value to
419 * @param value the value to set
420 * @throws IllegalArgumentException if <code>array</code> is not a long,
421 * float, or double array
422 * @throws NullPointerException if <code>array</code> is null
423 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
424 * bounds
425 * @see #set(Object, int, Object)
426 */
427 public static native void setLong(Object array, int index, long value);
428
429 /**
430 * Sets an element of a float array.
431 *
432 * @param array the array to set a value of
433 * @param index the array index to set the value to
434 * @param value the value to set
435 * @throws IllegalArgumentException if <code>array</code> is not a float
436 * or double array
437 * @throws NullPointerException if <code>array</code> is null
438 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
439 * bounds
440 * @see #set(Object, int, Object)
441 */
442 public static native void setFloat(Object array, int index, float value);
443
444 /**
445 * Sets an element of a double array.
446 *
447 * @param array the array to set a value of
448 * @param index the array index to set the value to
449 * @param value the value to set
450 * @throws IllegalArgumentException if <code>array</code> is not a double
451 * array
452 * @throws NullPointerException if <code>array</code> is null
453 * @throws ArrayIndexOutOfBoundsException if <code>index</code> is out of
454 * bounds
455 * @see #set(Object, int, Object)
456 */
457 public static native void setDouble(Object array, int index, double value);
458 }