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