org.apache.commons.lang3.reflect
Class FieldUtils

java.lang.Object
  extended by org.apache.commons.lang3.reflect.FieldUtils

public class FieldUtils
extends 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 1144929 2011-07-10 18:26:16Z ggregory $

Constructor Summary
FieldUtils()
          FieldUtils instances should NOT be constructed in standard programming.
 
Method Summary
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 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 a static Field value by name.
static Object readDeclaredStaticField(Class<?> cls, String fieldName, boolean forceAccess)
          Gets a static Field value 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 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 or field name is null

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 setAccessible method. False will only match public fields.
Returns:
the Field object
Throws:
IllegalArgumentException - if the class or field name is null

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 or field name is null

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 setAccessible method. False will only match public fields.
Returns:
the Field object
Throws:
IllegalArgumentException - if the class or field name is null

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 setAccessible 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, the field name is null or if the field 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 setAccessible method. False will only match public fields.
Returns:
the Field object
Throws:
IllegalArgumentException - if the class is null, the field name is null or if the field could not be found
IllegalAccessException - if the field is not made accessible

readDeclaredStaticField

public static Object readDeclaredStaticField(Class<?> cls,
                                             String fieldName)
                                      throws IllegalAccessException
Gets a static Field value 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, the field name is null or if the field 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 a static Field value 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 setAccessible method. False will only match public fields.
Returns:
the Field object
Throws:
IllegalArgumentException - if the class is null, the field name is null or if the field 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 setAccessible 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 or field name is null
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 setAccessible method. False will only match public fields.
Returns:
the field value
Throws:
IllegalArgumentException - if the class or field name is null
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 the class or field name is null
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 setAccessible method. False will only match public fields.
Returns:
the Field object
Throws:
IllegalArgumentException - if target or fieldName is null
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
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 setAccessible method. False will only match public fields.
Throws:
IllegalArgumentException - if the field is null or not static
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 the field cannot be located or is not static
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 setAccessible method. False will only match public fields.
Throws:
IllegalArgumentException - if the field cannot be located or is not static
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 the field cannot be located or is not static
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 setAccessible method. False will only match public fields.
Throws:
IllegalArgumentException - if the field cannot be located or is not static
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:
IllegalArgumentException - if the field is null
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 setAccessible method. False will only match public fields.
Throws:
IllegalArgumentException - if the field is null
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:
IllegalArgumentException - if target or fieldName is null
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 setAccessible method. False will only match public fields.
Throws:
IllegalArgumentException - if target or fieldName is null
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 or fieldName is null
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 setAccessible method. False will only match public fields.
Throws:
IllegalArgumentException - if target or fieldName is null
IllegalAccessException - if the field is not made accessible


Copyright © 2001-2011 The Apache Software Foundation. All Rights Reserved.