1 /*
2 * Copyright (c) 1996, 2026, 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 java.lang.annotation.Annotation;
29 import java.net.URL;
30 import java.security.CodeSource;
31 import java.util.Map;
32 import java.util.Set;
33 import java.util.Objects;
34 import jdk.internal.access.SharedSecrets;
35 import jdk.internal.event.FinalFieldMutationEvent;
36 import jdk.internal.loader.ClassLoaders;
37 import jdk.internal.misc.VM;
38 import jdk.internal.module.ModuleBootstrap;
39 import jdk.internal.module.Modules;
40 import jdk.internal.reflect.CallerSensitive;
41 import jdk.internal.reflect.FieldAccessor;
42 import jdk.internal.reflect.Reflection;
43 import jdk.internal.vm.annotation.ForceInline;
44 import jdk.internal.vm.annotation.Stable;
45 import sun.reflect.generics.repository.FieldRepository;
46 import sun.reflect.generics.factory.CoreReflectionFactory;
47 import sun.reflect.generics.factory.GenericsFactory;
48 import sun.reflect.generics.scope.ClassScope;
49 import sun.reflect.annotation.AnnotationParser;
50 import sun.reflect.annotation.AnnotationSupport;
51 import sun.reflect.annotation.TypeAnnotation;
52 import sun.reflect.annotation.TypeAnnotationParser;
53
54 /**
55 * A {@code Field} provides information about, and dynamic access to, a
56 * single field of a class or an interface. The reflected field may
57 * be a class (static) field or an instance field.
58 *
59 * <p>A {@code Field} permits widening conversions to occur during a get or
60 * set access operation, but throws an {@code IllegalArgumentException} if a
61 * narrowing conversion would occur.
62 *
63 * @see Member
64 * @see java.lang.Class
65 * @see java.lang.Class#getFields()
66 * @see java.lang.Class#getField(String)
67 * @see java.lang.Class#getDeclaredFields()
68 * @see java.lang.Class#getDeclaredField(String)
69 *
70 * @author Kenneth Russell
71 * @author Nakul Saraiya
72 * @since 1.1
73 */
74 public final
75 class Field extends AccessibleObject implements Member {
76 private final Class<?> clazz;
77 private final int slot;
78 // This is guaranteed to be interned by the VM in the 1.4
79 // reflection implementation
80 private final String name;
81 private final Class<?> type;
82 private final int modifiers;
83 private final boolean trustedFinal;
84 // Generics and annotations support
85 private final transient String signature;
86 private final byte[] annotations;
87
88 /**
89 * Fields are mutable due to {@link AccessibleObject#setAccessible(boolean)}.
90 * Thus, we return a new copy of a root each time a field is returned.
91 * Some lazily initialized immutable states can be stored on root and shared to the copies.
92 */
93 private Field root;
94 private transient volatile FieldRepository genericInfo;
95 private @Stable FieldAccessor fieldAccessor; // access control enabled
96 private @Stable FieldAccessor overrideFieldAccessor; // access control suppressed
97 // End shared states
98
99 // Generics infrastructure
100
101 private String getGenericSignature() {return signature;}
102
103 // Accessor for factory
104 private GenericsFactory getFactory() {
105 Class<?> c = getDeclaringClass();
106 // create scope and factory
107 return CoreReflectionFactory.make(c, ClassScope.make(c));
108 }
109
110 // Accessor for generic info repository
111 private FieldRepository getGenericInfo() {
112 var genericInfo = this.genericInfo;
113 if (genericInfo == null) {
114 var root = this.root;
115 if (root != null) {
116 genericInfo = root.getGenericInfo();
117 } else {
118 genericInfo = FieldRepository.make(getGenericSignature(), getFactory());
119 }
120 this.genericInfo = genericInfo;
121 }
122 return genericInfo;
123 }
124
125 /**
126 * Package-private constructor
127 */
128 @SuppressWarnings("deprecation")
129 Field(Class<?> declaringClass,
130 String name,
131 Class<?> type,
132 int modifiers,
133 boolean trustedFinal,
134 int slot,
135 String signature,
136 byte[] annotations)
137 {
138 this.clazz = declaringClass;
139 this.name = name;
140 this.type = type;
141 this.modifiers = modifiers;
142 this.trustedFinal = trustedFinal;
143 this.slot = slot;
144 this.signature = signature;
145 this.annotations = annotations;
146 }
147
148 /**
149 * Package-private routine (exposed to java.lang.Class via
150 * ReflectAccess) which returns a copy of this Field. The copy's
151 * "root" field points to this Field.
152 */
153 Field copy() {
154 // This routine enables sharing of FieldAccessor objects
155 // among Field objects which refer to the same underlying
156 // method in the VM. (All of this contortion is only necessary
157 // because of the "accessibility" bit in AccessibleObject,
158 // which implicitly requires that new java.lang.reflect
159 // objects be fabricated for each reflective call on Class
160 // objects.)
161 if (this.root != null)
162 throw new IllegalArgumentException("Can not copy a non-root Field");
163
164 Field res = new Field(clazz, name, type, modifiers, trustedFinal, slot, signature, annotations);
165 res.root = this;
166 // Might as well eagerly propagate this if already present
167 res.fieldAccessor = fieldAccessor;
168 res.overrideFieldAccessor = overrideFieldAccessor;
169 res.genericInfo = genericInfo;
170
171 return res;
172 }
173
174 /**
175 * {@inheritDoc}
176 *
177 * <p>If this reflected object represents a non-final field, and this method is
178 * used to enable access, then both <em>{@linkplain #get(Object) read}</em>
179 * and <em>{@linkplain #set(Object, Object) write}</em> access to the field
180 * are enabled.
181 *
182 * <p>If this reflected object represents a <em>non-modifiable</em> final field
183 * then enabling access only enables read access. Any attempt to {@linkplain
184 * #set(Object, Object) set} the field value throws an {@code
185 * IllegalAccessException}. The following fields are non-modifiable:
186 * <ul>
187 * <li>static final fields declared in any class or interface</li>
188 * <li>final fields declared in a {@linkplain Class#isRecord() record}</li>
189 * <li>final fields declared in a {@linkplain Class#isHidden() hidden class}</li>
190 * </ul>
191 * <p>If this reflected object represents a non-static final field in a class that
192 * is not a record class or hidden class, then enabling access will enable read
193 * access. Whether write access is allowed or not is checked when attempting to
194 * {@linkplain #set(Object, Object) set} the field value.
195 *
196 * @throws InaccessibleObjectException {@inheritDoc}
197 */
198 @Override
199 @CallerSensitive
200 public void setAccessible(boolean flag) {
201 if (flag) checkCanSetAccessible(Reflection.getCallerClass());
202 setAccessible0(flag);
203 }
204
205 @Override
206 void checkCanSetAccessible(Class<?> caller) {
207 checkCanSetAccessible(caller, clazz);
208 }
209
210 /**
211 * Returns the {@code Class} object representing the class or interface
212 * that declares the field represented by this {@code Field} object.
213 */
214 @Override
215 public Class<?> getDeclaringClass() {
216 return clazz;
217 }
218
219 /**
220 * Returns the name of the field represented by this {@code Field} object.
221 */
222 public String getName() {
223 return name;
224 }
225
226 /**
227 * Returns the Java language modifiers for the field represented
228 * by this {@code Field} object, as an integer. The {@code Modifier} class should
229 * be used to decode the modifiers.
230 *
231 * @see Modifier
232 * @see #accessFlags()
233 * @jls 8.3 Field Declarations
234 * @jls 9.3 Field (Constant) Declarations
235 */
236 public int getModifiers() {
237 return modifiers;
238 }
239
240 /**
241 * {@return an unmodifiable set of the {@linkplain AccessFlag
242 * access flags} for this field, possibly empty}
243 * @see #getModifiers()
244 * @jvms 4.5 Fields
245 * @since 20
246 */
247 @Override
248 public Set<AccessFlag> accessFlags() {
249 return reflectionFactory.parseAccessFlags(getModifiers(), AccessFlag.Location.FIELD, getDeclaringClass());
250 }
251
252 /**
253 * Returns {@code true} if this field represents an element of
254 * an enumerated class; returns {@code false} otherwise.
255 *
256 * @return {@code true} if and only if this field represents an element of
257 * an enumerated class.
258 * @since 1.5
259 * @jls 8.9.1 Enum Constants
260 */
261 public boolean isEnumConstant() {
262 return (getModifiers() & Modifier.ENUM) != 0;
263 }
264
265 /**
266 * Returns {@code true} if this field is a synthetic
267 * field; returns {@code false} otherwise.
268 *
269 * @return true if and only if this field is a synthetic
270 * field as defined by the Java Language Specification.
271 * @since 1.5
272 * @see <a
273 * href="{@docRoot}/java.base/java/lang/reflect/package-summary.html#LanguageJvmModel">Java
274 * programming language and JVM modeling in core reflection</a>
275 */
276 public boolean isSynthetic() {
277 return Modifier.isSynthetic(getModifiers());
278 }
279
280 /**
281 * Returns a {@code Class} object that identifies the
282 * declared type for the field represented by this
283 * {@code Field} object.
284 *
285 * @return a {@code Class} object identifying the declared
286 * type of the field represented by this object
287 */
288 public Class<?> getType() {
289 return type;
290 }
291
292 /**
293 * Returns a {@code Type} object that represents the declared type for
294 * the field represented by this {@code Field} object.
295 *
296 * <p>If the declared type of the field is a parameterized type,
297 * the {@code Type} object returned must accurately reflect the
298 * actual type arguments used in the source code.
299 *
300 * <p>If the type of the underlying field is a type variable or a
301 * parameterized type, it is created. Otherwise, it is resolved.
302 *
303 * @return a {@code Type} object that represents the declared type for
304 * the field represented by this {@code Field} object
305 * @throws GenericSignatureFormatError if the generic field
306 * signature does not conform to the format specified in
307 * <cite>The Java Virtual Machine Specification</cite>
308 * @throws TypeNotPresentException if the generic type
309 * signature of the underlying field refers to a non-existent
310 * class or interface declaration
311 * @throws MalformedParameterizedTypeException if the generic
312 * signature of the underlying field refers to a parameterized type
313 * that cannot be instantiated for any reason
314 * @since 1.5
315 */
316 public Type getGenericType() {
317 if (getGenericSignature() != null)
318 return getGenericInfo().getGenericType();
319 else
320 return getType();
321 }
322
323
324 /**
325 * Compares this {@code Field} against the specified object. Returns
326 * true if the objects are the same. Two {@code Field} objects are the same if
327 * they were declared by the same class and have the same name
328 * and type.
329 */
330 public boolean equals(Object obj) {
331 if (obj instanceof Field other) {
332 return (getDeclaringClass() == other.getDeclaringClass())
333 && (getName() == other.getName())
334 && (getType() == other.getType());
335 }
336 return false;
337 }
338
339 /**
340 * Returns a hashcode for this {@code Field}. This is computed as the
341 * exclusive-or of the hashcodes for the underlying field's
342 * declaring class name and its name.
343 */
344 public int hashCode() {
345 return getDeclaringClass().getName().hashCode() ^ getName().hashCode();
346 }
347
348 /**
349 * Returns a string describing this {@code Field}. The format is
350 * the access modifiers for the field, if any, followed
351 * by the field type, followed by a space, followed by
352 * the fully-qualified name of the class declaring the field,
353 * followed by a period, followed by the name of the field.
354 * For example:
355 * <pre>
356 * public static final int java.lang.Thread.MIN_PRIORITY
357 * private int java.io.FileDescriptor.fd
358 * </pre>
359 *
360 * <p>The modifiers are placed in canonical order as specified by
361 * "The Java Language Specification". This is {@code public},
362 * {@code protected} or {@code private} first, and then other
363 * modifiers in the following order: {@code static}, {@code final},
364 * {@code transient}, {@code volatile}.
365 *
366 * @return a string describing this {@code Field}
367 * @jls 8.3.1 Field Modifiers
368 */
369 public String toString() {
370 return modifierPrefix()
371 + getType().getTypeName() + " "
372 + getDeclaringClass().getTypeName() + "."
373 + getName();
374 }
375
376 private String modifierPrefix() {
377 StringBuilder sb = new StringBuilder();
378 Reflection.appendAccessControlModifiers(sb, modifiers);
379 if (Modifier.isStatic(modifiers))
380 sb.append("static ");
381 if (Modifier.isFinal(modifiers))
382 sb.append("final ");
383 if (Modifier.isTransient(modifiers))
384 sb.append("transient ");
385 if (Modifier.isVolatile(modifiers))
386 sb.append("volatile ");
387 return sb.toString();
388 }
389
390 @Override
391 String toShortString() {
392 return "field " + getDeclaringClass().getTypeName() + "." + getName();
393 }
394
395 /**
396 * Returns a string describing this {@code Field}, including
397 * its generic type. The format is the access modifiers for the
398 * field, if any, followed by the generic field type, followed by
399 * a space, followed by the fully-qualified name of the class
400 * declaring the field, followed by a period, followed by the name
401 * of the field.
402 *
403 * <p>The modifiers are placed in canonical order as specified by
404 * "The Java Language Specification". This is {@code public},
405 * {@code protected} or {@code private} first, and then other
406 * modifiers in the following order: {@code static}, {@code final},
407 * {@code transient}, {@code volatile}.
408 *
409 * @return a string describing this {@code Field}, including
410 * its generic type
411 *
412 * @since 1.5
413 * @jls 8.3.1 Field Modifiers
414 */
415 public String toGenericString() {
416 Type fieldType = getGenericType();
417 return modifierPrefix()
418 + fieldType.getTypeName() + " "
419 + getDeclaringClass().getTypeName() + "."
420 + getName();
421 }
422
423 /**
424 * Returns the value of the field represented by this {@code Field}, on
425 * the specified object. The value is automatically wrapped in an
426 * object if it has a primitive type.
427 *
428 * <p>The underlying field's value is obtained as follows:
429 *
430 * <p>If the underlying field is a static field, the {@code obj} argument
431 * is ignored; it may be null.
432 *
433 * <p>Otherwise, the underlying field is an instance field. If the
434 * specified {@code obj} argument is null, the method throws a
435 * {@code NullPointerException}. If the specified object is not an
436 * instance of the class or interface declaring the underlying
437 * field, the method throws an {@code IllegalArgumentException}.
438 *
439 * <p>If this {@code Field} object is enforcing Java language access control, and
440 * the underlying field is inaccessible, the method throws an
441 * {@code IllegalAccessException}.
442 * If the underlying field is static, the class that declared the
443 * field is initialized if it has not already been initialized.
444 *
445 * <p>Otherwise, the value is retrieved from the underlying instance
446 * or static field. If the field has a primitive type, the value
447 * is wrapped in an object before being returned, otherwise it is
448 * returned as is.
449 *
450 * <p>If the field is hidden in the type of {@code obj},
451 * the field's value is obtained according to the preceding rules.
452 *
453 * @param obj object from which the represented field's value is
454 * to be extracted
455 * @return the value of the represented field in object
456 * {@code obj}; primitive values are wrapped in an appropriate
457 * object before being returned
458 *
459 * @throws IllegalAccessException if this {@code Field} object
460 * is enforcing Java language access control and the underlying
461 * field is inaccessible.
462 * @throws IllegalArgumentException if the specified object is not an
463 * instance of the class or interface declaring the underlying
464 * field (or a subclass or implementor thereof).
465 * @throws NullPointerException if the specified object is null
466 * and the field is an instance field.
467 * @throws ExceptionInInitializerError if the initialization provoked
468 * by this method fails.
469 */
470 @CallerSensitive
471 @ForceInline // to ensure Reflection.getCallerClass optimization
472 public Object get(Object obj)
473 throws IllegalArgumentException, IllegalAccessException
474 {
475 if (!override) {
476 Class<?> caller = Reflection.getCallerClass();
477 checkAccess(caller, obj);
478 return getFieldAccessor().get(obj);
479 } else {
480 return getOverrideFieldAccessor().get(obj);
481 }
482 }
483
484 /**
485 * Gets the value of a static or instance {@code boolean} field.
486 *
487 * @param obj the object to extract the {@code boolean} value
488 * from
489 * @return the value of the {@code boolean} field
490 *
491 * @throws IllegalAccessException if this {@code Field} object
492 * is enforcing Java language access control and the underlying
493 * field is inaccessible.
494 * @throws IllegalArgumentException if the specified object is not
495 * an instance of the class or interface declaring the
496 * underlying field (or a subclass or implementor
497 * thereof), or if the field value cannot be
498 * converted to the type {@code boolean} by a
499 * widening conversion.
500 * @throws NullPointerException if the specified object is null
501 * and the field is an instance field.
502 * @throws ExceptionInInitializerError if the initialization provoked
503 * by this method fails.
504 * @see Field#get
505 */
506 @CallerSensitive
507 @ForceInline // to ensure Reflection.getCallerClass optimization
508 public boolean getBoolean(Object obj)
509 throws IllegalArgumentException, IllegalAccessException
510 {
511 if (!override) {
512 Class<?> caller = Reflection.getCallerClass();
513 checkAccess(caller, obj);
514 return getFieldAccessor().getBoolean(obj);
515 } else {
516 return getOverrideFieldAccessor().getBoolean(obj);
517 }
518 }
519
520 /**
521 * Gets the value of a static or instance {@code byte} field.
522 *
523 * @param obj the object to extract the {@code byte} value
524 * from
525 * @return the value of the {@code byte} field
526 *
527 * @throws IllegalAccessException if this {@code Field} object
528 * is enforcing Java language access control and the underlying
529 * field is inaccessible.
530 * @throws IllegalArgumentException if the specified object is not
531 * an instance of the class or interface declaring the
532 * underlying field (or a subclass or implementor
533 * thereof), or if the field value cannot be
534 * converted to the type {@code byte} by a
535 * widening conversion.
536 * @throws NullPointerException if the specified object is null
537 * and the field is an instance field.
538 * @throws ExceptionInInitializerError if the initialization provoked
539 * by this method fails.
540 * @see Field#get
541 */
542 @CallerSensitive
543 @ForceInline // to ensure Reflection.getCallerClass optimization
544 public byte getByte(Object obj)
545 throws IllegalArgumentException, IllegalAccessException
546 {
547 if (!override) {
548 Class<?> caller = Reflection.getCallerClass();
549 checkAccess(caller, obj);
550 return getFieldAccessor().getByte(obj);
551 } else {
552 return getOverrideFieldAccessor().getByte(obj);
553 }
554 }
555
556 /**
557 * Gets the value of a static or instance field of type
558 * {@code char} or of another primitive type convertible to
559 * type {@code char} via a widening conversion.
560 *
561 * @param obj the object to extract the {@code char} value
562 * from
563 * @return the value of the field converted to type {@code char}
564 *
565 * @throws IllegalAccessException if this {@code Field} object
566 * is enforcing Java language access control and the underlying
567 * field is inaccessible.
568 * @throws IllegalArgumentException if the specified object is not
569 * an instance of the class or interface declaring the
570 * underlying field (or a subclass or implementor
571 * thereof), or if the field value cannot be
572 * converted to the type {@code char} by a
573 * widening conversion.
574 * @throws NullPointerException if the specified object is null
575 * and the field is an instance field.
576 * @throws ExceptionInInitializerError if the initialization provoked
577 * by this method fails.
578 * @see Field#get
579 */
580 @CallerSensitive
581 @ForceInline // to ensure Reflection.getCallerClass optimization
582 public char getChar(Object obj)
583 throws IllegalArgumentException, IllegalAccessException
584 {
585 if (!override) {
586 Class<?> caller = Reflection.getCallerClass();
587 checkAccess(caller, obj);
588 return getFieldAccessor().getChar(obj);
589 } else {
590 return getOverrideFieldAccessor().getChar(obj);
591 }
592 }
593
594 /**
595 * Gets the value of a static or instance field of type
596 * {@code short} or of another primitive type convertible to
597 * type {@code short} via a widening conversion.
598 *
599 * @param obj the object to extract the {@code short} value
600 * from
601 * @return the value of the field converted to type {@code short}
602 *
603 * @throws IllegalAccessException if this {@code Field} object
604 * is enforcing Java language access control and the underlying
605 * field is inaccessible.
606 * @throws IllegalArgumentException if the specified object is not
607 * an instance of the class or interface declaring the
608 * underlying field (or a subclass or implementor
609 * thereof), or if the field value cannot be
610 * converted to the type {@code short} by a
611 * widening conversion.
612 * @throws NullPointerException if the specified object is null
613 * and the field is an instance field.
614 * @throws ExceptionInInitializerError if the initialization provoked
615 * by this method fails.
616 * @see Field#get
617 */
618 @CallerSensitive
619 @ForceInline // to ensure Reflection.getCallerClass optimization
620 public short getShort(Object obj)
621 throws IllegalArgumentException, IllegalAccessException
622 {
623 if (!override) {
624 Class<?> caller = Reflection.getCallerClass();
625 checkAccess(caller, obj);
626 return getFieldAccessor().getShort(obj);
627 } else {
628 return getOverrideFieldAccessor().getShort(obj);
629 }
630 }
631
632 /**
633 * Gets the value of a static or instance field of type
634 * {@code int} or of another primitive type convertible to
635 * type {@code int} via a widening conversion.
636 *
637 * @param obj the object to extract the {@code int} value
638 * from
639 * @return the value of the field converted to type {@code int}
640 *
641 * @throws IllegalAccessException if this {@code Field} object
642 * is enforcing Java language access control and the underlying
643 * field is inaccessible.
644 * @throws IllegalArgumentException if the specified object is not
645 * an instance of the class or interface declaring the
646 * underlying field (or a subclass or implementor
647 * thereof), or if the field value cannot be
648 * converted to the type {@code int} by a
649 * widening conversion.
650 * @throws NullPointerException if the specified object is null
651 * and the field is an instance field.
652 * @throws ExceptionInInitializerError if the initialization provoked
653 * by this method fails.
654 * @see Field#get
655 */
656 @CallerSensitive
657 @ForceInline // to ensure Reflection.getCallerClass optimization
658 public int getInt(Object obj)
659 throws IllegalArgumentException, IllegalAccessException
660 {
661 if (!override) {
662 Class<?> caller = Reflection.getCallerClass();
663 checkAccess(caller, obj);
664 return getFieldAccessor().getInt(obj);
665 } else {
666 return getOverrideFieldAccessor().getInt(obj);
667 }
668 }
669
670 /**
671 * Gets the value of a static or instance field of type
672 * {@code long} or of another primitive type convertible to
673 * type {@code long} via a widening conversion.
674 *
675 * @param obj the object to extract the {@code long} value
676 * from
677 * @return the value of the field converted to type {@code long}
678 *
679 * @throws IllegalAccessException if this {@code Field} object
680 * is enforcing Java language access control and the underlying
681 * field is inaccessible.
682 * @throws IllegalArgumentException if the specified object is not
683 * an instance of the class or interface declaring the
684 * underlying field (or a subclass or implementor
685 * thereof), or if the field value cannot be
686 * converted to the type {@code long} by a
687 * widening conversion.
688 * @throws NullPointerException if the specified object is null
689 * and the field is an instance field.
690 * @throws ExceptionInInitializerError if the initialization provoked
691 * by this method fails.
692 * @see Field#get
693 */
694 @CallerSensitive
695 @ForceInline // to ensure Reflection.getCallerClass optimization
696 public long getLong(Object obj)
697 throws IllegalArgumentException, IllegalAccessException
698 {
699 if (!override) {
700 Class<?> caller = Reflection.getCallerClass();
701 checkAccess(caller, obj);
702 return getFieldAccessor().getLong(obj);
703 } else {
704 return getOverrideFieldAccessor().getLong(obj);
705 }
706 }
707
708 /**
709 * Gets the value of a static or instance field of type
710 * {@code float} or of another primitive type convertible to
711 * type {@code float} via a widening conversion.
712 *
713 * @param obj the object to extract the {@code float} value
714 * from
715 * @return the value of the field converted to type {@code float}
716 *
717 * @throws IllegalAccessException if this {@code Field} object
718 * is enforcing Java language access control and the underlying
719 * field is inaccessible.
720 * @throws IllegalArgumentException if the specified object is not
721 * an instance of the class or interface declaring the
722 * underlying field (or a subclass or implementor
723 * thereof), or if the field value cannot be
724 * converted to the type {@code float} by a
725 * widening conversion.
726 * @throws NullPointerException if the specified object is null
727 * and the field is an instance field.
728 * @throws ExceptionInInitializerError if the initialization provoked
729 * by this method fails.
730 * @see Field#get
731 */
732 @CallerSensitive
733 @ForceInline // to ensure Reflection.getCallerClass optimization
734 public float getFloat(Object obj)
735 throws IllegalArgumentException, IllegalAccessException
736 {
737 if (!override) {
738 Class<?> caller = Reflection.getCallerClass();
739 checkAccess(caller, obj);
740 return getFieldAccessor().getFloat(obj);
741 } else {
742 return getOverrideFieldAccessor().getFloat(obj);
743 }
744 }
745
746 /**
747 * Gets the value of a static or instance field of type
748 * {@code double} or of another primitive type convertible to
749 * type {@code double} via a widening conversion.
750 *
751 * @param obj the object to extract the {@code double} value
752 * from
753 * @return the value of the field converted to type {@code double}
754 *
755 * @throws IllegalAccessException if this {@code Field} object
756 * is enforcing Java language access control and the underlying
757 * field is inaccessible.
758 * @throws IllegalArgumentException if the specified object is not
759 * an instance of the class or interface declaring the
760 * underlying field (or a subclass or implementor
761 * thereof), or if the field value cannot be
762 * converted to the type {@code double} by a
763 * widening conversion.
764 * @throws NullPointerException if the specified object is null
765 * and the field is an instance field.
766 * @throws ExceptionInInitializerError if the initialization provoked
767 * by this method fails.
768 * @see Field#get
769 */
770 @CallerSensitive
771 @ForceInline // to ensure Reflection.getCallerClass optimization
772 public double getDouble(Object obj)
773 throws IllegalArgumentException, IllegalAccessException
774 {
775 if (!override) {
776 Class<?> caller = Reflection.getCallerClass();
777 checkAccess(caller, obj);
778 return getFieldAccessor().getDouble(obj);
779 } else {
780 return getOverrideFieldAccessor().getDouble(obj);
781 }
782 }
783
784 /**
785 * Sets the field represented by this {@code Field} object on the
786 * specified object argument to the specified new value. The new
787 * value is automatically unwrapped if the underlying field has a
788 * primitive type.
789 *
790 * <p>The operation proceeds as follows:
791 *
792 * <p>If the underlying field is static, the {@code obj} argument is
793 * ignored; it may be null.
794 *
795 * <p>Otherwise the underlying field is an instance field. If the
796 * specified object argument is null, the method throws a
797 * {@code NullPointerException}. If the specified object argument is not
798 * an instance of the class or interface declaring the underlying
799 * field, the method throws an {@code IllegalArgumentException}.
800 *
801 * <p>If this {@code Field} object is enforcing Java language access control, and
802 * the underlying field is inaccessible, the method throws an
803 * {@code IllegalAccessException}.
804 *
805 * <p>If the underlying field is final, this {@code Field} object has <em>write</em>
806 * access if and only if all of the following conditions are true, where {@code D} is
807 * the field's {@linkplain #getDeclaringClass() declaring class}:
808 *
809 * <ul>
810 * <li>{@link #setAccessible(boolean) setAccessible(true)} has succeeded for this
811 * {@code Field} object.</li>
812 * <li><a href="doc-files/MutationMethods.html">final field mutation is enabled</a>
813 * for the caller's module.</li>
814 * <li> At least one of the following conditions holds:
815 * <ol type="a">
816 * <li> {@code D} and the caller class are in the same module.</li>
817 * <li> The field is {@code public} and {@code D} is {@code public} in a package
818 * that the module containing {@code D} exports to at least the caller's module.</li>
819 * <li> {@code D} is in a package that is {@linkplain Module#isOpen(String, Module)
820 * open} to the caller's module.</li>
821 * </ol>
822 * </li>
823 * <li>{@code D} is not a {@linkplain Class#isRecord() record class}.</li>
824 * <li>{@code D} is not a {@linkplain Class#isHidden() hidden class}.</li>
825 * <li>The field is non-static.</li>
826 * </ul>
827 *
828 * <p>If any of the above conditions is not met, this method throws an
829 * {@code IllegalAccessException}.
830 *
831 * <p>These conditions are more restrictive than the conditions specified by {@link
832 * #setAccessible(boolean)} to suppress access checks. In particular, updating a
833 * module to export or open a package cannot be used to allow <em>write</em> access
834 * to final fields with the {@code set} methods defined by {@code Field}.
835 * Condition (b) is not met if the module containing {@code D} has been updated with
836 * {@linkplain Module#addExports(String, Module) addExports} to export the package to
837 * the caller's module. Condition (c) is not met if the module containing {@code D}
838 * has been updated with {@linkplain Module#addOpens(String, Module) addOpens} to open
839 * the package to the caller's module.
840 *
841 * <p>This method may be called by <a href="{@docRoot}/../specs/jni/index.html">
842 * JNI code</a> with no caller class on the stack. In that case, and when the
843 * underlying field is final, this {@code Field} object has <em>write</em> access
844 * if and only if all of the following conditions are true, where {@code D} is the
845 * field's {@linkplain #getDeclaringClass() declaring class}:
846 *
847 * <ul>
848 * <li>{@code setAccessible(true)} has succeeded for this {@code Field} object.</li>
849 * <li>final field mutation is enabled for the unnamed module.</li>
850 * <li>The field is {@code public} and {@code D} is {@code public} in a package that
851 * is {@linkplain Module#isExported(String) exported} to all modules.</li>
852 * <li>{@code D} is not a {@linkplain Class#isRecord() record class}.</li>
853 * <li>{@code D} is not a {@linkplain Class#isHidden() hidden class}.</li>
854 * <li>The field is non-static.</li>
855 * </ul>
856 *
857 * <p>If any of the above conditions is not met, this method throws an
858 * {@code IllegalAccessException}.
859 *
860 * <p> Setting a final field in this way
861 * is meaningful only during deserialization or reconstruction of
862 * instances of classes with blank final fields, before they are
863 * made available for access by other parts of a program. Use in
864 * any other context may have unpredictable effects, including cases
865 * in which other parts of a program continue to use the original
866 * value of this field.
867 *
868 * <p>If the underlying field is of a primitive type, an unwrapping
869 * conversion is attempted to convert the new value to a value of
870 * a primitive type. If this attempt fails, the method throws an
871 * {@code IllegalArgumentException}.
872 *
873 * <p>If, after possible unwrapping, the new value cannot be
874 * converted to the type of the underlying field by an identity or
875 * widening conversion, the method throws an
876 * {@code IllegalArgumentException}.
877 *
878 * <p>If the underlying field is static, the class that declared the
879 * field is initialized if it has not already been initialized.
880 *
881 * <p>The field is set to the possibly unwrapped and widened new value.
882 *
883 * <p>If the field is hidden in the type of {@code obj},
884 * the field's value is set according to the preceding rules.
885 *
886 * @param obj the object whose field should be modified
887 * @param value the new value for the field of {@code obj}
888 * being modified
889 *
890 * @throws IllegalAccessException if this {@code Field} object
891 * is enforcing Java language access control and the underlying
892 * field is inaccessible or final;
893 * or if this {@code Field} object has no write access.
894 * @throws IllegalArgumentException if the specified object is not an
895 * instance of the class or interface declaring the underlying
896 * field (or a subclass or implementor thereof),
897 * or if an unwrapping conversion fails.
898 * @throws NullPointerException if the specified object is null
899 * and the field is an instance field.
900 * @throws ExceptionInInitializerError if the initialization provoked
901 * by this method fails.
902 *
903 * @see <a href="doc-files/MutationMethods.html">Mutation methods</a>
904 */
905 @CallerSensitive
906 @ForceInline // to ensure Reflection.getCallerClass optimization
907 public void set(Object obj, Object value)
908 throws IllegalArgumentException, IllegalAccessException
909 {
910 if (!override) {
911 Class<?> caller = Reflection.getCallerClass();
912 checkAccess(caller, obj);
913 getFieldAccessor().set(obj, value);
914 return;
915 }
916
917 FieldAccessor fa = getOverrideFieldAccessor();
918 if (!Modifier.isFinal(modifiers)) {
919 fa.set(obj, value);
920 } else {
921 setFinal(Reflection.getCallerClass(), obj, () -> fa.set(obj, value));
922 }
923 }
924
925 /**
926 * Sets the value of a field as a {@code boolean} on the specified object.
927 * This method is equivalent to
928 * {@code set(obj, zObj)},
929 * where {@code zObj} is a {@code Boolean} object and
930 * {@code zObj.booleanValue() == z}.
931 *
932 * @param obj the object whose field should be modified
933 * @param z the new value for the field of {@code obj}
934 * being modified
935 *
936 * @throws IllegalAccessException if this {@code Field} object
937 * is enforcing Java language access control and the underlying
938 * field is either inaccessible or final;
939 * or if this {@code Field} object has no write access.
940 * @throws IllegalArgumentException if the specified object is not an
941 * instance of the class or interface declaring the underlying
942 * field (or a subclass or implementor thereof),
943 * or if an unwrapping conversion fails.
944 * @throws NullPointerException if the specified object is null
945 * and the field is an instance field.
946 * @throws ExceptionInInitializerError if the initialization provoked
947 * by this method fails.
948 * @see Field#set
949 */
950 @CallerSensitive
951 @ForceInline // to ensure Reflection.getCallerClass optimization
952 public void setBoolean(Object obj, boolean z)
953 throws IllegalArgumentException, IllegalAccessException
954 {
955 if (!override) {
956 Class<?> caller = Reflection.getCallerClass();
957 checkAccess(caller, obj);
958 getFieldAccessor().setBoolean(obj, z);
959 return;
960 }
961
962 FieldAccessor fa = getOverrideFieldAccessor();
963 if (!Modifier.isFinal(modifiers)) {
964 fa.setBoolean(obj, z);
965 } else {
966 setFinal(Reflection.getCallerClass(), obj, () -> fa.setBoolean(obj, z));
967 }
968 }
969
970 /**
971 * Sets the value of a field as a {@code byte} on the specified object.
972 * This method is equivalent to
973 * {@code set(obj, bObj)},
974 * where {@code bObj} is a {@code Byte} object and
975 * {@code bObj.byteValue() == b}.
976 *
977 * @param obj the object whose field should be modified
978 * @param b the new value for the field of {@code obj}
979 * being modified
980 *
981 * @throws IllegalAccessException if this {@code Field} object
982 * is enforcing Java language access control and the underlying
983 * field is either inaccessible or final;
984 * or if this {@code Field} object has no write access.
985 * @throws IllegalArgumentException if the specified object is not an
986 * instance of the class or interface declaring the underlying
987 * field (or a subclass or implementor thereof),
988 * or if an unwrapping conversion fails.
989 * @throws NullPointerException if the specified object is null
990 * and the field is an instance field.
991 * @throws ExceptionInInitializerError if the initialization provoked
992 * by this method fails.
993 * @see Field#set
994 */
995 @CallerSensitive
996 @ForceInline // to ensure Reflection.getCallerClass optimization
997 public void setByte(Object obj, byte b)
998 throws IllegalArgumentException, IllegalAccessException
999 {
1000 if (!override) {
1001 Class<?> caller = Reflection.getCallerClass();
1002 checkAccess(caller, obj);
1003 getFieldAccessor().setByte(obj, b);
1004 return;
1005 }
1006
1007 FieldAccessor fa = getOverrideFieldAccessor();
1008 if (!Modifier.isFinal(modifiers)) {
1009 fa.setByte(obj, b);
1010 } else {
1011 setFinal(Reflection.getCallerClass(), obj, () -> fa.setByte(obj, b));
1012 }
1013 }
1014
1015 /**
1016 * Sets the value of a field as a {@code char} on the specified object.
1017 * This method is equivalent to
1018 * {@code set(obj, cObj)},
1019 * where {@code cObj} is a {@code Character} object and
1020 * {@code cObj.charValue() == c}.
1021 *
1022 * @param obj the object whose field should be modified
1023 * @param c the new value for the field of {@code obj}
1024 * being modified
1025 *
1026 * @throws IllegalAccessException if this {@code Field} object
1027 * is enforcing Java language access control and the underlying
1028 * field is either inaccessible or final;
1029 * or if this {@code Field} object has no write access.
1030 * @throws IllegalArgumentException if the specified object is not an
1031 * instance of the class or interface declaring the underlying
1032 * field (or a subclass or implementor thereof),
1033 * or if an unwrapping conversion fails.
1034 * @throws NullPointerException if the specified object is null
1035 * and the field is an instance field.
1036 * @throws ExceptionInInitializerError if the initialization provoked
1037 * by this method fails.
1038 * @see Field#set
1039 */
1040 @CallerSensitive
1041 @ForceInline // to ensure Reflection.getCallerClass optimization
1042 public void setChar(Object obj, char c)
1043 throws IllegalArgumentException, IllegalAccessException
1044 {
1045 if (!override) {
1046 Class<?> caller = Reflection.getCallerClass();
1047 checkAccess(caller, obj);
1048 getFieldAccessor().setChar(obj, c);
1049 return;
1050 }
1051
1052 FieldAccessor fa = getOverrideFieldAccessor();
1053 if (!Modifier.isFinal(modifiers)) {
1054 fa.setChar(obj, c);
1055 } else {
1056 setFinal(Reflection.getCallerClass(), obj, () -> fa.setChar(obj, c));
1057 }
1058 }
1059
1060 /**
1061 * Sets the value of a field as a {@code short} on the specified object.
1062 * This method is equivalent to
1063 * {@code set(obj, sObj)},
1064 * where {@code sObj} is a {@code Short} object and
1065 * {@code sObj.shortValue() == s}.
1066 *
1067 * @param obj the object whose field should be modified
1068 * @param s the new value for the field of {@code obj}
1069 * being modified
1070 *
1071 * @throws IllegalAccessException if this {@code Field} object
1072 * is enforcing Java language access control and the underlying
1073 * field is either inaccessible or final;
1074 * or if this {@code Field} object has no write access.
1075 * @throws IllegalArgumentException if the specified object is not an
1076 * instance of the class or interface declaring the underlying
1077 * field (or a subclass or implementor thereof),
1078 * or if an unwrapping conversion fails.
1079 * @throws NullPointerException if the specified object is null
1080 * and the field is an instance field.
1081 * @throws ExceptionInInitializerError if the initialization provoked
1082 * by this method fails.
1083 * @see Field#set
1084 */
1085 @CallerSensitive
1086 @ForceInline // to ensure Reflection.getCallerClass optimization
1087 public void setShort(Object obj, short s)
1088 throws IllegalArgumentException, IllegalAccessException
1089 {
1090 if (!override) {
1091 Class<?> caller = Reflection.getCallerClass();
1092 checkAccess(caller, obj);
1093 getFieldAccessor().setShort(obj, s);
1094 return;
1095 }
1096
1097 FieldAccessor fa = getOverrideFieldAccessor();
1098 if (!Modifier.isFinal(modifiers)) {
1099 fa.setShort(obj, s);
1100 } else {
1101 setFinal(Reflection.getCallerClass(), obj, () -> fa.setShort(obj, s));
1102 }
1103 }
1104
1105 /**
1106 * Sets the value of a field as an {@code int} on the specified object.
1107 * This method is equivalent to
1108 * {@code set(obj, iObj)},
1109 * where {@code iObj} is an {@code Integer} object and
1110 * {@code iObj.intValue() == i}.
1111 *
1112 * @param obj the object whose field should be modified
1113 * @param i the new value for the field of {@code obj}
1114 * being modified
1115 *
1116 * @throws IllegalAccessException if this {@code Field} object
1117 * is enforcing Java language access control and the underlying
1118 * field is either inaccessible or final;
1119 * or if this {@code Field} object has no write access.
1120 * @throws IllegalArgumentException if the specified object is not an
1121 * instance of the class or interface declaring the underlying
1122 * field (or a subclass or implementor thereof),
1123 * or if an unwrapping conversion fails.
1124 * @throws NullPointerException if the specified object is null
1125 * and the field is an instance field.
1126 * @throws ExceptionInInitializerError if the initialization provoked
1127 * by this method fails.
1128 * @see Field#set
1129 */
1130 @CallerSensitive
1131 @ForceInline // to ensure Reflection.getCallerClass optimization
1132 public void setInt(Object obj, int i)
1133 throws IllegalArgumentException, IllegalAccessException
1134 {
1135 if (!override) {
1136 Class<?> caller = Reflection.getCallerClass();
1137 checkAccess(caller, obj);
1138 getFieldAccessor().setInt(obj, i);
1139 return;
1140 }
1141
1142 FieldAccessor fa = getOverrideFieldAccessor();
1143 if (!Modifier.isFinal(modifiers)) {
1144 fa.setInt(obj, i);
1145 } else {
1146 setFinal(Reflection.getCallerClass(), obj, () -> fa.setInt(obj, i));
1147 }
1148 }
1149
1150 /**
1151 * Sets the value of a field as a {@code long} on the specified object.
1152 * This method is equivalent to
1153 * {@code set(obj, lObj)},
1154 * where {@code lObj} is a {@code Long} object and
1155 * {@code lObj.longValue() == l}.
1156 *
1157 * @param obj the object whose field should be modified
1158 * @param l the new value for the field of {@code obj}
1159 * being modified
1160 *
1161 * @throws IllegalAccessException if this {@code Field} object
1162 * is enforcing Java language access control and the underlying
1163 * field is either inaccessible or final;
1164 * or if this {@code Field} object has no write access.
1165 * @throws IllegalArgumentException if the specified object is not an
1166 * instance of the class or interface declaring the underlying
1167 * field (or a subclass or implementor thereof),
1168 * or if an unwrapping conversion fails.
1169 * @throws NullPointerException if the specified object is null
1170 * and the field is an instance field.
1171 * @throws ExceptionInInitializerError if the initialization provoked
1172 * by this method fails.
1173 * @see Field#set
1174 */
1175 @CallerSensitive
1176 @ForceInline // to ensure Reflection.getCallerClass optimization
1177 public void setLong(Object obj, long l)
1178 throws IllegalArgumentException, IllegalAccessException
1179 {
1180 if (!override) {
1181 Class<?> caller = Reflection.getCallerClass();
1182 checkAccess(caller, obj);
1183 getFieldAccessor().setLong(obj, l);
1184 return;
1185 }
1186
1187 FieldAccessor fa = getOverrideFieldAccessor();
1188 if (!Modifier.isFinal(modifiers)) {
1189 fa.setLong(obj, l);
1190 } else {
1191 setFinal(Reflection.getCallerClass(), obj, () -> fa.setLong(obj, l));
1192 }
1193 }
1194
1195 /**
1196 * Sets the value of a field as a {@code float} on the specified object.
1197 * This method is equivalent to
1198 * {@code set(obj, fObj)},
1199 * where {@code fObj} is a {@code Float} object and
1200 * {@code fObj.floatValue() == f}.
1201 *
1202 * @param obj the object whose field should be modified
1203 * @param f the new value for the field of {@code obj}
1204 * being modified
1205 *
1206 * @throws IllegalAccessException if this {@code Field} object
1207 * is enforcing Java language access control and the underlying
1208 * field is either inaccessible or final;
1209 * or if this {@code Field} object has no write access.
1210 * @throws IllegalArgumentException if the specified object is not an
1211 * instance of the class or interface declaring the underlying
1212 * field (or a subclass or implementor thereof),
1213 * or if an unwrapping conversion fails.
1214 * @throws NullPointerException if the specified object is null
1215 * and the field is an instance field.
1216 * @throws ExceptionInInitializerError if the initialization provoked
1217 * by this method fails.
1218 * @see Field#set
1219 */
1220 @CallerSensitive
1221 @ForceInline // to ensure Reflection.getCallerClass optimization
1222 public void setFloat(Object obj, float f)
1223 throws IllegalArgumentException, IllegalAccessException
1224 {
1225 if (!override) {
1226 Class<?> caller = Reflection.getCallerClass();
1227 checkAccess(caller, obj);
1228 getFieldAccessor().setFloat(obj, f);
1229 return;
1230 }
1231
1232 FieldAccessor fa = getOverrideFieldAccessor();
1233 if (!Modifier.isFinal(modifiers)) {
1234 fa.setFloat(obj, f);
1235 } else {
1236 setFinal(Reflection.getCallerClass(), obj, () -> fa.setFloat(obj, f));
1237 }
1238 }
1239
1240 /**
1241 * Sets the value of a field as a {@code double} on the specified object.
1242 * This method is equivalent to
1243 * {@code set(obj, dObj)},
1244 * where {@code dObj} is a {@code Double} object and
1245 * {@code dObj.doubleValue() == d}.
1246 *
1247 * @param obj the object whose field should be modified
1248 * @param d the new value for the field of {@code obj}
1249 * being modified
1250 *
1251 * @throws IllegalAccessException if this {@code Field} object
1252 * is enforcing Java language access control and the underlying
1253 * field is either inaccessible or final;
1254 * or if this {@code Field} object has no write access.
1255 * @throws IllegalArgumentException if the specified object is not an
1256 * instance of the class or interface declaring the underlying
1257 * field (or a subclass or implementor thereof),
1258 * or if an unwrapping conversion fails.
1259 * @throws NullPointerException if the specified object is null
1260 * and the field is an instance field.
1261 * @throws ExceptionInInitializerError if the initialization provoked
1262 * by this method fails.
1263 * @see Field#set
1264 */
1265 @CallerSensitive
1266 @ForceInline // to ensure Reflection.getCallerClass optimization
1267 public void setDouble(Object obj, double d)
1268 throws IllegalArgumentException, IllegalAccessException
1269 {
1270 if (!override) {
1271 Class<?> caller = Reflection.getCallerClass();
1272 checkAccess(caller, obj);
1273 getFieldAccessor().setDouble(obj, d);
1274 return;
1275 }
1276
1277 FieldAccessor fa = getOverrideFieldAccessor();
1278 if (!Modifier.isFinal(modifiers)) {
1279 fa.setDouble(obj, d);
1280 } else {
1281 setFinal(Reflection.getCallerClass(), obj, () -> fa.setDouble(obj, d));
1282 }
1283 }
1284
1285 // check access to field
1286 private void checkAccess(Class<?> caller, Object obj)
1287 throws IllegalAccessException
1288 {
1289 checkAccess(caller, clazz,
1290 Modifier.isStatic(modifiers) ? null : obj.getClass(),
1291 modifiers);
1292 }
1293
1294 private FieldAccessor getFieldAccessor() {
1295 FieldAccessor a = fieldAccessor;
1296 return (a != null) ? a : acquireFieldAccessor();
1297 }
1298
1299 private FieldAccessor getOverrideFieldAccessor() {
1300 FieldAccessor a = overrideFieldAccessor;
1301 return (a != null) ? a : acquireOverrideFieldAccessor();
1302 }
1303
1304 // NOTE that there is no synchronization used here. It is correct
1305 // (though not efficient) to generate more than one FieldAccessor
1306 // for a given Field. However, avoiding synchronization will
1307 // probably make the implementation more scalable.
1308 private FieldAccessor acquireFieldAccessor() {
1309 // First check to see if one has been created yet, and take it
1310 // if so
1311 Field root = this.root;
1312 FieldAccessor tmp = root == null ? null : root.fieldAccessor;
1313 if (tmp != null) {
1314 fieldAccessor = tmp;
1315 } else {
1316 // Otherwise fabricate one and propagate it up to the root
1317 tmp = reflectionFactory.newFieldAccessor(this, false);
1318 setFieldAccessor(tmp);
1319 }
1320 return tmp;
1321 }
1322
1323 private FieldAccessor acquireOverrideFieldAccessor() {
1324 // First check to see if one has been created yet, and take it
1325 // if so
1326 Field root = this.root;
1327 FieldAccessor tmp = root == null ? null : root.overrideFieldAccessor;
1328 if (tmp != null) {
1329 overrideFieldAccessor = tmp;
1330 } else {
1331 // Otherwise fabricate one and propagate it up to the root
1332 tmp = reflectionFactory.newFieldAccessor(this, true);
1333 setOverrideFieldAccessor(tmp);
1334 }
1335 return tmp;
1336 }
1337
1338 // Sets the fieldAccessor for this Field object and
1339 // (recursively) its root
1340 private void setFieldAccessor(FieldAccessor accessor) {
1341 fieldAccessor = accessor;
1342 // Propagate up
1343 Field root = this.root;
1344 if (root != null) {
1345 root.setFieldAccessor(accessor);
1346 }
1347 }
1348
1349 // Sets the overrideFieldAccessor for this Field object and
1350 // (recursively) its root
1351 private void setOverrideFieldAccessor(FieldAccessor accessor) {
1352 overrideFieldAccessor = accessor;
1353 // Propagate up
1354 Field root = this.root;
1355 if (root != null) {
1356 root.setOverrideFieldAccessor(accessor);
1357 }
1358 }
1359
1360 @Override
1361 /* package-private */ Field getRoot() {
1362 return root;
1363 }
1364
1365 /* package-private */ boolean isTrustedFinal() {
1366 return trustedFinal;
1367 }
1368
1369 /**
1370 * {@inheritDoc}
1371 *
1372 * @throws NullPointerException {@inheritDoc}
1373 * @since 1.5
1374 */
1375 @Override
1376 public <T extends Annotation> T getAnnotation(Class<T> annotationClass) {
1377 Objects.requireNonNull(annotationClass);
1378 return annotationClass.cast(declaredAnnotations().get(annotationClass));
1379 }
1380
1381 /**
1382 * {@inheritDoc}
1383 *
1384 * @throws NullPointerException {@inheritDoc}
1385 * @since 1.8
1386 */
1387 @Override
1388 public <T extends Annotation> T[] getAnnotationsByType(Class<T> annotationClass) {
1389 Objects.requireNonNull(annotationClass);
1390
1391 return AnnotationSupport.getDirectlyAndIndirectlyPresent(declaredAnnotations(), annotationClass);
1392 }
1393
1394 /**
1395 * {@inheritDoc}
1396 */
1397 @Override
1398 public Annotation[] getDeclaredAnnotations() {
1399 return AnnotationParser.toArray(declaredAnnotations());
1400 }
1401
1402 private transient volatile Map<Class<? extends Annotation>, Annotation> declaredAnnotations;
1403
1404 private Map<Class<? extends Annotation>, Annotation> declaredAnnotations() {
1405 Map<Class<? extends Annotation>, Annotation> declAnnos;
1406 if ((declAnnos = declaredAnnotations) == null) {
1407 synchronized (this) {
1408 if ((declAnnos = declaredAnnotations) == null) {
1409 Field root = this.root;
1410 if (root != null) {
1411 declAnnos = root.declaredAnnotations();
1412 } else {
1413 declAnnos = AnnotationParser.parseAnnotations(
1414 annotations,
1415 SharedSecrets.getJavaLangAccess()
1416 .getConstantPool(getDeclaringClass()),
1417 getDeclaringClass());
1418 }
1419 declaredAnnotations = declAnnos;
1420 }
1421 }
1422 }
1423 return declAnnos;
1424 }
1425
1426 private native byte[] getTypeAnnotationBytes0();
1427
1428 /**
1429 * Returns an AnnotatedType object that represents the use of a type to specify
1430 * the declared type of the field represented by this Field.
1431 * @return an object representing the declared type of the field
1432 * represented by this Field
1433 *
1434 * @since 1.8
1435 */
1436 public AnnotatedType getAnnotatedType() {
1437 return TypeAnnotationParser.buildAnnotatedType(getTypeAnnotationBytes0(),
1438 SharedSecrets.getJavaLangAccess().
1439 getConstantPool(getDeclaringClass()),
1440 this,
1441 getDeclaringClass(),
1442 getGenericType(),
1443 TypeAnnotation.TypeAnnotationTarget.FIELD);
1444 }
1445
1446 /**
1447 * A function that sets a field to a value.
1448 */
1449 @FunctionalInterface
1450 private interface FieldSetter {
1451 void setFieldValue() throws IllegalAccessException;
1452 }
1453
1454 /**
1455 * Attempts to set a final field.
1456 */
1457 private void setFinal(Class<?> caller, Object obj, FieldSetter setter) throws IllegalAccessException {
1458 if (obj != null && isFinalInstanceInNormalClass()) {
1459 preSetFinal(caller, false);
1460 setter.setFieldValue();
1461 postSetFinal(caller, false);
1462 } else {
1463 // throws IllegalAccessException if static, or field in record or hidden class
1464 setter.setFieldValue();
1465 }
1466 }
1467
1468 /**
1469 * Return true if this field is a final instance field in a normal class (not a
1470 * record class or hidden class),
1471 */
1472 private boolean isFinalInstanceInNormalClass() {
1473 return Modifier.isFinal(modifiers)
1474 && !Modifier.isStatic(modifiers)
1475 && !clazz.isRecord()
1476 && !clazz.isHidden();
1477 }
1478
1479 /**
1480 * Check that the caller is allowed to unreflect for mutation a final instance field
1481 * in a normal class.
1482 * @throws IllegalAccessException if not allowed
1483 */
1484 void checkAllowedToUnreflectFinalSetter(Class<?> caller) throws IllegalAccessException {
1485 Objects.requireNonNull(caller);
1486 preSetFinal(caller, true);
1487 postSetFinal(caller, true);
1488 }
1489
1490 /**
1491 * Invoke before attempting to mutate, or unreflect for mutation, a final instance
1492 * field in a normal class.
1493 * @throws IllegalAccessException if not allowed
1494 */
1495 private void preSetFinal(Class<?> caller, boolean unreflect) throws IllegalAccessException {
1496 assert isFinalInstanceInNormalClass();
1497
1498 if (caller != null) {
1499 // check if declaring class in package that is open to caller, or public field
1500 // and declaring class is public in package exported to caller
1501 if (!isFinalDeeplyAccessible(caller)) {
1502 throw new IllegalAccessException(notAccessibleToCallerMessage(caller, unreflect));
1503 }
1504 } else {
1505 // no java caller, only allowed if field is public in exported package
1506 if (!Reflection.verifyPublicMemberAccess(clazz, modifiers)) {
1507 throw new IllegalAccessException(notAccessibleToNoCallerMessage(unreflect));
1508 }
1509 }
1510
1511 // check if field mutation is enabled for caller module or illegal final field
1512 // mutation is allowed
1513 var mode = ModuleBootstrap.illegalFinalFieldMutation();
1514 if (mode == ModuleBootstrap.IllegalFinalFieldMutation.DENY
1515 && !Modules.isFinalMutationEnabled(moduleToCheck(caller))) {
1516 throw new IllegalAccessException(callerNotAllowedToMutateMessage(caller, unreflect));
1517 }
1518 }
1519
1520 /**
1521 * Invoke after mutating a final instance field, or when unreflecting a final instance
1522 * field for mutation, to print a warning and record a JFR event.
1523 */
1524 private void postSetFinal(Class<?> caller, boolean unreflect) {
1525 assert isFinalInstanceInNormalClass();
1526
1527 var mode = ModuleBootstrap.illegalFinalFieldMutation();
1528 if (mode == ModuleBootstrap.IllegalFinalFieldMutation.WARN) {
1529 // first mutation prints warning
1530 Module moduleToCheck = moduleToCheck(caller);
1531 if (Modules.tryEnableFinalMutation(moduleToCheck)) {
1532 String warningMsg = finalFieldMutationWarning(caller, unreflect);
1533 String targetModule = (caller != null && moduleToCheck.isNamed())
1534 ? moduleToCheck.getName()
1535 : "ALL-UNNAMED";
1536 VM.initialErr().printf("""
1537 WARNING: %s
1538 WARNING: Use --enable-final-field-mutation=%s to avoid a warning
1539 WARNING: Mutating final fields will be blocked in a future release unless final field mutation is enabled
1540 """, warningMsg, targetModule);
1541 }
1542 } else if (mode == ModuleBootstrap.IllegalFinalFieldMutation.DEBUG) {
1543 // print warning and stack trace
1544 var sb = new StringBuilder(finalFieldMutationWarning(caller, unreflect));
1545 StackWalker.getInstance(StackWalker.Option.RETAIN_CLASS_REFERENCE)
1546 .forEach(sf -> {
1547 sb.append(System.lineSeparator()).append("\tat " + sf);
1548 });
1549 VM.initialErr().println(sb);
1550 }
1551
1552 // record JFR event
1553 FinalFieldMutationEvent.offer(getDeclaringClass(), getName());
1554 }
1555
1556 /**
1557 * Returns true if this final field is "deeply accessible" to the caller.
1558 * The field is deeply accessible if declaring class is in a package that is open
1559 * to the caller's module, or the field is public in a public class that is exported
1560 * to the caller's module.
1561 *
1562 * Updates to the module of the declaring class at runtime with {@code Module.addExports}
1563 * or {@code Module.addOpens} have no impact on the result of this method.
1564 */
1565 private boolean isFinalDeeplyAccessible(Class<?> caller) {
1566 assert isFinalInstanceInNormalClass();
1567
1568 // all fields in unnamed modules are deeply accessible
1569 Module declaringModule = clazz.getModule();
1570 if (!declaringModule.isNamed()) return true;
1571
1572 // all fields in the caller's module are deeply accessible
1573 Module callerModule = caller.getModule();
1574 if (callerModule == declaringModule) return true;
1575
1576 // public field, public class, package exported to caller's module
1577 String pn = clazz.getPackageName();
1578 if (Modifier.isPublic(modifiers)
1579 && Modifier.isPublic(clazz.getModifiers())
1580 && Modules.isStaticallyExported(declaringModule, pn, callerModule)) {
1581 return true;
1582 }
1583
1584 // package open to caller's module
1585 return Modules.isStaticallyOpened(declaringModule, pn, callerModule);
1586 }
1587
1588 /**
1589 * Returns the Module to use for access checks with the given caller.
1590 */
1591 private Module moduleToCheck(Class<?> caller) {
1592 if (caller != null) {
1593 return caller.getModule();
1594 } else {
1595 // no java caller, only allowed if field is public in exported package
1596 return ClassLoaders.appClassLoader().getUnnamedModule();
1597 }
1598 }
1599
1600 /**
1601 * Returns the warning message to print when this final field is mutated by
1602 * the given possibly-null caller.
1603 */
1604 private String finalFieldMutationWarning(Class<?> caller, boolean unreflect) {
1605 assert Modifier.isFinal(modifiers);
1606 String source;
1607 if (caller != null) {
1608 source = caller + " in " + caller.getModule();
1609 CodeSource cs = caller.getProtectionDomain().getCodeSource();
1610 if (cs != null) {
1611 URL url = cs.getLocation();
1612 if (url != null) {
1613 source += " (" + url + ")";
1614 }
1615 }
1616 } else {
1617 source = "JNI attached thread with no caller frame";
1618 }
1619 return String.format("Final field %s in %s has been %s by %s",
1620 name,
1621 clazz,
1622 (unreflect) ? "unreflected for mutation" : "mutated reflectively",
1623 source);
1624 }
1625
1626 /**
1627 * Returns the message for an IllegalAccessException when a final field cannot be
1628 * mutated because the declaring class is in a package that is not "deeply accessible"
1629 * to the caller.
1630 */
1631 private String notAccessibleToCallerMessage(Class<?> caller, boolean unreflect) {
1632 String exportsOrOpens = Modifier.isPublic(modifiers)
1633 && Modifier.isPublic(clazz.getModifiers()) ? "exports" : "opens";
1634 return String.format("%s, %s does not explicitly \"%s\" package %s to %s",
1635 cannotSetFieldMessage(caller, unreflect),
1636 clazz.getModule(),
1637 exportsOrOpens,
1638 clazz.getPackageName(),
1639 caller.getModule());
1640 }
1641
1642 /**
1643 * Returns the exception message for the IllegalAccessException when this
1644 * final field cannot be mutated because the caller module is not allowed
1645 * to mutate final fields.
1646 */
1647 private String callerNotAllowedToMutateMessage(Class<?> caller, boolean unreflect) {
1648 if (caller != null) {
1649 return String.format("%s, %s is not allowed to mutate final fields",
1650 cannotSetFieldMessage(caller, unreflect),
1651 caller.getModule());
1652 } else {
1653 return notAccessibleToNoCallerMessage(unreflect);
1654 }
1655 }
1656
1657 /**
1658 * Returns the message for an IllegalAccessException when a field is not
1659 * accessible to a JNI attached thread.
1660 */
1661 private String notAccessibleToNoCallerMessage(boolean unreflect) {
1662 return cannotSetFieldMessage("JNI attached thread with no caller frame cannot", unreflect);
1663 }
1664
1665 /**
1666 * Returns a message to indicate that the caller cannot set/unreflect this final field.
1667 */
1668 private String cannotSetFieldMessage(Class<?> caller, boolean unreflect) {
1669 return cannotSetFieldMessage(caller + " (in " + caller.getModule() + ") cannot", unreflect);
1670 }
1671
1672 /**
1673 * Returns a message to indicate that a field cannot be set/unreflected.
1674 */
1675 private String cannotSetFieldMessage(String prefix, boolean unreflect) {
1676 if (unreflect) {
1677 return prefix + " unreflect final field " + clazz.getName() + "." + name
1678 + " (in " + clazz.getModule() + ") for mutation";
1679 } else {
1680 return prefix + " set final field " + clazz.getName() + "." + name
1681 + " (in " + clazz.getModule() + ")";
1682 }
1683 }
1684 }