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