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