home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / lang / reflect / Array.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  19.5 KB  |  463 lines
  1. /*
  2.  * @(#)Array.java    1.5 98/03/18
  3.  *
  4.  * Copyright 1996, 1997 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.lang.reflect;
  16.  
  17. /**
  18.  * The Array class provides static methods to dynamically create and
  19.  * access Java arrays.
  20.  *
  21.  * <p>Array permits widening conversions to occur during a get or set
  22.  * operation, but throws an IllegalArgumentException if a narrowing
  23.  * conversion would occur.
  24.  *
  25.  * @author Nakul Saraiya
  26.  */
  27. public final
  28. class Array {
  29.  
  30.     /**
  31.      * Constructor.  Class Array is not instantiable.
  32.      */
  33.     private Array() {}
  34.  
  35.     /**
  36.      * Creates a new array with the specified component type and
  37.      * length.
  38.  
  39.      * The effect is that of the equivalent array creation expression:
  40.      * <pre>
  41.      *    new componentType[length]
  42.      * </pre>
  43.      *
  44.      * @param componentType the Class object representing the
  45.      * component type of the new array
  46.      * @param length the length of the new array
  47.      * @return the new array
  48.      * @exception NullPointerException if the specified
  49.      * componentType parameter is null
  50.      * @exception NegativeArraySizeException if the specified length
  51.      * is negative
  52.      */
  53.     public static Object newInstance(Class componentType, int length)
  54.     throws NegativeArraySizeException {
  55.     return newArray(componentType, length);
  56.     }
  57.  
  58.     /**
  59.      * Creates a new array with the specified component type and
  60.      * dimensions.
  61.      *
  62.      * <p>The effect is that of the equivalent array creation expression:
  63.      * <pre>
  64.      *    new componentType[dimensions[0]][dimensions[1]]...
  65.      * </pre>
  66.      *
  67.      * @param componentType the Class object representing the component
  68.      * type of the new array
  69.      * @param dimensions an array of ints representing the dimensions of
  70.      * the new array
  71.      * @return the new array
  72.      * @exception NullPointerException if the specified 
  73.      * componentType argument is null
  74.      * @exception IllegalArgumentException if the specified dimensions
  75.      * argument is a zero-dimensional array, or if the number of
  76.      * requested dimensions exceeds the limit on the number of array dimensions 
  77.      * supported by the implementation (typically 255).
  78.      * @exception NegativeArraySizeException if any of the components in
  79.      * the specified dimension argument is negative.
  80.      */
  81.     public static Object newInstance(Class componentType, int[] dimensions)
  82.     throws IllegalArgumentException, NegativeArraySizeException {
  83.     return multiNewArray(componentType, dimensions);
  84.     }
  85.  
  86.     /**
  87.      * Returns the length of the specified array object, as an int.
  88.      *
  89.      * @param array the array
  90.      * @return the length of the array
  91.      * @exception IllegalArgumentException if the object argument is not
  92.      * an array
  93.      */
  94.     public static native int getLength(Object array)
  95.     throws IllegalArgumentException;
  96.  
  97.     /**
  98.      * Returns the value of the indexed component in the specified
  99.      * array object.  The value is automatically wrapped in an object
  100.      * if it has a primitive type.
  101.      *
  102.      * @param array the array
  103.      * @param index the index
  104.      * @return the (possibly wrapped) value of the indexed component in
  105.      * the specified array
  106.      * @exception NullPointerException If the specified object is null
  107.      * @exception IllegalArgumentException If the specified object is not
  108.      * an array
  109.      * @exception ArrayIndexOutOfBoundsException If the specified index
  110.      * argument is negative, or if it is greater than or equal to the
  111.      * length of the specified array
  112.      */
  113.     public static native Object get(Object array, int index)
  114.      throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  115.  
  116.     /**
  117.      * Returns the value of the indexed component in the specified
  118.      * array object, as a boolean.
  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 index
  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.     /**
  136.      * Returns the value of the indexed component in the specified
  137.      * array object, as a byte.
  138.      *
  139.      * @param array the array
  140.      * @param index the index
  141.      * @return the value of the indexed component in the specified array
  142.      * @exception NullPointerException If the specified object is null
  143.      * @exception IllegalArgumentException If the specified object is not
  144.      * an array, or if the indexed element cannot be converted to the
  145.      * return type by an identity or widening conversion
  146.      * @exception ArrayIndexOutOfBoundsException If the specified index
  147.      * argument is negative, or if it is greater than or equal to the
  148.      * length of the specified array
  149.      * @see Array#get
  150.      */
  151.     public static native byte getByte(Object array, int index)
  152.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  153.  
  154.     /**
  155.      * Returns the value of the indexed component in the specified
  156.      * array object, as a char.
  157.      *
  158.      * @param array the array
  159.      * @param index the index
  160.      * @return the value of the indexed component in the specified array
  161.      * @exception NullPointerException If the specified object is null
  162.      * @exception IllegalArgumentException If the specified object is not
  163.      * an array, or if the indexed element cannot be converted to the
  164.      * return type by an identity or widening conversion
  165.      * @exception ArrayIndexOutOfBoundsException If the specified index
  166.      * argument is negative, or if it is greater than or equal to the
  167.      * length of the specified array
  168.      * @see Array#get
  169.      */
  170.     public static native char getChar(Object array, int index)
  171.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  172.  
  173.     /**
  174.      * Returns the value of the indexed component in the specified
  175.      * array object, as a short.
  176.      *
  177.      * @param array the array
  178.      * @param index the index
  179.      * @return the value of the indexed component in the specified array
  180.      * @exception NullPointerException If the specified object is null
  181.      * @exception IllegalArgumentException If the specified object is not
  182.      * an array, or if the indexed element cannot be converted to the
  183.      * return type by an identity or widening conversion
  184.      * @exception ArrayIndexOutOfBoundsException If the specified index
  185.      * argument is negative, or if it is greater than or equal to the
  186.      * length of the specified array
  187.      * @see Array#get
  188.      */
  189.     public static native short getShort(Object array, int index)
  190.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  191.  
  192.     /**
  193.      * Returns the value of the indexed component in the specified
  194.      * array object, as an int.
  195.      *
  196.      * @param array the array
  197.      * @param index the index
  198.      * @return the value of the indexed component in the specified array
  199.      * @exception NullPointerException If the specified object is null
  200.      * @exception IllegalArgumentException If the specified object is not
  201.      * an array, or if the indexed element cannot be converted to the
  202.      * return type by an identity or widening conversion
  203.      * @exception ArrayIndexOutOfBoundsException If the specified index
  204.      * argument is negative, or if it is greater than or equal to the
  205.      * length of the specified array
  206.      * @see Array#get
  207.      */
  208.     public static native int getInt(Object array, int index)
  209.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  210.  
  211.     /**
  212.      * Returns the value of the indexed component in the specified
  213.      * array object, as a long.
  214.      *
  215.      * @param array the array
  216.      * @param index the index
  217.      * @return the value of the indexed component in the specified array
  218.      * @exception NullPointerException If the specified object is null
  219.      * @exception IllegalArgumentException If the specified object is not
  220.      * an array, or if the indexed element cannot be converted to the
  221.      * return type by an identity or widening conversion
  222.      * @exception ArrayIndexOutOfBoundsException If the specified index
  223.      * argument is negative, or if it is greater than or equal to the
  224.      * length of the specified array
  225.      * @see Array#get
  226.      */
  227.     public static native long getLong(Object array, int index)
  228.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  229.  
  230.     /**
  231.      * Returns the value of the indexed component in the specified
  232.      * array object, as a float.
  233.      *
  234.      * @param array the array
  235.      * @param index the index
  236.      * @return the value of the indexed component in the specified array
  237.      * @exception NullPointerException If the specified object is null
  238.      * @exception IllegalArgumentException If the specified object is not
  239.      * an array, or if the indexed element cannot be converted to the
  240.      * return type by an identity or widening conversion
  241.      * @exception ArrayIndexOutOfBoundsException If the specified index
  242.      * argument is negative, or if it is greater than or equal to the
  243.      * length of the specified array
  244.      * @see Array#get
  245.      */
  246.     public static native float getFloat(Object array, int index)
  247.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  248.  
  249.     /**
  250.      * Returns the value of the indexed component in the specified
  251.      * array object, as a double.
  252.      *
  253.      * @param array the array
  254.      * @param index the index
  255.      * @return the value of the indexed component in the specified array
  256.      * @exception NullPointerException If the specified object is null
  257.      * @exception IllegalArgumentException If the specified object is not
  258.      * an array, or if the indexed element cannot be converted to the
  259.      * return type by an identity or widening conversion
  260.      * @exception ArrayIndexOutOfBoundsException If the specified index
  261.      * argument is negative, or if it is greater than or equal to the
  262.      * length of the specified array
  263.      * @see Array#get
  264.      */
  265.     public static native double getDouble(Object array, int index)
  266.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  267.  
  268.     /**
  269.      * Sets the value of the indexed component of the specified array
  270.      * object to the specified new value.  The new value is first
  271.      * automatically unwrapped if the array has a primitive component
  272.      * type.
  273.      * @param array the array
  274.      * @param index the index into the array
  275.      * @param value the new value of the indexed component
  276.      * @exception NullPointerException If the specified object argument
  277.      * is null, or if the array component type is primitive and the specified
  278.      * value is null
  279.      * @exception IllegalArgumentException If the specified object argument
  280.      * is not an array, or if the array component type is primitive and
  281.      * the specified value cannot be converted to the primitive type by
  282.      * a combination of unwrapping and identity or widening conversions
  283.      * @exception ArrayIndexOutOfBoundsException If the specified index
  284.      * argument is negative, or if it is greater than or equal to
  285.      * the length of the specified array
  286.      */
  287.     public static native void set(Object array, int index, Object value)
  288.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  289.  
  290.     /**
  291.      * Sets the value of the indexed component of the specified array
  292.      * object to the specified boolean value.
  293.      * @param array the array
  294.      * @param index the index into the array
  295.      * @param value the new value of the indexed component
  296.      * @exception NullPointerException If the specified object argument
  297.      * is null
  298.      * @exception IllegalArgumentException If the specified object argument
  299.      * is not an array, or if the the specified value cannot be converted
  300.      * to the underlying array's component type by an identity or a
  301.      * primitive widening widening conversion
  302.      * @exception ArrayIndexOutOfBoundsException If the specified index
  303.      * argument is negative, or if it is greater than or equal to
  304.      * the length of the specified array
  305.      * @see Array#set
  306.      */
  307.     public static native void setBoolean(Object array, int index, boolean z)
  308.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  309.  
  310.     /**
  311.      * Sets the value of the indexed component of the specified array
  312.      * object to the specified boolean value.
  313.      * @param array the array
  314.      * @param index the index into the array
  315.      * @param value the new value of the indexed component
  316.      * @exception NullPointerException If the specified object argument
  317.      * is null
  318.      * @exception IllegalArgumentException If the specified object argument
  319.       * is not an array, or if the the specified value cannot be converted
  320.      * to the underlying array's component type by an identity or a
  321.      * primitive widening widening conversion
  322.      * @exception ArrayIndexOutOfBoundsException If the specified index
  323.      * argument is negative, or if it is greater than or equal to
  324.      * the length of the specified array
  325.      * @see Array#set
  326.      */
  327.     public static native void setByte(Object array, int index, byte b)
  328.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  329.  
  330.     /**
  331.      * Sets the value of the indexed component of the specified array
  332.      * object to the specified byte value.
  333.      * @param array the array
  334.      * @param index the index into the array
  335.      * @param value the new value of the indexed component
  336.      * @exception NullPointerException If the specified object argument
  337.      * is null
  338.      * @exception IllegalArgumentException If the specified object argument
  339.      * is not an array, or if the the specified value cannot be converted
  340.      * to the underlying array's component type by an identity or a
  341.      * primitive widening widening conversion
  342.      * @exception ArrayIndexOutOfBoundsException If the specified index
  343.      * argument is negative, or if it is greater than or equal to
  344.      * the length of the specified array
  345.      * @see Array#set
  346.      */
  347.     public static native void setChar(Object array, int index, char c)
  348.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  349.  
  350.     /**
  351.      * Sets the value of the indexed component of the specified array
  352.      * object to the specified short value.
  353.      * @param array the array
  354.      * @param index the index into the array
  355.      * @param value the new value of the indexed component
  356.      * @exception NullPointerException If the specified object argument
  357.      * is null
  358.      * @exception IllegalArgumentException If the specified object argument
  359.      * is not an array, or if the the specified value cannot be converted
  360.      * to the underlying array's component type by an identity or a
  361.      * primitive widening widening conversion
  362.      * @exception ArrayIndexOutOfBoundsException If the specified index
  363.      * argument is negative, or if it is greater than or equal to
  364.      * the length of the specified array
  365.      * @see Array#set
  366.      */
  367.     public static native void setShort(Object array, int index, short s)
  368.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  369.  
  370.     /**
  371.      * Sets the value of the indexed component of the specified array
  372.      * object to the specified int value.
  373.      * @param array the array
  374.      * @param index the index into the array
  375.      * @param value the new value of the indexed component
  376.      * @exception NullPointerException If the specified object argument
  377.      * is null
  378.      * @exception IllegalArgumentException If the specified object argument
  379.      * is not an array, or if the the specified value cannot be converted
  380.      * to the underlying array's component type by an identity or a
  381.      * primitive widening widening conversion
  382.      * @exception ArrayIndexOutOfBoundsException If the specified index
  383.      * argument is negative, or if it is greater than or equal to
  384.      * the length of the specified array
  385.      * @see Array#set
  386.      */
  387.     public static native void setInt(Object array, int index, int i)
  388.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  389.  
  390.     /**
  391.      * Sets the value of the indexed component of the specified array
  392.      * object to the specified long value.
  393.      * @param array the array
  394.      * @param index the index into the array
  395.      * @param value the new value of the indexed component
  396.      * @exception NullPointerException If the specified object argument
  397.      * is null
  398.      * @exception IllegalArgumentException If the specified object argument
  399.      * is not an array, or if the the specified value cannot be converted
  400.      * to the underlying array's component type by an identity or a
  401.      * primitive widening widening conversion
  402.      * @exception ArrayIndexOutOfBoundsException If the specified index
  403.      * argument is negative, or if it is greater than or equal to
  404.      * the length of the specified array
  405.      * @see Array#set
  406.      */
  407.     public static native void setLong(Object array, int index, long l)
  408.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  409.  
  410.     /**
  411.      * Sets the value of the indexed component of the specified array
  412.      * object to the specified float value.
  413.      * @param array the array
  414.      * @param index the index into the array
  415.      * @param value the new value of the indexed component
  416.      * @exception NullPointerException If the specified object argument
  417.      * is null
  418.      * @exception IllegalArgumentException If the specified object argument
  419.      * is not an array, or if the the specified value cannot be converted
  420.      * to the underlying array's component type by an identity or a
  421.      * primitive widening widening conversion
  422.      * @exception ArrayIndexOutOfBoundsException If the specified index
  423.      * argument is negative, or if it is greater than or equal to
  424.      * the length of the specified array
  425.      * @see Array#set
  426.      */
  427.     public static native void setFloat(Object array, int index, float f)
  428.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  429.  
  430.     /**
  431.      * Sets the value of the indexed component of the specified array
  432.      * object to the specified double value.
  433.      * @param array the array
  434.      * @param index the index into the array
  435.      * @param value the new value of the indexed component
  436.      * @exception NullPointerException If the specified object argument
  437.      * is null
  438.      * @exception IllegalArgumentException If the specified object argument
  439.      * is not an array, or if the the specified value cannot be converted
  440.      * to the underlying array's component type by an identity or a
  441.      * primitive widening widening conversion
  442.      * @exception ArrayIndexOutOfBoundsException If the specified index
  443.      * argument is negative, or if it is greater than or equal to
  444.      * the length of the specified array
  445.      * @see Array#set
  446.      */
  447.     public static native void setDouble(Object array, int index, double d)
  448.     throws IllegalArgumentException, ArrayIndexOutOfBoundsException;
  449.  
  450.     /*
  451.      * Private
  452.      */
  453.  
  454.     private static native Object newArray(Class componentType, int length)
  455.     throws NegativeArraySizeException;
  456.  
  457.     private static native Object multiNewArray(Class componentType,
  458.     int[] dimensions)
  459.     throws IllegalArgumentException, NegativeArraySizeException;
  460.  
  461.  
  462. }
  463.