Save This Page
Home » openjdk-7 » java » lang » reflect » [javadoc | source]
    1   /*
    2    * Copyright (c) 1996, 2006, 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        * @param componentType the {@code Class} object representing the
   59        * component type of the new array
   60        * @param length the length of the new array
   61        * @return the new array
   62        * @exception NullPointerException if the specified
   63        * {@code componentType} parameter is null
   64        * @exception IllegalArgumentException if componentType is {@link Void#TYPE}
   65        * @exception NegativeArraySizeException if the specified {@code length}
   66        * is negative
   67        */
   68       public static Object newInstance(Class<?> componentType, int length)
   69           throws NegativeArraySizeException {
   70           return newArray(componentType, length);
   71       }
   72   
   73       /**
   74        * Creates a new array
   75        * with the specified component type and dimensions.
   76        * If {@code componentType}
   77        * represents a non-array class or interface, the new array
   78        * has {@code dimensions.length} dimensions and
   79        * {@code componentType} as its component type. If
   80        * {@code componentType} represents an array class, the
   81        * number of dimensions of the new array is equal to the sum
   82        * of {@code dimensions.length} and the number of
   83        * dimensions of {@code componentType}. In this case, the
   84        * component type of the new array is the component type of
   85        * {@code componentType}.
   86        *
   87        * <p>The number of dimensions of the new array must not
   88        * exceed the number of array dimensions supported by the
   89        * implementation (typically 255).
   90        *
   91        * @param componentType the {@code Class} object representing the component
   92        * type of the new array
   93        * @param dimensions an array of {@code int} representing the dimensions of
   94        * the new array
   95        * @return the new array
   96        * @exception NullPointerException if the specified
   97        * {@code componentType} argument is null
   98        * @exception IllegalArgumentException if the specified {@code dimensions}
   99        * argument is a zero-dimensional array, or if the number of
  100        * requested dimensions exceeds the limit on the number of array dimensions
  101        * supported by the implementation (typically 255), or if componentType
  102        * is {@link Void#TYPE}.
  103        * @exception NegativeArraySizeException if any of the components in
  104        * the specified {@code dimensions} argument is negative.
  105        */
  106       public static Object newInstance(Class<?> componentType, int... dimensions)
  107           throws IllegalArgumentException, NegativeArraySizeException {
  108           return multiNewArray(componentType, dimensions);
  109       }
  110   
  111       /**
  112        * Returns the length of the specified array object, as an {@code int}.
  113        *
  114        * @param array the array
  115        * @return the length of the array
  116        * @exception IllegalArgumentException if the object argument is not
  117        * an array
  118        */
  119       public static native int getLength(Object array)
  120           throws IllegalArgumentException;
  121   
  122       /**
  123        * Returns the value of the indexed component in the specified
  124        * array object.  The value is automatically wrapped in an object
  125        * if it has a primitive type.
  126        *
  127        * @param array the array
  128        * @param index the index
  129        * @return the (possibly wrapped) value of the indexed component in
  130        * the specified array
  131        * @exception NullPointerException If the specified object is null
  132        * @exception IllegalArgumentException If the specified object is not
  133        * an array
  134        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  135        * argument is negative, or if it is greater than or equal to the
  136        * length of the specified array
  137        */
  138       public static native Object get(Object array, int index)
  139           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  140   
  141       /**
  142        * Returns the value of the indexed component in the specified
  143        * array object, as a {@code boolean}.
  144        *
  145        * @param array the array
  146        * @param index the index
  147        * @return the value of the indexed component in the specified array
  148        * @exception NullPointerException If the specified object is null
  149        * @exception IllegalArgumentException If the specified object is not
  150        * an array, or if the indexed element cannot be converted to the
  151        * return type by an identity or widening conversion
  152        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  153        * argument is negative, or if it is greater than or equal to the
  154        * length of the specified array
  155        * @see Array#get
  156        */
  157       public static native boolean getBoolean(Object array, int index)
  158           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  159   
  160       /**
  161        * Returns the value of the indexed component in the specified
  162        * array object, as a {@code byte}.
  163        *
  164        * @param array the array
  165        * @param index the index
  166        * @return the value of the indexed component in the specified array
  167        * @exception NullPointerException If the specified object is null
  168        * @exception IllegalArgumentException If the specified object is not
  169        * an array, or if the indexed element cannot be converted to the
  170        * return type by an identity or widening conversion
  171        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  172        * argument is negative, or if it is greater than or equal to the
  173        * length of the specified array
  174        * @see Array#get
  175        */
  176       public static native byte getByte(Object array, int index)
  177           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  178   
  179       /**
  180        * Returns the value of the indexed component in the specified
  181        * array object, as a {@code char}.
  182        *
  183        * @param array the array
  184        * @param index the index
  185        * @return the value of the indexed component in the specified array
  186        * @exception NullPointerException If the specified object is null
  187        * @exception IllegalArgumentException If the specified object is not
  188        * an array, or if the indexed element cannot be converted to the
  189        * return type by an identity or widening conversion
  190        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  191        * argument is negative, or if it is greater than or equal to the
  192        * length of the specified array
  193        * @see Array#get
  194        */
  195       public static native char getChar(Object array, int index)
  196           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  197   
  198       /**
  199        * Returns the value of the indexed component in the specified
  200        * array object, as a {@code short}.
  201        *
  202        * @param array the array
  203        * @param index the index
  204        * @return the value of the indexed component in the specified array
  205        * @exception NullPointerException If the specified object is null
  206        * @exception IllegalArgumentException If the specified object is not
  207        * an array, or if the indexed element cannot be converted to the
  208        * return type by an identity or widening conversion
  209        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  210        * argument is negative, or if it is greater than or equal to the
  211        * length of the specified array
  212        * @see Array#get
  213        */
  214       public static native short getShort(Object array, int index)
  215           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  216   
  217       /**
  218        * Returns the value of the indexed component in the specified
  219        * array object, as an {@code int}.
  220        *
  221        * @param array the array
  222        * @param index the index
  223        * @return the value of the indexed component in the specified array
  224        * @exception NullPointerException If the specified object is null
  225        * @exception IllegalArgumentException If the specified object is not
  226        * an array, or if the indexed element cannot be converted to the
  227        * return type by an identity or widening conversion
  228        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  229        * argument is negative, or if it is greater than or equal to the
  230        * length of the specified array
  231        * @see Array#get
  232        */
  233       public static native int getInt(Object array, int index)
  234           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  235   
  236       /**
  237        * Returns the value of the indexed component in the specified
  238        * array object, as a {@code long}.
  239        *
  240        * @param array the array
  241        * @param index the index
  242        * @return the value of the indexed component in the specified array
  243        * @exception NullPointerException If the specified object is null
  244        * @exception IllegalArgumentException If the specified object is not
  245        * an array, or if the indexed element cannot be converted to the
  246        * return type by an identity or widening conversion
  247        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  248        * argument is negative, or if it is greater than or equal to the
  249        * length of the specified array
  250        * @see Array#get
  251        */
  252       public static native long getLong(Object array, int index)
  253           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  254   
  255       /**
  256        * Returns the value of the indexed component in the specified
  257        * array object, as a {@code float}.
  258        *
  259        * @param array the array
  260        * @param index the index
  261        * @return the value of the indexed component in the specified array
  262        * @exception NullPointerException If the specified object is null
  263        * @exception IllegalArgumentException If the specified object is not
  264        * an array, or if the indexed element cannot be converted to the
  265        * return type by an identity or widening conversion
  266        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  267        * argument is negative, or if it is greater than or equal to the
  268        * length of the specified array
  269        * @see Array#get
  270        */
  271       public static native float getFloat(Object array, int index)
  272           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  273   
  274       /**
  275        * Returns the value of the indexed component in the specified
  276        * array object, as a {@code double}.
  277        *
  278        * @param array the array
  279        * @param index the index
  280        * @return the value of the indexed component in the specified array
  281        * @exception NullPointerException If the specified object is null
  282        * @exception IllegalArgumentException If the specified object is not
  283        * an array, or if the indexed element cannot be converted to the
  284        * return type by an identity or widening conversion
  285        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  286        * argument is negative, or if it is greater than or equal to the
  287        * length of the specified array
  288        * @see Array#get
  289        */
  290       public static native double getDouble(Object array, int index)
  291           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  292   
  293       /**
  294        * Sets the value of the indexed component of the specified array
  295        * object to the specified new value.  The new value is first
  296        * automatically unwrapped if the array has a primitive component
  297        * type.
  298        * @param array the array
  299        * @param index the index into the array
  300        * @param value 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 array component type is primitive and
  305        * an unwrapping conversion fails
  306        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  307        * argument is negative, or if it is greater than or equal to
  308        * the length of the specified array
  309        */
  310       public static native void set(Object array, int index, Object value)
  311           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  312   
  313       /**
  314        * Sets the value of the indexed component of the specified array
  315        * object to the specified {@code boolean} value.
  316        * @param array the array
  317        * @param index the index into the array
  318        * @param z the new value of the indexed component
  319        * @exception NullPointerException If the specified object argument
  320        * is null
  321        * @exception IllegalArgumentException If the specified object argument
  322        * is not an array, or if the specified value cannot be converted
  323        * to the underlying array's component type by an identity or a
  324        * primitive widening conversion
  325        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  326        * argument is negative, or if it is greater than or equal to
  327        * the length of the specified array
  328        * @see Array#set
  329        */
  330       public static native void setBoolean(Object array, int index, boolean z)
  331           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  332   
  333       /**
  334        * Sets the value of the indexed component of the specified array
  335        * object to the specified {@code byte} value.
  336        * @param array the array
  337        * @param index the index into the array
  338        * @param b the new value of the indexed component
  339        * @exception NullPointerException If the specified object argument
  340        * is null
  341        * @exception IllegalArgumentException If the specified object argument
  342        * is not an array, or if the specified value cannot be converted
  343        * to the underlying array's component type by an identity or a
  344        * primitive widening conversion
  345        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  346        * argument is negative, or if it is greater than or equal to
  347        * the length of the specified array
  348        * @see Array#set
  349        */
  350       public static native void setByte(Object array, int index, byte b)
  351           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  352   
  353       /**
  354        * Sets the value of the indexed component of the specified array
  355        * object to the specified {@code char} value.
  356        * @param array the array
  357        * @param index the index into the array
  358        * @param c the new value of the indexed component
  359        * @exception NullPointerException If the specified object argument
  360        * is null
  361        * @exception IllegalArgumentException If the specified object argument
  362        * is not an array, or if the specified value cannot be converted
  363        * to the underlying array's component type by an identity or a
  364        * primitive widening conversion
  365        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  366        * argument is negative, or if it is greater than or equal to
  367        * the length of the specified array
  368        * @see Array#set
  369        */
  370       public static native void setChar(Object array, int index, char c)
  371           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  372   
  373       /**
  374        * Sets the value of the indexed component of the specified array
  375        * object to the specified {@code short} value.
  376        * @param array the array
  377        * @param index the index into the array
  378        * @param s the new value of the indexed component
  379        * @exception NullPointerException If the specified object argument
  380        * is null
  381        * @exception IllegalArgumentException If the specified object argument
  382        * is not an array, or if the specified value cannot be converted
  383        * to the underlying array's component type by an identity or a
  384        * primitive widening conversion
  385        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  386        * argument is negative, or if it is greater than or equal to
  387        * the length of the specified array
  388        * @see Array#set
  389        */
  390       public static native void setShort(Object array, int index, short s)
  391           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  392   
  393       /**
  394        * Sets the value of the indexed component of the specified array
  395        * object to the specified {@code int} value.
  396        * @param array the array
  397        * @param index the index into the array
  398        * @param i the new value of the indexed component
  399        * @exception NullPointerException If the specified object argument
  400        * is null
  401        * @exception IllegalArgumentException If the specified object argument
  402        * is not an array, or if the specified value cannot be converted
  403        * to the underlying array's component type by an identity or a
  404        * primitive widening conversion
  405        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  406        * argument is negative, or if it is greater than or equal to
  407        * the length of the specified array
  408        * @see Array#set
  409        */
  410       public static native void setInt(Object array, int index, int i)
  411           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  412   
  413       /**
  414        * Sets the value of the indexed component of the specified array
  415        * object to the specified {@code long} value.
  416        * @param array the array
  417        * @param index the index into the array
  418        * @param l the new value of the indexed component
  419        * @exception NullPointerException If the specified object argument
  420        * is null
  421        * @exception IllegalArgumentException If the specified object argument
  422        * is not an array, or if the specified value cannot be converted
  423        * to the underlying array's component type by an identity or a
  424        * primitive widening conversion
  425        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  426        * argument is negative, or if it is greater than or equal to
  427        * the length of the specified array
  428        * @see Array#set
  429        */
  430       public static native void setLong(Object array, int index, long l)
  431           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  432   
  433       /**
  434        * Sets the value of the indexed component of the specified array
  435        * object to the specified {@code float} value.
  436        * @param array the array
  437        * @param index the index into the array
  438        * @param f the new value of the indexed component
  439        * @exception NullPointerException If the specified object argument
  440        * is null
  441        * @exception IllegalArgumentException If the specified object argument
  442        * is not an array, or if the specified value cannot be converted
  443        * to the underlying array's component type by an identity or a
  444        * primitive widening conversion
  445        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  446        * argument is negative, or if it is greater than or equal to
  447        * the length of the specified array
  448        * @see Array#set
  449        */
  450       public static native void setFloat(Object array, int index, float f)
  451           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  452   
  453       /**
  454        * Sets the value of the indexed component of the specified array
  455        * object to the specified {@code double} value.
  456        * @param array the array
  457        * @param index the index into the array
  458        * @param d the new value of the indexed component
  459        * @exception NullPointerException If the specified object argument
  460        * is null
  461        * @exception IllegalArgumentException If the specified object argument
  462        * is not an array, or if the specified value cannot be converted
  463        * to the underlying array's component type by an identity or a
  464        * primitive widening conversion
  465        * @exception ArrayIndexOutOfBoundsException If the specified {@code index}
  466        * argument is negative, or if it is greater than or equal to
  467        * the length of the specified array
  468        * @see Array#set
  469        */
  470       public static native void setDouble(Object array, int index, double d)
  471           throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  472   
  473       /*
  474        * Private
  475        */
  476   
  477       private static native Object newArray(Class componentType, int length)
  478           throws NegativeArraySizeException;
  479   
  480       private static native Object multiNewArray(Class componentType,
  481           int[] dimensions)
  482           throws IllegalArgumentException, NegativeArraySizeException;
  483   
  484   
  485   }

Save This Page
Home » openjdk-7 » java » lang » reflect » [javadoc | source]