< prev index next >

src/java.base/share/classes/java/lang/reflect/Field.java

Print this page

  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.lang.reflect;
  27 
  28 import jdk.internal.access.SharedSecrets;
  29 import jdk.internal.reflect.CallerSensitive;
  30 import jdk.internal.reflect.FieldAccessor;
  31 import jdk.internal.reflect.Reflection;
  32 import jdk.internal.vm.annotation.ForceInline;
  33 import jdk.internal.vm.annotation.Stable;
  34 import sun.reflect.generics.repository.FieldRepository;
  35 import sun.reflect.generics.factory.CoreReflectionFactory;
  36 import sun.reflect.generics.factory.GenericsFactory;
  37 import sun.reflect.generics.scope.ClassScope;
  38 import java.lang.annotation.Annotation;
  39 import java.util.Map;

  40 import java.util.Objects;
  41 import sun.reflect.annotation.AnnotationParser;
  42 import sun.reflect.annotation.AnnotationSupport;
  43 import sun.reflect.annotation.TypeAnnotation;
  44 import sun.reflect.annotation.TypeAnnotationParser;
  45 
  46 /**
  47  * A {@code Field} provides information about, and dynamic access to, a
  48  * single field of a class or an interface.  The reflected field may
  49  * be a class (static) field or an instance field.
  50  *
  51  * <p>A {@code Field} permits widening conversions to occur during a get or
  52  * set access operation, but throws an {@code IllegalArgumentException} if a
  53  * narrowing conversion would occur.
  54  *
  55  * @see Member
  56  * @see java.lang.Class
  57  * @see java.lang.Class#getFields()
  58  * @see java.lang.Class#getField(String)
  59  * @see java.lang.Class#getDeclaredFields()

 111             genericInfo = FieldRepository.make(getGenericSignature(),
 112                                                getFactory());
 113         }
 114         return genericInfo; //return cached repository
 115     }
 116 
 117 
 118     /**
 119      * Package-private constructor
 120      */
 121     @SuppressWarnings("deprecation")
 122     Field(Class<?> declaringClass,
 123           String name,
 124           Class<?> type,
 125           int modifiers,
 126           boolean trustedFinal,
 127           int slot,
 128           String signature,
 129           byte[] annotations)
 130     {

 131         this.clazz = declaringClass;
 132         this.name = name;
 133         this.type = type;
 134         this.modifiers = modifiers;
 135         this.trustedFinal = trustedFinal;
 136         this.slot = slot;
 137         this.signature = signature;
 138         this.annotations = annotations;
 139     }
 140 
 141     /**
 142      * Package-private routine (exposed to java.lang.Class via
 143      * ReflectAccess) which returns a copy of this Field. The copy's
 144      * "root" field points to this Field.
 145      */
 146     Field copy() {
 147         // This routine enables sharing of FieldAccessor objects
 148         // among Field objects which refer to the same underlying
 149         // method in the VM. (All of this contortion is only necessary
 150         // because of the "accessibility" bit in AccessibleObject,

 185      * that declares the field represented by this {@code Field} object.
 186      */
 187     @Override
 188     public Class<?> getDeclaringClass() {
 189         return clazz;
 190     }
 191 
 192     /**
 193      * Returns the name of the field represented by this {@code Field} object.
 194      */
 195     public String getName() {
 196         return name;
 197     }
 198 
 199     /**
 200      * Returns the Java language modifiers for the field represented
 201      * by this {@code Field} object, as an integer. The {@code Modifier} class should
 202      * be used to decode the modifiers.
 203      *
 204      * @see Modifier

 205      * @jls 8.3 Field Declarations
 206      * @jls 9.3 Field (Constant) Declarations
 207      */
 208     public int getModifiers() {
 209         return modifiers;
 210     }
 211 












 212     /**
 213      * Returns {@code true} if this field represents an element of
 214      * an enumerated class; returns {@code false} otherwise.
 215      *
 216      * @return {@code true} if and only if this field represents an element of
 217      * an enumerated class.
 218      * @since 1.5
 219      * @jls 8.9.1 Enum Constants
 220      */
 221     public boolean isEnumConstant() {
 222         return (getModifiers() & Modifier.ENUM) != 0;
 223     }
 224 
 225     /**
 226      * Returns {@code true} if this field is a synthetic
 227      * field; returns {@code false} otherwise.
 228      *
 229      * @return true if and only if this field is a synthetic
 230      * field as defined by the Java Language Specification.
 231      * @since 1.5

 313      * followed by a period, followed by the name of the field.
 314      * For example:
 315      * <pre>
 316      *    public static final int java.lang.Thread.MIN_PRIORITY
 317      *    private int java.io.FileDescriptor.fd
 318      * </pre>
 319      *
 320      * <p>The modifiers are placed in canonical order as specified by
 321      * "The Java Language Specification".  This is {@code public},
 322      * {@code protected} or {@code private} first, and then other
 323      * modifiers in the following order: {@code static}, {@code final},
 324      * {@code transient}, {@code volatile}.
 325      *
 326      * @return a string describing this {@code Field}
 327      * @jls 8.3.1 Field Modifiers
 328      */
 329     public String toString() {
 330         int mod = getModifiers();
 331         return (((mod == 0) ? "" : (Modifier.toString(mod) + " "))
 332             + getType().getTypeName() + " "
 333             + getDeclaringClass().getTypeName() + "."
 334             + getName());
 335     }
 336 
 337     @Override
 338     String toShortString() {
 339         return "field " + getDeclaringClass().getTypeName() + "." + getName();








 340     }
 341 
 342     /**
 343      * Returns a string describing this {@code Field}, including
 344      * its generic type.  The format is the access modifiers for the
 345      * field, if any, followed by the generic field type, followed by
 346      * a space, followed by the fully-qualified name of the class
 347      * declaring the field, followed by a period, followed by the name
 348      * of the field.
 349      *
 350      * <p>The modifiers are placed in canonical order as specified by
 351      * "The Java Language Specification".  This is {@code public},
 352      * {@code protected} or {@code private} first, and then other
 353      * modifiers in the following order: {@code static}, {@code final},
 354      * {@code transient}, {@code volatile}.
 355      *
 356      * @return a string describing this {@code Field}, including
 357      * its generic type
 358      *
 359      * @since 1.5
 360      * @jls 8.3.1 Field Modifiers
 361      */
 362     public String toGenericString() {
 363         int mod = getModifiers();
 364         Type fieldType = getGenericType();
 365         return (((mod == 0) ? "" : (Modifier.toString(mod) + " "))
 366             + fieldType.getTypeName() + " "
 367             + getDeclaringClass().getTypeName() + "."
 368             + getName());
 369     }
 370 
 371     /**
 372      * Returns the value of the field represented by this {@code Field}, on
 373      * the specified object. The value is automatically wrapped in an
 374      * object if it has a primitive type.
 375      *
 376      * <p>The underlying field's value is obtained as follows:
 377      *
 378      * <p>If the underlying field is a static field, the {@code obj} argument
 379      * is ignored; it may be null.
 380      *
 381      * <p>Otherwise, the underlying field is an instance field.  If the
 382      * specified {@code obj} argument is null, the method throws a
 383      * {@code NullPointerException}. If the specified object is not an
 384      * instance of the class or interface declaring the underlying
 385      * field, the method throws an {@code IllegalArgumentException}.
 386      *
 387      * <p>If this {@code Field} object is enforcing Java language access control, and

 740      * <p>If the underlying field is static, the {@code obj} argument is
 741      * ignored; it may be null.
 742      *
 743      * <p>Otherwise the underlying field is an instance field.  If the
 744      * specified object argument is null, the method throws a
 745      * {@code NullPointerException}.  If the specified object argument is not
 746      * an instance of the class or interface declaring the underlying
 747      * field, the method throws an {@code IllegalArgumentException}.
 748      *
 749      * <p>If this {@code Field} object is enforcing Java language access control, and
 750      * the underlying field is inaccessible, the method throws an
 751      * {@code IllegalAccessException}.
 752      *
 753      * <p>If the underlying field is final, this {@code Field} object has
 754      * <em>write</em> access if and only if the following conditions are met:
 755      * <ul>
 756      * <li>{@link #setAccessible(boolean) setAccessible(true)} has succeeded for
 757      *     this {@code Field} object;</li>
 758      * <li>the field is non-static; and</li>
 759      * <li>the field's declaring class is not a {@linkplain Class#isHidden()
 760      *     hidden class}; and</li>


 761      * <li>the field's declaring class is not a {@linkplain Class#isRecord()
 762      *     record class}.</li>
 763      * </ul>
 764      * If any of the above checks is not met, this method throws an
 765      * {@code IllegalAccessException}.
 766      *
 767      * <p> Setting a final field in this way
 768      * is meaningful only during deserialization or reconstruction of
 769      * instances of classes with blank final fields, before they are
 770      * made available for access by other parts of a program. Use in
 771      * any other context may have unpredictable effects, including cases
 772      * in which other parts of a program continue to use the original
 773      * value of this field.
 774      *
 775      * <p>If the underlying field is of a primitive type, an unwrapping
 776      * conversion is attempted to convert the new value to a value of
 777      * a primitive type.  If this attempt fails, the method throws an
 778      * {@code IllegalArgumentException}.
 779      *
 780      * <p>If, after possible unwrapping, the new value cannot be

  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.lang.reflect;
  27 
  28 import jdk.internal.access.SharedSecrets;
  29 import jdk.internal.reflect.CallerSensitive;
  30 import jdk.internal.reflect.FieldAccessor;
  31 import jdk.internal.reflect.Reflection;
  32 import jdk.internal.vm.annotation.ForceInline;
  33 import jdk.internal.vm.annotation.Stable;
  34 import sun.reflect.generics.repository.FieldRepository;
  35 import sun.reflect.generics.factory.CoreReflectionFactory;
  36 import sun.reflect.generics.factory.GenericsFactory;
  37 import sun.reflect.generics.scope.ClassScope;
  38 import java.lang.annotation.Annotation;
  39 import java.util.Map;
  40 import java.util.Set;
  41 import java.util.Objects;
  42 import sun.reflect.annotation.AnnotationParser;
  43 import sun.reflect.annotation.AnnotationSupport;
  44 import sun.reflect.annotation.TypeAnnotation;
  45 import sun.reflect.annotation.TypeAnnotationParser;
  46 
  47 /**
  48  * A {@code Field} provides information about, and dynamic access to, a
  49  * single field of a class or an interface.  The reflected field may
  50  * be a class (static) field or an instance field.
  51  *
  52  * <p>A {@code Field} permits widening conversions to occur during a get or
  53  * set access operation, but throws an {@code IllegalArgumentException} if a
  54  * narrowing conversion would occur.
  55  *
  56  * @see Member
  57  * @see java.lang.Class
  58  * @see java.lang.Class#getFields()
  59  * @see java.lang.Class#getField(String)
  60  * @see java.lang.Class#getDeclaredFields()

 112             genericInfo = FieldRepository.make(getGenericSignature(),
 113                                                getFactory());
 114         }
 115         return genericInfo; //return cached repository
 116     }
 117 
 118 
 119     /**
 120      * Package-private constructor
 121      */
 122     @SuppressWarnings("deprecation")
 123     Field(Class<?> declaringClass,
 124           String name,
 125           Class<?> type,
 126           int modifiers,
 127           boolean trustedFinal,
 128           int slot,
 129           String signature,
 130           byte[] annotations)
 131     {
 132         assert declaringClass.isPrimaryType();
 133         this.clazz = declaringClass;
 134         this.name = name;
 135         this.type = type;
 136         this.modifiers = modifiers;
 137         this.trustedFinal = trustedFinal;
 138         this.slot = slot;
 139         this.signature = signature;
 140         this.annotations = annotations;
 141     }
 142 
 143     /**
 144      * Package-private routine (exposed to java.lang.Class via
 145      * ReflectAccess) which returns a copy of this Field. The copy's
 146      * "root" field points to this Field.
 147      */
 148     Field copy() {
 149         // This routine enables sharing of FieldAccessor objects
 150         // among Field objects which refer to the same underlying
 151         // method in the VM. (All of this contortion is only necessary
 152         // because of the "accessibility" bit in AccessibleObject,

 187      * that declares the field represented by this {@code Field} object.
 188      */
 189     @Override
 190     public Class<?> getDeclaringClass() {
 191         return clazz;
 192     }
 193 
 194     /**
 195      * Returns the name of the field represented by this {@code Field} object.
 196      */
 197     public String getName() {
 198         return name;
 199     }
 200 
 201     /**
 202      * Returns the Java language modifiers for the field represented
 203      * by this {@code Field} object, as an integer. The {@code Modifier} class should
 204      * be used to decode the modifiers.
 205      *
 206      * @see Modifier
 207      * @see #accessFlags()
 208      * @jls 8.3 Field Declarations
 209      * @jls 9.3 Field (Constant) Declarations
 210      */
 211     public int getModifiers() {
 212         return modifiers;
 213     }
 214 
 215     /**
 216      * {@return an unmodifiable set of the {@linkplain AccessFlag
 217      * access flags} for this field, possibly empty}
 218      * @see #getModifiers()
 219      * @jvms 4.5 Fields
 220      * @since 20
 221      */
 222     @Override
 223     public Set<AccessFlag> accessFlags() {
 224         return AccessFlag.maskToAccessFlags(getModifiers(), AccessFlag.Location.FIELD);
 225     }
 226 
 227     /**
 228      * Returns {@code true} if this field represents an element of
 229      * an enumerated class; returns {@code false} otherwise.
 230      *
 231      * @return {@code true} if and only if this field represents an element of
 232      * an enumerated class.
 233      * @since 1.5
 234      * @jls 8.9.1 Enum Constants
 235      */
 236     public boolean isEnumConstant() {
 237         return (getModifiers() & Modifier.ENUM) != 0;
 238     }
 239 
 240     /**
 241      * Returns {@code true} if this field is a synthetic
 242      * field; returns {@code false} otherwise.
 243      *
 244      * @return true if and only if this field is a synthetic
 245      * field as defined by the Java Language Specification.
 246      * @since 1.5

 328      * followed by a period, followed by the name of the field.
 329      * For example:
 330      * <pre>
 331      *    public static final int java.lang.Thread.MIN_PRIORITY
 332      *    private int java.io.FileDescriptor.fd
 333      * </pre>
 334      *
 335      * <p>The modifiers are placed in canonical order as specified by
 336      * "The Java Language Specification".  This is {@code public},
 337      * {@code protected} or {@code private} first, and then other
 338      * modifiers in the following order: {@code static}, {@code final},
 339      * {@code transient}, {@code volatile}.
 340      *
 341      * @return a string describing this {@code Field}
 342      * @jls 8.3.1 Field Modifiers
 343      */
 344     public String toString() {
 345         int mod = getModifiers();
 346         return (((mod == 0) ? "" : (Modifier.toString(mod) + " "))
 347             + getType().getTypeName() + " "
 348             + getDeclaringClassTypeName() + "."
 349             + getName());
 350     }
 351 
 352     @Override
 353     String toShortString() {
 354         return "field " + getDeclaringClassTypeName() + "." + getName();
 355     }
 356 
 357     String getDeclaringClassTypeName() {
 358         Class<?> c = getDeclaringClass();
 359         if (c.isPrimitiveClass()) {
 360             c = c.asValueType();
 361         }
 362         return c.getTypeName();
 363     }
 364 
 365     /**
 366      * Returns a string describing this {@code Field}, including
 367      * its generic type.  The format is the access modifiers for the
 368      * field, if any, followed by the generic field type, followed by
 369      * a space, followed by the fully-qualified name of the class
 370      * declaring the field, followed by a period, followed by the name
 371      * of the field.
 372      *
 373      * <p>The modifiers are placed in canonical order as specified by
 374      * "The Java Language Specification".  This is {@code public},
 375      * {@code protected} or {@code private} first, and then other
 376      * modifiers in the following order: {@code static}, {@code final},
 377      * {@code transient}, {@code volatile}.
 378      *
 379      * @return a string describing this {@code Field}, including
 380      * its generic type
 381      *
 382      * @since 1.5
 383      * @jls 8.3.1 Field Modifiers
 384      */
 385     public String toGenericString() {
 386         int mod = getModifiers();
 387         Type fieldType = getGenericType();
 388         return (((mod == 0) ? "" : (Modifier.toString(mod) + " "))
 389             + fieldType.getTypeName() + " "
 390             + getDeclaringClassTypeName() + "."
 391             + getName());
 392     }
 393 
 394     /**
 395      * Returns the value of the field represented by this {@code Field}, on
 396      * the specified object. The value is automatically wrapped in an
 397      * object if it has a primitive type.
 398      *
 399      * <p>The underlying field's value is obtained as follows:
 400      *
 401      * <p>If the underlying field is a static field, the {@code obj} argument
 402      * is ignored; it may be null.
 403      *
 404      * <p>Otherwise, the underlying field is an instance field.  If the
 405      * specified {@code obj} argument is null, the method throws a
 406      * {@code NullPointerException}. If the specified object is not an
 407      * instance of the class or interface declaring the underlying
 408      * field, the method throws an {@code IllegalArgumentException}.
 409      *
 410      * <p>If this {@code Field} object is enforcing Java language access control, and

 763      * <p>If the underlying field is static, the {@code obj} argument is
 764      * ignored; it may be null.
 765      *
 766      * <p>Otherwise the underlying field is an instance field.  If the
 767      * specified object argument is null, the method throws a
 768      * {@code NullPointerException}.  If the specified object argument is not
 769      * an instance of the class or interface declaring the underlying
 770      * field, the method throws an {@code IllegalArgumentException}.
 771      *
 772      * <p>If this {@code Field} object is enforcing Java language access control, and
 773      * the underlying field is inaccessible, the method throws an
 774      * {@code IllegalAccessException}.
 775      *
 776      * <p>If the underlying field is final, this {@code Field} object has
 777      * <em>write</em> access if and only if the following conditions are met:
 778      * <ul>
 779      * <li>{@link #setAccessible(boolean) setAccessible(true)} has succeeded for
 780      *     this {@code Field} object;</li>
 781      * <li>the field is non-static; and</li>
 782      * <li>the field's declaring class is not a {@linkplain Class#isHidden()
 783      *     hidden class};</li>
 784      * <li>the field's declaring class is not a {@linkplain Class#isValue()
 785      *     value class}; and</li>
 786      * <li>the field's declaring class is not a {@linkplain Class#isRecord()
 787      *     record class}.</li>
 788      * </ul>
 789      * If any of the above checks is not met, this method throws an
 790      * {@code IllegalAccessException}.
 791      *
 792      * <p> Setting a final field in this way
 793      * is meaningful only during deserialization or reconstruction of
 794      * instances of classes with blank final fields, before they are
 795      * made available for access by other parts of a program. Use in
 796      * any other context may have unpredictable effects, including cases
 797      * in which other parts of a program continue to use the original
 798      * value of this field.
 799      *
 800      * <p>If the underlying field is of a primitive type, an unwrapping
 801      * conversion is attempted to convert the new value to a value of
 802      * a primitive type.  If this attempt fails, the method throws an
 803      * {@code IllegalArgumentException}.
 804      *
 805      * <p>If, after possible unwrapping, the new value cannot be
< prev index next >