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 / Field.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  16.2 KB  |  439 lines
  1. /*
  2.  * @(#)Field.java    1.14 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.  * A Field provides information about, and dynamic access to, a
  19.  * single field of a class or an interface.  The reflected field may
  20.  * be a class (static) field or an instance field.
  21.  *
  22.  * <p>A Field permits widening conversions to occur during a get or
  23.  * set access operation, but throws an IllegalArgumentException if a
  24.  * narrowing conversion would occur.
  25.  *
  26.  * @see Member
  27.  * @see java.lang.Class
  28.  * @see java.lang.Class#getFields()
  29.  * @see java.lang.Class#getField()
  30.  * @see java.lang.Class#getDeclaredFields()
  31.  * @see java.lang.Class#getDeclaredField()
  32.  *
  33.  * @author Nakul Saraiya
  34.  */
  35. public final
  36. class Field extends AccessibleObject implements Member {
  37.  
  38.     private Class        clazz;
  39.     private int            slot;
  40.     private String        name;
  41.     private Class        type;
  42.     private int            modifiers;
  43.  
  44.     /**
  45.      * Constructor.  Only the Java Virtual Machine may construct a Field.
  46.      */
  47.     private Field() {}
  48.  
  49.     /**
  50.      * Returns the Class object representing the class or interface
  51.      * that declares the field represented by this Field object.
  52.      */
  53.     public Class getDeclaringClass() {
  54.     return clazz;
  55.     }
  56.  
  57.     /**
  58.      * Returns the name of the field represented by this Field object.
  59.      */
  60.     public String getName() {
  61.     return name;
  62.     }
  63.  
  64.     /**
  65.      * Returns the Java language modifiers for the field represented
  66.      * by this Field object, as an integer. The Modifier class should
  67.      * be used to decode the modifiers.
  68.      *
  69.      * @see Modifier
  70.      */
  71.     public int getModifiers() {
  72.     return modifiers;
  73.     }
  74.  
  75.     /**
  76.      * Returns a Class object that identifies the declared type for
  77.      * the field represented by this Field object.
  78.      */
  79.     public Class getType() {
  80.     return type;
  81.     }
  82.  
  83.     /**
  84.      * Compares this Field against the specified object.  Returns
  85.      * true if the objects are the same.  Two Fields are the same if
  86.      * they were declared by the same class and have the same name
  87.      * and type.
  88.      */
  89.     public boolean equals(Object obj) {
  90.     if (obj != null && obj instanceof Field) {
  91.         Field other = (Field)obj;
  92.         return (getDeclaringClass() == other.getDeclaringClass())
  93.         && (getName().equals(other.getName()))
  94.         && (getType() == other.getType());
  95.     }
  96.     return false;
  97.     }
  98.  
  99.     /**
  100.      * Returns a hashcode for this Field.  This is computed as the
  101.      * exclusive-or of the hashcodes for the underlying field's
  102.      * declaring class name and its name.
  103.      */
  104.     public int hashCode() {
  105.     return getDeclaringClass().getName().hashCode() ^ getName().hashCode();
  106.     }
  107.  
  108.     /**
  109.      * Return a string describing this Field.  The format is
  110.      * the access modifiers for the field, if any, followed
  111.      * by the field type, followed by a space, followed by
  112.      * the fully-qualified name of the class declaring the field,
  113.      * followed by a period, followed by the name of the field.
  114.      * For example:
  115.      * <pre>
  116.      *    public static final int java.lang.Thread.MIN_PRIORITY
  117.      *    private int java.io.FileDescriptor.fd
  118.      * </pre>
  119.      *
  120.      * <p>The modifiers are placed in canonical order as specified by
  121.      * "The Java Language Specification".  This is <tt>public</tt>,
  122.      * <tt>protected</tt> or <tt>private</tt> first, and then other
  123.      * modifiers in the following order: <tt>static</tt>, <tt>final</tt>,
  124.      * <tt>transient</tt>, <tt>volatile</tt>.
  125.      */
  126.     public String toString() {
  127.     int mod = getModifiers();
  128.     return (((mod == 0) ? "" : (Modifier.toString(mod) + " "))
  129.         + getTypeName(getType()) + " "
  130.         + getTypeName(getDeclaringClass()) + "."
  131.         + getName());
  132.     }
  133.  
  134.     /**
  135.      * Returns the value of the field represented by this Field, on
  136.      * the specified object. The value is automatically wrapped in an
  137.      * object if it has a primitive type.
  138.      *
  139.      * <p>The underlying field's value is obtained as follows:
  140.      *
  141.      * <p>If the underlying field is a static field, the object argument
  142.      * is ignored; it may be null.
  143.      *
  144.      * <p>Otherwise, the underlying field is an instance field.  If the
  145.      * specified object argument is null, the method throws a
  146.      * NullPointerException. If the specified object is not an
  147.      * instance of the class or interface declaring the underlying
  148.      * field, the method throws an IllegalArgumentException.
  149.      *
  150.      * <p>If this Field object enforces Java language access control, and
  151.      * the underlying field is inaccessible, the method throws an
  152.      * IllegalAccessException.
  153.      *
  154.      * <p>Otherwise, the value is retrieved from the underlying instance
  155.      * or static field.  If the field has a primitive type, the value
  156.      * is wrapped in an object before being returned, otherwise it is
  157.      * returned as is.
  158.      *
  159.      * @exception IllegalAccessException    if the underlying constructor
  160.      *              is inaccessible.
  161.      * @exception IllegalArgumentException  if the specified object is not an
  162.      *              instance of the class or interface declaring the underlying
  163.      *              field.
  164.      * @exception NullPointerException      if the specified object is null.
  165.      */
  166.     public native Object get(Object obj)
  167.     throws IllegalArgumentException, IllegalAccessException;
  168.  
  169.     /**
  170.      * Get the value of a field as a boolean on specified object.
  171.      *
  172.      * @exception IllegalAccessException    if the underlying constructor
  173.      *              is inaccessible.
  174.      * @exception IllegalArgumentException  if the field value cannot be
  175.      *              converted to the return type by a widening conversion.
  176.      * @see       Field#get
  177.      */
  178.     public native boolean getBoolean(Object obj)
  179.     throws IllegalArgumentException, IllegalAccessException;
  180.  
  181.     /**
  182.      * Get the value of a field as a byte on specified object.
  183.      *
  184.      * @exception IllegalAccessException    if the underlying constructor
  185.      *              is inaccessible.
  186.      * @exception IllegalArgumentException  if the field value cannot be
  187.      *              converted to the return type by a widening conversion.
  188.      * @see       Field#get
  189.      */
  190.     public native byte getByte(Object obj)
  191.     throws IllegalArgumentException, IllegalAccessException;
  192.  
  193.     /**
  194.      * Get the value of a field as a char on specified object.
  195.      *
  196.      * @exception IllegalAccessException    if the underlying constructor
  197.      *              is inaccessible.
  198.      * @exception IllegalArgumentException  if the field value cannot be
  199.      *              converted to the return type by a widening conversion.
  200.      * @see       Field#get
  201.      */
  202.     public native char getChar(Object obj)
  203.     throws IllegalArgumentException, IllegalAccessException;
  204.  
  205.     /**
  206.      * Get the value of a field as a short on specified object.
  207.      *
  208.      * @exception IllegalAccessException    if the underlying constructor
  209.      *              is inaccessible.
  210.      * @exception IllegalArgumentException  if the field value cannot be
  211.      *              converted to the return type by a widening conversion.
  212.      * @see       Field#get
  213.      */
  214.     public native short getShort(Object obj)
  215.     throws IllegalArgumentException, IllegalAccessException;
  216.  
  217.     /**
  218.      * Get the value of a field as a int on specified object.
  219.      *
  220.      * @exception IllegalAccessException    if the underlying constructor
  221.      *              is inaccessible.
  222.      * @exception IllegalArgumentException  if the field value cannot be
  223.      *              converted to the return type by a widening conversion.
  224.      * @see       Field#get
  225.      */
  226.     public native int getInt(Object obj)
  227.     throws IllegalArgumentException, IllegalAccessException;
  228.  
  229.     /**
  230.      * Get the value of a field as a long on specified object.
  231.      *
  232.      * @exception IllegalAccessException    if the underlying constructor
  233.      *              is inaccessible.
  234.      * @exception IllegalArgumentException  if the field value cannot be
  235.      *              converted to the return type by a widening conversion.
  236.      * @see       Field#get
  237.      */
  238.     public native long getLong(Object obj)
  239.     throws IllegalArgumentException, IllegalAccessException;
  240.  
  241.     /**
  242.      * Get the value of a field as a float on specified object.
  243.      *
  244.      * @exception IllegalAccessException    if the underlying constructor
  245.      *              is inaccessible.
  246.      * @exception IllegalArgumentException  if the field value cannot be
  247.      *              converted to the return type by a widening conversion.
  248.      * @see       Field#get
  249.      */
  250.     public native float getFloat(Object obj)
  251.     throws IllegalArgumentException, IllegalAccessException;
  252.  
  253.     /**
  254.      * Get the value of a field as a double on specified object.
  255.      *
  256.      * @exception IllegalAccessException    if the underlying constructor
  257.      *              is inaccessible.
  258.      * @exception IllegalArgumentException  if the field value cannot be
  259.      *              converted to the return type by a widening conversion.
  260.      * @see       Field#get
  261.      */
  262.     public native double getDouble(Object obj)
  263.     throws IllegalArgumentException, IllegalAccessException;
  264.  
  265.     /**
  266.      * Sets the field represented by this Field object on the
  267.      * specified object argument to the specified new value. The new
  268.      * value is automatically unwrapped if the underlying field has a
  269.      * primitive type.
  270.      *
  271.      * <p>The operation proceeds as follows:
  272.      *
  273.      * <p>If the underlying field is static, the object argument is
  274.      * ignored; it may be null.
  275.      *
  276.      * <p>Otherwise the underlying field is an instance field.  If the
  277.      * specified object argument is null, the method throws a
  278.      * NullPointerException.  If the specified object argument is not
  279.      * an instance of the class or interface declaring the underlying
  280.      * field, the method throws an IllegalArgumentException.
  281.      *
  282.      * <p>If this Field object enforces Java language access control, and
  283.      * the underlying field is inaccessible, the method throws an
  284.      * IllegalAccessException.
  285.      *
  286.      * <p>If the underlying field is final, the method throws an
  287.      * IllegalAccessException.
  288.      *
  289.      * <p>If the underlying field is of a primitive type, an unwrapping
  290.      * conversion is attempted to convert the new value to a value of
  291.      * a primitive type.  If this attempt fails, the method throws an
  292.      * IllegalArgumentException.
  293.      *
  294.      * <p>If, after possible unwrapping, the new value cannot be
  295.      * converted to the type of the underlying field by an identity or
  296.      * widening conversion, the method throws an
  297.      * IllegalArgumentException.
  298.      *
  299.      * <p>The field is set to the possibly unwrapped and widened new value.
  300.      *
  301.      * @exception IllegalAccessException    if the underlying constructor
  302.      *              is inaccessible.
  303.      * @exception IllegalArgumentException  if the specified object is not an
  304.      *              instance of the class or interface declaring the underlying
  305.      *              field, or if an unwrapping conversion fails.
  306.      * @exception NullPointerException      if the specified object is null.
  307.      */
  308.     public native void set(Object obj, Object value)
  309.     throws IllegalArgumentException, IllegalAccessException;
  310.  
  311.     /**
  312.      * Set the value of a field as a boolean on specified object.
  313.      *
  314.      * @exception IllegalAccessException    if the underlying constructor
  315.      *              is inaccessible.
  316.      * @exception IllegalArgumentException  if the specified object is not an
  317.      *              instance of the class or interface declaring the underlying
  318.      *              field, or if an unwrapping conversion fails.
  319.      * @see       Field#set
  320.      */
  321.     public native void setBoolean(Object obj, boolean z)
  322.     throws IllegalArgumentException, IllegalAccessException;
  323.  
  324.     /**
  325.      * Set the value of a field as a byte on specified object.
  326.      *
  327.      * @exception IllegalAccessException    if the underlying constructor
  328.      *              is inaccessible.
  329.      * @exception IllegalArgumentException  if the specified object is not an
  330.      *              instance of the class or interface declaring the underlying
  331.      *              field, or if an unwrapping conversion fails.
  332.      * @see       Field#set
  333.      */
  334.     public native void setByte(Object obj, byte b)
  335.     throws IllegalArgumentException, IllegalAccessException;
  336.  
  337.     /**
  338.      * Set the value of a field as a char on specified object.
  339.      *
  340.      * @exception IllegalAccessException    if the underlying constructor
  341.      *              is inaccessible.
  342.      * @exception IllegalArgumentException  if the specified object is not an
  343.      *              instance of the class or interface declaring the underlying
  344.      *              field, or if an unwrapping conversion fails.
  345.      * @see       Field#set
  346.      */
  347.     public native void setChar(Object obj, char c)
  348.     throws IllegalArgumentException, IllegalAccessException;
  349.  
  350.     /**
  351.      * Set the value of a field as a short on specified object.
  352.      *
  353.      * @exception IllegalAccessException    if the underlying constructor
  354.      *              is inaccessible.
  355.      * @exception IllegalArgumentException  if the specified object is not an
  356.      *              instance of the class or interface declaring the underlying
  357.      *              field, or if an unwrapping conversion fails.
  358.      * @see       Field#set
  359.      */
  360.     public native void setShort(Object obj, short s)
  361.     throws IllegalArgumentException, IllegalAccessException;
  362.  
  363.     /**
  364.      * Set the value of a field as an int on specified object.
  365.      *
  366.      * @exception IllegalAccessException    if the underlying constructor
  367.      *              is inaccessible.
  368.      * @exception IllegalArgumentException  if the specified object is not an
  369.      *              instance of the class or interface declaring the underlying
  370.      *              field, or if an unwrapping conversion fails.
  371.      * @see       Field#set
  372.      */
  373.     public native void setInt(Object obj, int i)
  374.     throws IllegalArgumentException, IllegalAccessException;
  375.  
  376.     /**
  377.      * Set the value of a field as a long on specified object.
  378.      *
  379.      * @exception IllegalAccessException    if the underlying constructor
  380.      *              is inaccessible.
  381.      * @exception IllegalArgumentException  if the specified object is not an
  382.      *              instance of the class or interface declaring the underlying
  383.      *              field, or if an unwrapping conversion fails.
  384.      * @see       Field#set
  385.      */
  386.     public native void setLong(Object obj, long l)
  387.     throws IllegalArgumentException, IllegalAccessException;
  388.  
  389.     /**
  390.      * Set the value of a field as a float on specified object.
  391.      *
  392.      * @exception IllegalAccessException    if the underlying constructor
  393.      *              is inaccessible.
  394.      * @exception IllegalArgumentException  if the specified object is not an
  395.      *              instance of the class or interface declaring the underlying
  396.      *              field, or if an unwrapping conversion fails.
  397.      * @see       Field#set
  398.      */
  399.     public native void setFloat(Object obj, float f)
  400.     throws IllegalArgumentException, IllegalAccessException;
  401.  
  402.     /**
  403.      * Set the value of a field as a double on specified object.
  404.      *
  405.      * @exception IllegalAccessException    if the underlying constructor
  406.      *              is inaccessible.
  407.      * @exception IllegalArgumentException  if the specified object is not an
  408.      *              instance of the class or interface declaring the underlying
  409.      *              field, or if an unwrapping conversion fails.
  410.      * @see       Field#set
  411.      */
  412.     public native void setDouble(Object obj, double d)
  413.     throws IllegalArgumentException, IllegalAccessException;
  414.  
  415.     /*
  416.      * Utility routine to paper over array type names
  417.      */
  418.     static String getTypeName(Class type) {
  419.     if (type.isArray()) {
  420.         try {
  421.         Class cl = type;
  422.         int dimensions = 0;
  423.         while (cl.isArray()) {
  424.             dimensions++;
  425.             cl = cl.getComponentType();
  426.         }
  427.         StringBuffer sb = new StringBuffer();
  428.         sb.append(cl.getName());
  429.         for (int i = 0; i < dimensions; i++) {
  430.             sb.append("[]");
  431.         }
  432.         return sb.toString();
  433.         } catch (Throwable e) { /*FALLTHRU*/ }
  434.     }
  435.     return type.getName();
  436.     }
  437.  
  438. }
  439.