gomp-20050608-branch/libjava/classpath/vm/reference/java/lang/reflect/Field.java

   1 /* java.lang.reflect.Field - reflection of Java fields
   2    Copyright (C) 1998, 2001 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.lang.reflect;
  40
  41 /**
  42  * The Field class represents a member variable of a class. It also allows
  43  * dynamic access to a member, via reflection. This works for both
  44  * static and instance fields. Operations on Field objects know how to
  45  * do widening conversions, but throw {@link IllegalArgumentException} if
  46  * a narrowing conversion would be necessary. You can query for information
  47  * on this Field regardless of location, but get and set access may be limited
  48  * by Java language access controls. If you can't do it in the compiler, you
  49  * can't normally do it here either.<p>
  50  *
  51  * <B>Note:</B> This class returns and accepts types as Classes, even
  52  * primitive types; there are Class types defined that represent each
  53  * different primitive type.  They are <code>java.lang.Boolean.TYPE,
  54  * java.lang.Byte.TYPE,</code>, also available as <code>boolean.class,
  55  * byte.class</code>, etc.  These are not to be confused with the
  56  * classes <code>java.lang.Boolean, java.lang.Byte</code>, etc., which are
  57  * real classes.<p>
  58  *
  59  * Also note that this is not a serializable class.  It is entirely feasible
  60  * to make it serializable using the Externalizable interface, but this is
  61  * on Sun, not me.
  62  *
  63  * @author John Keiser
  64  * @author Eric Blake <ebb9@email.byu.edu>
  65  * @see Member
  66  * @see Class
  67  * @see Class#getField(String)
  68  * @see Class#getDeclaredField(String)
  69  * @see Class#getFields()
  70  * @see Class#getDeclaredFields()
  71  * @since 1.1
  72  * @status updated to 1.4
  73  */
  74 public final class Field
  75 extends AccessibleObject implements Member
  76 {
  77   private Class declaringClass;
  78   private String name;
  79   private int slot;
  80
  81   /**
  82    * This class is uninstantiable except natively.
  83    */
  84   private Field(Class declaringClass, String name, int slot)
  85   {
  86     this.declaringClass = declaringClass;
  87     this.name = name;
  88     this.slot = slot;
  89   }
  90
  91   /**
  92    * Gets the class that declared this field, or the class where this field
  93    * is a non-inherited member.
  94    * @return the class that declared this member
  95    */
  96   public Class getDeclaringClass()
  97   {
  98     return declaringClass;
  99   }
 100
 101   /**
 102    * Gets the name of this field.
 103    * @return the name of this field
 104    */
 105   public String getName()
 106   {
 107     return name;
 108   }
 109
 110   /**
 111    * Gets the modifiers this field uses.  Use the <code>Modifier</code>
 112    * class to interpret the values.  A field can only have a subset of the
 113    * following modifiers: public, private, protected, static, final,
 114    * transient, and volatile.
 115    *
 116    * @return an integer representing the modifiers to this Member
 117    * @see Modifier
 118    */
 119   public native int getModifiers();
 120
 121   /**
 122    * Gets the type of this field.
 123    * @return the type of this field
 124    */
 125   public native Class getType();
 126
 127   /**
 128    * Compare two objects to see if they are semantically equivalent.
 129    * Two Fields are semantically equivalent if they have the same declaring
 130    * class, name, and type. Since you can't creat a Field except through
 131    * the VM, this is just the == relation.
 132    *
 133    * @param o the object to compare to
 134    * @return <code>true</code> if they are equal; <code>false</code> if not
 135    */
 136   public boolean equals(Object o)
 137   {
 138     if (!(o instanceof Field))
 139       return false;
 140     Field that = (Field)o;
 141     if (this.getDeclaringClass() != that.getDeclaringClass())
 142       return false;
 143     if (!this.getName().equals(that.getName()))
 144       return false;
 145     if (this.getType() != that.getType())
 146       return false;
 147     return true;
 148   }
 149
 150   /**
 151    * Get the hash code for the Field. The Field hash code is the hash code
 152    * of its name XOR'd with the hash code of its class name.
 153    *
 154    * @return the hash code for the object.
 155    */
 156   public int hashCode()
 157   {
 158     return getDeclaringClass().getName().hashCode() ^ getName().hashCode();
 159   }
 160
 161   /**
 162    * Get a String representation of the Field. A Field's String
 163    * representation is "&lt;modifiers&gt; &lt;type&gt;
 164    * &lt;class&gt;.&lt;fieldname&gt;".<br> Example:
 165    * <code>public transient boolean gnu.parse.Parser.parseComplete</code>
 166    *
 167    * @return the String representation of the Field
 168    */
 169   public String toString()
 170   {
 171     // 64 is a reasonable buffer initial size for field
 172     StringBuffer sb = new StringBuffer(64);
 173     Modifier.toString(getModifiers(), sb).append(' ');
 174     sb.append(getType().getName()).append(' ');
 175     sb.append(getDeclaringClass().getName()).append('.');
 176     sb.append(getName());
 177     return sb.toString();
 178   }
 179
 180   /**
 181    * Get the value of this Field.  If it is primitive, it will be wrapped
 182    * in the appropriate wrapper type (boolean = java.lang.Boolean).<p>
 183    *
 184    * If the field is static, <code>o</code> will be ignored. Otherwise, if
 185    * <code>o</code> is null, you get a <code>NullPointerException</code>,
 186    * and if it is incompatible with the declaring class of the field, you
 187    * get an <code>IllegalArgumentException</code>.<p>
 188    *
 189    * Next, if this Field enforces access control, your runtime context is
 190    * evaluated, and you may have an <code>IllegalAccessException</code> if
 191    * you could not access this field in similar compiled code. If the field
 192    * is static, and its class is uninitialized, you trigger class
 193    * initialization, which may end in a
 194    * <code>ExceptionInInitializerError</code>.<p>
 195    *
 196    * Finally, the field is accessed, and primitives are wrapped (but not
 197    * necessarily in new objects). This method accesses the field of the
 198    * declaring class, even if the instance passed in belongs to a subclass
 199    * which declares another field to hide this one.
 200    *
 201    * @param o the object to get the value of this Field from
 202    * @return the value of the Field
 203    * @throws IllegalAccessException if you could not normally access this field
 204    *         (i.e. it is not public)
 205    * @throws IllegalArgumentException if <code>o</code> is not an instance of
 206    *         the class or interface declaring this field
 207    * @throws NullPointerException if <code>o</code> is null and this field
 208    *         requires an instance
 209    * @throws ExceptionInInitializerError if accessing a static field triggered
 210    *         class initialization, which then failed
 211    * @see #getBoolean(Object)
 212    * @see #getByte(Object)
 213    * @see #getChar(Object)
 214    * @see #getShort(Object)
 215    * @see #getInt(Object)
 216    * @see #getLong(Object)
 217    * @see #getFloat(Object)
 218    * @see #getDouble(Object)
 219    */
 220   public native Object get(Object o)
 221     throws IllegalAccessException;
 222
 223   /**
 224    * Get the value of this boolean Field. If the field is static,
 225    * <code>o</code> will be ignored.
 226    *
 227    * @param o the object to get the value of this Field from
 228    * @return the value of the Field
 229    * @throws IllegalAccessException if you could not normally access this field
 230    *         (i.e. it is not public)
 231    * @throws IllegalArgumentException if this is not a boolean field of
 232    *         <code>o</code>, or if <code>o</code> is not an instance of the
 233    *         declaring class of this field
 234    * @throws NullPointerException if <code>o</code> is null and this field
 235    *         requires an instance
 236    * @throws ExceptionInInitializerError if accessing a static field triggered
 237    *         class initialization, which then failed
 238    * @see #get(Object)
 239    */
 240   public native boolean getBoolean(Object o)
 241     throws IllegalAccessException;
 242
 243   /**
 244    * Get the value of this byte Field. If the field is static,
 245    * <code>o</code> will be ignored.
 246    *
 247    * @param o the object to get the value of this Field from
 248    * @return the value of the Field
 249    * @throws IllegalAccessException if you could not normally access this field
 250    *         (i.e. it is not public)
 251    * @throws IllegalArgumentException if this is not a byte field of
 252    *         <code>o</code>, or if <code>o</code> is not an instance of the
 253    *         declaring class of this field
 254    * @throws NullPointerException if <code>o</code> is null and this field
 255    *         requires an instance
 256    * @throws ExceptionInInitializerError if accessing a static field triggered
 257    *         class initialization, which then failed
 258    * @see #get(Object)
 259    */
 260   public native byte getByte(Object o)
 261     throws IllegalAccessException;
 262
 263   /**
 264    * Get the value of this Field as a char. If the field is static,
 265    * <code>o</code> will be ignored.
 266    *
 267    * @throws IllegalAccessException if you could not normally access this field
 268    *         (i.e. it is not public)
 269    * @throws IllegalArgumentException if this is not a char field of
 270    *         <code>o</code>, or if <code>o</code> is not an instance
 271    *         of the declaring class of this field
 272    * @throws NullPointerException if <code>o</code> is null and this field
 273    *         requires an instance
 274    * @throws ExceptionInInitializerError if accessing a static field triggered
 275    *         class initialization, which then failed
 276    * @see #get(Object)
 277    */
 278   public native char getChar(Object o)
 279     throws IllegalAccessException;
 280
 281   /**
 282    * Get the value of this Field as a short. If the field is static,
 283    * <code>o</code> will be ignored.
 284    *
 285    * @param o the object to get the value of this Field from
 286    * @return the value of the Field
 287    * @throws IllegalAccessException if you could not normally access this field
 288    *         (i.e. it is not public)
 289    * @throws IllegalArgumentException if this is not a byte or short
 290    *         field of <code>o</code>, or if <code>o</code> is not an instance
 291    *         of the declaring class of this field
 292    * @throws NullPointerException if <code>o</code> is null and this field
 293    *         requires an instance
 294    * @throws ExceptionInInitializerError if accessing a static field triggered
 295    *         class initialization, which then failed
 296    * @see #get(Object)
 297    */
 298   public native short getShort(Object o)
 299     throws IllegalAccessException;
 300
 301   /**
 302    * Get the value of this Field as an int. If the field is static,
 303    * <code>o</code> will be ignored.
 304    *
 305    * @param o the object to get the value of this Field from
 306    * @return the value of the Field
 307    * @throws IllegalAccessException if you could not normally access this field
 308    *         (i.e. it is not public)
 309    * @throws IllegalArgumentException if this is not a byte, short, char, or
 310    *         int field of <code>o</code>, or if <code>o</code> is not an
 311    *         instance of the declaring class of this field
 312    * @throws NullPointerException if <code>o</code> is null and this field
 313    *         requires an instance
 314    * @throws ExceptionInInitializerError if accessing a static field triggered
 315    *         class initialization, which then failed
 316    * @see #get(Object)
 317    */
 318   public native int getInt(Object o)
 319     throws IllegalAccessException;
 320
 321   /**
 322    * Get the value of this Field as a long. If the field is static,
 323    * <code>o</code> will be ignored.
 324    *
 325    * @param o the object to get the value of this Field from
 326    * @return the value of the Field
 327    * @throws IllegalAccessException if you could not normally access this field
 328    *         (i.e. it is not public)
 329    * @throws IllegalArgumentException if this is not a byte, short, char, int,
 330    *         or long field of <code>o</code>, or if <code>o</code> is not an
 331    *         instance of the declaring class of this field
 332    * @throws NullPointerException if <code>o</code> is null and this field
 333    *         requires an instance
 334    * @throws ExceptionInInitializerError if accessing a static field triggered
 335    *         class initialization, which then failed
 336    * @see #get(Object)
 337    */
 338   public native long getLong(Object o)
 339     throws IllegalAccessException;
 340
 341   /**
 342    * Get the value of this Field as a float. If the field is static,
 343    * <code>o</code> will be ignored.
 344    *
 345    * @param o the object to get the value of this Field from
 346    * @return the value of the Field
 347    * @throws IllegalAccessException if you could not normally access this field
 348    *         (i.e. it is not public)
 349    * @throws IllegalArgumentException if this is not a byte, short, char, int,
 350    *         long, or float field of <code>o</code>, or if <code>o</code> is
 351    *         not an instance of the declaring class of this field
 352    * @throws NullPointerException if <code>o</code> is null and this field
 353    *         requires an instance
 354    * @throws ExceptionInInitializerError if accessing a static field triggered
 355    *         class initialization, which then failed
 356    * @see #get(Object)
 357    */
 358   public native float getFloat(Object o)
 359     throws IllegalAccessException;
 360
 361   /**
 362    * Get the value of this Field as a double. If the field is static,
 363    * <code>o</code> will be ignored.
 364    *
 365    * @param o the object to get the value of this Field from
 366    * @return the value of the Field
 367    * @throws IllegalAccessException if you could not normally access this field
 368    *         (i.e. it is not public)
 369    * @throws IllegalArgumentException if this is not a byte, short, char, int,
 370    *         long, float, or double field of <code>o</code>, or if
 371    *         <code>o</code> is not an instance of the declaring class of this
 372    *         field
 373    * @throws NullPointerException if <code>o</code> is null and this field
 374    *         requires an instance
 375    * @throws ExceptionInInitializerError if accessing a static field triggered
 376    *         class initialization, which then failed
 377    * @see #get(Object)
 378    */
 379   public native double getDouble(Object o)
 380     throws IllegalAccessException;
 381
 382   /**
 383    * Set the value of this Field.  If it is a primitive field, the value
 384    * will be unwrapped from the passed object (boolean = java.lang.Boolean).<p>
 385    *
 386    * If the field is static, <code>o</code> will be ignored. Otherwise, if
 387    * <code>o</code> is null, you get a <code>NullPointerException</code>,
 388    * and if it is incompatible with the declaring class of the field, you
 389    * get an <code>IllegalArgumentException</code>.<p>
 390    *
 391    * Next, if this Field enforces access control, your runtime context is
 392    * evaluated, and you may have an <code>IllegalAccessException</code> if
 393    * you could not access this field in similar compiled code. This also
 394    * occurs whether or not there is access control if the field is final.
 395    * If the field is primitive, and unwrapping your argument fails, you will
 396    * get an <code>IllegalArgumentException</code>; likewise, this error
 397    * happens if <code>value</code> cannot be cast to the correct object type.
 398    * If the field is static, and its class is uninitialized, you trigger class
 399    * initialization, which may end in a
 400    * <code>ExceptionInInitializerError</code>.<p>
 401    *
 402    * Finally, the field is set with the widened value. This method accesses
 403    * the field of the declaring class, even if the instance passed in belongs
 404    * to a subclass which declares another field to hide this one.
 405    *
 406    * @param o the object to set this Field on
 407    * @param value the value to set this Field to
 408    * @throws IllegalAccessException if you could not normally access this field
 409    *         (i.e. it is not public)
 410    * @throws IllegalArgumentException if <code>value</code> cannot be
 411    *         converted by a widening conversion to the underlying type of
 412    *         the Field, or if <code>o</code> is not an instance of the class
 413    *         declaring this field
 414    * @throws NullPointerException if <code>o</code> is null and this field
 415    *         requires an instance
 416    * @throws ExceptionInInitializerError if accessing a static field triggered
 417    *         class initialization, which then failed
 418    * @see #setBoolean(Object, boolean)
 419    * @see #setByte(Object, byte)
 420    * @see #setChar(Object, char)
 421    * @see #setShort(Object, short)
 422    * @see #setInt(Object, int)
 423    * @see #setLong(Object, long)
 424    * @see #setFloat(Object, float)
 425    * @see #setDouble(Object, double)
 426    */
 427   public native void set(Object o, Object value)
 428     throws IllegalAccessException;
 429
 430   /**
 431    * Set this boolean Field. If the field is static, <code>o</code> will be
 432    * ignored.
 433    *
 434    * @param o the object to set this Field on
 435    * @param value the value to set this Field to
 436    * @throws IllegalAccessException if you could not normally access this field
 437    *         (i.e. it is not public)
 438    * @throws IllegalArgumentException if this is not a boolean field, or if
 439    *         <code>o</code> is not an instance of the class declaring this
 440    *         field
 441    * @throws NullPointerException if <code>o</code> is null and this field
 442    *         requires an instance
 443    * @throws ExceptionInInitializerError if accessing a static field triggered
 444    *         class initialization, which then failed
 445    * @see #set(Object, Object)
 446    */
 447   public native void setBoolean(Object o, boolean value)
 448     throws IllegalAccessException;
 449
 450   /**
 451    * Set this byte Field. If the field is static, <code>o</code> will be
 452    * ignored.
 453    *
 454    * @param o the object to set this Field on
 455    * @param value the value to set this Field to
 456    * @throws IllegalAccessException if you could not normally access this field
 457    *         (i.e. it is not public)
 458    * @throws IllegalArgumentException if this is not a byte, short, int, long,
 459    *         float, or double field, or if <code>o</code> is not an instance
 460    *         of the class declaring this field
 461    * @throws NullPointerException if <code>o</code> is null and this field
 462    *         requires an instance
 463    * @throws ExceptionInInitializerError if accessing a static field triggered
 464    *         class initialization, which then failed
 465    * @see #set(Object, Object)
 466    */
 467   public native void setByte(Object o, byte value)
 468     throws IllegalAccessException;
 469
 470   /**
 471    * Set this char Field. If the field is static, <code>o</code> will be
 472    * ignored.
 473    *
 474    * @param o the object to set this Field on
 475    * @param value the value to set this Field to
 476    * @throws IllegalAccessException if you could not normally access this field
 477    *         (i.e. it is not public)
 478    * @throws IllegalArgumentException if this is not a char, int, long,
 479    *         float, or double field, or if <code>o</code> is not an instance
 480    *         of the class declaring this field
 481    * @throws NullPointerException if <code>o</code> is null and this field
 482    *         requires an instance
 483    * @throws ExceptionInInitializerError if accessing a static field triggered
 484    *         class initialization, which then failed
 485    * @see #set(Object, Object)
 486    */
 487   public native void setChar(Object o, char value)
 488     throws IllegalAccessException;
 489
 490   /**
 491    * Set this short Field. If the field is static, <code>o</code> will be
 492    * ignored.
 493    *
 494    * @param o the object to set this Field on
 495    * @param value the value to set this Field to
 496    * @throws IllegalAccessException if you could not normally access this field
 497    *         (i.e. it is not public)
 498    * @throws IllegalArgumentException if this is not a short, int, long,
 499    *         float, or double field, or if <code>o</code> is not an instance
 500    *         of the class declaring this field
 501    * @throws NullPointerException if <code>o</code> is null and this field
 502    *         requires an instance
 503    * @throws ExceptionInInitializerError if accessing a static field triggered
 504    *         class initialization, which then failed
 505    * @see #set(Object, Object)
 506    */
 507   public native void setShort(Object o, short value)
 508     throws IllegalAccessException;
 509
 510   /**
 511    * Set this int Field. If the field is static, <code>o</code> will be
 512    * ignored.
 513    *
 514    * @param o the object to set this Field on
 515    * @param value the value to set this Field to
 516    * @throws IllegalAccessException if you could not normally access this field
 517    *         (i.e. it is not public)
 518    * @throws IllegalArgumentException if this is not an int, long, float, or
 519    *         double field, or if <code>o</code> is not an instance of the
 520    *         class declaring this field
 521    * @throws NullPointerException if <code>o</code> is null and this field
 522    *         requires an instance
 523    * @throws ExceptionInInitializerError if accessing a static field triggered
 524    *         class initialization, which then failed
 525    * @see #set(Object, Object)
 526    */
 527   public native void setInt(Object o, int value)
 528     throws IllegalAccessException;
 529
 530   /**
 531    * Set this long Field. If the field is static, <code>o</code> will be
 532    * ignored.
 533    *
 534    * @param o the object to set this Field on
 535    * @param value the value to set this Field to
 536    * @throws IllegalAccessException if you could not normally access this field
 537    *         (i.e. it is not public)
 538    * @throws IllegalArgumentException if this is not a long, float, or double
 539    *         field, or if <code>o</code> is not an instance of the class
 540    *         declaring this field
 541    * @throws NullPointerException if <code>o</code> is null and this field
 542    *         requires an instance
 543    * @throws ExceptionInInitializerError if accessing a static field triggered
 544    *         class initialization, which then failed
 545    * @see #set(Object, Object)
 546    */
 547   public native void setLong(Object o, long value)
 548     throws IllegalAccessException;
 549
 550   /**
 551    * Set this float Field. If the field is static, <code>o</code> will be
 552    * ignored.
 553    *
 554    * @param o the object to set this Field on
 555    * @param value the value to set this Field to
 556    * @throws IllegalAccessException if you could not normally access this field
 557    *         (i.e. it is not public)
 558    * @throws IllegalArgumentException if this is not a float or long field, or
 559    *         if <code>o</code> is not an instance of the class declaring this
 560    *         field
 561    * @throws NullPointerException if <code>o</code> is null and this field
 562    *         requires an instance
 563    * @throws ExceptionInInitializerError if accessing a static field triggered
 564    *         class initialization, which then failed
 565    * @see #set(Object, Object)
 566    */
 567   public native void setFloat(Object o, float value)
 568     throws IllegalAccessException;
 569
 570   /**
 571    * Set this double Field. If the field is static, <code>o</code> will be
 572    * ignored.
 573    *
 574    * @param o the object to set this Field on
 575    * @param value the value to set this Field to
 576    * @throws IllegalAccessException if you could not normally access this field
 577    *         (i.e. it is not public)
 578    * @throws IllegalArgumentException if this is not a double field, or if
 579    *         <code>o</code> is not an instance of the class declaring this
 580    *         field
 581    * @throws NullPointerException if <code>o</code> is null and this field
 582    *         requires an instance
 583    * @throws ExceptionInInitializerError if accessing a static field triggered
 584    *         class initialization, which then failed
 585    * @see #set(Object, Object)
 586    */
 587   public native void setDouble(Object o, double value)
 588     throws IllegalAccessException;
 589 }