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