View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3.reflect;
18  
19  import java.lang.annotation.Annotation;
20  import java.lang.reflect.Field;
21  import java.lang.reflect.Modifier;
22  import java.util.ArrayList;
23  import java.util.Collections;
24  import java.util.List;
25  import java.util.Objects;
26  import java.util.stream.Collectors;
27  
28  import org.apache.commons.lang3.ArrayUtils;
29  import org.apache.commons.lang3.ClassUtils;
30  import org.apache.commons.lang3.JavaVersion;
31  import org.apache.commons.lang3.StringUtils;
32  import org.apache.commons.lang3.SystemUtils;
33  import org.apache.commons.lang3.Validate;
34  
35  /**
36   * Utilities for working with {@link Field}s by reflection. Adapted and refactored from the dormant [reflect] Commons
37   * sandbox component.
38   * <p>
39   * The ability is provided to break the scoping restrictions coded by the programmer. This can allow fields to be
40   * changed that shouldn't be. This facility should be used with care.
41   * </p>
42   * @since 2.5
43   */
44  public class FieldUtils {
45  
46      /**
47       * Gets all fields of the given class and its parents (if any).
48       *
49       * @param cls
50       *            the {@link Class} to query
51       * @return an array of Fields (possibly empty).
52       * @throws NullPointerException
53       *             if the class is {@code null}
54       * @since 3.2
55       */
56      public static Field[] getAllFields(final Class<?> cls) {
57          return getAllFieldsList(cls).toArray(ArrayUtils.EMPTY_FIELD_ARRAY);
58      }
59  
60      /**
61       * Gets all fields of the given class and its parents (if any).
62       *
63       * @param cls
64       *            the {@link Class} to query
65       * @return a list of Fields (possibly empty).
66       * @throws NullPointerException
67       *             if the class is {@code null}
68       * @since 3.2
69       */
70      public static List<Field> getAllFieldsList(final Class<?> cls) {
71          Objects.requireNonNull(cls, "cls");
72          final List<Field> allFields = new ArrayList<>();
73          Class<?> currentClass = cls;
74          while (currentClass != null) {
75              final Field[] declaredFields = currentClass.getDeclaredFields();
76              Collections.addAll(allFields, declaredFields);
77              currentClass = currentClass.getSuperclass();
78          }
79          return allFields;
80      }
81  
82      /**
83       * Gets an accessible {@link Field} by name respecting scope. Only the specified class will be considered.
84       *
85       * @param cls
86       *            the {@link Class} to reflect, must not be {@code null}
87       * @param fieldName
88       *            the field name to obtain
89       * @return the Field object
90       * @throws NullPointerException
91       *             if the class is {@code null}
92       * @throws IllegalArgumentException
93       *             if the field name is {@code null}, blank, or empty
94       */
95      public static Field getDeclaredField(final Class<?> cls, final String fieldName) {
96          return getDeclaredField(cls, fieldName, false);
97      }
98  
99      /**
100      * Gets an accessible {@link Field} by name, breaking scope if requested. Only the specified class will be
101      * considered.
102      *
103      * @param cls
104      *            the {@link Class} to reflect, must not be {@code null}
105      * @param fieldName
106      *            the field name to obtain
107      * @param forceAccess
108      *            whether to break scope restrictions using the
109      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
110      *            match {@code public} fields.
111      * @return the Field object
112      * @throws NullPointerException
113      *             if the class is {@code null}
114      * @throws IllegalArgumentException
115      *             if the field name is {@code null}, blank, or empty
116      */
117     public static Field getDeclaredField(final Class<?> cls, final String fieldName, final boolean forceAccess) {
118         Objects.requireNonNull(cls, "cls");
119         Validate.isTrue(StringUtils.isNotBlank(fieldName), "The field name must not be blank/empty");
120         try {
121             // only consider the specified class by using getDeclaredField()
122             final Field field = cls.getDeclaredField(fieldName);
123             if (!MemberUtils.isAccessible(field)) {
124                 if (!forceAccess) {
125                     return null;
126                 }
127                 field.setAccessible(true);
128             }
129             return field;
130         } catch (final NoSuchFieldException ignored) {
131             // ignore
132         }
133         return null;
134     }
135 
136     /**
137      * Gets an accessible {@link Field} by name respecting scope. Superclasses/interfaces will be considered.
138      *
139      * @param cls
140      *            the {@link Class} to reflect, must not be {@code null}
141      * @param fieldName
142      *            the field name to obtain
143      * @return the Field object
144      * @throws NullPointerException
145      *             if the class is {@code null}
146      * @throws IllegalArgumentException
147      *             if the field name is {@code null}, blank, or empty
148      */
149     public static Field getField(final Class<?> cls, final String fieldName) {
150         return MemberUtils.setAccessibleWorkaround(getField(cls, fieldName, false));
151     }
152 
153     /**
154      * Gets an accessible {@link Field} by name, breaking scope if requested. Superclasses/interfaces will be
155      * considered.
156      *
157      * @param cls
158      *            the {@link Class} to reflect, must not be {@code null}
159      * @param fieldName
160      *            the field name to obtain
161      * @param forceAccess
162      *            whether to break scope restrictions using the
163      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
164      *            match {@code public} fields.
165      * @return the Field object
166      * @throws NullPointerException if the class is {@code null}
167      * @throws IllegalArgumentException if the field name is blank or empty or is matched at multiple places
168      * in the inheritance hierarchy
169      */
170     public static Field getField(final Class<?> cls, final String fieldName, final boolean forceAccess) {
171         Objects.requireNonNull(cls, "cls");
172         Validate.isTrue(StringUtils.isNotBlank(fieldName), "The field name must not be blank/empty");
173         // FIXME is this workaround still needed? lang requires Java 6
174         // Sun Java 1.3 has a bugged implementation of getField hence we write the
175         // code ourselves
176 
177         // getField() will return the Field object with the declaring class
178         // set correctly to the class that declares the field. Thus requesting the
179         // field on a subclass will return the field from the superclass.
180         //
181         // priority order for lookup:
182         // searchclass private/protected/package/public
183         // superclass protected/package/public
184         // private/different package blocks access to further superclasses
185         // implementedinterface public
186 
187         // check up the superclass hierarchy
188         for (Class<?> acls = cls; acls != null; acls = acls.getSuperclass()) {
189             try {
190                 final Field field = acls.getDeclaredField(fieldName);
191                 // getDeclaredField checks for non-public scopes as well
192                 // and it returns accurate results
193                 if (!MemberUtils.isPublic(field)) {
194                     if (!forceAccess) {
195                         continue;
196                     }
197                     field.setAccessible(true);
198                 }
199                 return field;
200             } catch (final NoSuchFieldException ignored) {
201                 // ignore
202             }
203         }
204         // check the public interface case. This must be manually searched for
205         // incase there is a public supersuperclass field hidden by a private/package
206         // superclass field.
207         Field match = null;
208         for (final Class<?> class1 : ClassUtils.getAllInterfaces(cls)) {
209             try {
210                 final Field test = class1.getField(fieldName);
211                 Validate.isTrue(match == null, "Reference to field %s is ambiguous relative to %s"
212                         + "; a matching field exists on two or more implemented interfaces.", fieldName, cls);
213                 match = test;
214             } catch (final NoSuchFieldException ignored) {
215                 // ignore
216             }
217         }
218         return match;
219     }
220 
221     /**
222      * Gets all fields of the given class and its parents (if any) that are annotated with the given annotation.
223      * @param cls
224      *            the {@link Class} to query
225      * @param annotationCls
226      *            the {@link Annotation} that must be present on a field to be matched
227      * @return a list of Fields (possibly empty).
228      * @throws NullPointerException
229      *            if the class or annotation are {@code null}
230      * @since 3.4
231      */
232     public static List<Field> getFieldsListWithAnnotation(final Class<?> cls, final Class<? extends Annotation> annotationCls) {
233         Objects.requireNonNull(annotationCls, "annotationCls");
234         return getAllFieldsList(cls).stream().filter(field -> field.getAnnotation(annotationCls) != null).collect(Collectors.toList());
235     }
236 
237     /**
238      * Gets all fields of the given class and its parents (if any) that are annotated with the given annotation.
239      * @param cls
240      *            the {@link Class} to query
241      * @param annotationCls
242      *            the {@link Annotation} that must be present on a field to be matched
243      * @return an array of Fields (possibly empty).
244      * @throws NullPointerException
245      *            if the class or annotation are {@code null}
246      * @since 3.4
247      */
248     public static Field[] getFieldsWithAnnotation(final Class<?> cls, final Class<? extends Annotation> annotationCls) {
249         return getFieldsListWithAnnotation(cls, annotationCls).toArray(ArrayUtils.EMPTY_FIELD_ARRAY);
250     }
251 
252     /**
253      * Reads the named {@code public} {@link Field}. Only the class of the specified object will be considered.
254      *
255      * @param target
256      *            the object to reflect, must not be {@code null}
257      * @param fieldName
258      *            the field name to obtain
259      * @return the value of the field
260      * @throws NullPointerException
261      *             if {@code target} is {@code null}
262      * @throws IllegalArgumentException
263      *             if {@code fieldName} is {@code null}, blank or empty, or could not be found
264      * @throws IllegalAccessException
265      *             if the named field is not {@code public}
266      */
267     public static Object readDeclaredField(final Object target, final String fieldName) throws IllegalAccessException {
268         return readDeclaredField(target, fieldName, false);
269     }
270 
271     /**
272      * Gets a {@link Field} value by name. Only the class of the specified object will be considered.
273      *
274      * @param target
275      *            the object to reflect, must not be {@code null}
276      * @param fieldName
277      *            the field name to obtain
278      * @param forceAccess
279      *            whether to break scope restrictions using the
280      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
281      *            match public fields.
282      * @return the Field object
283      * @throws NullPointerException
284      *             if {@code target} is {@code null}
285      * @throws IllegalArgumentException
286      *             if {@code fieldName} is {@code null}, blank or empty, or could not be found
287      * @throws IllegalAccessException
288      *             if the field is not made accessible
289      */
290     public static Object readDeclaredField(final Object target, final String fieldName, final boolean forceAccess) throws IllegalAccessException {
291         Objects.requireNonNull(target, "target");
292         final Class<?> cls = target.getClass();
293         final Field field = getDeclaredField(cls, fieldName, forceAccess);
294         Validate.isTrue(field != null, "Cannot locate declared field %s.%s", cls, fieldName);
295         // already forced access above, don't repeat it here:
296         return readField(field, target, false);
297     }
298 
299     /**
300      * Gets the value of a {@code static} {@link Field} by name. The field must be {@code public}. Only the specified
301      * class will be considered.
302      *
303      * @param cls
304      *            the {@link Class} to reflect, must not be {@code null}
305      * @param fieldName
306      *            the field name to obtain
307      * @return the value of the field
308      * @throws NullPointerException
309      *             if the class is {@code null}, or the field could not be found
310      * @throws IllegalArgumentException
311      *             if the field name is {@code null}, blank, empty, or is not {@code static}
312      * @throws IllegalAccessException
313      *             if the field is not accessible
314      */
315     public static Object readDeclaredStaticField(final Class<?> cls, final String fieldName) throws IllegalAccessException {
316         return readDeclaredStaticField(cls, fieldName, false);
317     }
318 
319     /**
320      * Gets the value of a {@code static} {@link Field} by name. Only the specified class will be considered.
321      *
322      * @param cls
323      *            the {@link Class} to reflect, must not be {@code null}
324      * @param fieldName
325      *            the field name to obtain
326      * @param forceAccess
327      *            whether to break scope restrictions using the
328      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
329      *            match {@code public} fields.
330      * @return the Field object
331      * @throws NullPointerException
332      *             if the class is {@code null}, or the field could not be found
333      * @throws IllegalArgumentException
334      *             if the field name is blank or empty, is not {@code static}
335      * @throws IllegalAccessException
336      *             if the field is not made accessible
337      */
338     public static Object readDeclaredStaticField(final Class<?> cls, final String fieldName, final boolean forceAccess) throws IllegalAccessException {
339         final Field field = getDeclaredField(cls, fieldName, forceAccess);
340         Validate.notNull(field, "Cannot locate declared field %s.%s", cls.getName(), fieldName);
341         // already forced access above, don't repeat it here:
342         return readStaticField(field, false);
343     }
344 
345     /**
346      * Reads an accessible {@link Field}.
347      *
348      * @param field
349      *            the field to use
350      * @param target
351      *            the object to call on, may be {@code null} for {@code static} fields
352      * @return the field value
353      * @throws NullPointerException
354      *             if the field is {@code null}
355      * @throws IllegalAccessException
356      *             if the field is not accessible
357      */
358     public static Object readField(final Field field, final Object target) throws IllegalAccessException {
359         return readField(field, target, false);
360     }
361 
362     /**
363      * Reads a {@link Field}.
364      *
365      * @param field
366      *            the field to use
367      * @param target
368      *            the object to call on, may be {@code null} for {@code static} fields
369      * @param forceAccess
370      *            whether to break scope restrictions using the
371      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method.
372      * @return the field value
373      * @throws NullPointerException
374      *             if the field is {@code null}
375      * @throws IllegalAccessException
376      *             if the field is not made accessible
377      */
378     public static Object readField(final Field field, final Object target, final boolean forceAccess) throws IllegalAccessException {
379         Objects.requireNonNull(field, "field");
380         if (forceAccess && !field.isAccessible()) {
381             field.setAccessible(true);
382         } else {
383             MemberUtils.setAccessibleWorkaround(field);
384         }
385         return field.get(target);
386     }
387 
388     /**
389      * Reads the named {@code public} {@link Field}. Superclasses will be considered.
390      *
391      * @param target
392      *            the object to reflect, must not be {@code null}
393      * @param fieldName
394      *            the field name to obtain
395      * @return the value of the field
396      * @throws NullPointerException
397      *             if the target is {@code null}
398      * @throws IllegalArgumentException
399      *             if the field name is {@code null}, blank, empty, or could not be found
400      * @throws IllegalAccessException
401      *             if the named field is not {@code public}
402      */
403     public static Object readField(final Object target, final String fieldName) throws IllegalAccessException {
404         return readField(target, fieldName, false);
405     }
406 
407     /**
408      * Reads the named {@link Field}. Superclasses will be considered.
409      *
410      * @param target
411      *            the object to reflect, must not be {@code null}
412      * @param fieldName
413      *            the field name to obtain
414      * @param forceAccess
415      *            whether to break scope restrictions using the
416      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
417      *            match {@code public} fields.
418      * @return the field value
419      * @throws NullPointerException
420      *             if {@code target} is {@code null}
421      * @throws IllegalArgumentException
422      *             if the field name is {@code null}, blank, empty, or could not be found
423      * @throws IllegalAccessException
424      *             if the named field is not made accessible
425      */
426     public static Object readField(final Object target, final String fieldName, final boolean forceAccess) throws IllegalAccessException {
427         Objects.requireNonNull(target, "target");
428         final Class<?> cls = target.getClass();
429         final Field field = getField(cls, fieldName, forceAccess);
430         Validate.isTrue(field != null, "Cannot locate field %s on %s", fieldName, cls);
431         // already forced access above, don't repeat it here:
432         return readField(field, target, false);
433     }
434 
435     /**
436      * Reads the named {@code public static} {@link Field}. Superclasses will be considered.
437      *
438      * @param cls
439      *            the {@link Class} to reflect, must not be {@code null}
440      * @param fieldName
441      *            the field name to obtain
442      * @return the value of the field
443      * @throws NullPointerException
444      *             if the class is {@code null}, or the field could not be found
445      * @throws IllegalArgumentException
446      *             if the field name is {@code null}, blank or empty, or is not {@code static}
447      * @throws IllegalAccessException
448      *             if the field is not accessible
449      */
450     public static Object readStaticField(final Class<?> cls, final String fieldName) throws IllegalAccessException {
451         return readStaticField(cls, fieldName, false);
452     }
453 
454     /**
455      * Reads the named {@code static} {@link Field}. Superclasses will be considered.
456      *
457      * @param cls
458      *            the {@link Class} to reflect, must not be {@code null}
459      * @param fieldName
460      *            the field name to obtain
461      * @param forceAccess
462      *            whether to break scope restrictions using the
463      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
464      *            match {@code public} fields.
465      * @return the Field object
466      * @throws NullPointerException
467      *             if the class is {@code null}, or the field could not be found
468      * @throws IllegalArgumentException
469      *             if the field name is {@code null}, blank or empty, or is not {@code static}
470      * @throws IllegalAccessException
471      *             if the field is not made accessible
472      */
473     public static Object readStaticField(final Class<?> cls, final String fieldName, final boolean forceAccess) throws IllegalAccessException {
474         final Field field = getField(cls, fieldName, forceAccess);
475         Validate.notNull(field, "Cannot locate field '%s' on %s", fieldName, cls);
476         // already forced access above, don't repeat it here:
477         return readStaticField(field, false);
478     }
479 
480     /**
481      * Reads an accessible {@code static} {@link Field}.
482      *
483      * @param field
484      *            to read
485      * @return the field value
486      * @throws NullPointerException
487      *             if the field is {@code null}
488      * @throws IllegalArgumentException
489      *             if the field is not {@code static}
490      * @throws IllegalAccessException
491      *             if the field is not accessible
492      */
493     public static Object readStaticField(final Field field) throws IllegalAccessException {
494         return readStaticField(field, false);
495     }
496 
497     /**
498      * Reads a static {@link Field}.
499      *
500      * @param field
501      *            to read
502      * @param forceAccess
503      *            whether to break scope restrictions using the
504      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method.
505      * @return the field value
506      * @throws NullPointerException
507      *             if the field is {@code null}
508      * @throws IllegalArgumentException
509      *             if the field is not {@code static}
510      * @throws IllegalAccessException
511      *             if the field is not made accessible
512      */
513     public static Object readStaticField(final Field field, final boolean forceAccess) throws IllegalAccessException {
514         Objects.requireNonNull(field, "field");
515         Validate.isTrue(MemberUtils.isStatic(field), "The field '%s' is not static", field.getName());
516         return readField(field, (Object) null, forceAccess);
517     }
518 
519     /**
520      * Removes the final modifier from a {@link Field}.
521      *
522      * @param field
523      *            to remove the final modifier
524      * @throws NullPointerException
525      *             if the field is {@code null}
526      * @since 3.2
527      */
528     public static void removeFinalModifier(final Field field) {
529         removeFinalModifier(field, true);
530     }
531 
532     /**
533      * Removes the final modifier from a {@link Field}.
534      *
535      * @param field
536      *            to remove the final modifier
537      * @param forceAccess
538      *            whether to break scope restrictions using the
539      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
540      *            match {@code public} fields.
541      * @throws NullPointerException
542      *             if the field is {@code null}
543      * @deprecated As of Java 12, we can no longer drop the {@code final} modifier, thus
544      *             rendering this method obsolete. The JDK discussion about this change can be found
545      *             here: https://mail.openjdk.java.net/pipermail/core-libs-dev/2018-November/056486.html
546      * @since 3.3
547      */
548     @Deprecated
549     public static void removeFinalModifier(final Field field, final boolean forceAccess) {
550         Objects.requireNonNull(field, "field");
551 
552         try {
553             if (Modifier.isFinal(field.getModifiers())) {
554                 // Do all JREs implement Field with a private ivar called "modifiers"?
555                 final Field modifiersField = Field.class.getDeclaredField("modifiers");
556                 final boolean doForceAccess = forceAccess && !modifiersField.isAccessible();
557                 if (doForceAccess) {
558                     modifiersField.setAccessible(true);
559                 }
560                 try {
561                     modifiersField.setInt(field, field.getModifiers() & ~Modifier.FINAL);
562                 } finally {
563                     if (doForceAccess) {
564                         modifiersField.setAccessible(false);
565                     }
566                 }
567             }
568         } catch (final NoSuchFieldException | IllegalAccessException e) {
569             if (SystemUtils.isJavaVersionAtLeast(JavaVersion.JAVA_12)) {
570               throw new UnsupportedOperationException(
571                   "In java 12+ final cannot be removed.",
572                   e
573               );
574             }
575             // else no exception is thrown because we can modify final.
576         }
577     }
578 
579     /**
580      * Writes a {@code public} {@link Field}. Only the specified class will be considered.
581      *
582      * @param target
583      *            the object to reflect, must not be {@code null}
584      * @param fieldName
585      *            the field name to obtain
586      * @param value
587      *            to set
588      * @throws NullPointerException
589      *             if {@code target} is {@code null}
590      * @throws IllegalArgumentException
591      *             if {@code fieldName} is {@code null}, blank or empty, or could not be found,
592      *             or {@code value} is not assignable
593      * @throws IllegalAccessException
594      *             if the field is not made accessible
595      */
596     public static void writeDeclaredField(final Object target, final String fieldName, final Object value) throws IllegalAccessException {
597         writeDeclaredField(target, fieldName, value, false);
598     }
599 
600     /**
601      * Writes a {@code public} {@link Field}. Only the specified class will be considered.
602      *
603      * @param target
604      *            the object to reflect, must not be {@code null}
605      * @param fieldName
606      *            the field name to obtain
607      * @param value
608      *            to set
609      * @param forceAccess
610      *            whether to break scope restrictions using the
611      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
612      *            match {@code public} fields.
613      * @throws IllegalArgumentException
614      *             if {@code fieldName} is {@code null}, blank or empty, or could not be found,
615      *             or {@code value} is not assignable
616      * @throws IllegalAccessException
617      *             if the field is not made accessible
618      */
619     public static void writeDeclaredField(final Object target, final String fieldName, final Object value, final boolean forceAccess)
620             throws IllegalAccessException {
621         Objects.requireNonNull(target, "target");
622         final Class<?> cls = target.getClass();
623         final Field field = getDeclaredField(cls, fieldName, forceAccess);
624         Validate.isTrue(field != null, "Cannot locate declared field %s.%s", cls.getName(), fieldName);
625         // already forced access above, don't repeat it here:
626         writeField(field, target, value, false);
627     }
628 
629     /**
630      * Writes a named {@code public static} {@link Field}. Only the specified class will be considered.
631      *
632      * @param cls
633      *            {@link Class} on which the field is to be found
634      * @param fieldName
635      *            to write
636      * @param value
637      *            to set
638      * @throws NullPointerException
639      *             if {@code cls} is {@code null} or the field cannot be located
640      * @throws IllegalArgumentException
641      *             if the field name is {@code null}, blank, empty, not {@code static}, or {@code value} is not assignable
642      * @throws IllegalAccessException
643      *             if the field is not {@code public} or is {@code final}
644      */
645     public static void writeDeclaredStaticField(final Class<?> cls, final String fieldName, final Object value) throws IllegalAccessException {
646         writeDeclaredStaticField(cls, fieldName, value, false);
647     }
648 
649     /**
650      * Writes a named {@code static} {@link Field}. Only the specified class will be considered.
651      *
652      * @param cls
653      *            {@link Class} on which the field is to be found
654      * @param fieldName
655      *            to write
656      * @param value
657      *            to set
658      * @param forceAccess
659      *            whether to break scope restrictions using the {@code AccessibleObject#setAccessible(boolean)} method.
660      *            {@code false} will only match {@code public} fields.
661      * @throws NullPointerException
662      *             if {@code cls} is {@code null} or the field cannot be located
663      * @throws IllegalArgumentException
664      *             if the field name is {@code null}, blank, empty, not {@code static}, or {@code value} is not assignable
665      * @throws IllegalAccessException
666      *             if the field is not made accessible or is {@code final}
667      */
668     public static void writeDeclaredStaticField(final Class<?> cls, final String fieldName, final Object value, final boolean forceAccess)
669             throws IllegalAccessException {
670         final Field field = getDeclaredField(cls, fieldName, forceAccess);
671         Validate.notNull(field, "Cannot locate declared field %s.%s", cls.getName(), fieldName);
672         // already forced access above, don't repeat it here:
673         writeField(field, (Object) null, value, false);
674     }
675 
676     /**
677      * Writes an accessible {@link Field}.
678      *
679      * @param field
680      *            to write
681      * @param target
682      *            the object to call on, may be {@code null} for {@code static} fields
683      * @param value
684      *            to set
685      * @throws NullPointerException
686      *             if the field is {@code null}
687      * @throws IllegalArgumentException
688      *             if {@code value} is not assignable
689      * @throws IllegalAccessException
690      *             if the field is not accessible or is {@code final}
691      */
692     public static void writeField(final Field field, final Object target, final Object value) throws IllegalAccessException {
693         writeField(field, target, value, false);
694     }
695 
696     /**
697      * Writes a {@link Field}.
698      *
699      * @param field
700      *            to write
701      * @param target
702      *            the object to call on, may be {@code null} for {@code static} fields
703      * @param value
704      *            to set
705      * @param forceAccess
706      *            whether to break scope restrictions using the
707      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
708      *            match {@code public} fields.
709      * @throws NullPointerException
710      *             if the field is {@code null}
711      * @throws IllegalArgumentException
712      *             if {@code value} is not assignable
713      * @throws IllegalAccessException
714      *             if the field is not made accessible or is {@code final}
715      */
716     public static void writeField(final Field field, final Object target, final Object value, final boolean forceAccess)
717             throws IllegalAccessException {
718         Objects.requireNonNull(field, "field");
719         if (forceAccess && !field.isAccessible()) {
720             field.setAccessible(true);
721         } else {
722             MemberUtils.setAccessibleWorkaround(field);
723         }
724         field.set(target, value);
725     }
726 
727     /**
728      * Writes a {@code public} {@link Field}. Superclasses will be considered.
729      *
730      * @param target
731      *            the object to reflect, must not be {@code null}
732      * @param fieldName
733      *            the field name to obtain
734      * @param value
735      *            to set
736      * @throws NullPointerException
737      *             if {@code target} is {@code null}
738      * @throws IllegalArgumentException
739      *             if {@code fieldName} is {@code null}, blank, empty, or could not be found,
740      *             or {@code value} is not assignable
741      * @throws IllegalAccessException
742      *             if the field is not accessible
743      */
744     public static void writeField(final Object target, final String fieldName, final Object value) throws IllegalAccessException {
745         writeField(target, fieldName, value, false);
746     }
747 
748     /**
749      * Writes a {@link Field}. Superclasses will be considered.
750      *
751      * @param target
752      *            the object to reflect, must not be {@code null}
753      * @param fieldName
754      *            the field name to obtain
755      * @param value
756      *            to set
757      * @param forceAccess
758      *            whether to break scope restrictions using the
759      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
760      *            match {@code public} fields.
761      * @throws NullPointerException
762      *             if {@code target} is {@code null}
763      * @throws IllegalArgumentException
764      *             if {@code fieldName} is {@code null}, blank, empty, or could not be found,
765      *             or {@code value} is not assignable
766      * @throws IllegalAccessException
767      *             if the field is not made accessible
768      */
769     public static void writeField(final Object target, final String fieldName, final Object value, final boolean forceAccess)
770             throws IllegalAccessException {
771         Objects.requireNonNull(target, "target");
772         final Class<?> cls = target.getClass();
773         final Field field = getField(cls, fieldName, forceAccess);
774         Validate.isTrue(field != null, "Cannot locate declared field %s.%s", cls.getName(), fieldName);
775         // already forced access above, don't repeat it here:
776         writeField(field, target, value, false);
777     }
778 
779     /**
780      * Writes a named {@code public static} {@link Field}. Superclasses will be considered.
781      *
782      * @param cls
783      *            {@link Class} on which the field is to be found
784      * @param fieldName
785      *            to write
786      * @param value
787      *            to set
788      * @throws NullPointerException
789      *             if {@code target} is {@code null}
790      * @throws IllegalArgumentException
791      *             if {@code fieldName} is {@code null}, blank or empty, the field cannot be located or is
792      *             not {@code static}, or {@code value} is not assignable
793      * @throws IllegalAccessException
794      *             if the field is not {@code public} or is {@code final}
795      */
796     public static void writeStaticField(final Class<?> cls, final String fieldName, final Object value) throws IllegalAccessException {
797         writeStaticField(cls, fieldName, value, false);
798     }
799 
800     /**
801      * Writes a named {@code static} {@link Field}. Superclasses will be considered.
802      *
803      * @param cls
804      *            {@link Class} on which the field is to be found
805      * @param fieldName
806      *            to write
807      * @param value
808      *            to set
809      * @param forceAccess
810      *            whether to break scope restrictions using the
811      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
812      *            match {@code public} fields.
813      * @throws NullPointerException
814      *             if {@code cls} is {@code null} or the field cannot be located
815      * @throws IllegalArgumentException
816      *             if {@code fieldName} is {@code null}, blank or empty, the field not {@code static}, or {@code value} is not assignable
817      * @throws IllegalAccessException
818      *             if the field is not made accessible or is {@code final}
819      */
820     public static void writeStaticField(final Class<?> cls, final String fieldName, final Object value, final boolean forceAccess)
821             throws IllegalAccessException {
822         final Field field = getField(cls, fieldName, forceAccess);
823         Validate.notNull(field, "Cannot locate field %s on %s", fieldName, cls);
824         // already forced access above, don't repeat it here:
825         writeStaticField(field, value, false);
826     }
827 
828     /**
829      * Writes a {@code public static} {@link Field}.
830      *
831      * @param field
832      *            to write
833      * @param value
834      *            to set
835      * @throws NullPointerException
836      *              if the field is {@code null}
837      * @throws IllegalArgumentException
838      *              if the field is not {@code static}, or {@code value} is not assignable
839      * @throws IllegalAccessException
840      *             if the field is not {@code public} or is {@code final}
841      */
842     public static void writeStaticField(final Field field, final Object value) throws IllegalAccessException {
843         writeStaticField(field, value, false);
844     }
845 
846     /**
847      * Writes a static {@link Field}.
848      *
849      * @param field
850      *            to write
851      * @param value
852      *            to set
853      * @param forceAccess
854      *            whether to break scope restrictions using the
855      *            {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} method. {@code false} will only
856      *            match {@code public} fields.
857      * @throws NullPointerException
858      *              if the field is {@code null}
859      * @throws IllegalArgumentException
860      *              if the field is not {@code static}, or {@code value} is not assignable
861      * @throws IllegalAccessException
862      *             if the field is not made accessible or is {@code final}
863      */
864     public static void writeStaticField(final Field field, final Object value, final boolean forceAccess) throws IllegalAccessException {
865         Objects.requireNonNull(field, "field");
866         Validate.isTrue(MemberUtils.isStatic(field), "The field %s.%s is not static", field.getDeclaringClass().getName(),
867                 field.getName());
868         writeField(field, (Object) null, value, forceAccess);
869     }
870 
871     /**
872      * {@link FieldUtils} instances should NOT be constructed in standard programming.
873      * <p>
874      * This constructor is {@code public} to permit tools that require a JavaBean instance to operate.
875      * </p>
876      *
877      * @deprecated TODO Make private in 4.0.
878      */
879     @Deprecated
880     public FieldUtils() {
881         // empty
882     }
883 }