org.apache.commons.lang3.reflect

## Class FieldUtils

- java.lang.Object
- - org.apache.commons.lang3.reflect.FieldUtils

-     public class FieldUtils
      extends Object

  Utilities for working with `Field`s by reflection. Adapted and refactored from the dormant [reflect] Commons sandbox component.

  The ability is provided to break the scoping restrictions coded by the programmer. This can allow fields to be changed that shouldn't be. This facility should be used with care.

  Since:
    2.5

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `FieldUtils()` `FieldUtils` instances should NOT be constructed in standard programming.

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Field[]` | `getAllFields(Class<?> cls)` Gets all fields of the given class and its parents (if any).
    `static List<Field>` | `getAllFieldsList(Class<?> cls)` Gets all fields of the given class and its parents (if any).
    `static Field` | `getDeclaredField(Class<?> cls, String fieldName)` Gets an accessible `Field` by name respecting scope.
    `static Field` | `getDeclaredField(Class<?> cls, String fieldName, boolean forceAccess)` Gets an accessible `Field` by name, breaking scope if requested.
    `static Field` | `getField(Class<?> cls, String fieldName)` Gets an accessible `Field` by name respecting scope.
    `static Field` | `getField(Class<?> cls, String fieldName, boolean forceAccess)` Gets an accessible `Field` by name, breaking scope if requested.
    `static List<Field>` | `getFieldsListWithAnnotation(Class<?> cls, Class<? extends Annotation> annotationCls)` Gets all fields of the given class and its parents (if any) that are annotated with the given annotation.
    `static Field[]` | `getFieldsWithAnnotation(Class<?> cls, Class<? extends Annotation> annotationCls)` Gets all fields of the given class and its parents (if any) that are annotated with the given annotation.
    `static Object` | `readDeclaredField(Object target, String fieldName)` Reads the named `public` `Field`.
    `static Object` | `readDeclaredField(Object target, String fieldName, boolean forceAccess)` Gets a `Field` value by name.
    `static Object` | `readDeclaredStaticField(Class<?> cls, String fieldName)` Gets the value of a `static` `Field` by name.
    `static Object` | `readDeclaredStaticField(Class<?> cls, String fieldName, boolean forceAccess)` Gets the value of a `static` `Field` by name.
    `static Object` | `readField(Field field, Object target)` Reads an accessible `Field`.
    `static Object` | `readField(Field field, Object target, boolean forceAccess)` Reads a `Field`.
    `static Object` | `readField(Object target, String fieldName)` Reads the named `public` `Field`.
    `static Object` | `readField(Object target, String fieldName, boolean forceAccess)` Reads the named `Field`.
    `static Object` | `readStaticField(Class<?> cls, String fieldName)` Reads the named `public static` `Field`.
    `static Object` | `readStaticField(Class<?> cls, String fieldName, boolean forceAccess)` Reads the named `static` `Field`.
    `static Object` | `readStaticField(Field field)` Reads an accessible `static` `Field`.
    `static Object` | `readStaticField(Field field, boolean forceAccess)` Reads a static `Field`.
    `static void` | `removeFinalModifier(Field field)` Removes the final modifier from a `Field`.
    `static void` | `removeFinalModifier(Field field, boolean forceAccess)` Deprecated. As of Java 12, we can no longer drop the `final` modifier, thus rendering this method obsolete. The JDK discussion about this change can be found here: http://mail.openjdk.java.net/pipermail/core-libs-dev/2018-November/056486.html
    `static void` | `writeDeclaredField(Object target, String fieldName, Object value)` Writes a `public` `Field`.
    `static void` | `writeDeclaredField(Object target, String fieldName, Object value, boolean forceAccess)` Writes a `public` `Field`.
    `static void` | `writeDeclaredStaticField(Class<?> cls, String fieldName, Object value)` Writes a named `public static` `Field`.
    `static void` | `writeDeclaredStaticField(Class<?> cls, String fieldName, Object value, boolean forceAccess)` Writes a named `static` `Field`.
    `static void` | `writeField(Field field, Object target, Object value)` Writes an accessible `Field`.
    `static void` | `writeField(Field field, Object target, Object value, boolean forceAccess)` Writes a `Field`.
    `static void` | `writeField(Object target, String fieldName, Object value)` Writes a `public` `Field`.
    `static void` | `writeField(Object target, String fieldName, Object value, boolean forceAccess)` Writes a `Field`.
    `static void` | `writeStaticField(Class<?> cls, String fieldName, Object value)` Writes a named `public static` `Field`.
    `static void` | `writeStaticField(Class<?> cls, String fieldName, Object value, boolean forceAccess)` Writes a named `static` `Field`.
    `static void` | `writeStaticField(Field field, Object value)` Writes a `public static` `Field`.
    `static void` | `writeStaticField(Field field, Object value, boolean forceAccess)` Writes a static `Field`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### FieldUtils

          public FieldUtils()

      `FieldUtils` instances should NOT be constructed in standard programming.

      This constructor is `public` to permit tools that require a JavaBean instance to operate.

  - ### Method Detail

    - #### getField

          public static Field getField(Class<?> cls,
                                       String fieldName)

      Gets an accessible `Field` by name respecting scope. Superclasses/interfaces will be considered.
      Parameters:
        `cls` - the `Class` to reflect, must not be `null`
        `fieldName` - the field name to obtain
      Returns:
        the Field object
      Throws:
        `IllegalArgumentException` - if the class is `null`, or the field name is blank or empty

    - #### getField

          public static Field getField(Class<?> cls,
                                       String fieldName,
                                       boolean forceAccess)

      Gets an accessible `Field` by name, breaking scope if requested. Superclasses/interfaces will be considered.
      Parameters:
        `cls` - the `Class` to reflect, must not be `null`
        `fieldName` - the field name to obtain
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method. `false` will only match `public` fields.
      Returns:
        the Field object
      Throws:
        `NullPointerException` - if the class is `null`
        `IllegalArgumentException` - if the field name is blank or empty or is matched at multiple places in the inheritance hierarchy

    - #### getDeclaredField

          public static Field getDeclaredField(Class<?> cls,
                                               String fieldName)

      Gets an accessible `Field` by name respecting scope. Only the specified class will be considered.
      Parameters:
        `cls` - the `Class` to reflect, must not be `null`
        `fieldName` - the field name to obtain
      Returns:
        the Field object
      Throws:
        `IllegalArgumentException` - if the class is `null`, or the field name is blank or empty

    - #### getDeclaredField

          public static Field getDeclaredField(Class<?> cls,
                                               String fieldName,
                                               boolean forceAccess)

      Gets an accessible `Field` by name, breaking scope if requested. Only the specified class will be considered.
      Parameters:
        `cls` - the `Class` to reflect, must not be `null`
        `fieldName` - the field name to obtain
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method. `false` will only match `public` fields.
      Returns:
        the Field object
      Throws:
        `IllegalArgumentException` - if the class is `null`, or the field name is blank or empty

    - #### getAllFields

          public static Field[] getAllFields(Class<?> cls)

      Gets all fields of the given class and its parents (if any).
      Parameters:
        `cls` - the `Class` to query
      Returns:
        an array of Fields (possibly empty).
      Throws:
        `IllegalArgumentException` - if the class is `null`
      Since:
        3.2

    - #### getAllFieldsList

          public static List<Field> getAllFieldsList(Class<?> cls)

      Gets all fields of the given class and its parents (if any).
      Parameters:
        `cls` - the `Class` to query
      Returns:
        an array of Fields (possibly empty).
      Throws:
        `IllegalArgumentException` - if the class is `null`
      Since:
        3.2

    - #### getFieldsWithAnnotation

          public static Field[] getFieldsWithAnnotation(Class<?> cls,
                                                        Class<? extends Annotation> annotationCls)

      Gets all fields of the given class and its parents (if any) that are annotated with the given annotation.
      Parameters:
        `cls` - the `Class` to query
        `annotationCls` - the `Annotation` that must be present on a field to be matched
      Returns:
        an array of Fields (possibly empty).
      Throws:
        `IllegalArgumentException` - if the class or annotation are `null`
      Since:
        3.4

    - #### getFieldsListWithAnnotation

          public static List<Field> getFieldsListWithAnnotation(Class<?> cls,
                                                                Class<? extends Annotation> annotationCls)

      Gets all fields of the given class and its parents (if any) that are annotated with the given annotation.
      Parameters:
        `cls` - the `Class` to query
        `annotationCls` - the `Annotation` that must be present on a field to be matched
      Returns:
        a list of Fields (possibly empty).
      Throws:
        `IllegalArgumentException` - if the class or annotation are `null`
      Since:
        3.4

    - #### readStaticField

          public static Object readStaticField(Field field)
                                        throws IllegalAccessException

      Reads an accessible `static` `Field`.
      Parameters:
        `field` - to read
      Returns:
        the field value
      Throws:
        `IllegalArgumentException` - if the field is `null`, or not `static`
        `IllegalAccessException` - if the field is not accessible

    - #### readStaticField

          public static Object readStaticField(Field field,
                                               boolean forceAccess)
                                        throws IllegalAccessException

      Reads a static `Field`.
      Parameters:
        `field` - to read
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method.
      Returns:
        the field value
      Throws:
        `IllegalArgumentException` - if the field is `null` or not `static`
        `IllegalAccessException` - if the field is not made accessible

    - #### readStaticField

          public static Object readStaticField(Class<?> cls,
                                               String fieldName)
                                        throws IllegalAccessException

      Reads the named `public static` `Field`. Superclasses will be considered.
      Parameters:
        `cls` - the `Class` to reflect, must not be `null`
        `fieldName` - the field name to obtain
      Returns:
        the value of the field
      Throws:
        `IllegalArgumentException` - if the class is `null`, or the field name is blank or empty, is not `static`, or could not be found
        `IllegalAccessException` - if the field is not accessible

    - #### readStaticField

          public static Object readStaticField(Class<?> cls,
                                               String fieldName,
                                               boolean forceAccess)
                                        throws IllegalAccessException

      Reads the named `static` `Field`. Superclasses will be considered.
      Parameters:
        `cls` - the `Class` to reflect, must not be `null`
        `fieldName` - the field name to obtain
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method. `false` will only match `public` fields.
      Returns:
        the Field object
      Throws:
        `IllegalArgumentException` - if the class is `null`, or the field name is blank or empty, is not `static`, or could not be found
        `IllegalAccessException` - if the field is not made accessible

    - #### readDeclaredStaticField

          public static Object readDeclaredStaticField(Class<?> cls,
                                                       String fieldName)
                                                throws IllegalAccessException

      Gets the value of a `static` `Field` by name. The field must be `public`. Only the specified class will be considered.
      Parameters:
        `cls` - the `Class` to reflect, must not be `null`
        `fieldName` - the field name to obtain
      Returns:
        the value of the field
      Throws:
        `IllegalArgumentException` - if the class is `null`, or the field name is blank or empty, is not `static`, or could not be found
        `IllegalAccessException` - if the field is not accessible

    - #### readDeclaredStaticField

          public static Object readDeclaredStaticField(Class<?> cls,
                                                       String fieldName,
                                                       boolean forceAccess)
                                                throws IllegalAccessException

      Gets the value of a `static` `Field` by name. Only the specified class will be considered.
      Parameters:
        `cls` - the `Class` to reflect, must not be `null`
        `fieldName` - the field name to obtain
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method. `false` will only match `public` fields.
      Returns:
        the Field object
      Throws:
        `IllegalArgumentException` - if the class is `null`, or the field name is blank or empty, is not `static`, or could not be found
        `IllegalAccessException` - if the field is not made accessible

    - #### readField

          public static Object readField(Field field,
                                         Object target)
                                  throws IllegalAccessException

      Reads an accessible `Field`.
      Parameters:
        `field` - the field to use
        `target` - the object to call on, may be `null` for `static` fields
      Returns:
        the field value
      Throws:
        `IllegalArgumentException` - if the field is `null`
        `IllegalAccessException` - if the field is not accessible

    - #### readField

          public static Object readField(Field field,
                                         Object target,
                                         boolean forceAccess)
                                  throws IllegalAccessException

      Reads a `Field`.
      Parameters:
        `field` - the field to use
        `target` - the object to call on, may be `null` for `static` fields
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method.
      Returns:
        the field value
      Throws:
        `IllegalArgumentException` - if the field is `null`
        `IllegalAccessException` - if the field is not made accessible

    - #### readField

          public static Object readField(Object target,
                                         String fieldName)
                                  throws IllegalAccessException

      Reads the named `public` `Field`. Superclasses will be considered.
      Parameters:
        `target` - the object to reflect, must not be `null`
        `fieldName` - the field name to obtain
      Returns:
        the value of the field
      Throws:
        `IllegalArgumentException` - if the class is `null`, or the field name is blank or empty or could not be found
        `IllegalAccessException` - if the named field is not `public`

    - #### readField

          public static Object readField(Object target,
                                         String fieldName,
                                         boolean forceAccess)
                                  throws IllegalAccessException

      Reads the named `Field`. Superclasses will be considered.
      Parameters:
        `target` - the object to reflect, must not be `null`
        `fieldName` - the field name to obtain
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method. `false` will only match `public` fields.
      Returns:
        the field value
      Throws:
        `IllegalArgumentException` - if `target` is `null`, or the field name is blank or empty or could not be found
        `IllegalAccessException` - if the named field is not made accessible

    - #### readDeclaredField

          public static Object readDeclaredField(Object target,
                                                 String fieldName)
                                          throws IllegalAccessException

      Reads the named `public` `Field`. Only the class of the specified object will be considered.
      Parameters:
        `target` - the object to reflect, must not be `null`
        `fieldName` - the field name to obtain
      Returns:
        the value of the field
      Throws:
        `IllegalArgumentException` - if `target` is `null`, or the field name is blank or empty or could not be found
        `IllegalAccessException` - if the named field is not `public`

    - #### readDeclaredField

          public static Object readDeclaredField(Object target,
                                                 String fieldName,
                                                 boolean forceAccess)
                                          throws IllegalAccessException

      Gets a `Field` value by name. Only the class of the specified object will be considered.
      Parameters:
        `target` - the object to reflect, must not be `null`
        `fieldName` - the field name to obtain
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method. `false` will only match public fields.
      Returns:
        the Field object
      Throws:
        `IllegalArgumentException` - if `target` is `null`, or the field name is blank or empty or could not be found
        `IllegalAccessException` - if the field is not made accessible

    - #### writeStaticField

          public static void writeStaticField(Field field,
                                              Object value)
                                       throws IllegalAccessException

      Writes a `public static` `Field`.
      Parameters:
        `field` - to write
        `value` - to set
      Throws:
        `IllegalArgumentException` - if the field is `null` or not `static`, or `value` is not assignable
        `IllegalAccessException` - if the field is not `public` or is `final`

    - #### writeStaticField

          public static void writeStaticField(Field field,
                                              Object value,
                                              boolean forceAccess)
                                       throws IllegalAccessException

      Writes a static `Field`.
      Parameters:
        `field` - to write
        `value` - to set
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method. `false` will only match `public` fields.
      Throws:
        `IllegalArgumentException` - if the field is `null` or not `static`, or `value` is not assignable
        `IllegalAccessException` - if the field is not made accessible or is `final`

    - #### writeStaticField

          public static void writeStaticField(Class<?> cls,
                                              String fieldName,
                                              Object value)
                                       throws IllegalAccessException

      Writes a named `public static` `Field`. Superclasses will be considered.
      Parameters:
        `cls` - `Class` on which the field is to be found
        `fieldName` - to write
        `value` - to set
      Throws:
        `IllegalArgumentException` - if `cls` is `null`, the field name is blank or empty, the field cannot be located or is not `static`, or `value` is not assignable
        `IllegalAccessException` - if the field is not `public` or is `final`

    - #### writeStaticField

          public static void writeStaticField(Class<?> cls,
                                              String fieldName,
                                              Object value,
                                              boolean forceAccess)
                                       throws IllegalAccessException

      Writes a named `static` `Field`. Superclasses will be considered.
      Parameters:
        `cls` - `Class` on which the field is to be found
        `fieldName` - to write
        `value` - to set
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method. `false` will only match `public` fields.
      Throws:
        `IllegalArgumentException` - if `cls` is `null`, the field name is blank or empty, the field cannot be located or is not `static`, or `value` is not assignable
        `IllegalAccessException` - if the field is not made accessible or is `final`

    - #### writeDeclaredStaticField

          public static void writeDeclaredStaticField(Class<?> cls,
                                                      String fieldName,
                                                      Object value)
                                               throws IllegalAccessException

      Writes a named `public static` `Field`. Only the specified class will be considered.
      Parameters:
        `cls` - `Class` on which the field is to be found
        `fieldName` - to write
        `value` - to set
      Throws:
        `IllegalArgumentException` - if `cls` is `null`, the field name is blank or empty, the field cannot be located or is not `static`, or `value` is not assignable
        `IllegalAccessException` - if the field is not `public` or is `final`

    - #### writeDeclaredStaticField

          public static void writeDeclaredStaticField(Class<?> cls,
                                                      String fieldName,
                                                      Object value,
                                                      boolean forceAccess)
                                               throws IllegalAccessException

      Writes a named `static` `Field`. Only the specified class will be considered.
      Parameters:
        `cls` - `Class` on which the field is to be found
        `fieldName` - to write
        `value` - to set
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject#setAccessible(boolean)` method. `false` will only match `public` fields.
      Throws:
        `IllegalArgumentException` - if `cls` is `null`, the field name is blank or empty, the field cannot be located or is not `static`, or `value` is not assignable
        `IllegalAccessException` - if the field is not made accessible or is `final`

    - #### writeField

          public static void writeField(Field field,
                                        Object target,
                                        Object value)
                                 throws IllegalAccessException

      Writes an accessible `Field`.
      Parameters:
        `field` - to write
        `target` - the object to call on, may be `null` for `static` fields
        `value` - to set
      Throws:
        `IllegalAccessException` - if the field or target is `null`, the field is not accessible or is `final`, or `value` is not assignable

    - #### writeField

          public static void writeField(Field field,
                                        Object target,
                                        Object value,
                                        boolean forceAccess)
                                 throws IllegalAccessException

      Writes a `Field`.
      Parameters:
        `field` - to write
        `target` - the object to call on, may be `null` for `static` fields
        `value` - to set
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method. `false` will only match `public` fields.
      Throws:
        `IllegalArgumentException` - if the field is `null` or `value` is not assignable
        `IllegalAccessException` - if the field is not made accessible or is `final`

    - #### removeFinalModifier

          public static void removeFinalModifier(Field field)

      Removes the final modifier from a `Field`.
      Parameters:
        `field` - to remove the final modifier
      Throws:
        `IllegalArgumentException` - if the field is `null`
      Since:
        3.2

    - #### removeFinalModifier

          @Deprecated
          public static void removeFinalModifier(Field field,
                                                              boolean forceAccess)

      Deprecated. As of Java 12, we can no longer drop the `final` modifier, thus rendering this method obsolete. The JDK discussion about this change can be found here: http://mail.openjdk.java.net/pipermail/core-libs-dev/2018-November/056486.html
      Removes the final modifier from a `Field`.
      Parameters:
        `field` - to remove the final modifier
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method. `false` will only match `public` fields.
      Throws:
        `IllegalArgumentException` - if the field is `null`
      Since:
        3.3

    - #### writeField

          public static void writeField(Object target,
                                        String fieldName,
                                        Object value)
                                 throws IllegalAccessException

      Writes a `public` `Field`. Superclasses will be considered.
      Parameters:
        `target` - the object to reflect, must not be `null`
        `fieldName` - the field name to obtain
        `value` - to set
      Throws:
        `IllegalArgumentException` - if `target` is `null`, `fieldName` is blank or empty or could not be found, or `value` is not assignable
        `IllegalAccessException` - if the field is not accessible

    - #### writeField

          public static void writeField(Object target,
                                        String fieldName,
                                        Object value,
                                        boolean forceAccess)
                                 throws IllegalAccessException

      Writes a `Field`. Superclasses will be considered.
      Parameters:
        `target` - the object to reflect, must not be `null`
        `fieldName` - the field name to obtain
        `value` - to set
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method. `false` will only match `public` fields.
      Throws:
        `IllegalArgumentException` - if `target` is `null`, `fieldName` is blank or empty or could not be found, or `value` is not assignable
        `IllegalAccessException` - if the field is not made accessible

    - #### writeDeclaredField

          public static void writeDeclaredField(Object target,
                                                String fieldName,
                                                Object value)
                                         throws IllegalAccessException

      Writes a `public` `Field`. Only the specified class will be considered.
      Parameters:
        `target` - the object to reflect, must not be `null`
        `fieldName` - the field name to obtain
        `value` - to set
      Throws:
        `IllegalArgumentException` - if `target` is `null`, `fieldName` is blank or empty or could not be found, or `value` is not assignable
        `IllegalAccessException` - if the field is not made accessible

    - #### writeDeclaredField

          public static void writeDeclaredField(Object target,
                                                String fieldName,
                                                Object value,
                                                boolean forceAccess)
                                         throws IllegalAccessException

      Writes a `public` `Field`. Only the specified class will be considered.
      Parameters:
        `target` - the object to reflect, must not be `null`
        `fieldName` - the field name to obtain
        `value` - to set
        `forceAccess` - whether to break scope restrictions using the `AccessibleObject.setAccessible(boolean)` method. `false` will only match `public` fields.
      Throws:
        `IllegalArgumentException` - if `target` is `null`, `fieldName` is blank or empty or could not be found, or `value` is not assignable
        `IllegalAccessException` - if the field is not made accessible

Copyright © 2001–2020 The Apache Software Foundation. All rights reserved.