KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > lang > reflect > Array


1 /*
2  * @(#)Array.java 1.21 04/04/20
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.lang.reflect;
9
10 /**
11  * The <code>Array</code> class provides static methods to dynamically create and
12  * access Java arrays.
13  *
14  * <p><code>Array</code> permits widening conversions to occur during a get or set
15  * operation, but throws an <code>IllegalArgumentException</code> if a narrowing
16  * conversion would occur.
17  *
18  * @author Nakul Saraiya
19  */

20 public final
21 class Array {
22
23     /**
24      * Constructor. Class Array is not instantiable.
25      */

26     private Array() {}
27
28     /**
29      * Creates a new array with the specified component type and
30      * length.
31      * Invoking this method is equivalent to creating an array
32      * as follows:
33      * <blockquote>
34      * <pre>
35      * int[] x = {length};
36      * Array.newInstance(componentType, x);
37      * </pre>
38      * </blockquote>
39      *
40      * @param componentType the <code>Class</code> object representing the
41      * component type of the new array
42      * @param length the length of the new array
43      * @return the new array
44      * @exception NullPointerException if the specified
45      * <code>componentType</code> parameter is null
46      * @exception IllegalArgumentException if componentType is Void.TYPE
47      * @exception NegativeArraySizeException if the specified <code>length</code>
48      * is negative
49      */

50     public static Object JavaDoc newInstance(Class JavaDoc<?> componentType, int length)
51     throws NegativeArraySizeException JavaDoc {
52     return newArray(componentType, length);
53     }
54
55     /**
56      * Creates a new array
57      * with the specified component type and dimensions.
58      * If <code>componentType</code>
59      * represents a non-array class or interface, the new array
60      * has <code>dimensions.length</code> dimensions and&nbsp;
61      * <code>componentType&nbsp;</code> as its component type. If
62      * <code>componentType</code> represents an array class, the
63      * number of dimensions of the new array is equal to the sum
64      * of <code>dimensions.length</code> and the number of
65      * dimensions of <code>componentType</code>. In this case, the
66      * component type of the new array is the component type of
67      * <code>componentType</code>.
68      *
69      * <p>The number of dimensions of the new array must not
70      * exceed the number of array dimensions supported by the
71      * implementation (typically 255).
72      *
73      * @param componentType the <code>Class</code> object representing the component
74      * type of the new array
75      * @param dimensions an array of <code>int</code> types representing the dimensions of
76      * the new array
77      * @return the new array
78      * @exception NullPointerException if the specified
79      * <code>componentType</code> argument is null
80      * @exception IllegalArgumentException if the specified <code>dimensions</code>
81      * argument is a zero-dimensional array, or if the number of
82      * requested dimensions exceeds the limit on the number of array dimensions
83      * supported by the implementation (typically 255), or if componentType
84      * is Void.TYPE.
85      * @exception NegativeArraySizeException if any of the components in
86      * the specified <code>dimensions</code> argument is negative.
87      */

88     public static Object JavaDoc newInstance(Class JavaDoc<?> componentType, int[] dimensions)
89     throws IllegalArgumentException JavaDoc, NegativeArraySizeException JavaDoc {
90     return multiNewArray(componentType, dimensions);
91     }
92
93     /**
94      * Returns the length of the specified array object, as an <code>int</code>.
95      *
96      * @param array the array
97      * @return the length of the array
98      * @exception IllegalArgumentException if the object argument is not
99      * an array
100      */

101     public static native int getLength(Object JavaDoc array)
102     throws IllegalArgumentException JavaDoc;
103
104     /**
105      * Returns the value of the indexed component in the specified
106      * array object. The value is automatically wrapped in an object
107      * if it has a primitive type.
108      *
109      * @param array the array
110      * @param index the index
111      * @return the (possibly wrapped) value of the indexed component in
112      * the specified array
113      * @exception NullPointerException If the specified object is null
114      * @exception IllegalArgumentException If the specified object is not
115      * an array
116      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
117      * argument is negative, or if it is greater than or equal to the
118      * length of the specified array
119      */

120     public static native Object JavaDoc get(Object JavaDoc array, int index)
121     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
122
123     /**
124      * Returns the value of the indexed component in the specified
125      * array object, as a <code>boolean</code>.
126      *
127      * @param array the array
128      * @param index the index
129      * @return the value of the indexed component in the specified array
130      * @exception NullPointerException If the specified object is null
131      * @exception IllegalArgumentException If the specified object is not
132      * an array, or if the indexed element cannot be converted to the
133      * return type by an identity or widening conversion
134      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
135      * argument is negative, or if it is greater than or equal to the
136      * length of the specified array
137      * @see Array#get
138      */

139     public static native boolean getBoolean(Object JavaDoc array, int index)
140     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
141
142     /**
143      * Returns the value of the indexed component in the specified
144      * array object, as a <code>byte</code>.
145      *
146      * @param array the array
147      * @param index the index
148      * @return the value of the indexed component in the specified array
149      * @exception NullPointerException If the specified object is null
150      * @exception IllegalArgumentException If the specified object is not
151      * an array, or if the indexed element cannot be converted to the
152      * return type by an identity or widening conversion
153      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
154      * argument is negative, or if it is greater than or equal to the
155      * length of the specified array
156      * @see Array#get
157      */

158     public static native byte getByte(Object JavaDoc array, int index)
159     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
160
161     /**
162      * Returns the value of the indexed component in the specified
163      * array object, as a <code>char</code>.
164      *
165      * @param array the array
166      * @param index the index
167      * @return the value of the indexed component in the specified array
168      * @exception NullPointerException If the specified object is null
169      * @exception IllegalArgumentException If the specified object is not
170      * an array, or if the indexed element cannot be converted to the
171      * return type by an identity or widening conversion
172      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
173      * argument is negative, or if it is greater than or equal to the
174      * length of the specified array
175      * @see Array#get
176      */

177     public static native char getChar(Object JavaDoc array, int index)
178     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
179
180     /**
181      * Returns the value of the indexed component in the specified
182      * array object, as a <code>short</code>.
183      *
184      * @param array the array
185      * @param index the index
186      * @return the value of the indexed component in the specified array
187      * @exception NullPointerException If the specified object is null
188      * @exception IllegalArgumentException If the specified object is not
189      * an array, or if the indexed element cannot be converted to the
190      * return type by an identity or widening conversion
191      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
192      * argument is negative, or if it is greater than or equal to the
193      * length of the specified array
194      * @see Array#get
195      */

196     public static native short getShort(Object JavaDoc array, int index)
197     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
198
199     /**
200      * Returns the value of the indexed component in the specified
201      * array object, as an <code>int</code>.
202      *
203      * @param array the array
204      * @param index the index
205      * @return the value of the indexed component in the specified array
206      * @exception NullPointerException If the specified object is null
207      * @exception IllegalArgumentException If the specified object is not
208      * an array, or if the indexed element cannot be converted to the
209      * return type by an identity or widening conversion
210      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
211      * argument is negative, or if it is greater than or equal to the
212      * length of the specified array
213      * @see Array#get
214      */

215     public static native int getInt(Object JavaDoc array, int index)
216     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
217
218     /**
219      * Returns the value of the indexed component in the specified
220      * array object, as a <code>long</code>.
221      *
222      * @param array the array
223      * @param index the index
224      * @return the value of the indexed component in the specified array
225      * @exception NullPointerException If the specified object is null
226      * @exception IllegalArgumentException If the specified object is not
227      * an array, or if the indexed element cannot be converted to the
228      * return type by an identity or widening conversion
229      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
230      * argument is negative, or if it is greater than or equal to the
231      * length of the specified array
232      * @see Array#get
233      */

234     public static native long getLong(Object JavaDoc array, int index)
235     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
236
237     /**
238      * Returns the value of the indexed component in the specified
239      * array object, as a <code>float</code>.
240      *
241      * @param array the array
242      * @param index the index
243      * @return the value of the indexed component in the specified array
244      * @exception NullPointerException If the specified object is null
245      * @exception IllegalArgumentException If the specified object is not
246      * an array, or if the indexed element cannot be converted to the
247      * return type by an identity or widening conversion
248      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
249      * argument is negative, or if it is greater than or equal to the
250      * length of the specified array
251      * @see Array#get
252      */

253     public static native float getFloat(Object JavaDoc array, int index)
254     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
255
256     /**
257      * Returns the value of the indexed component in the specified
258      * array object, as a <code>double</code>.
259      *
260      * @param array the array
261      * @param index the index
262      * @return the value of the indexed component in the specified array
263      * @exception NullPointerException If the specified object is null
264      * @exception IllegalArgumentException If the specified object is not
265      * an array, or if the indexed element cannot be converted to the
266      * return type by an identity or widening conversion
267      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
268      * argument is negative, or if it is greater than or equal to the
269      * length of the specified array
270      * @see Array#get
271      */

272     public static native double getDouble(Object JavaDoc array, int index)
273     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
274
275     /**
276      * Sets the value of the indexed component of the specified array
277      * object to the specified new value. The new value is first
278      * automatically unwrapped if the array has a primitive component
279      * type.
280      * @param array the array
281      * @param index the index into the array
282      * @param value the new value of the indexed component
283      * @exception NullPointerException If the specified object argument
284      * is null
285      * @exception IllegalArgumentException If the specified object argument
286      * is not an array, or if the array component type is primitive and
287      * an unwrapping conversion fails
288      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
289      * argument is negative, or if it is greater than or equal to
290      * the length of the specified array
291      */

292     public static native void set(Object JavaDoc array, int index, Object JavaDoc value)
293     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
294
295     /**
296      * Sets the value of the indexed component of the specified array
297      * object to the specified <code>boolean</code> value.
298      * @param array the array
299      * @param index the index into the array
300      * @param z the new value of the indexed component
301      * @exception NullPointerException If the specified object argument
302      * is null
303      * @exception IllegalArgumentException If the specified object argument
304      * is not an array, or if the specified value cannot be converted
305      * to the underlying array's component type by an identity or a
306      * primitive widening conversion
307      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
308      * argument is negative, or if it is greater than or equal to
309      * the length of the specified array
310      * @see Array#set
311      */

312     public static native void setBoolean(Object JavaDoc array, int index, boolean z)
313     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
314
315     /**
316      * Sets the value of the indexed component of the specified array
317      * object to the specified <code>byte</code> value.
318      * @param array the array
319      * @param index the index into the array
320      * @param b the new value of the indexed component
321      * @exception NullPointerException If the specified object argument
322      * is null
323      * @exception IllegalArgumentException If the specified object argument
324      * is not an array, or if the specified value cannot be converted
325      * to the underlying array's component type by an identity or a
326      * primitive widening conversion
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      * @see Array#set
331      */

332     public static native void setByte(Object JavaDoc array, int index, byte b)
333     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
334
335     /**
336      * Sets the value of the indexed component of the specified array
337      * object to the specified <code>char</code> value.
338      * @param array the array
339      * @param index the index into the array
340      * @param c 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 specified value cannot be converted
345      * to the underlying array's component type by an identity or a
346      * primitive 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 setChar(Object JavaDoc array, int index, char c)
353     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
354
355     /**
356      * Sets the value of the indexed component of the specified array
357      * object to the specified <code>short</code> value.
358      * @param array the array
359      * @param index the index into the array
360      * @param s the new value of the indexed component
361      * @exception NullPointerException If the specified object argument
362      * is null
363      * @exception IllegalArgumentException If the specified object argument
364      * is not an array, or if the specified value cannot be converted
365      * to the underlying array's component type by an identity or a
366      * primitive widening conversion
367      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
368      * argument is negative, or if it is greater than or equal to
369      * the length of the specified array
370      * @see Array#set
371      */

372     public static native void setShort(Object JavaDoc array, int index, short s)
373     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
374
375     /**
376      * Sets the value of the indexed component of the specified array
377      * object to the specified <code>int</code> value.
378      * @param array the array
379      * @param index the index into the array
380      * @param i the new value of the indexed component
381      * @exception NullPointerException If the specified object argument
382      * is null
383      * @exception IllegalArgumentException If the specified object argument
384      * is not an array, or if the specified value cannot be converted
385      * to the underlying array's component type by an identity or a
386      * primitive widening conversion
387      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
388      * argument is negative, or if it is greater than or equal to
389      * the length of the specified array
390      * @see Array#set
391      */

392     public static native void setInt(Object JavaDoc array, int index, int i)
393     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
394
395     /**
396      * Sets the value of the indexed component of the specified array
397      * object to the specified <code>long</code> value.
398      * @param array the array
399      * @param index the index into the array
400      * @param l the new value of the indexed component
401      * @exception NullPointerException If the specified object argument
402      * is null
403      * @exception IllegalArgumentException If the specified object argument
404      * is not an array, or if the specified value cannot be converted
405      * to the underlying array's component type by an identity or a
406      * primitive widening conversion
407      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
408      * argument is negative, or if it is greater than or equal to
409      * the length of the specified array
410      * @see Array#set
411      */

412     public static native void setLong(Object JavaDoc array, int index, long l)
413     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
414
415     /**
416      * Sets the value of the indexed component of the specified array
417      * object to the specified <code>float</code> value.
418      * @param array the array
419      * @param index the index into the array
420      * @param f the new value of the indexed component
421      * @exception NullPointerException If the specified object argument
422      * is null
423      * @exception IllegalArgumentException If the specified object argument
424      * is not an array, or if the specified value cannot be converted
425      * to the underlying array's component type by an identity or a
426      * primitive widening conversion
427      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
428      * argument is negative, or if it is greater than or equal to
429      * the length of the specified array
430      * @see Array#set
431      */

432     public static native void setFloat(Object JavaDoc array, int index, float f)
433     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
434
435     /**
436      * Sets the value of the indexed component of the specified array
437      * object to the specified <code>double</code> value.
438      * @param array the array
439      * @param index the index into the array
440      * @param d the new value of the indexed component
441      * @exception NullPointerException If the specified object argument
442      * is null
443      * @exception IllegalArgumentException If the specified object argument
444      * is not an array, or if the specified value cannot be converted
445      * to the underlying array's component type by an identity or a
446      * primitive widening conversion
447      * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
448      * argument is negative, or if it is greater than or equal to
449      * the length of the specified array
450      * @see Array#set
451      */

452     public static native void setDouble(Object JavaDoc array, int index, double d)
453     throws IllegalArgumentException JavaDoc, ArrayIndexOutOfBoundsException JavaDoc;
454
455     /*
456      * Private
457      */

458
459     private static native Object JavaDoc newArray(Class JavaDoc componentType, int length)
460     throws NegativeArraySizeException JavaDoc;
461
462     private static native Object JavaDoc multiNewArray(Class JavaDoc componentType,
463     int[] dimensions)
464     throws IllegalArgumentException JavaDoc, NegativeArraySizeException JavaDoc;
465
466
467 }
468
Popular Tags