org.apache.commons.lang3.reflect

Class FieldUtils

java.lang.Object

org.apache.commons.lang3.reflect.FieldUtils

public class FieldUtils
extends java.lang.Object

Utilities for working with Fields 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

Version:

$Id: FieldUtils.java 1620579 2014-08-26 11:53:51Z britter $

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
static java.lang.reflect.Field[]	getAllFields(java.lang.Class<?> cls) Gets all fields of the given class and its parents (if any).
static java.util.List<java.lang.reflect.Field>	getAllFieldsList(java.lang.Class<?> cls) Gets all fields of the given class and its parents (if any).
static java.lang.reflect.Field	getDeclaredField(java.lang.Class<?> cls, java.lang.String fieldName) Gets an accessible Field by name respecting scope.
static java.lang.reflect.Field	getDeclaredField(java.lang.Class<?> cls, java.lang.String fieldName, boolean forceAccess) Gets an accessible Field by name, breaking scope if requested.
static java.lang.reflect.Field	getField(java.lang.Class<?> cls, java.lang.String fieldName) Gets an accessible Field by name respecting scope.
static java.lang.reflect.Field	getField(java.lang.Class<?> cls, java.lang.String fieldName, boolean forceAccess) Gets an accessible Field by name, breaking scope if requested.
static java.util.List<java.lang.reflect.Field>	getFieldsListWithAnnotation(java.lang.Class<?> cls, java.lang.Class<? extends java.lang.annotation.Annotation> annotationCls) Gets all fields of the given class and its parents (if any) that are annotated with the given annotation.
static java.lang.reflect.Field[]	getFieldsWithAnnotation(java.lang.Class<?> cls, java.lang.Class<? extends java.lang.annotation.Annotation> annotationCls) Gets all fields of the given class and its parents (if any) that are annotated with the given annotation.
static java.lang.Object	readDeclaredField(java.lang.Object target, java.lang.String fieldName) Reads the named public Field.
static java.lang.Object	readDeclaredField(java.lang.Object target, java.lang.String fieldName, boolean forceAccess) Gets a Field value by name.
static java.lang.Object	readDeclaredStaticField(java.lang.Class<?> cls, java.lang.String fieldName) Gets the value of a static Field by name.
static java.lang.Object	readDeclaredStaticField(java.lang.Class<?> cls, java.lang.String fieldName, boolean forceAccess) Gets the value of a static Field by name.
static java.lang.Object	readField(java.lang.reflect.Field field, java.lang.Object target) Reads an accessible Field.
static java.lang.Object	readField(java.lang.reflect.Field field, java.lang.Object target, boolean forceAccess) Reads a Field.
static java.lang.Object	readField(java.lang.Object target, java.lang.String fieldName) Reads the named public Field.
static java.lang.Object	readField(java.lang.Object target, java.lang.String fieldName, boolean forceAccess) Reads the named Field.
static java.lang.Object	readStaticField(java.lang.Class<?> cls, java.lang.String fieldName) Reads the named public static Field.
static java.lang.Object	readStaticField(java.lang.Class<?> cls, java.lang.String fieldName, boolean forceAccess) Reads the named static Field.
static java.lang.Object	readStaticField(java.lang.reflect.Field field) Reads an accessible static Field.
static java.lang.Object	readStaticField(java.lang.reflect.Field field, boolean forceAccess) Reads a static Field.
static void	removeFinalModifier(java.lang.reflect.Field field) Removes the final modifier from a Field.
static void	removeFinalModifier(java.lang.reflect.Field field, boolean forceAccess) Removes the final modifier from a Field.
static void	writeDeclaredField(java.lang.Object target, java.lang.String fieldName, java.lang.Object value) Writes a public Field.
static void	writeDeclaredField(java.lang.Object target, java.lang.String fieldName, java.lang.Object value, boolean forceAccess) Writes a public Field.
static void	writeDeclaredStaticField(java.lang.Class<?> cls, java.lang.String fieldName, java.lang.Object value) Writes a named public static Field.
static void	writeDeclaredStaticField(java.lang.Class<?> cls, java.lang.String fieldName, java.lang.Object value, boolean forceAccess) Writes a named static Field.
static void	writeField(java.lang.reflect.Field field, java.lang.Object target, java.lang.Object value) Writes an accessible Field.
static void	writeField(java.lang.reflect.Field field, java.lang.Object target, java.lang.Object value, boolean forceAccess) Writes a Field.
static void	writeField(java.lang.Object target, java.lang.String fieldName, java.lang.Object value) Writes a public Field.
static void	writeField(java.lang.Object target, java.lang.String fieldName, java.lang.Object value, boolean forceAccess) Writes a Field.
static void	writeStaticField(java.lang.Class<?> cls, java.lang.String fieldName, java.lang.Object value) Writes a named public static Field.
static void	writeStaticField(java.lang.Class<?> cls, java.lang.String fieldName, java.lang.Object value, boolean forceAccess) Writes a named static Field.
static void	writeStaticField(java.lang.reflect.Field field, java.lang.Object value) Writes a public static Field.
static void	writeStaticField(java.lang.reflect.Field field, java.lang.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 java.lang.reflect.Field getField(java.lang.Class<?> cls,
                               java.lang.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:

java.lang.IllegalArgumentException - if the class is null, or the field name is blank or empty

getField

public static java.lang.reflect.Field getField(java.lang.Class<?> cls,
                               java.lang.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:

java.lang.IllegalArgumentException - if the class is null, or the field name is blank or empty or is matched at multiple places in the inheritance hierarchy

getDeclaredField

public static java.lang.reflect.Field getDeclaredField(java.lang.Class<?> cls,
                                       java.lang.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:

java.lang.IllegalArgumentException - if the class is null, or the field name is blank or empty

getDeclaredField

public static java.lang.reflect.Field getDeclaredField(java.lang.Class<?> cls,
                                       java.lang.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:

java.lang.IllegalArgumentException - if the class is null, or the field name is blank or empty

getAllFields

public static java.lang.reflect.Field[] getAllFields(java.lang.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:

java.lang.IllegalArgumentException - if the class is null

Since:

3.2

getAllFieldsList

public static java.util.List<java.lang.reflect.Field> getAllFieldsList(java.lang.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:

java.lang.IllegalArgumentException - if the class is null

Since:

3.2

getFieldsWithAnnotation

public static java.lang.reflect.Field[] getFieldsWithAnnotation(java.lang.Class<?> cls,
                                                java.lang.Class<? extends java.lang.annotation.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:

java.lang.IllegalArgumentException - if the class or annotation are null

Since:

3.4

getFieldsListWithAnnotation

public static java.util.List<java.lang.reflect.Field> getFieldsListWithAnnotation(java.lang.Class<?> cls,
                                                                  java.lang.Class<? extends java.lang.annotation.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:

java.lang.IllegalArgumentException - if the class or annotation are null

Since:

3.4

readStaticField

public static java.lang.Object readStaticField(java.lang.reflect.Field field)
                                        throws java.lang.IllegalAccessException

Reads an accessible static Field.

Parameters:

field - to read

Returns:

the field value

Throws:

java.lang.IllegalArgumentException - if the field is null, or not static

java.lang.IllegalAccessException - if the field is not accessible

readStaticField

public static java.lang.Object readStaticField(java.lang.reflect.Field field,
                               boolean forceAccess)
                                        throws java.lang.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:

java.lang.IllegalArgumentException - if the field is null or not static

java.lang.IllegalAccessException - if the field is not made accessible

readStaticField

public static java.lang.Object readStaticField(java.lang.Class<?> cls,
                               java.lang.String fieldName)
                                        throws java.lang.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:

java.lang.IllegalArgumentException - if the class is null, or the field name is blank or empty, is not static, or could not be found

java.lang.IllegalAccessException - if the field is not accessible

readStaticField

public static java.lang.Object readStaticField(java.lang.Class<?> cls,
                               java.lang.String fieldName,
                               boolean forceAccess)
                                        throws java.lang.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:

java.lang.IllegalArgumentException - if the class is null, or the field name is blank or empty, is not static, or could not be found

java.lang.IllegalAccessException - if the field is not made accessible

readDeclaredStaticField

public static java.lang.Object readDeclaredStaticField(java.lang.Class<?> cls,
                                       java.lang.String fieldName)
                                                throws java.lang.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:

java.lang.IllegalArgumentException - if the class is null, or the field name is blank or empty, is not static, or could not be found

java.lang.IllegalAccessException - if the field is not accessible

readDeclaredStaticField

public static java.lang.Object readDeclaredStaticField(java.lang.Class<?> cls,
                                       java.lang.String fieldName,
                                       boolean forceAccess)
                                                throws java.lang.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:

java.lang.IllegalArgumentException - if the class is null, or the field name is blank or empty, is not static, or could not be found

java.lang.IllegalAccessException - if the field is not made accessible

readField

public static java.lang.Object readField(java.lang.reflect.Field field,
                         java.lang.Object target)
                                  throws java.lang.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:

java.lang.IllegalArgumentException - if the field is null

java.lang.IllegalAccessException - if the field is not accessible

readField

public static java.lang.Object readField(java.lang.reflect.Field field,
                         java.lang.Object target,
                         boolean forceAccess)
                                  throws java.lang.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:

java.lang.IllegalArgumentException - if the field is null

java.lang.IllegalAccessException - if the field is not made accessible

readField

public static java.lang.Object readField(java.lang.Object target,
                         java.lang.String fieldName)
                                  throws java.lang.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:

java.lang.IllegalArgumentException - if the class is null, or the field name is blank or empty or could not be found

java.lang.IllegalAccessException - if the named field is not public

readField

public static java.lang.Object readField(java.lang.Object target,
                         java.lang.String fieldName,
                         boolean forceAccess)
                                  throws java.lang.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:

java.lang.IllegalArgumentException - if target is null, or the field name is blank or empty or could not be found

java.lang.IllegalAccessException - if the named field is not made accessible

readDeclaredField

public static java.lang.Object readDeclaredField(java.lang.Object target,
                                 java.lang.String fieldName)
                                          throws java.lang.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:

java.lang.IllegalArgumentException - if target is null, or the field name is blank or empty or could not be found

java.lang.IllegalAccessException - if the named field is not public

readDeclaredField

public static java.lang.Object readDeclaredField(java.lang.Object target,
                                 java.lang.String fieldName,
                                 boolean forceAccess)
                                          throws java.lang.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:

java.lang.IllegalArgumentException - if target is null, or the field name is blank or empty or could not be found

java.lang.IllegalAccessException - if the field is not made accessible

writeStaticField

public static void writeStaticField(java.lang.reflect.Field field,
                    java.lang.Object value)
                             throws java.lang.IllegalAccessException

Writes a public static Field.

Parameters:

field - to write

value - to set

Throws:

java.lang.IllegalArgumentException - if the field is null or not static, or value is not assignable

java.lang.IllegalAccessException - if the field is not public or is final

writeStaticField

public static void writeStaticField(java.lang.reflect.Field field,
                    java.lang.Object value,
                    boolean forceAccess)
                             throws java.lang.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:

java.lang.IllegalArgumentException - if the field is null or not static, or value is not assignable

java.lang.IllegalAccessException - if the field is not made accessible or is final

writeStaticField

public static void writeStaticField(java.lang.Class<?> cls,
                    java.lang.String fieldName,
                    java.lang.Object value)
                             throws java.lang.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:

java.lang.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

java.lang.IllegalAccessException - if the field is not public or is final

writeStaticField

public static void writeStaticField(java.lang.Class<?> cls,
                    java.lang.String fieldName,
                    java.lang.Object value,
                    boolean forceAccess)
                             throws java.lang.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:

java.lang.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

java.lang.IllegalAccessException - if the field is not made accessible or is final

writeDeclaredStaticField

public static void writeDeclaredStaticField(java.lang.Class<?> cls,
                            java.lang.String fieldName,
                            java.lang.Object value)
                                     throws java.lang.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:

java.lang.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

java.lang.IllegalAccessException - if the field is not public or is final

writeDeclaredStaticField

public static void writeDeclaredStaticField(java.lang.Class<?> cls,
                            java.lang.String fieldName,
                            java.lang.Object value,
                            boolean forceAccess)
                                     throws java.lang.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:

java.lang.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

java.lang.IllegalAccessException - if the field is not made accessible or is final

writeField

public static void writeField(java.lang.reflect.Field field,
              java.lang.Object target,
              java.lang.Object value)
                       throws java.lang.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:

java.lang.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(java.lang.reflect.Field field,
              java.lang.Object target,
              java.lang.Object value,
              boolean forceAccess)
                       throws java.lang.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:

java.lang.IllegalArgumentException - if the field is null or value is not assignable

java.lang.IllegalAccessException - if the field is not made accessible or is final

removeFinalModifier

public static void removeFinalModifier(java.lang.reflect.Field field)

Removes the final modifier from a Field.

Parameters:

field - to remove the final modifier

Throws:

java.lang.IllegalArgumentException - if the field is null

Since:

3.2

removeFinalModifier

public static void removeFinalModifier(java.lang.reflect.Field field,
                       boolean forceAccess)

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:

java.lang.IllegalArgumentException - if the field is null

Since:

3.3

writeField

public static void writeField(java.lang.Object target,
              java.lang.String fieldName,
              java.lang.Object value)
                       throws java.lang.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:

java.lang.IllegalArgumentException - if target is null, fieldName is blank or empty or could not be found, or value is not assignable

java.lang.IllegalAccessException - if the field is not accessible

writeField

public static void writeField(java.lang.Object target,
              java.lang.String fieldName,
              java.lang.Object value,
              boolean forceAccess)
                       throws java.lang.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:

java.lang.IllegalArgumentException - if target is null, fieldName is blank or empty or could not be found, or value is not assignable

java.lang.IllegalAccessException - if the field is not made accessible

writeDeclaredField

public static void writeDeclaredField(java.lang.Object target,
                      java.lang.String fieldName,
                      java.lang.Object value)
                               throws java.lang.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:

java.lang.IllegalArgumentException - if target is null, fieldName is blank or empty or could not be found, or value is not assignable

java.lang.IllegalAccessException - if the field is not made accessible

writeDeclaredField

public static void writeDeclaredField(java.lang.Object target,
                      java.lang.String fieldName,
                      java.lang.Object value,
                      boolean forceAccess)
                               throws java.lang.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:

java.lang.IllegalArgumentException - if target is null, fieldName is blank or empty or could not be found, or value is not assignable

java.lang.IllegalAccessException - if the field is not made accessible