1 /* java.lang.reflect.Field - reflection of Java fields
2 Copyright (C) 1998, 2001, 2005 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
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)
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.
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
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
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. */
39 package java.lang.reflect;
41 import gnu.java.lang.ClassHelper;
43 import gnu.java.lang.reflect.FieldSignatureParser;
45 import java.lang.annotation.Annotation;
50 * The Field class represents a member variable of a class. It also allows
51 * dynamic access to a member, via reflection. This works for both
52 * static and instance fields. Operations on Field objects know how to
53 * do widening conversions, but throw {@link IllegalArgumentException} if
54 * a narrowing conversion would be necessary. You can query for information
55 * on this Field regardless of location, but get and set access may be limited
56 * by Java language access controls. If you can't do it in the compiler, you
57 * can't normally do it here either.<p>
59 * <B>Note:</B> This class returns and accepts types as Classes, even
60 * primitive types; there are Class types defined that represent each
61 * different primitive type. They are <code>java.lang.Boolean.TYPE,
62 * java.lang.Byte.TYPE,</code>, also available as <code>boolean.class,
63 * byte.class</code>, etc. These are not to be confused with the
64 * classes <code>java.lang.Boolean, java.lang.Byte</code>, etc., which are
67 * Also note that this is not a serializable class. It is entirely feasible
68 * to make it serializable using the Externalizable interface, but this is
72 * @author Eric Blake <ebb9@email.byu.edu>
75 * @see Class#getField(String)
76 * @see Class#getDeclaredField(String)
77 * @see Class#getFields()
78 * @see Class#getDeclaredFields()
80 * @status updated to 1.4
82 public final class Field
83 extends AccessibleObject implements Member
90 * Unparsed annotations.
92 private byte[] annotations = null;
95 * Annotations get parsed the first time they are
96 * accessed and are then cached it this map.
98 private transient Map<Class<? extends Annotation>, Annotation> declaredAnnotations = null;
100 private static final int FIELD_MODIFIERS
101 = Modifier.FINAL | Modifier.PRIVATE | Modifier.PROTECTED
102 | Modifier.PUBLIC | Modifier.STATIC | Modifier.TRANSIENT
106 * Helper array for creating a new array from a java.util.Container.
108 private static final Annotation[] EMPTY_ANNOTATIONS_ARRAY =
112 * This class is uninstantiable except natively.
114 private Field(Class declaringClass, String name, int slot)
116 this.clazz = declaringClass;
122 * Gets the class that declared this field, or the class where this field
123 * is a non-inherited member.
124 * @return the class that declared this member
126 public Class<?> getDeclaringClass()
132 * Gets the name of this field.
133 * @return the name of this field
135 public String getName()
141 * Return the raw modifiers for this field.
142 * @return the field's modifiers
144 private native int getModifiersInternal();
147 * Gets the modifiers this field uses. Use the <code>Modifier</code>
148 * class to interpret the values. A field can only have a subset of the
149 * following modifiers: public, private, protected, static, final,
150 * transient, and volatile.
152 * @return an integer representing the modifiers to this Member
155 public int getModifiers()
157 return getModifiersInternal() & FIELD_MODIFIERS;
161 * Return true if this field is synthetic, false otherwise.
164 public boolean isSynthetic()
166 return (getModifiersInternal() & Modifier.SYNTHETIC) != 0;
170 * Return true if this field represents an enum constant,
174 public boolean isEnumConstant()
176 return (getModifiersInternal() & Modifier.ENUM) != 0;
180 * Gets the type of this field.
181 * @return the type of this field
183 public native Class<?> getType();
186 * Compare two objects to see if they are semantically equivalent.
187 * Two Fields are semantically equivalent if they have the same declaring
188 * class, name, and type. Since you can't creat a Field except through
189 * the VM, this is just the == relation.
191 * @param o the object to compare to
192 * @return <code>true</code> if they are equal; <code>false</code> if not
194 public boolean equals(Object o)
196 if (!(o instanceof Field))
198 Field that = (Field)o;
199 if (this.getDeclaringClass() != that.getDeclaringClass())
201 if (!this.getName().equals(that.getName()))
203 if (this.getType() != that.getType())
209 * Get the hash code for the Field. The Field hash code is the hash code
210 * of its name XOR'd with the hash code of its class name.
212 * @return the hash code for the object.
214 public int hashCode()
216 return getDeclaringClass().getName().hashCode() ^ getName().hashCode();
220 * Get a String representation of the Field. A Field's String
221 * representation is "<modifiers> <type>
222 * <class>.<fieldname>".<br> Example:
223 * <code>public transient boolean gnu.parse.Parser.parseComplete</code>
225 * @return the String representation of the Field
227 public String toString()
229 // 64 is a reasonable buffer initial size for field
230 StringBuilder sb = new StringBuilder(64);
231 Modifier.toString(getModifiers(), sb).append(' ');
232 sb.append(ClassHelper.getUserName(getType())).append(' ');
233 sb.append(getDeclaringClass().getName()).append('.');
234 sb.append(getName());
235 return sb.toString();
238 public String toGenericString()
240 StringBuilder sb = new StringBuilder(64);
241 Modifier.toString(getModifiers(), sb).append(' ');
242 sb.append(getGenericType()).append(' ');
243 sb.append(getDeclaringClass().getName()).append('.');
244 sb.append(getName());
245 return sb.toString();
249 * Get the value of this Field. If it is primitive, it will be wrapped
250 * in the appropriate wrapper type (boolean = java.lang.Boolean).<p>
252 * If the field is static, <code>o</code> will be ignored. Otherwise, if
253 * <code>o</code> is null, you get a <code>NullPointerException</code>,
254 * and if it is incompatible with the declaring class of the field, you
255 * get an <code>IllegalArgumentException</code>.<p>
257 * Next, if this Field enforces access control, your runtime context is
258 * evaluated, and you may have an <code>IllegalAccessException</code> if
259 * you could not access this field in similar compiled code. If the field
260 * is static, and its class is uninitialized, you trigger class
261 * initialization, which may end in a
262 * <code>ExceptionInInitializerError</code>.<p>
264 * Finally, the field is accessed, and primitives are wrapped (but not
265 * necessarily in new objects). This method accesses the field of the
266 * declaring class, even if the instance passed in belongs to a subclass
267 * which declares another field to hide this one.
269 * @param o the object to get the value of this Field from
270 * @return the value of the Field
271 * @throws IllegalAccessException if you could not normally access this field
272 * (i.e. it is not public)
273 * @throws IllegalArgumentException if <code>o</code> is not an instance of
274 * the class or interface declaring this field
275 * @throws NullPointerException if <code>o</code> is null and this field
276 * requires an instance
277 * @throws ExceptionInInitializerError if accessing a static field triggered
278 * class initialization, which then failed
279 * @see #getBoolean(Object)
280 * @see #getByte(Object)
281 * @see #getChar(Object)
282 * @see #getShort(Object)
283 * @see #getInt(Object)
284 * @see #getLong(Object)
285 * @see #getFloat(Object)
286 * @see #getDouble(Object)
288 public native Object get(Object o)
289 throws IllegalAccessException;
292 * Get the value of this boolean Field. If the field is static,
293 * <code>o</code> will be ignored.
295 * @param o the object to get the value of this Field from
296 * @return the value of the Field
297 * @throws IllegalAccessException if you could not normally access this field
298 * (i.e. it is not public)
299 * @throws IllegalArgumentException if this is not a boolean field of
300 * <code>o</code>, or if <code>o</code> is not an instance of the
301 * declaring class of this field
302 * @throws NullPointerException if <code>o</code> is null and this field
303 * requires an instance
304 * @throws ExceptionInInitializerError if accessing a static field triggered
305 * class initialization, which then failed
308 public native boolean getBoolean(Object o)
309 throws IllegalAccessException;
312 * Get the value of this byte Field. If the field is static,
313 * <code>o</code> will be ignored.
315 * @param o the object to get the value of this Field from
316 * @return the value of the Field
317 * @throws IllegalAccessException if you could not normally access this field
318 * (i.e. it is not public)
319 * @throws IllegalArgumentException if this is not a byte field of
320 * <code>o</code>, or if <code>o</code> is not an instance of the
321 * declaring class of this field
322 * @throws NullPointerException if <code>o</code> is null and this field
323 * requires an instance
324 * @throws ExceptionInInitializerError if accessing a static field triggered
325 * class initialization, which then failed
328 public native byte getByte(Object o)
329 throws IllegalAccessException;
332 * Get the value of this Field as a char. If the field is static,
333 * <code>o</code> will be ignored.
335 * @throws IllegalAccessException if you could not normally access this field
336 * (i.e. it is not public)
337 * @throws IllegalArgumentException if this is not a char field of
338 * <code>o</code>, or if <code>o</code> is not an instance
339 * of the declaring class of this field
340 * @throws NullPointerException if <code>o</code> is null and this field
341 * requires an instance
342 * @throws ExceptionInInitializerError if accessing a static field triggered
343 * class initialization, which then failed
346 public native char getChar(Object o)
347 throws IllegalAccessException;
350 * Get the value of this Field as a short. If the field is static,
351 * <code>o</code> will be ignored.
353 * @param o the object to get the value of this Field from
354 * @return the value of the Field
355 * @throws IllegalAccessException if you could not normally access this field
356 * (i.e. it is not public)
357 * @throws IllegalArgumentException if this is not a byte or short
358 * field of <code>o</code>, or if <code>o</code> is not an instance
359 * of the declaring class of this field
360 * @throws NullPointerException if <code>o</code> is null and this field
361 * requires an instance
362 * @throws ExceptionInInitializerError if accessing a static field triggered
363 * class initialization, which then failed
366 public native short getShort(Object o)
367 throws IllegalAccessException;
370 * Get the value of this Field as an int. If the field is static,
371 * <code>o</code> will be ignored.
373 * @param o the object to get the value of this Field from
374 * @return the value of the Field
375 * @throws IllegalAccessException if you could not normally access this field
376 * (i.e. it is not public)
377 * @throws IllegalArgumentException if this is not a byte, short, char, or
378 * int field of <code>o</code>, or if <code>o</code> is not an
379 * instance of the declaring class of this field
380 * @throws NullPointerException if <code>o</code> is null and this field
381 * requires an instance
382 * @throws ExceptionInInitializerError if accessing a static field triggered
383 * class initialization, which then failed
386 public native int getInt(Object o)
387 throws IllegalAccessException;
390 * Get the value of this Field as a long. If the field is static,
391 * <code>o</code> will be ignored.
393 * @param o the object to get the value of this Field from
394 * @return the value of the Field
395 * @throws IllegalAccessException if you could not normally access this field
396 * (i.e. it is not public)
397 * @throws IllegalArgumentException if this is not a byte, short, char, int,
398 * or long field of <code>o</code>, or if <code>o</code> is not an
399 * instance of the declaring class of this field
400 * @throws NullPointerException if <code>o</code> is null and this field
401 * requires an instance
402 * @throws ExceptionInInitializerError if accessing a static field triggered
403 * class initialization, which then failed
406 public native long getLong(Object o)
407 throws IllegalAccessException;
410 * Get the value of this Field as a float. If the field is static,
411 * <code>o</code> will be ignored.
413 * @param o the object to get the value of this Field from
414 * @return the value of the Field
415 * @throws IllegalAccessException if you could not normally access this field
416 * (i.e. it is not public)
417 * @throws IllegalArgumentException if this is not a byte, short, char, int,
418 * long, or float field of <code>o</code>, or if <code>o</code> is
419 * not an instance of the declaring class of this field
420 * @throws NullPointerException if <code>o</code> is null and this field
421 * requires an instance
422 * @throws ExceptionInInitializerError if accessing a static field triggered
423 * class initialization, which then failed
426 public native float getFloat(Object o)
427 throws IllegalAccessException;
430 * Get the value of this Field as a double. If the field is static,
431 * <code>o</code> will be ignored.
433 * @param o the object to get the value of this Field from
434 * @return the value of the Field
435 * @throws IllegalAccessException if you could not normally access this field
436 * (i.e. it is not public)
437 * @throws IllegalArgumentException if this is not a byte, short, char, int,
438 * long, float, or double field of <code>o</code>, or if
439 * <code>o</code> is not an instance of the declaring class of this
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
447 public native double getDouble(Object o)
448 throws IllegalAccessException;
451 * Set the value of this Field. If it is a primitive field, the value
452 * will be unwrapped from the passed object (boolean = java.lang.Boolean).<p>
454 * If the field is static, <code>o</code> will be ignored. Otherwise, if
455 * <code>o</code> is null, you get a <code>NullPointerException</code>,
456 * and if it is incompatible with the declaring class of the field, you
457 * get an <code>IllegalArgumentException</code>.<p>
459 * Next, if this Field enforces access control, your runtime context is
460 * evaluated, and you may have an <code>IllegalAccessException</code> if
461 * you could not access this field in similar compiled code. This also
462 * occurs whether or not there is access control if the field is final.
463 * If the field is primitive, and unwrapping your argument fails, you will
464 * get an <code>IllegalArgumentException</code>; likewise, this error
465 * happens if <code>value</code> cannot be cast to the correct object type.
466 * If the field is static, and its class is uninitialized, you trigger class
467 * initialization, which may end in a
468 * <code>ExceptionInInitializerError</code>.<p>
470 * Finally, the field is set with the widened value. This method accesses
471 * the field of the declaring class, even if the instance passed in belongs
472 * to a subclass which declares another field to hide this one.
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 <code>value</code> cannot be
479 * converted by a widening conversion to the underlying type of
480 * the Field, or if <code>o</code> is not an instance of the class
481 * declaring this field
482 * @throws NullPointerException if <code>o</code> is null and this field
483 * requires an instance
484 * @throws ExceptionInInitializerError if accessing a static field triggered
485 * class initialization, which then failed
486 * @see #setBoolean(Object, boolean)
487 * @see #setByte(Object, byte)
488 * @see #setChar(Object, char)
489 * @see #setShort(Object, short)
490 * @see #setInt(Object, int)
491 * @see #setLong(Object, long)
492 * @see #setFloat(Object, float)
493 * @see #setDouble(Object, double)
495 public native void set(Object o, Object value)
496 throws IllegalAccessException;
499 * Set this boolean Field. If the field is static, <code>o</code> will be
502 * @param o the object to set this Field on
503 * @param value the value to set this Field to
504 * @throws IllegalAccessException if you could not normally access this field
505 * (i.e. it is not public)
506 * @throws IllegalArgumentException if this is not a boolean field, or if
507 * <code>o</code> is not an instance of the class declaring this
509 * @throws NullPointerException if <code>o</code> is null and this field
510 * requires an instance
511 * @throws ExceptionInInitializerError if accessing a static field triggered
512 * class initialization, which then failed
513 * @see #set(Object, Object)
515 public native void setBoolean(Object o, boolean value)
516 throws IllegalAccessException;
519 * Set this byte Field. If the field is static, <code>o</code> will be
522 * @param o the object to set this Field on
523 * @param value the value to set this Field to
524 * @throws IllegalAccessException if you could not normally access this field
525 * (i.e. it is not public)
526 * @throws IllegalArgumentException if this is not a byte, short, int, long,
527 * float, or double field, or if <code>o</code> is not an instance
528 * of the class declaring this field
529 * @throws NullPointerException if <code>o</code> is null and this field
530 * requires an instance
531 * @throws ExceptionInInitializerError if accessing a static field triggered
532 * class initialization, which then failed
533 * @see #set(Object, Object)
535 public native void setByte(Object o, byte value)
536 throws IllegalAccessException;
539 * Set this char Field. If the field is static, <code>o</code> will be
542 * @param o the object to set this Field on
543 * @param value the value to set this Field to
544 * @throws IllegalAccessException if you could not normally access this field
545 * (i.e. it is not public)
546 * @throws IllegalArgumentException if this is not a char, int, long,
547 * float, or double field, or if <code>o</code> is not an instance
548 * of the class declaring this field
549 * @throws NullPointerException if <code>o</code> is null and this field
550 * requires an instance
551 * @throws ExceptionInInitializerError if accessing a static field triggered
552 * class initialization, which then failed
553 * @see #set(Object, Object)
555 public native void setChar(Object o, char value)
556 throws IllegalAccessException;
559 * Set this short Field. If the field is static, <code>o</code> will be
562 * @param o the object to set this Field on
563 * @param value the value to set this Field to
564 * @throws IllegalAccessException if you could not normally access this field
565 * (i.e. it is not public)
566 * @throws IllegalArgumentException if this is not a short, int, long,
567 * float, or double field, or if <code>o</code> is not an instance
568 * of the class declaring this field
569 * @throws NullPointerException if <code>o</code> is null and this field
570 * requires an instance
571 * @throws ExceptionInInitializerError if accessing a static field triggered
572 * class initialization, which then failed
573 * @see #set(Object, Object)
575 public native void setShort(Object o, short value)
576 throws IllegalAccessException;
579 * Set this int Field. If the field is static, <code>o</code> will be
582 * @param o the object to set this Field on
583 * @param value the value to set this Field to
584 * @throws IllegalAccessException if you could not normally access this field
585 * (i.e. it is not public)
586 * @throws IllegalArgumentException if this is not an int, long, float, or
587 * double field, or if <code>o</code> is not an instance of the
588 * class declaring this field
589 * @throws NullPointerException if <code>o</code> is null and this field
590 * requires an instance
591 * @throws ExceptionInInitializerError if accessing a static field triggered
592 * class initialization, which then failed
593 * @see #set(Object, Object)
595 public native void setInt(Object o, int value)
596 throws IllegalAccessException;
599 * Set this long Field. If the field is static, <code>o</code> will be
602 * @param o the object to set this Field on
603 * @param value the value to set this Field to
604 * @throws IllegalAccessException if you could not normally access this field
605 * (i.e. it is not public)
606 * @throws IllegalArgumentException if this is not a long, float, or double
607 * field, or if <code>o</code> is not an instance of the class
608 * declaring this field
609 * @throws NullPointerException if <code>o</code> is null and this field
610 * requires an instance
611 * @throws ExceptionInInitializerError if accessing a static field triggered
612 * class initialization, which then failed
613 * @see #set(Object, Object)
615 public native void setLong(Object o, long value)
616 throws IllegalAccessException;
619 * Set this float Field. If the field is static, <code>o</code> will be
622 * @param o the object to set this Field on
623 * @param value the value to set this Field to
624 * @throws IllegalAccessException if you could not normally access this field
625 * (i.e. it is not public)
626 * @throws IllegalArgumentException if this is not a float or long field, or
627 * if <code>o</code> is not an instance of the class declaring this
629 * @throws NullPointerException if <code>o</code> is null and this field
630 * requires an instance
631 * @throws ExceptionInInitializerError if accessing a static field triggered
632 * class initialization, which then failed
633 * @see #set(Object, Object)
635 public native void setFloat(Object o, float value)
636 throws IllegalAccessException;
639 * Set this double Field. If the field is static, <code>o</code> will be
642 * @param o the object to set this Field on
643 * @param value the value to set this Field to
644 * @throws IllegalAccessException if you could not normally access this field
645 * (i.e. it is not public)
646 * @throws IllegalArgumentException if this is not a double field, or if
647 * <code>o</code> is not an instance of the class declaring this
649 * @throws NullPointerException if <code>o</code> is null and this field
650 * requires an instance
651 * @throws ExceptionInInitializerError if accessing a static field triggered
652 * class initialization, which then failed
653 * @see #set(Object, Object)
655 public native void setDouble(Object o, double value)
656 throws IllegalAccessException;
659 * Return the generic type of the field. If the field type is not a generic
660 * type, the method returns the same as <code>getType()</code>.
662 * @throws GenericSignatureFormatError if the generic signature does
663 * not conform to the format specified in the Virtual Machine
664 * specification, version 3.
667 public Type getGenericType()
669 String signature = getSignature();
670 if (signature == null)
672 FieldSignatureParser p = new FieldSignatureParser(getDeclaringClass(),
674 return p.getFieldType();
678 * Return the String in the Signature attribute for this field. If there
679 * is no Signature attribute, return null.
681 private native String getSignature();
684 * @throws NullPointerException {@inheritDoc}
687 public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
688 if (annotationClass == null)
689 throw new NullPointerException();
691 return (T)declaredAnnotations().get(annotationClass);
697 public Annotation[] getDeclaredAnnotations() {
698 return declaredAnnotations().values().toArray(EMPTY_ANNOTATIONS_ARRAY);
702 * Parses the annotations if they aren't parsed yet and stores them into
703 * the declaredAnnotations map and return this map.
705 private synchronized native Map<Class<? extends Annotation>, Annotation> declaredAnnotations();