1. /*
  2. * @(#)Array.java 1.10 00/02/02
  3. *
  4. * Copyright 1996-2000 Sun Microsystems, Inc. All Rights Reserved.
  5. *
  6. * This software is the proprietary information of Sun Microsystems, Inc.
  7. * Use is subject to license terms.
  8. *
  9. */
  10. package java.lang.reflect;
  11. /**
  12. * The <code>Array</code> class provides static methods to dynamically create and
  13. * access Java arrays.
  14. *
  15. * <p><code>Array</code> permits widening conversions to occur during a get or set
  16. * operation, but throws an <code>IllegalArgumentException</code> if a narrowing
  17. * conversion would occur.
  18. *
  19. * @author Nakul Saraiya
  20. */
  21. public final
  22. class Array {
  23. /**
  24. * Constructor. Class Array is not instantiable.
  25. */
  26. private Array() {}
  27. /**
  28. * Creates a new array with the specified component type and
  29. * length.
  30. * Invoking this method is equivalent to creating an array
  31. * as follows:
  32. * <blockquote>
  33. * <pre>
  34. * int[] x = {length};
  35. * Array.newInstance(componentType, x);
  36. * </pre>
  37. * </blockquote>
  38. *
  39. * @param componentType the <code>Class</code> object representing the
  40. * component type of the new array
  41. * @param length the length of the new array
  42. * @return the new array
  43. * @exception NullPointerException if the specified
  44. * <code>componentType</code> parameter is null
  45. * @exception NegativeArraySizeException if the specified <code>length</code>
  46. * is negative
  47. */
  48. public static Object newInstance(Class componentType, int length)
  49. throws NegativeArraySizeException {
  50. return newArray(componentType, length);
  51. }
  52. /**
  53. * Creates a new array
  54. * with the specified component type and dimensions.
  55. * If <code>componentType</code>
  56. * represents a non-array class or interface, the new array
  57. * has <code>dimensions.length</code> dimensions and 
  58. * <code>componentType </code> as its component type. If
  59. * <code>componentType</code> represents an array class, the
  60. * number of dimensions of the new array is equal to the sum
  61. * of <code>dimensions.length</code> and the number of
  62. * dimensions of <code>componentType</code>. In this case, the
  63. * component type of the new array is the component type of
  64. * <code>componentType</code>.
  65. *
  66. * <p>The number of dimensions of the new array must not
  67. * exceed the number of array dimensions supported by the
  68. * implementation (typically 255).
  69. *
  70. * @param componentType the <code>Class</code> object representing the component
  71. * type of the new array
  72. * @param dimensions an array of <code>int</code> types representing the dimensions of
  73. * the new array
  74. * @return the new array
  75. * @exception NullPointerException if the specified
  76. * <code>componentType</code> argument is null
  77. * @exception IllegalArgumentException if the specified <code>dimensions</code>
  78. * argument is a zero-dimensional array, or if the number of
  79. * requested dimensions exceeds the limit on the number of array dimensions
  80. * supported by the implementation (typically 255).
  81. * @exception NegativeArraySizeException if any of the components in
  82. * the specified <code>dimensions</code> argument is negative.
  83. */
  84. public static Object newInstance(Class componentType, int[] dimensions)
  85. throws IllegalArgumentException, NegativeArraySizeException {
  86. return multiNewArray(componentType, dimensions);
  87. }
  88. /**
  89. * Returns the length of the specified array object, as an <code>int</code>.
  90. *
  91. * @param array the array
  92. * @return the length of the array
  93. * @exception IllegalArgumentException if the object argument is not
  94. * an array
  95. */
  96. public static native int getLength(Object array)
  97. throws IllegalArgumentException;
  98. /**
  99. * Returns the value of the indexed component in the specified
  100. * array object. The value is automatically wrapped in an object
  101. * if it has a primitive type.
  102. *
  103. * @param array the array
  104. * @param index the index
  105. * @return the (possibly wrapped) value of the indexed component in
  106. * the specified array
  107. * @exception NullPointerException If the specified object is null
  108. * @exception IllegalArgumentException If the specified object is not
  109. * an array
  110. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  111. * argument is negative, or if it is greater than or equal to the
  112. * length of the specified array
  113. */
  114. public static native Object get(Object array, int index)
  115. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  116. /**
  117. * Returns the value of the indexed component in the specified
  118. * array object, as a <code>boolean</code>.
  119. *
  120. * @param array the array
  121. * @param index the index
  122. * @return the value of the indexed component in the specified array
  123. * @exception NullPointerException If the specified object is null
  124. * @exception IllegalArgumentException If the specified object is not
  125. * an array, or if the indexed element cannot be converted to the
  126. * return type by an identity or widening conversion
  127. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  128. * argument is negative, or if it is greater than or equal to the
  129. * length of the specified array
  130. * @see Array#get
  131. */
  132. public static native boolean getBoolean(Object array, int index)
  133. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  134. /**
  135. * Returns the value of the indexed component in the specified
  136. * array object, as a <code>byte</code>.
  137. *
  138. * @param array the array
  139. * @param index the index
  140. * @return the value of the indexed component in the specified array
  141. * @exception NullPointerException If the specified object is null
  142. * @exception IllegalArgumentException If the specified object is not
  143. * an array, or if the indexed element cannot be converted to the
  144. * return type by an identity or widening conversion
  145. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  146. * argument is negative, or if it is greater than or equal to the
  147. * length of the specified array
  148. * @see Array#get
  149. */
  150. public static native byte getByte(Object array, int index)
  151. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  152. /**
  153. * Returns the value of the indexed component in the specified
  154. * array object, as a <code>char</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 char getChar(Object array, int index)
  169. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  170. /**
  171. * Returns the value of the indexed component in the specified
  172. * array object, as a <code>short</code>.
  173. *
  174. * @param array the array
  175. * @param index the index
  176. * @return the value of the indexed component in the specified array
  177. * @exception NullPointerException If the specified object is null
  178. * @exception IllegalArgumentException If the specified object is not
  179. * an array, or if the indexed element cannot be converted to the
  180. * return type by an identity or widening conversion
  181. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  182. * argument is negative, or if it is greater than or equal to the
  183. * length of the specified array
  184. * @see Array#get
  185. */
  186. public static native short getShort(Object array, int index)
  187. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  188. /**
  189. * Returns the value of the indexed component in the specified
  190. * array object, as an <code>int</code>.
  191. *
  192. * @param array the array
  193. * @param index the index
  194. * @return the value of the indexed component in the specified array
  195. * @exception NullPointerException If the specified object is null
  196. * @exception IllegalArgumentException If the specified object is not
  197. * an array, or if the indexed element cannot be converted to the
  198. * return type by an identity or widening conversion
  199. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  200. * argument is negative, or if it is greater than or equal to the
  201. * length of the specified array
  202. * @see Array#get
  203. */
  204. public static native int getInt(Object array, int index)
  205. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  206. /**
  207. * Returns the value of the indexed component in the specified
  208. * array object, as a <code>long</code>.
  209. *
  210. * @param array the array
  211. * @param index the index
  212. * @return the value of the indexed component in the specified array
  213. * @exception NullPointerException If the specified object is null
  214. * @exception IllegalArgumentException If the specified object is not
  215. * an array, or if the indexed element cannot be converted to the
  216. * return type by an identity or widening conversion
  217. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  218. * argument is negative, or if it is greater than or equal to the
  219. * length of the specified array
  220. * @see Array#get
  221. */
  222. public static native long getLong(Object array, int index)
  223. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  224. /**
  225. * Returns the value of the indexed component in the specified
  226. * array object, as a <code>float</code>.
  227. *
  228. * @param array the array
  229. * @param index the index
  230. * @return the value of the indexed component in the specified array
  231. * @exception NullPointerException If the specified object is null
  232. * @exception IllegalArgumentException If the specified object is not
  233. * an array, or if the indexed element cannot be converted to the
  234. * return type by an identity or widening conversion
  235. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  236. * argument is negative, or if it is greater than or equal to the
  237. * length of the specified array
  238. * @see Array#get
  239. */
  240. public static native float getFloat(Object array, int index)
  241. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  242. /**
  243. * Returns the value of the indexed component in the specified
  244. * array object, as a <code>double</code>.
  245. *
  246. * @param array the array
  247. * @param index the index
  248. * @return the value of the indexed component in the specified array
  249. * @exception NullPointerException If the specified object is null
  250. * @exception IllegalArgumentException If the specified object is not
  251. * an array, or if the indexed element cannot be converted to the
  252. * return type by an identity or widening conversion
  253. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  254. * argument is negative, or if it is greater than or equal to the
  255. * length of the specified array
  256. * @see Array#get
  257. */
  258. public static native double getDouble(Object array, int index)
  259. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  260. /**
  261. * Sets the value of the indexed component of the specified array
  262. * object to the specified new value. The new value is first
  263. * automatically unwrapped if the array has a primitive component
  264. * type.
  265. * @param array the array
  266. * @param index the index into the array
  267. * @param value the new value of the indexed component
  268. * @exception NullPointerException If the specified object argument
  269. * is null, or if the array component type is primitive and the specified
  270. * value is null
  271. * @exception IllegalArgumentException If the specified object argument
  272. * is not an array, or if the array component type is primitive and
  273. * the specified value cannot be converted to the primitive type by
  274. * a combination of unwrapping and identity or widening conversions
  275. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  276. * argument is negative, or if it is greater than or equal to
  277. * the length of the specified array
  278. */
  279. public static native void set(Object array, int index, Object value)
  280. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  281. /**
  282. * Sets the value of the indexed component of the specified array
  283. * object to the specified <code>boolean</code> value.
  284. * @param array the array
  285. * @param index the index into the array
  286. * @param value the new value of the indexed component
  287. * @exception NullPointerException If the specified object argument
  288. * is null
  289. * @exception IllegalArgumentException If the specified object argument
  290. * is not an array, or if the the specified value cannot be converted
  291. * to the underlying array's component type by an identity or a
  292. * primitive widening widening conversion
  293. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  294. * argument is negative, or if it is greater than or equal to
  295. * the length of the specified array
  296. * @see Array#set
  297. */
  298. public static native void setBoolean(Object array, int index, boolean z)
  299. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  300. /**
  301. * Sets the value of the indexed component of the specified array
  302. * object to the specified <code>boolean</code> value.
  303. * @param array the array
  304. * @param index the index into the array
  305. * @param value the new value of the indexed component
  306. * @exception NullPointerException If the specified object argument
  307. * is null
  308. * @exception IllegalArgumentException If the specified object argument
  309. * is not an array, or if the the specified value cannot be converted
  310. * to the underlying array's component type by an identity or a
  311. * primitive widening widening conversion
  312. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  313. * argument is negative, or if it is greater than or equal to
  314. * the length of the specified array
  315. * @see Array#set
  316. */
  317. public static native void setByte(Object array, int index, byte b)
  318. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  319. /**
  320. * Sets the value of the indexed component of the specified array
  321. * object to the specified <code>byte</code> value.
  322. * @param array the array
  323. * @param index the index into the array
  324. * @param value the new value of the indexed component
  325. * @exception NullPointerException If the specified object argument
  326. * is null
  327. * @exception IllegalArgumentException If the specified object argument
  328. * is not an array, or if the the specified value cannot be converted
  329. * to the underlying array's component type by an identity or a
  330. * primitive widening widening conversion
  331. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  332. * argument is negative, or if it is greater than or equal to
  333. * the length of the specified array
  334. * @see Array#set
  335. */
  336. public static native void setChar(Object array, int index, char c)
  337. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  338. /**
  339. * Sets the value of the indexed component of the specified array
  340. * object to the specified <code>short</code> value.
  341. * @param array the array
  342. * @param index the index into the array
  343. * @param value the new value of the indexed component
  344. * @exception NullPointerException If the specified object argument
  345. * is null
  346. * @exception IllegalArgumentException If the specified object argument
  347. * is not an array, or if the the specified value cannot be converted
  348. * to the underlying array's component type by an identity or a
  349. * primitive widening widening conversion
  350. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  351. * argument is negative, or if it is greater than or equal to
  352. * the length of the specified array
  353. * @see Array#set
  354. */
  355. public static native void setShort(Object array, int index, short s)
  356. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  357. /**
  358. * Sets the value of the indexed component of the specified array
  359. * object to the specified <code>int</code> value.
  360. * @param array the array
  361. * @param index the index into the array
  362. * @param value the new value of the indexed component
  363. * @exception NullPointerException If the specified object argument
  364. * is null
  365. * @exception IllegalArgumentException If the specified object argument
  366. * is not an array, or if the the specified value cannot be converted
  367. * to the underlying array's component type by an identity or a
  368. * primitive widening widening conversion
  369. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  370. * argument is negative, or if it is greater than or equal to
  371. * the length of the specified array
  372. * @see Array#set
  373. */
  374. public static native void setInt(Object array, int index, int i)
  375. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  376. /**
  377. * Sets the value of the indexed component of the specified array
  378. * object to the specified <code>long</code> value.
  379. * @param array the array
  380. * @param index the index into the array
  381. * @param value 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 the specified value cannot be converted
  386. * to the underlying array's component type by an identity or a
  387. * primitive widening widening conversion
  388. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  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 setLong(Object array, int index, long l)
  394. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  395. /**
  396. * Sets the value of the indexed component of the specified array
  397. * object to the specified <code>float</code> value.
  398. * @param array the array
  399. * @param index the index into the array
  400. * @param value 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 the specified value cannot be converted
  405. * to the underlying array's component type by an identity or a
  406. * primitive widening 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 setFloat(Object array, int index, float f)
  413. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  414. /**
  415. * Sets the value of the indexed component of the specified array
  416. * object to the specified <code>double</code> value.
  417. * @param array the array
  418. * @param index the index into the array
  419. * @param value the new value of the indexed component
  420. * @exception NullPointerException If the specified object argument
  421. * is null
  422. * @exception IllegalArgumentException If the specified object argument
  423. * is not an array, or if the the specified value cannot be converted
  424. * to the underlying array's component type by an identity or a
  425. * primitive widening widening conversion
  426. * @exception ArrayIndexOutOfBoundsException If the specified <code>index</code>
  427. * argument is negative, or if it is greater than or equal to
  428. * the length of the specified array
  429. * @see Array#set
  430. */
  431. public static native void setDouble(Object array, int index, double d)
  432. throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  433. /*
  434. * Private
  435. */
  436. private static native Object newArray(Class componentType, int length)
  437. throws NegativeArraySizeException;
  438. private static native Object multiNewArray(Class componentType,
  439. int[] dimensions)
  440. throws IllegalArgumentException, NegativeArraySizeException;
  441. }