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