Java Core Reflection

The class java.lang.reflect.Field

    

    package java.lang.reflect;

    public final class Field extends Object implements Member

A Field provides information about, and access to, a single field of a class or interface. The reflected field may be a class variable (static field) or an instance variable (instance field).

Only the Java Virtual Machine may create Field objects; user code obtains Field references via the methods getField, getFields, getDeclaredField, and getDeclaredFields of class Class.

A Field permits widening conversions to occur during get or set operations, but throws an IllegalArgumentException if a narrowing conversion would occur.

Methods

getDeclaringClass

    public Class getDeclaringClass()

Returns the Class object representing the class or interface that declares the field represented by this Field object.

getName

    public String getName()

Returns the simple name of the field represented by this Field object.

getModifiers

    public int getModifiers()

Returns the Java language modifiers for the field represented by this Field object, encoded in an integer. The Modifier class should be used to decode the modifiers.

The modifier encodings are defined in The Java Virtual Machine Specification, Table 4.3.

getType

    public Class getType()

Returns a Class object that identifies the declared type for the field represented by this Field object.

equals

    public boolean equals(Object obj)

Compares this Field against the specified Object. Returns true if they are the same; false otherwise. Two Field objects are the same if they have the same declaring class and the same name.

This method overrides the equals method of class Object.

hashCode

    public int hashCode()

Returns a hashcode for this Field object. This is computed as the exclusive-or of the hashcodes for the Field's declaring class name and its simple name.

This method overrides the hashCode method of class Object.

toString

    public String toString()

Returns a String object describing this Field. The format is the Java language modifiers for the represented field, if any, followed by the field type, followed by a space, followed by the fully-qualified name of the class declaring the field, followed by a period, followed by the name of the field. For example:

public static final int java.lang.Thread.MIN_PRIORITY private int java.io.FileDescriptor.fd The modifiers are placed in canonical order as specified in The Java Language Specification. This is public, protected, or private first, and then other modifiers in the following order: static, final, transient, and volatile.

This method overrides the toString method of class Object.

get

    public Object get(Object obj) 

        throws NullPointerException, IllegalArgumentException,

            IllegalAccessException

Returns the value of the field represented by this Field, on the specified object. The value is automatically wrapped in an object if it has a primitive type.

The underlying field's value is obtained as follows:

If the underlying field is a static field, the object argument is ignored; it may be null.
Otherwise, the underlying field is an instance field. If the specified object argument is null, the method throws a NullPointerException. If the specified object is not an instance of the class or interface declaring the underlying field, the method throws an IllegalArgumentException.
If this Field object enforces Java language access control, and the underlying field is inaccessible, the method throws an IllegalAccessException.
Otherwise, the value is retrieved from the underlying instance or static field. If the field has a primitive type, the value is wrapped in an object before being returned, otherwise it is returned as is.

Primitive variants of Field.get are also provided for efficiency; these avoid the final wrapping conversion. They are described below.

getBoolean

    public boolean getBoolean(Object obj)

        throws NullPointerException, IllegalArgumentException,

            IllegalAccessException

Returns the value of the field represented by this Field object on the specified object, as a boolean. See Field.get for the detailed procedure.

If the underlying field is not of type boolean, the method throws an IllegalArgumentException.

getByte

    public byte getByte(Object obj)

        throws NullPointerException, IllegalArgumentException,

        IllegalAccessException

Returns the value of the field represented by this Field object on the specified object, as a byte. See Field.get for the detailed procedure.

If the underlying field is not of type byte, the method throws an IllegalArgumentException.

getChar

    public char getChar(Object obj)

        throws NullPointerException, IllegalArgumentException,

            IllegalAccessException

Returns the value of the field represented by this Field object on the specified object, as a char. See Field.get for the detailed procedure.

If the underlying field's value is not of type char, the method throws an IllegalArgumentException.

getShort

    public short getShort(Object obj)

        throws NullPointerException, IllegalArgumentException,

            IllegalAccessException

Returns the value of the field represented by this Field object on the specified object, as a short. See Field.get for the detailed procedure.

If the underlying field's value cannot be converted to a short by an identity or a widening conversion, the method throws an IllegalArgumentException.

getInt

    public int getInt(Object obj)

        throws NullPointerException, IllegalArgumentException,

            IllegalAccessException

Returns the value of the field represented by this Field object on the specified object, as an int. See Field.get for the detailed procedure.

If the underlying field's value cannot be converted to an int by an identity or a widening conversion, the method throws an IllegalArgumentException.

getLong

    public long getLong(Object obj)

        throws NullPointerException, IllegalArgumentException,

            IllegalAccessException

Returns the value of the field represented by this Field object on the specified object, as a long. See Field.get for the detailed procedure.

If the underlying field's value cannot be converted to a long by an identity or a widening conversion, the method throws an IllegalArgumentException.

getFloat

    public float getFloat(Object obj)

        throws NullPointerException, IllegalArgumentException,

            IllegalAccessException

Returns the value of the field represented by this Field object on the specified object, as a float. See Field.get for the detailed procedure.

If the underlying field's value cannot be converted to a float by an identity or a widening conversion, the method throws an IllegalArgumentException.

getDouble

    public double getDouble(Object obj)

        throws NullPointerException, IllegalArgumentException,

            IllegalAccessException

Returns the value of the field represented by this Field object on the specified object, as a double. See Field.get for the detailed procedure.

If the underlying field's value cannot be converted to a double by an identity or a widening conversion, the method throws an IllegalArgumentException.

set

    public void set(Object obj, Object value)

        throws NullPointerException, IllegalArgumentException,

            IllegalAccessException

Sets the field represented by this Field object on the specified object argument to the specified new value. The new value is automatically unwrapped if the underlying field has a primitive type.

The operation proceeds as follows:

If the underlying field is a static field, the object argument is ignored; it may be null.
Otherwise the underlying field is an instance field. If the specified object argument is null, the method throws a NullPointerException. If the specified object argument is not an instance of the class or interface declaring the underlying field, the method throws an IllegalArgumentException.
If this Field object enforces Java language access control, and the underlying field is inaccessible, the method throws an IllegalAccessException.
If the underlying field is a final field, the method throws an IllegalAccessException.
If the underlying field is of a primitive type, an unwrapping conversion is attempted to convert the new object value to a value of a primitive type. If the new object value is null, the conversion fails by throwing a NullPointerException. If the new object value is not an instance of a standard Java wrapper class, the conversion fails by throwing an IllegalArgumentException.
If, after possible unwrapping, the new value cannot be converted to the type of the underlying field by an identity or a widening conversion, the method throws an IllegalArgumentException.
The field is set to the possibly unwrapped and widened new value.

Primitive variants of Field.set are also provided for efficiency; these let application code avoid having to wrap the new field value. They are described below.

setBoolean

    public void setBoolean(Object obj, boolean z)

        throws NullPointerException, IllegalArgumentException,

            IllegalAccessException

Sets the value of the field represented by this Field object on the specified object argument to the specified boolean value. See Field.set for the detailed procedure.

If the underlying field is not of type boolean, the method throws an IllegalArgumentException.

setByte

    public void setByte(Object obj, byte b)

        throws NullPointerException, IllegalArgumentException,

            IllegalAccessException

Sets the value of the field represented by this Field object on the specified object argument to the specified byte value. See Field.set for the detailed procedure.