GNU Classpath (0.20) | |
Frames | No Frames |
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 "<modifiers> <type> 164: * <class>.<fieldname>".<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: }
GNU Classpath (0.20) |