1 /*
2 * Copyright (c) 1996, 2024, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
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()
61 * @see java.lang.Class#getDeclaredField(String)
62 *
63 * @author Kenneth Russell
64 * @author Nakul Saraiya
65 * @since 1.1
66 */
67 public final
68 class Field extends AccessibleObject implements Member {
69 private final Class<?> clazz;
70 private final int slot;
71 // This is guaranteed to be interned by the VM in the 1.4
72 // reflection implementation
73 private final String name;
74 private final Class<?> type;
75 private final int modifiers;
76 private final int flags;
77 // Generics and annotations support
78 private final transient String signature;
79 private final byte[] annotations;
80
81 /**
82 * Fields are mutable due to {@link AccessibleObject#setAccessible(boolean)}.
83 * Thus, we return a new copy of a root each time a field is returned.
84 * Some lazily initialized immutable states can be stored on root and shared to the copies.
85 */
86 private Field root;
87 private transient volatile FieldRepository genericInfo;
88 private @Stable FieldAccessor fieldAccessor; // access control enabled
89 private @Stable FieldAccessor overrideFieldAccessor; // access control suppressed
90 // End shared states
91
92 // Generics infrastructure
93
94 private String getGenericSignature() {return signature;}
95
96 // Accessor for factory
97 private GenericsFactory getFactory() {
98 Class<?> c = getDeclaringClass();
99 // create scope and factory
100 return CoreReflectionFactory.make(c, ClassScope.make(c));
101 }
102
103 // Accessor for generic info repository
104 private FieldRepository getGenericInfo() {
105 var genericInfo = this.genericInfo;
106 if (genericInfo == null) {
107 var root = this.root;
108 if (root != null) {
109 genericInfo = root.getGenericInfo();
110 } else {
111 genericInfo = FieldRepository.make(getGenericSignature(), getFactory());
112 }
113 this.genericInfo = genericInfo;
114 }
115 return genericInfo;
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 int flags,
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.flags = flags;
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,
151 // which implicitly requires that new java.lang.reflect
152 // objects be fabricated for each reflective call on Class
153 // objects.)
154 if (this.root != null)
155 throw new IllegalArgumentException("Can not copy a non-root Field");
156
157 Field res = new Field(clazz, name, type, modifiers, flags, slot, signature, annotations);
158 res.root = this;
159 // Might as well eagerly propagate this if already present
160 res.fieldAccessor = fieldAccessor;
161 res.overrideFieldAccessor = overrideFieldAccessor;
162 res.genericInfo = genericInfo;
163
164 return res;
165 }
166
167 /**
168 * @throws InaccessibleObjectException {@inheritDoc}
169 * @throws SecurityException {@inheritDoc}
170 */
171 @Override
172 @CallerSensitive
173 public void setAccessible(boolean flag) {
174 AccessibleObject.checkPermission();
175 if (flag) checkCanSetAccessible(Reflection.getCallerClass());
176 setAccessible0(flag);
177 }
178
179 @Override
180 void checkCanSetAccessible(Class<?> caller) {
181 checkCanSetAccessible(caller, clazz);
182 }
183
184 /**
185 * Returns the {@code Class} object representing the class or interface
186 * that declares the field represented by this {@code Field} object.
187 */
188 @Override
189 public Class<?> getDeclaringClass() {
190 return clazz;
191 }
192
193 /**
194 * Returns the name of the field represented by this {@code Field} object.
195 */
196 public String getName() {
197 return name;
198 }
199
200 /**
201 * Returns the Java language modifiers for the field represented
202 * by this {@code Field} object, as an integer. The {@code Modifier} class should
203 * be used to decode the modifiers.
204 *
205 * @see Modifier
206 * @see #accessFlags()
207 * @jls 8.3 Field Declarations
208 * @jls 9.3 Field (Constant) Declarations
209 */
210 public int getModifiers() {
211 return modifiers;
212 }
213
214 /**
215 * {@return an unmodifiable set of the {@linkplain AccessFlag
216 * access flags} for this field, possibly empty}
217 * The {@code AccessFlags} may depend on the class file format version of the class.
218 *
219 * @see #getModifiers()
220 * @jvms 4.5 Fields
221 * @since 20
222 */
223 @Override
224 public Set<AccessFlag> accessFlags() {
225 int major = SharedSecrets.getJavaLangAccess().classFileFormatVersion(getDeclaringClass()) & 0xffff;
226 var cffv = ClassFileFormatVersion.fromMajor(major);
227 return AccessFlag.maskToAccessFlags(getModifiers(), AccessFlag.Location.FIELD, cffv);
228 }
229
230 /**
231 * Returns {@code true} if this field represents an element of
232 * an enumerated class; returns {@code false} otherwise.
233 *
234 * @return {@code true} if and only if this field represents an element of
235 * an enumerated class.
236 * @since 1.5
237 * @jls 8.9.1 Enum Constants
238 */
239 public boolean isEnumConstant() {
240 return (getModifiers() & Modifier.ENUM) != 0;
241 }
242
243 /**
244 * Returns {@code true} if this field is a synthetic
245 * field; returns {@code false} otherwise.
246 *
247 * @return true if and only if this field is a synthetic
248 * field as defined by the Java Language Specification.
249 * @since 1.5
250 * @see <a
251 * href="{@docRoot}/java.base/java/lang/reflect/package-summary.html#LanguageJvmModel">Java
252 * programming language and JVM modeling in core reflection</a>
253 */
254 public boolean isSynthetic() {
255 return Modifier.isSynthetic(getModifiers());
256 }
257
258 /**
259 * Returns a {@code Class} object that identifies the
260 * declared type for the field represented by this
261 * {@code Field} object.
262 *
263 * @return a {@code Class} object identifying the declared
264 * type of the field represented by this object
265 */
266 public Class<?> getType() {
267 return type;
268 }
269
270 /**
271 * Returns a {@code Type} object that represents the declared type for
272 * the field represented by this {@code Field} object.
273 *
274 * <p>If the declared type of the field is a parameterized type,
275 * the {@code Type} object returned must accurately reflect the
276 * actual type arguments used in the source code.
277 *
278 * <p>If the type of the underlying field is a type variable or a
279 * parameterized type, it is created. Otherwise, it is resolved.
280 *
281 * @return a {@code Type} object that represents the declared type for
282 * the field represented by this {@code Field} object
283 * @throws GenericSignatureFormatError if the generic field
284 * signature does not conform to the format specified in
285 * <cite>The Java Virtual Machine Specification</cite>
286 * @throws TypeNotPresentException if the generic type
287 * signature of the underlying field refers to a non-existent
288 * class or interface declaration
289 * @throws MalformedParameterizedTypeException if the generic
290 * signature of the underlying field refers to a parameterized type
291 * that cannot be instantiated for any reason
292 * @since 1.5
293 */
294 public Type getGenericType() {
295 if (getGenericSignature() != null)
296 return getGenericInfo().getGenericType();
297 else
298 return getType();
299 }
300
301
302 /**
303 * Compares this {@code Field} against the specified object. Returns
304 * true if the objects are the same. Two {@code Field} objects are the same if
305 * they were declared by the same class and have the same name
306 * and type.
307 */
308 public boolean equals(Object obj) {
309 if (obj instanceof Field other) {
310 return (getDeclaringClass() == other.getDeclaringClass())
311 && (getName() == other.getName())
312 && (getType() == other.getType());
313 }
314 return false;
315 }
316
317 /**
318 * Returns a hashcode for this {@code Field}. This is computed as the
319 * exclusive-or of the hashcodes for the underlying field's
320 * declaring class name and its name.
321 */
322 public int hashCode() {
323 return getDeclaringClass().getName().hashCode() ^ getName().hashCode();
324 }
325
326 /**
327 * Returns a string describing this {@code Field}. The format is
328 * the access modifiers for the field, if any, followed
329 * by the field type, followed by a space, followed by
330 * the fully-qualified name of the class declaring the field,
331 * followed by a period, followed by the name of the field.
332 * For example:
333 * <pre>
334 * public static final int java.lang.Thread.MIN_PRIORITY
335 * private int java.io.FileDescriptor.fd
336 * </pre>
337 *
338 * <p>The modifiers are placed in canonical order as specified by
339 * "The Java Language Specification". This is {@code public},
340 * {@code protected} or {@code private} first, and then other
341 * modifiers in the following order: {@code static}, {@code final},
342 * {@code transient}, {@code volatile}.
343 *
344 * @return a string describing this {@code Field}
345 * @jls 8.3.1 Field Modifiers
346 */
347 public String toString() {
348 int mod = getModifiers();
349 return (((mod == 0) ? "" : (Modifier.toString(mod) + " "))
350 + getType().getTypeName() + " "
351 + getDeclaringClass().getTypeName() + "."
352 + getName());
353 }
354
355 @Override
356 String toShortString() {
357 return "field " + getDeclaringClass().getTypeName() + "." + getName();
358 }
359
360 /**
361 * Returns a string describing this {@code Field}, including
362 * its generic type. The format is the access modifiers for the
363 * field, if any, followed by the generic field type, followed by
364 * a space, followed by the fully-qualified name of the class
365 * declaring the field, followed by a period, followed by the name
366 * of the field.
367 *
368 * <p>The modifiers are placed in canonical order as specified by
369 * "The Java Language Specification". This is {@code public},
370 * {@code protected} or {@code private} first, and then other
371 * modifiers in the following order: {@code static}, {@code final},
372 * {@code transient}, {@code volatile}.
373 *
374 * @return a string describing this {@code Field}, including
375 * its generic type
376 *
377 * @since 1.5
378 * @jls 8.3.1 Field Modifiers
379 */
380 public String toGenericString() {
381 int mod = getModifiers();
382 Type fieldType = getGenericType();
383 return (((mod == 0) ? "" : (Modifier.toString(mod) + " "))
384 + fieldType.getTypeName() + " "
385 + getDeclaringClass().getTypeName() + "."
386 + getName());
387 }
388
389 /**
390 * Returns the value of the field represented by this {@code Field}, on
391 * the specified object. The value is automatically wrapped in an
392 * object if it has a primitive type.
393 *
394 * <p>The underlying field's value is obtained as follows:
395 *
396 * <p>If the underlying field is a static field, the {@code obj} argument
397 * is ignored; it may be null.
398 *
399 * <p>Otherwise, the underlying field is an instance field. If the
400 * specified {@code obj} argument is null, the method throws a
401 * {@code NullPointerException}. If the specified object is not an
402 * instance of the class or interface declaring the underlying
403 * field, the method throws an {@code IllegalArgumentException}.
404 *
405 * <p>If this {@code Field} object is enforcing Java language access control, and
406 * the underlying field is inaccessible, the method throws an
407 * {@code IllegalAccessException}.
408 * If the underlying field is static, the class that declared the
409 * field is initialized if it has not already been initialized.
410 *
411 * <p>Otherwise, the value is retrieved from the underlying instance
412 * or static field. If the field has a primitive type, the value
413 * is wrapped in an object before being returned, otherwise it is
414 * returned as is.
415 *
416 * <p>If the field is hidden in the type of {@code obj},
417 * the field's value is obtained according to the preceding rules.
418 *
419 * @param obj object from which the represented field's value is
420 * to be extracted
421 * @return the value of the represented field in object
422 * {@code obj}; primitive values are wrapped in an appropriate
423 * object before being returned
424 *
425 * @throws IllegalAccessException if this {@code Field} object
426 * is enforcing Java language access control and the underlying
427 * field is inaccessible.
428 * @throws IllegalArgumentException if the specified object is not an
429 * instance of the class or interface declaring the underlying
430 * field (or a subclass or implementor thereof).
431 * @throws NullPointerException if the specified object is null
432 * and the field is an instance field.
433 * @throws ExceptionInInitializerError if the initialization provoked
434 * by this method fails.
435 */
436 @CallerSensitive
437 @ForceInline // to ensure Reflection.getCallerClass optimization
438 public Object get(Object obj)
439 throws IllegalArgumentException, IllegalAccessException
440 {
441 if (!override) {
442 Class<?> caller = Reflection.getCallerClass();
443 checkAccess(caller, obj);
444 return getFieldAccessor().get(obj);
445 } else {
446 return getOverrideFieldAccessor().get(obj);
447 }
448 }
449
450 /**
451 * Gets the value of a static or instance {@code boolean} field.
452 *
453 * @param obj the object to extract the {@code boolean} value
454 * from
455 * @return the value of the {@code boolean} field
456 *
457 * @throws IllegalAccessException if this {@code Field} object
458 * is enforcing Java language access control and the underlying
459 * field is inaccessible.
460 * @throws IllegalArgumentException if the specified object is not
461 * an instance of the class or interface declaring the
462 * underlying field (or a subclass or implementor
463 * thereof), or if the field value cannot be
464 * converted to the type {@code boolean} by a
465 * widening conversion.
466 * @throws NullPointerException if the specified object is null
467 * and the field is an instance field.
468 * @throws ExceptionInInitializerError if the initialization provoked
469 * by this method fails.
470 * @see Field#get
471 */
472 @CallerSensitive
473 @ForceInline // to ensure Reflection.getCallerClass optimization
474 public boolean getBoolean(Object obj)
475 throws IllegalArgumentException, IllegalAccessException
476 {
477 if (!override) {
478 Class<?> caller = Reflection.getCallerClass();
479 checkAccess(caller, obj);
480 return getFieldAccessor().getBoolean(obj);
481 } else {
482 return getOverrideFieldAccessor().getBoolean(obj);
483 }
484 }
485
486 /**
487 * Gets the value of a static or instance {@code byte} field.
488 *
489 * @param obj the object to extract the {@code byte} value
490 * from
491 * @return the value of the {@code byte} field
492 *
493 * @throws IllegalAccessException if this {@code Field} object
494 * is enforcing Java language access control and the underlying
495 * field is inaccessible.
496 * @throws IllegalArgumentException if the specified object is not
497 * an instance of the class or interface declaring the
498 * underlying field (or a subclass or implementor
499 * thereof), or if the field value cannot be
500 * converted to the type {@code byte} by a
501 * widening conversion.
502 * @throws NullPointerException if the specified object is null
503 * and the field is an instance field.
504 * @throws ExceptionInInitializerError if the initialization provoked
505 * by this method fails.
506 * @see Field#get
507 */
508 @CallerSensitive
509 @ForceInline // to ensure Reflection.getCallerClass optimization
510 public byte getByte(Object obj)
511 throws IllegalArgumentException, IllegalAccessException
512 {
513 if (!override) {
514 Class<?> caller = Reflection.getCallerClass();
515 checkAccess(caller, obj);
516 return getFieldAccessor().getByte(obj);
517 } else {
518 return getOverrideFieldAccessor().getByte(obj);
519 }
520 }
521
522 /**
523 * Gets the value of a static or instance field of type
524 * {@code char} or of another primitive type convertible to
525 * type {@code char} via a widening conversion.
526 *
527 * @param obj the object to extract the {@code char} value
528 * from
529 * @return the value of the field converted to type {@code char}
530 *
531 * @throws IllegalAccessException if this {@code Field} object
532 * is enforcing Java language access control and the underlying
533 * field is inaccessible.
534 * @throws IllegalArgumentException if the specified object is not
535 * an instance of the class or interface declaring the
536 * underlying field (or a subclass or implementor
537 * thereof), or if the field value cannot be
538 * converted to the type {@code char} by a
539 * widening conversion.
540 * @throws NullPointerException if the specified object is null
541 * and the field is an instance field.
542 * @throws ExceptionInInitializerError if the initialization provoked
543 * by this method fails.
544 * @see Field#get
545 */
546 @CallerSensitive
547 @ForceInline // to ensure Reflection.getCallerClass optimization
548 public char getChar(Object obj)
549 throws IllegalArgumentException, IllegalAccessException
550 {
551 if (!override) {
552 Class<?> caller = Reflection.getCallerClass();
553 checkAccess(caller, obj);
554 return getFieldAccessor().getChar(obj);
555 } else {
556 return getOverrideFieldAccessor().getChar(obj);
557 }
558 }
559
560 /**
561 * Gets the value of a static or instance field of type
562 * {@code short} or of another primitive type convertible to
563 * type {@code short} via a widening conversion.
564 *
565 * @param obj the object to extract the {@code short} value
566 * from
567 * @return the value of the field converted to type {@code short}
568 *
569 * @throws IllegalAccessException if this {@code Field} object
570 * is enforcing Java language access control and the underlying
571 * field is inaccessible.
572 * @throws IllegalArgumentException if the specified object is not
573 * an instance of the class or interface declaring the
574 * underlying field (or a subclass or implementor
575 * thereof), or if the field value cannot be
576 * converted to the type {@code short} by a
577 * widening conversion.
578 * @throws NullPointerException if the specified object is null
579 * and the field is an instance field.
580 * @throws ExceptionInInitializerError if the initialization provoked
581 * by this method fails.
582 * @see Field#get
583 */
584 @CallerSensitive
585 @ForceInline // to ensure Reflection.getCallerClass optimization
586 public short getShort(Object obj)
587 throws IllegalArgumentException, IllegalAccessException
588 {
589 if (!override) {
590 Class<?> caller = Reflection.getCallerClass();
591 checkAccess(caller, obj);
592 return getFieldAccessor().getShort(obj);
593 } else {
594 return getOverrideFieldAccessor().getShort(obj);
595 }
596 }
597
598 /**
599 * Gets the value of a static or instance field of type
600 * {@code int} or of another primitive type convertible to
601 * type {@code int} via a widening conversion.
602 *
603 * @param obj the object to extract the {@code int} value
604 * from
605 * @return the value of the field converted to type {@code int}
606 *
607 * @throws IllegalAccessException if this {@code Field} object
608 * is enforcing Java language access control and the underlying
609 * field is inaccessible.
610 * @throws IllegalArgumentException if the specified object is not
611 * an instance of the class or interface declaring the
612 * underlying field (or a subclass or implementor
613 * thereof), or if the field value cannot be
614 * converted to the type {@code int} by a
615 * widening conversion.
616 * @throws NullPointerException if the specified object is null
617 * and the field is an instance field.
618 * @throws ExceptionInInitializerError if the initialization provoked
619 * by this method fails.
620 * @see Field#get
621 */
622 @CallerSensitive
623 @ForceInline // to ensure Reflection.getCallerClass optimization
624 public int getInt(Object obj)
625 throws IllegalArgumentException, IllegalAccessException
626 {
627 if (!override) {
628 Class<?> caller = Reflection.getCallerClass();
629 checkAccess(caller, obj);
630 return getFieldAccessor().getInt(obj);
631 } else {
632 return getOverrideFieldAccessor().getInt(obj);
633 }
634 }
635
636 /**
637 * Gets the value of a static or instance field of type
638 * {@code long} or of another primitive type convertible to
639 * type {@code long} via a widening conversion.
640 *
641 * @param obj the object to extract the {@code long} value
642 * from
643 * @return the value of the field converted to type {@code long}
644 *
645 * @throws IllegalAccessException if this {@code Field} object
646 * is enforcing Java language access control and the underlying
647 * field is inaccessible.
648 * @throws IllegalArgumentException if the specified object is not
649 * an instance of the class or interface declaring the
650 * underlying field (or a subclass or implementor
651 * thereof), or if the field value cannot be
652 * converted to the type {@code long} by a
653 * widening conversion.
654 * @throws NullPointerException if the specified object is null
655 * and the field is an instance field.
656 * @throws ExceptionInInitializerError if the initialization provoked
657 * by this method fails.
658 * @see Field#get
659 */
660 @CallerSensitive
661 @ForceInline // to ensure Reflection.getCallerClass optimization
662 public long getLong(Object obj)
663 throws IllegalArgumentException, IllegalAccessException
664 {
665 if (!override) {
666 Class<?> caller = Reflection.getCallerClass();
667 checkAccess(caller, obj);
668 return getFieldAccessor().getLong(obj);
669 } else {
670 return getOverrideFieldAccessor().getLong(obj);
671 }
672 }
673
674 /**
675 * Gets the value of a static or instance field of type
676 * {@code float} or of another primitive type convertible to
677 * type {@code float} via a widening conversion.
678 *
679 * @param obj the object to extract the {@code float} value
680 * from
681 * @return the value of the field converted to type {@code float}
682 *
683 * @throws IllegalAccessException if this {@code Field} object
684 * is enforcing Java language access control and the underlying
685 * field is inaccessible.
686 * @throws IllegalArgumentException if the specified object is not
687 * an instance of the class or interface declaring the
688 * underlying field (or a subclass or implementor
689 * thereof), or if the field value cannot be
690 * converted to the type {@code float} by a
691 * widening conversion.
692 * @throws NullPointerException if the specified object is null
693 * and the field is an instance field.
694 * @throws ExceptionInInitializerError if the initialization provoked
695 * by this method fails.
696 * @see Field#get
697 */
698 @CallerSensitive
699 @ForceInline // to ensure Reflection.getCallerClass optimization
700 public float getFloat(Object obj)
701 throws IllegalArgumentException, IllegalAccessException
702 {
703 if (!override) {
704 Class<?> caller = Reflection.getCallerClass();
705 checkAccess(caller, obj);
706 return getFieldAccessor().getFloat(obj);
707 } else {
708 return getOverrideFieldAccessor().getFloat(obj);
709 }
710 }
711
712 /**
713 * Gets the value of a static or instance field of type
714 * {@code double} or of another primitive type convertible to
715 * type {@code double} via a widening conversion.
716 *
717 * @param obj the object to extract the {@code double} value
718 * from
719 * @return the value of the field converted to type {@code double}
720 *
721 * @throws IllegalAccessException if this {@code Field} object
722 * is enforcing Java language access control and the underlying
723 * field is inaccessible.
724 * @throws IllegalArgumentException if the specified object is not
725 * an instance of the class or interface declaring the
726 * underlying field (or a subclass or implementor
727 * thereof), or if the field value cannot be
728 * converted to the type {@code double} by a
729 * widening conversion.
730 * @throws NullPointerException if the specified object is null
731 * and the field is an instance field.
732 * @throws ExceptionInInitializerError if the initialization provoked
733 * by this method fails.
734 * @see Field#get
735 */
736 @CallerSensitive
737 @ForceInline // to ensure Reflection.getCallerClass optimization
738 public double getDouble(Object obj)
739 throws IllegalArgumentException, IllegalAccessException
740 {
741 if (!override) {
742 Class<?> caller = Reflection.getCallerClass();
743 checkAccess(caller, obj);
744 return getFieldAccessor().getDouble(obj);
745 } else {
746 return getOverrideFieldAccessor().getDouble(obj);
747 }
748 }
749
750 /**
751 * Sets the field represented by this {@code Field} object on the
752 * specified object argument to the specified new value. The new
753 * value is automatically unwrapped if the underlying field has a
754 * primitive type.
755 *
756 * <p>The operation proceeds as follows:
757 *
758 * <p>If the underlying field is static, the {@code obj} argument is
759 * ignored; it may be null.
760 *
761 * <p>Otherwise the underlying field is an instance field. If the
762 * specified object argument is null, the method throws a
763 * {@code NullPointerException}. If the specified object argument is not
764 * an instance of the class or interface declaring the underlying
765 * field, the method throws an {@code IllegalArgumentException}.
766 *
767 * <p>If this {@code Field} object is enforcing Java language access control, and
768 * the underlying field is inaccessible, the method throws an
769 * {@code IllegalAccessException}.
770 *
771 * <p>If the underlying field is final, this {@code Field} object has
772 * <em>write</em> access if and only if the following conditions are met:
773 * <ul>
774 * <li>{@link #setAccessible(boolean) setAccessible(true)} has succeeded for
775 * this {@code Field} object;</li>
776 * <li>the field is non-static; and</li>
777 * <li>the field's declaring class is not a {@linkplain Class#isHidden()
778 * hidden class};</li>
779 * <li>the field's declaring class is not a {@linkplain Class#isValue()
780 * value class}; and</li>
781 * <li>the field's declaring class is not a {@linkplain Class#isRecord()
782 * record class}.</li>
783 * </ul>
784 * If any of the above checks is not met, this method throws an
785 * {@code IllegalAccessException}.
786 *
787 * <p> Setting a final field in this way
788 * is meaningful only during deserialization or reconstruction of
789 * instances of classes with blank final fields, before they are
790 * made available for access by other parts of a program. Use in
791 * any other context may have unpredictable effects, including cases
792 * in which other parts of a program continue to use the original
793 * value of this field.
794 *
795 * <p>If the underlying field is of a primitive type, an unwrapping
796 * conversion is attempted to convert the new value to a value of
797 * a primitive type. If this attempt fails, the method throws an
798 * {@code IllegalArgumentException}.
799 *
800 * <p>If, after possible unwrapping, the new value cannot be
801 * converted to the type of the underlying field by an identity or
802 * widening conversion, the method throws an
803 * {@code IllegalArgumentException}.
804 *
805 * <p>If the underlying field is static, the class that declared the
806 * field is initialized if it has not already been initialized.
807 *
808 * <p>The field is set to the possibly unwrapped and widened new value.
809 *
810 * <p>If the field is hidden in the type of {@code obj},
811 * the field's value is set according to the preceding rules.
812 *
813 * @param obj the object whose field should be modified
814 * @param value the new value for the field of {@code obj}
815 * being modified
816 *
817 * @throws IllegalAccessException if this {@code Field} object
818 * is enforcing Java language access control and the underlying
819 * field is inaccessible or final;
820 * or if this {@code Field} object has no write access.
821 * @throws IllegalArgumentException if the specified object is not an
822 * instance of the class or interface declaring the underlying
823 * field (or a subclass or implementor thereof),
824 * or if an unwrapping conversion fails.
825 * @throws NullPointerException if the specified object is null
826 * and the field is an instance field.
827 * @throws ExceptionInInitializerError if the initialization provoked
828 * by this method fails.
829 */
830 @CallerSensitive
831 @ForceInline // to ensure Reflection.getCallerClass optimization
832 public void set(Object obj, Object value)
833 throws IllegalArgumentException, IllegalAccessException
834 {
835 if (!override) {
836 Class<?> caller = Reflection.getCallerClass();
837 checkAccess(caller, obj);
838 getFieldAccessor().set(obj, value);
839 } else {
840 getOverrideFieldAccessor().set(obj, value);
841 }
842 }
843
844 /**
845 * Sets the value of a field as a {@code boolean} on the specified object.
846 * This method is equivalent to
847 * {@code set(obj, zObj)},
848 * where {@code zObj} is a {@code Boolean} object and
849 * {@code zObj.booleanValue() == z}.
850 *
851 * @param obj the object whose field should be modified
852 * @param z the new value for the field of {@code obj}
853 * being modified
854 *
855 * @throws IllegalAccessException if this {@code Field} object
856 * is enforcing Java language access control and the underlying
857 * field is either inaccessible or final;
858 * or if this {@code Field} object has no write access.
859 * @throws IllegalArgumentException if the specified object is not an
860 * instance of the class or interface declaring the underlying
861 * field (or a subclass or implementor thereof),
862 * or if an unwrapping conversion fails.
863 * @throws NullPointerException if the specified object is null
864 * and the field is an instance field.
865 * @throws ExceptionInInitializerError if the initialization provoked
866 * by this method fails.
867 * @see Field#set
868 */
869 @CallerSensitive
870 @ForceInline // to ensure Reflection.getCallerClass optimization
871 public void setBoolean(Object obj, boolean z)
872 throws IllegalArgumentException, IllegalAccessException
873 {
874 if (!override) {
875 Class<?> caller = Reflection.getCallerClass();
876 checkAccess(caller, obj);
877 getFieldAccessor().setBoolean(obj, z);
878 } else {
879 getOverrideFieldAccessor().setBoolean(obj, z);
880 }
881 }
882
883 /**
884 * Sets the value of a field as a {@code byte} on the specified object.
885 * This method is equivalent to
886 * {@code set(obj, bObj)},
887 * where {@code bObj} is a {@code Byte} object and
888 * {@code bObj.byteValue() == b}.
889 *
890 * @param obj the object whose field should be modified
891 * @param b the new value for the field of {@code obj}
892 * being modified
893 *
894 * @throws IllegalAccessException if this {@code Field} object
895 * is enforcing Java language access control and the underlying
896 * field is either inaccessible or final;
897 * or if this {@code Field} object has no write access.
898 * @throws IllegalArgumentException if the specified object is not an
899 * instance of the class or interface declaring the underlying
900 * field (or a subclass or implementor thereof),
901 * or if an unwrapping conversion fails.
902 * @throws NullPointerException if the specified object is null
903 * and the field is an instance field.
904 * @throws ExceptionInInitializerError if the initialization provoked
905 * by this method fails.
906 * @see Field#set
907 */
908 @CallerSensitive
909 @ForceInline // to ensure Reflection.getCallerClass optimization
910 public void setByte(Object obj, byte b)
911 throws IllegalArgumentException, IllegalAccessException
912 {
913 if (!override) {
914 Class<?> caller = Reflection.getCallerClass();
915 checkAccess(caller, obj);
916 getFieldAccessor().setByte(obj, b);
917 } else {
918 getOverrideFieldAccessor().setByte(obj, b);
919 }
920 }
921
922 /**
923 * Sets the value of a field as a {@code char} on the specified object.
924 * This method is equivalent to
925 * {@code set(obj, cObj)},
926 * where {@code cObj} is a {@code Character} object and
927 * {@code cObj.charValue() == c}.
928 *
929 * @param obj the object whose field should be modified
930 * @param c the new value for the field of {@code obj}
931 * being modified
932 *
933 * @throws IllegalAccessException if this {@code Field} object
934 * is enforcing Java language access control and the underlying
935 * field is either inaccessible or final;
936 * or if this {@code Field} object has no write access.
937 * @throws IllegalArgumentException if the specified object is not an
938 * instance of the class or interface declaring the underlying
939 * field (or a subclass or implementor thereof),
940 * or if an unwrapping conversion fails.
941 * @throws NullPointerException if the specified object is null
942 * and the field is an instance field.
943 * @throws ExceptionInInitializerError if the initialization provoked
944 * by this method fails.
945 * @see Field#set
946 */
947 @CallerSensitive
948 @ForceInline // to ensure Reflection.getCallerClass optimization
949 public void setChar(Object obj, char c)
950 throws IllegalArgumentException, IllegalAccessException
951 {
952 if (!override) {
953 Class<?> caller = Reflection.getCallerClass();
954 checkAccess(caller, obj);
955 getFieldAccessor().setChar(obj, c);
956 } else {
957 getOverrideFieldAccessor().setChar(obj, c);
958 }
959 }
960
961 /**
962 * Sets the value of a field as a {@code short} on the specified object.
963 * This method is equivalent to
964 * {@code set(obj, sObj)},
965 * where {@code sObj} is a {@code Short} object and
966 * {@code sObj.shortValue() == s}.
967 *
968 * @param obj the object whose field should be modified
969 * @param s the new value for the field of {@code obj}
970 * being modified
971 *
972 * @throws IllegalAccessException if this {@code Field} object
973 * is enforcing Java language access control and the underlying
974 * field is either inaccessible or final;
975 * or if this {@code Field} object has no write access.
976 * @throws IllegalArgumentException if the specified object is not an
977 * instance of the class or interface declaring the underlying
978 * field (or a subclass or implementor thereof),
979 * or if an unwrapping conversion fails.
980 * @throws NullPointerException if the specified object is null
981 * and the field is an instance field.
982 * @throws ExceptionInInitializerError if the initialization provoked
983 * by this method fails.
984 * @see Field#set
985 */
986 @CallerSensitive
987 @ForceInline // to ensure Reflection.getCallerClass optimization
988 public void setShort(Object obj, short s)
989 throws IllegalArgumentException, IllegalAccessException
990 {
991 if (!override) {
992 Class<?> caller = Reflection.getCallerClass();
993 checkAccess(caller, obj);
994 getFieldAccessor().setShort(obj, s);
995 } else {
996 getOverrideFieldAccessor().setShort(obj, s);
997 }
998 }
999
1000 /**
1001 * Sets the value of a field as an {@code int} on the specified object.
1002 * This method is equivalent to
1003 * {@code set(obj, iObj)},
1004 * where {@code iObj} is an {@code Integer} object and
1005 * {@code iObj.intValue() == i}.
1006 *
1007 * @param obj the object whose field should be modified
1008 * @param i the new value for the field of {@code obj}
1009 * being modified
1010 *
1011 * @throws IllegalAccessException if this {@code Field} object
1012 * is enforcing Java language access control and the underlying
1013 * field is either inaccessible or final;
1014 * or if this {@code Field} object has no write access.
1015 * @throws IllegalArgumentException if the specified object is not an
1016 * instance of the class or interface declaring the underlying
1017 * field (or a subclass or implementor thereof),
1018 * or if an unwrapping conversion fails.
1019 * @throws NullPointerException if the specified object is null
1020 * and the field is an instance field.
1021 * @throws ExceptionInInitializerError if the initialization provoked
1022 * by this method fails.
1023 * @see Field#set
1024 */
1025 @CallerSensitive
1026 @ForceInline // to ensure Reflection.getCallerClass optimization
1027 public void setInt(Object obj, int i)
1028 throws IllegalArgumentException, IllegalAccessException
1029 {
1030 if (!override) {
1031 Class<?> caller = Reflection.getCallerClass();
1032 checkAccess(caller, obj);
1033 getFieldAccessor().setInt(obj, i);
1034 } else {
1035 getOverrideFieldAccessor().setInt(obj, i);
1036 }
1037 }
1038
1039 /**
1040 * Sets the value of a field as a {@code long} on the specified object.
1041 * This method is equivalent to
1042 * {@code set(obj, lObj)},
1043 * where {@code lObj} is a {@code Long} object and
1044 * {@code lObj.longValue() == l}.
1045 *
1046 * @param obj the object whose field should be modified
1047 * @param l the new value for the field of {@code obj}
1048 * being modified
1049 *
1050 * @throws IllegalAccessException if this {@code Field} object
1051 * is enforcing Java language access control and the underlying
1052 * field is either inaccessible or final;
1053 * or if this {@code Field} object has no write access.
1054 * @throws IllegalArgumentException if the specified object is not an
1055 * instance of the class or interface declaring the underlying
1056 * field (or a subclass or implementor thereof),
1057 * or if an unwrapping conversion fails.
1058 * @throws NullPointerException if the specified object is null
1059 * and the field is an instance field.
1060 * @throws ExceptionInInitializerError if the initialization provoked
1061 * by this method fails.
1062 * @see Field#set
1063 */
1064 @CallerSensitive
1065 @ForceInline // to ensure Reflection.getCallerClass optimization
1066 public void setLong(Object obj, long l)
1067 throws IllegalArgumentException, IllegalAccessException
1068 {
1069 if (!override) {
1070 Class<?> caller = Reflection.getCallerClass();
1071 checkAccess(caller, obj);
1072 getFieldAccessor().setLong(obj, l);
1073 } else {
1074 getOverrideFieldAccessor().setLong(obj, l);
1075 }
1076 }
1077
1078 /**
1079 * Sets the value of a field as a {@code float} on the specified object.
1080 * This method is equivalent to
1081 * {@code set(obj, fObj)},
1082 * where {@code fObj} is a {@code Float} object and
1083 * {@code fObj.floatValue() == f}.
1084 *
1085 * @param obj the object whose field should be modified
1086 * @param f the new value for the field of {@code obj}
1087 * being modified
1088 *
1089 * @throws IllegalAccessException if this {@code Field} object
1090 * is enforcing Java language access control and the underlying
1091 * field is either inaccessible or final;
1092 * or if this {@code Field} object has no write access.
1093 * @throws IllegalArgumentException if the specified object is not an
1094 * instance of the class or interface declaring the underlying
1095 * field (or a subclass or implementor thereof),
1096 * or if an unwrapping conversion fails.
1097 * @throws NullPointerException if the specified object is null
1098 * and the field is an instance field.
1099 * @throws ExceptionInInitializerError if the initialization provoked
1100 * by this method fails.
1101 * @see Field#set
1102 */
1103 @CallerSensitive
1104 @ForceInline // to ensure Reflection.getCallerClass optimization
1105 public void setFloat(Object obj, float f)
1106 throws IllegalArgumentException, IllegalAccessException
1107 {
1108 if (!override) {
1109 Class<?> caller = Reflection.getCallerClass();
1110 checkAccess(caller, obj);
1111 getFieldAccessor().setFloat(obj, f);
1112 } else {
1113 getOverrideFieldAccessor().setFloat(obj, f);
1114 }
1115 }
1116
1117 /**
1118 * Sets the value of a field as a {@code double} on the specified object.
1119 * This method is equivalent to
1120 * {@code set(obj, dObj)},
1121 * where {@code dObj} is a {@code Double} object and
1122 * {@code dObj.doubleValue() == d}.
1123 *
1124 * @param obj the object whose field should be modified
1125 * @param d the new value for the field of {@code obj}
1126 * being modified
1127 *
1128 * @throws IllegalAccessException if this {@code Field} object
1129 * is enforcing Java language access control and the underlying
1130 * field is either inaccessible or final;
1131 * or if this {@code Field} object has no write access.
1132 * @throws IllegalArgumentException if the specified object is not an
1133 * instance of the class or interface declaring the underlying
1134 * field (or a subclass or implementor thereof),
1135 * or if an unwrapping conversion fails.
1136 * @throws NullPointerException if the specified object is null
1137 * and the field is an instance field.
1138 * @throws ExceptionInInitializerError if the initialization provoked
1139 * by this method fails.
1140 * @see Field#set
1141 */
1142 @CallerSensitive
1143 @ForceInline // to ensure Reflection.getCallerClass optimization
1144 public void setDouble(Object obj, double d)
1145 throws IllegalArgumentException, IllegalAccessException
1146 {
1147 if (!override) {
1148 Class<?> caller = Reflection.getCallerClass();
1149 checkAccess(caller, obj);
1150 getFieldAccessor().setDouble(obj, d);
1151 } else {
1152 getOverrideFieldAccessor().setDouble(obj, d);
1153 }
1154 }
1155
1156 // check access to field
1157 private void checkAccess(Class<?> caller, Object obj)
1158 throws IllegalAccessException
1159 {
1160 checkAccess(caller, clazz,
1161 Modifier.isStatic(modifiers) ? null : obj.getClass(),
1162 modifiers);
1163 }
1164
1165 // security check is done before calling this method
1166 private FieldAccessor getFieldAccessor() {
1167 FieldAccessor a = fieldAccessor;
1168 return (a != null) ? a : acquireFieldAccessor();
1169 }
1170
1171 private FieldAccessor getOverrideFieldAccessor() {
1172 FieldAccessor a = overrideFieldAccessor;
1173 return (a != null) ? a : acquireOverrideFieldAccessor();
1174 }
1175
1176 // NOTE that there is no synchronization used here. It is correct
1177 // (though not efficient) to generate more than one FieldAccessor
1178 // for a given Field. However, avoiding synchronization will
1179 // probably make the implementation more scalable.
1180 private FieldAccessor acquireFieldAccessor() {
1181 // First check to see if one has been created yet, and take it
1182 // if so
1183 Field root = this.root;
1184 FieldAccessor tmp = root == null ? null : root.fieldAccessor;
1185 if (tmp != null) {
1186 fieldAccessor = tmp;
1187 } else {
1188 // Otherwise fabricate one and propagate it up to the root
1189 tmp = reflectionFactory.newFieldAccessor(this, false);
1190 setFieldAccessor(tmp);
1191 }
1192 return tmp;
1193 }
1194
1195 private FieldAccessor acquireOverrideFieldAccessor() {
1196 // First check to see if one has been created yet, and take it
1197 // if so
1198 Field root = this.root;
1199 FieldAccessor tmp = root == null ? null : root.overrideFieldAccessor;
1200 if (tmp != null) {
1201 overrideFieldAccessor = tmp;
1202 } else {
1203 // Otherwise fabricate one and propagate it up to the root
1204 tmp = reflectionFactory.newFieldAccessor(this, true);
1205 setOverrideFieldAccessor(tmp);
1206 }
1207 return tmp;
1208 }
1209
1210 // Sets the fieldAccessor for this Field object and
1211 // (recursively) its root
1212 private void setFieldAccessor(FieldAccessor accessor) {
1213 fieldAccessor = accessor;
1214 // Propagate up
1215 Field root = this.root;
1216 if (root != null) {
1217 root.setFieldAccessor(accessor);
1218 }
1219 }
1220
1221 // Sets the overrideFieldAccessor for this Field object and
1222 // (recursively) its root
1223 private void setOverrideFieldAccessor(FieldAccessor accessor) {
1224 overrideFieldAccessor = accessor;
1225 // Propagate up
1226 Field root = this.root;
1227 if (root != null) {
1228 root.setOverrideFieldAccessor(accessor);
1229 }
1230 }
1231
1232 @Override
1233 /* package-private */ Field getRoot() {
1234 return root;
1235 }
1236
1237 private static final int TRUST_FINAL = 0x0010;
1238 private static final int NULL_RESTRICTED = 0x0020;
1239
1240 /* package-private */ boolean isTrustedFinal() {
1241 return (flags & TRUST_FINAL) == TRUST_FINAL;
1242 }
1243
1244 /* package-private */ boolean isNullRestricted() {
1245 return (flags & NULL_RESTRICTED) == NULL_RESTRICTED;
1246 }
1247
1248 /**
1249 * {@inheritDoc}
1250 *
1251 * @throws NullPointerException {@inheritDoc}
1252 * @since 1.5
1253 */
1254 @Override
1255 public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
1256 Objects.requireNonNull(annotationClass);
1257 return annotationClass.cast(declaredAnnotations().get(annotationClass));
1258 }
1259
1260 /**
1261 * {@inheritDoc}
1262 *
1263 * @throws NullPointerException {@inheritDoc}
1264 * @since 1.8
1265 */
1266 @Override
1267 public <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass) {
1268 Objects.requireNonNull(annotationClass);
1269
1270 return AnnotationSupport.getDirectlyAndIndirectlyPresent(declaredAnnotations(), annotationClass);
1271 }
1272
1273 /**
1274 * {@inheritDoc}
1275 */
1276 @Override
1277 public Annotation[] getDeclaredAnnotations() {
1278 return AnnotationParser.toArray(declaredAnnotations());
1279 }
1280
1281 private transient volatile Map<Class<? extends Annotation>, Annotation> declaredAnnotations;
1282
1283 private Map<Class<? extends Annotation>, Annotation> declaredAnnotations() {
1284 Map<Class<? extends Annotation>, Annotation> declAnnos;
1285 if ((declAnnos = declaredAnnotations) == null) {
1286 synchronized (this) {
1287 if ((declAnnos = declaredAnnotations) == null) {
1288 Field root = this.root;
1289 if (root != null) {
1290 declAnnos = root.declaredAnnotations();
1291 } else {
1292 declAnnos = AnnotationParser.parseAnnotations(
1293 annotations,
1294 SharedSecrets.getJavaLangAccess()
1295 .getConstantPool(getDeclaringClass()),
1296 getDeclaringClass());
1297 }
1298 declaredAnnotations = declAnnos;
1299 }
1300 }
1301 }
1302 return declAnnos;
1303 }
1304
1305 private native byte[] getTypeAnnotationBytes0();
1306
1307 /**
1308 * Returns an AnnotatedType object that represents the use of a type to specify
1309 * the declared type of the field represented by this Field.
1310 * @return an object representing the declared type of the field
1311 * represented by this Field
1312 *
1313 * @since 1.8
1314 */
1315 public AnnotatedType getAnnotatedType() {
1316 return TypeAnnotationParser.buildAnnotatedType(getTypeAnnotationBytes0(),
1317 SharedSecrets.getJavaLangAccess().
1318 getConstantPool(getDeclaringClass()),
1319 this,
1320 getDeclaringClass(),
1321 getGenericType(),
1322 TypeAnnotation.TypeAnnotationTarget.FIELD);
1323 }
1324 }