1 /* 2 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.lang.reflect; 27 28 /** 29 * The {@code Array} class provides static methods to dynamically create and 30 * access Java arrays. 31 * 32 * <p>{@code Array} permits widening conversions to occur during a get or set 33 * operation, but throws an {@code IllegalArgumentException} if a narrowing 34 * conversion would occur. 35 * 36 * @author Nakul Saraiya 37 */ 38 public final 39 class Array { 40 41 /** 42 * Constructor. Class Array is not instantiable. 43 */ 44 private Array() {} 45 46 /** 47 * Creates a new array with the specified component type and 48 * length. 49 * Invoking this method is equivalent to creating an array 50 * as follows: 51 * <blockquote> 52 * <pre> 53 * int[] x = {length}; 54 * Array.newInstance(componentType, x); 55 * </pre> 56 * </blockquote> 57 * 58 * <p>The number of dimensions of the new array must not 59 * exceed 255. 60 * 61 * @param componentType the {@code Class} object representing the 62 * component type of the new array 63 * @param length the length of the new array 64 * @return the new array 65 * @exception NullPointerException if the specified 66 * {@code componentType} parameter is null 67 * @exception IllegalArgumentException if componentType is {@link 68 * Void#TYPE} or if the number of dimensions of the requested array 69 * instance exceed 255. 70 * @exception NegativeArraySizeException if the specified {@code length} 71 * is negative 72 */ 73 public static Object newInstance(Class<?> componentType, int length) 74 throws NegativeArraySizeException { 75 return newArray(componentType, length); 76 } 77 78 /** 79 * Creates a new array 80 * with the specified component type and dimensions. 81 * If {@code componentType} 82 * represents a non-array class or interface, the new array 83 * has {@code dimensions.length} dimensions and 84 * {@code componentType} as its component type. If 85 * {@code componentType} represents an array class, the 86 * number of dimensions of the new array is equal to the sum 87 * of {@code dimensions.length} and the number of 88 * dimensions of {@code componentType}. In this case, the 89 * component type of the new array is the component type of 90 * {@code componentType}. 91 * 92 * <p>The number of dimensions of the new array must not 93 * exceed 255. 94 * 95 * @param componentType the {@code Class} object representing the component 96 * type of the new array 97 * @param dimensions an array of {@code int} representing the dimensions of 98 * the new array 99 * @return the new array 100 * @exception NullPointerException if the specified 101 * {@code componentType} argument is null 102 * @exception IllegalArgumentException if the specified {@code dimensions} 103 * argument is a zero-dimensional array, if componentType is {@link 104 * Void#TYPE}, or if the number of dimensions of the requested array 105 * instance exceed 255. 106 * @exception NegativeArraySizeException if any of the components in 107 * the specified {@code dimensions} argument is negative. 108 */ 109 public static Object newInstance(Class<?> componentType, int... dimensions) 110 throws IllegalArgumentException, NegativeArraySizeException { 111 return multiNewArray(componentType, dimensions); 112 } 113 114 /** 115 * Returns the length of the specified array object, as an {@code int}. 116 * 117 * @param array the array 118 * @return the length of the array 119 * @exception IllegalArgumentException if the object argument is not 120 * an array 121 */ 122 public static native int getLength(Object array) 123 throws IllegalArgumentException; 124 125 /** 126 * Returns the value of the indexed component in the specified 127 * array object. The value is automatically wrapped in an object 128 * if it has a primitive type. 129 * 130 * @param array the array 131 * @param index the index 132 * @return the (possibly wrapped) value of the indexed component in 133 * the specified array 134 * @exception NullPointerException If the specified object is null 135 * @exception IllegalArgumentException If the specified object is not 136 * an array 137 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 138 * argument is negative, or if it is greater than or equal to the 139 * length of the specified array 140 */ 141 public static native Object get(Object array, int index) 142 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 143 144 /** 145 * Returns the value of the indexed component in the specified 146 * array object, as a {@code boolean}. 147 * 148 * @param array the array 149 * @param index the index 150 * @return the value of the indexed component in the specified array 151 * @exception NullPointerException If the specified object is null 152 * @exception IllegalArgumentException If the specified object is not 153 * an array, or if the indexed element cannot be converted to the 154 * return type by an identity or widening conversion 155 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 156 * argument is negative, or if it is greater than or equal to the 157 * length of the specified array 158 * @see Array#get 159 */ 160 public static native boolean getBoolean(Object array, int index) 161 throws IllegalArgumentException, 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, ArrayIndexOutOfBoundsException; 181 182 /** 183 * Returns the value of the indexed component in the specified 184 * array object, as a {@code char}. 185 * 186 * @param array the array 187 * @param index the index 188 * @return the value of the indexed component in the specified array 189 * @exception NullPointerException If the specified object is null 190 * @exception IllegalArgumentException If the specified object is not 191 * an array, or if the indexed element cannot be converted to the 192 * return type by an identity or widening conversion 193 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 194 * argument is negative, or if it is greater than or equal to the 195 * length of the specified array 196 * @see Array#get 197 */ 198 public static native char getChar(Object array, int index) 199 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 200 201 /** 202 * Returns the value of the indexed component in the specified 203 * array object, as a {@code short}. 204 * 205 * @param array the array 206 * @param index the index 207 * @return the value of the indexed component in the specified array 208 * @exception NullPointerException If the specified object is null 209 * @exception IllegalArgumentException If the specified object is not 210 * an array, or if the indexed element cannot be converted to the 211 * return type by an identity or widening conversion 212 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 213 * argument is negative, or if it is greater than or equal to the 214 * length of the specified array 215 * @see Array#get 216 */ 217 public static native short getShort(Object array, int index) 218 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 219 220 /** 221 * Returns the value of the indexed component in the specified 222 * array object, as an {@code int}. 223 * 224 * @param array the array 225 * @param index the index 226 * @return the value of the indexed component in the specified array 227 * @exception NullPointerException If the specified object is null 228 * @exception IllegalArgumentException If the specified object is not 229 * an array, or if the indexed element cannot be converted to the 230 * return type by an identity or widening conversion 231 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 232 * argument is negative, or if it is greater than or equal to the 233 * length of the specified array 234 * @see Array#get 235 */ 236 public static native int getInt(Object array, int index) 237 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 238 239 /** 240 * Returns the value of the indexed component in the specified 241 * array object, as a {@code long}. 242 * 243 * @param array the array 244 * @param index the index 245 * @return the value of the indexed component in the specified array 246 * @exception NullPointerException If the specified object is null 247 * @exception IllegalArgumentException If the specified object is not 248 * an array, or if the indexed element cannot be converted to the 249 * return type by an identity or widening conversion 250 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 251 * argument is negative, or if it is greater than or equal to the 252 * length of the specified array 253 * @see Array#get 254 */ 255 public static native long getLong(Object array, int index) 256 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 257 258 /** 259 * Returns the value of the indexed component in the specified 260 * array object, as a {@code float}. 261 * 262 * @param array the array 263 * @param index the index 264 * @return the value of the indexed component in the specified array 265 * @exception NullPointerException If the specified object is null 266 * @exception IllegalArgumentException If the specified object is not 267 * an array, or if the indexed element cannot be converted to the 268 * return type by an identity or widening conversion 269 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 270 * argument is negative, or if it is greater than or equal to the 271 * length of the specified array 272 * @see Array#get 273 */ 274 public static native float getFloat(Object array, int index) 275 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 276 277 /** 278 * Returns the value of the indexed component in the specified 279 * array object, as a {@code double}. 280 * 281 * @param array the array 282 * @param index the index 283 * @return the value of the indexed component in the specified array 284 * @exception NullPointerException If the specified object is null 285 * @exception IllegalArgumentException If the specified object is not 286 * an array, or if the indexed element cannot be converted to the 287 * return type by an identity or widening conversion 288 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 289 * argument is negative, or if it is greater than or equal to the 290 * length of the specified array 291 * @see Array#get 292 */ 293 public static native double getDouble(Object array, int index) 294 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 295 296 /** 297 * Sets the value of the indexed component of the specified array 298 * object to the specified new value. The new value is first 299 * automatically unwrapped if the array has a primitive component 300 * type. 301 * @param array the array 302 * @param index the index into the array 303 * @param value the new value of the indexed component 304 * @exception NullPointerException If the specified object argument 305 * is null 306 * @exception IllegalArgumentException If the specified object argument 307 * is not an array, or if the array component type is primitive and 308 * an unwrapping conversion fails 309 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 310 * argument is negative, or if it is greater than or equal to 311 * the length of the specified array 312 */ 313 public static native void set(Object array, int index, Object value) 314 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 315 316 /** 317 * Sets the value of the indexed component of the specified array 318 * object to the specified {@code boolean} value. 319 * @param array the array 320 * @param index the index into the array 321 * @param z the new value of the indexed component 322 * @exception NullPointerException If the specified object argument 323 * is null 324 * @exception IllegalArgumentException If the specified object argument 325 * is not an array, or if the specified value cannot be converted 326 * to the underlying array's component type by an identity or a 327 * primitive widening conversion 328 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 329 * argument is negative, or if it is greater than or equal to 330 * the length of the specified array 331 * @see Array#set 332 */ 333 public static native void setBoolean(Object array, int index, boolean z) 334 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 335 336 /** 337 * Sets the value of the indexed component of the specified array 338 * object to the specified {@code byte} value. 339 * @param array the array 340 * @param index the index into the array 341 * @param b the new value of the indexed component 342 * @exception NullPointerException If the specified object argument 343 * is null 344 * @exception IllegalArgumentException If the specified object argument 345 * is not an array, or if the specified value cannot be converted 346 * to the underlying array's component type by an identity or a 347 * primitive widening conversion 348 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 349 * argument is negative, or if it is greater than or equal to 350 * the length of the specified array 351 * @see Array#set 352 */ 353 public static native void setByte(Object array, int index, byte b) 354 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 355 356 /** 357 * Sets the value of the indexed component of the specified array 358 * object to the specified {@code char} value. 359 * @param array the array 360 * @param index the index into the array 361 * @param c 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 specified value cannot be converted 366 * to the underlying array's component type by an identity or a 367 * primitive widening conversion 368 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 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 setChar(Object array, int index, char c) 374 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 375 376 /** 377 * Sets the value of the indexed component of the specified array 378 * object to the specified {@code short} value. 379 * @param array the array 380 * @param index the index into the array 381 * @param s the new value of the indexed component 382 * @exception NullPointerException If the specified object argument 383 * is null 384 * @exception IllegalArgumentException If the specified object argument 385 * is not an array, or if the specified value cannot be converted 386 * to the underlying array's component type by an identity or a 387 * primitive widening conversion 388 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 389 * argument is negative, or if it is greater than or equal to 390 * the length of the specified array 391 * @see Array#set 392 */ 393 public static native void setShort(Object array, int index, short s) 394 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 395 396 /** 397 * Sets the value of the indexed component of the specified array 398 * object to the specified {@code int} value. 399 * @param array the array 400 * @param index the index into the array 401 * @param i the new value of the indexed component 402 * @exception NullPointerException If the specified object argument 403 * is null 404 * @exception IllegalArgumentException If the specified object argument 405 * is not an array, or if the specified value cannot be converted 406 * to the underlying array's component type by an identity or a 407 * primitive widening conversion 408 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 409 * argument is negative, or if it is greater than or equal to 410 * the length of the specified array 411 * @see Array#set 412 */ 413 public static native void setInt(Object array, int index, int i) 414 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 415 416 /** 417 * Sets the value of the indexed component of the specified array 418 * object to the specified {@code long} value. 419 * @param array the array 420 * @param index the index into the array 421 * @param l the new value of the indexed component 422 * @exception NullPointerException If the specified object argument 423 * is null 424 * @exception IllegalArgumentException If the specified object argument 425 * is not an array, or if the specified value cannot be converted 426 * to the underlying array's component type by an identity or a 427 * primitive widening conversion 428 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 429 * argument is negative, or if it is greater than or equal to 430 * the length of the specified array 431 * @see Array#set 432 */ 433 public static native void setLong(Object array, int index, long l) 434 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 435 436 /** 437 * Sets the value of the indexed component of the specified array 438 * object to the specified {@code float} value. 439 * @param array the array 440 * @param index the index into the array 441 * @param f the new value of the indexed component 442 * @exception NullPointerException If the specified object argument 443 * is null 444 * @exception IllegalArgumentException If the specified object argument 445 * is not an array, or if the specified value cannot be converted 446 * to the underlying array's component type by an identity or a 447 * primitive widening conversion 448 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 449 * argument is negative, or if it is greater than or equal to 450 * the length of the specified array 451 * @see Array#set 452 */ 453 public static native void setFloat(Object array, int index, float f) 454 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 455 456 /** 457 * Sets the value of the indexed component of the specified array 458 * object to the specified {@code double} value. 459 * @param array the array 460 * @param index the index into the array 461 * @param d the new value of the indexed component 462 * @exception NullPointerException If the specified object argument 463 * is null 464 * @exception IllegalArgumentException If the specified object argument 465 * is not an array, or if the specified value cannot be converted 466 * to the underlying array's component type by an identity or a 467 * primitive widening conversion 468 * @exception ArrayIndexOutOfBoundsException If the specified {@code index} 469 * argument is negative, or if it is greater than or equal to 470 * the length of the specified array 471 * @see Array#set 472 */ 473 public static native void setDouble(Object array, int index, double d) 474 throws IllegalArgumentException, ArrayIndexOutOfBoundsException; 475 476 /* 477 * Private 478 */ 479 480 private static native Object newArray(Class<?> componentType, int length) 481 throws NegativeArraySizeException; 482 483 private static native Object multiNewArray(Class<?> componentType, 484 int[] dimensions) 485 throws IllegalArgumentException, NegativeArraySizeException; 486 487 488 }