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