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   newInstance(Class  <?> componentType, int length)
51      throws NegativeArraySizeException   {
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   newInstance(Class  <?> componentType, int[] dimensions)
89      throws IllegalArgumentException  , NegativeArraySizeException   {
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   array)
102     throws IllegalArgumentException  ;
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   get(Object   array, int index)
121     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index)
140     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index)
159     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index)
178     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index)
197     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index)
216     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index)
235     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index)
254     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index)
273     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index, Object   value)
293     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index, boolean z)
313     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index, byte b)
333     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index, char c)
353     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index, short s)
373     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index, int i)
393     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index, long l)
413     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index, float f)
433     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
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   array, int index, double d)
453     throws IllegalArgumentException  , ArrayIndexOutOfBoundsException  ;
454 
455     /*
456      * Private
457      */
458 
459     private static native Object   newArray(Class   componentType, int length)
460     throws NegativeArraySizeException  ;
461 
462     private static native Object   multiNewArray(Class   componentType,
463     int[] dimensions)
464     throws IllegalArgumentException  , NegativeArraySizeException  ;
465 
466 
467 }
468
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags