Package 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
  Description
  `FieldUtils()`
  `FieldUtils` instances should NOT be constructed in standard programming.

- ## Method Summary

  Modifier and Type
  Method
  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(Object target, String fieldName)`
  Reads the named `public` `Field`.
  `static Object`
  `readField(Object target, String fieldName, boolean forceAccess)`
  Reads the named `Field`.
  `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`
  `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.
  `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(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`
  `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`
  `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 Details

  - ### 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 Details

  - ### 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:
      `NullPointerException` - 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:
      a list of Fields (possibly empty).
    Throws:
      `NullPointerException` - if the class is `null`
    Since:
      3.2

  - ### 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:
      `NullPointerException` - if the class is `null`
      `IllegalArgumentException` - if the field name is `null`, 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:
      `NullPointerException` - if the class is `null`
      `IllegalArgumentException` - if the field name is `null`, blank, or empty

  - ### 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:
      `NullPointerException` - if the class is `null`
      `IllegalArgumentException` - if the field name is `null`, 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

  - ### 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:
      `NullPointerException` - if the class or annotation are `null`
    Since:
      3.4

  - ### 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:
      `NullPointerException` - if the class or annotation are `null`
    Since:
      3.4

  - ### 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:
      `NullPointerException` - if `target` is `null`
      `IllegalArgumentException` - if `fieldName` is `null`, 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:
      `NullPointerException` - if `target` is `null`
      `IllegalArgumentException` - if `fieldName` is `null`, blank or empty, 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:
      `NullPointerException` - if the class is `null`, or the field could not be found
      `IllegalArgumentException` - if the field name is `null`, blank, empty, or is not `static`
      `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:
      `NullPointerException` - if the class is `null`, or the field could not be found
      `IllegalArgumentException` - if the field name is blank or empty, is not `static`
      `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:
      `NullPointerException` - 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:
      `NullPointerException` - 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:
      `NullPointerException` - if the target is `null`
      `IllegalArgumentException` - if the field name is `null`, blank, 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:
      `NullPointerException` - if `target` is `null`
      `IllegalArgumentException` - if the field name is `null`, blank, empty, or could not be found
      `IllegalAccessException` - if the named 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:
      `NullPointerException` - if the class is `null`, or the field could not be found
      `IllegalArgumentException` - if the field name is `null`, blank or empty, or is not `static`
      `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:
      `NullPointerException` - if the class is `null`, or the field could not be found
      `IllegalArgumentException` - if the field name is `null`, blank or empty, or is not `static`
      `IllegalAccessException` - if the field is not made accessible

  - ### readStaticField

    public static Object readStaticField(Field field) throws IllegalAccessException
    Reads an accessible `static` `Field`.
    Parameters:
      `field` - to read
    Returns:
      the field value
    Throws:
      `NullPointerException` - if the field is `null`
      `IllegalArgumentException` - if the field is 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:
      `NullPointerException` - if the field is `null`
      `IllegalArgumentException` - if the field is not `static`
      `IllegalAccessException` - if the field is not made accessible

  - ### removeFinalModifier

    public static void removeFinalModifier(Field field)
    Removes the final modifier from a `Field`.
    Parameters:
      `field` - to remove the final modifier
    Throws:
      `NullPointerException` - 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: https://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:
      `NullPointerException` - if the field is `null`
    Since:
      3.3

  - ### 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:
      `NullPointerException` - if `target` is `null`
      `IllegalArgumentException` - if `fieldName` is `null`, 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 `fieldName` is `null`, blank or empty, or could not be found, or `value` is not assignable
      `IllegalAccessException` - if the field is not made accessible

  - ### 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:
      `NullPointerException` - if `cls` is `null` or the field cannot be located
      `IllegalArgumentException` - if the field name is `null`, blank, empty, 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:
      `NullPointerException` - if `cls` is `null` or the field cannot be located
      `IllegalArgumentException` - if the field name is `null`, blank, empty, 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:
      `NullPointerException` - if the field is `null`
      `IllegalArgumentException` - if `value` is not assignable
      `IllegalAccessException` - if the field is not accessible or is `final`

  - ### 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:
      `NullPointerException` - if the field is `null`
      `IllegalArgumentException` - if `value` is not assignable
      `IllegalAccessException` - if the field is not made accessible or is `final`

  - ### 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:
      `NullPointerException` - if `target` is `null`
      `IllegalArgumentException` - if `fieldName` is `null`, blank, 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:
      `NullPointerException` - if `target` is `null`
      `IllegalArgumentException` - if `fieldName` is `null`, blank, empty, or could not be found, or `value` is not assignable
      `IllegalAccessException` - if the field is not made accessible

  - ### 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:
      `NullPointerException` - if `target` is `null`
      `IllegalArgumentException` - if `fieldName` is `null`, 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:
      `NullPointerException` - if `cls` is `null` or the field cannot be located
      `IllegalArgumentException` - if `fieldName` is `null`, blank or empty, the field not `static`, or `value` is not assignable
      `IllegalAccessException` - if the field is not made accessible or is `final`

  - ### writeStaticField

    public static void writeStaticField(Field field, Object value) throws IllegalAccessException
    Writes a `public static` `Field`.
    Parameters:
      `field` - to write
      `value` - to set
    Throws:
      `NullPointerException` - if the field is `null`
      `IllegalArgumentException` - if the field is 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:
      `NullPointerException` - if the field is `null`
      `IllegalArgumentException` - if the field is not `static`, or `value` is not assignable
      `IllegalAccessException` - if the field is not made accessible or is `final`