Contents | Prev | Next

Overview

The Java^TM Core Reflection API provides a small, type-safe and secure API which supports introspection about the classes and objects in the current Java Virtual Machine. If permitted by security policy, the API can be used to construct new class instances and new arrays, to access and modify fields of objects and classes, to invoke methods on objects and classes, and to access and modify elements of arrays.

The reflection API consists of:

Three new classes-Field, Method, and Constructor-that reflect class and interface members and constructors; these provide reflective information about the underlying member or constructor, as well as a type-safe means to use the member or constructor to operate on Java objects,
New methods of class Class that provide for the construction of new instances of Field, Method and Constructor,
One new class-Array-that provides methods to dynamically construct and access Java arrays, and,
One new utility class-Modifier-that helps decode Java language modifier information about classes and their members.

There are also some additions to the java.lang package to support reflection:

Two new classes-Byte and Short. These are subclasses of the class Number, similar to the class Integer, whose instances serve as object wrappers for primitive values of type byte and short,
New objects, instances of the class Class, to represent the primitive Java types boolean, byte, char, short, int, long, float and double and the keyword void at run-time, and,
A new uninstantiable placeholder class-Void-to hold a reference to the Class object representing the keyword void.

The reflection API accomodates two categories of applications:

Standard applications that need to discover and use all of the public members of a target object based on its run-time class. These applications require run-time access to the public fields, methods, and constructors of an object. Examples in this category are services like Java^TM Beans[1] and lightweight tools like object inspectors. These applications can use the instances of the classes Field, Method, and Constructor obtained from the methods getField, getMethod, getConstructor, getFields, getMethods, and getConstructors of class Class.
Sophisticated applications that need to discover and use the members declared by a given class. These applications need run-time access to the implementation of a class at the level provided by a .class file. Examples in this category are development tools such as debuggers, interpreters, inspectors, and class browsers, and run-time services such as Java^TM Object Serialization[2]. These applications can use the instances of the classes Field, Method, and Constructor obtained from the methods getDeclaredField, getDeclaredMethod, getDeclaredConstructor, getDeclaredFields, getDeclaredMethods, and getDeclaredConstructors of class Class.

Reflection Model

The Field, Method, and Constructor classes are final, and are only created by the Java Virtual Machine. Objects which are instances of these classes are used to manipulate the underlying objects, getting and setting field values, invoking methods on objects or classes, and creating new instances of classes. The final uninstantiable class Array provides static methods that permit creating new arrays, and getting and setting the elements of arrays.

The classes Field, Method and Constructor implement the Member interface. The methods of Member are used to query a reflected member for basic identifying information. This consists of the class or interface declaring the member, the name of the member, and the Java language modifiers (such as public, protected, abstract, synchronized, etc.) for the member.

A Field object represents a reflected field. The underlying field may be a class variable (static field) or an instance variable (non-static field). Methods of class Field can be used to obtain the type of the underlying field, and to get and set the underlying field's value on objects.

A Method object represents a reflected method. The underlying method may be an abstract method, an instance method, or a class (static) method. Methods of class Method can be used to obtain the formal parameter types, the return type, and the checked exception types of the underlying method. The invoke method of class Method can be used to invoke the underlying method on objects. Instance and abstract method invocation uses dynamic method resolution based on the target object's run-time class and the reflected method's declaring class, name, and formal parameter types. (Thus, it is permissible to invoke a reflected interface method on an object that is an instance of a class that implements the interface.) Static method invocation uses the underlying static method of the method's declaring class.

A Constructor object represents a reflected constructor. Methods of class Constructor can be used to obtain the formal parameter types and the checked exception types of the underlying constructor. The newInstance method of class Constructor can be used to create and initialize a new instance of the class that declares the constructor, provided the class is instantiable.

The Array class is an uninstantiable class that exports class methods to create Java arrays with primitive or class component types, and to get and set array component values.

The Modifier class is an uninstantiable class that exports class methods to decode Java language modifiers for classes and members, which are encoded in an integer.

Finally, there are nine new Class objects (not classes) that are used to represent the eight primitive Java types and void at run-time. These objects are used by the reflection API to represent primitive field types, primitive method and constructor parameter types, and primitive method return types. These Class objects are created by the Java Virtual Machine, and have the same names as the types that they represent. The Class objects may only be referenced via the following public final static variables:


    java.lang.Boolean.TYPE
    java.lang.Character.TYPE
    java.lang.Byte.TYPE
    java.lang.Short.TYPE
    java.lang.Integer.TYPE
    java.lang.Long.TYPE
    java.lang.Float.TYPE
    java.lang.Double.TYPE
    java.lang.Void.TYPE

Security Model

Access to the reflection API is controlled on a class-by-class basis by the system's security manager. There are two levels of checks to enforce security and safety, as follows:

The new methods of class Class that give reflective access to a member or a set of members of a class are the only source for instances of Field, Method, and Constructor. These methods first delegate security checking to the system security manager, which throws a SecurityException should the request be denied.
If initial reflective access to a member or a set of members is granted, standard Java language access control checks for protected, default (package) access and private classes and members will normally occur when the individual reflected members are used to operate on the underlying members of objects, such as to get or set field values, to invoke methods, or to create and initialize new objects. However, unrestricted access may be granted to privileged code; a future version of this specification will define the interface by which this may be accomplished.

The initial policy decision is centralized in a new method of class SecurityManager:


    void checkMemberAccess(Class,int) throws SecurityException

where the Class parameter identifies the class or interface whose members need to be accessed and the int parameter identifies the set of members to be accessed-either Member.PUBLIC or Member.DECLARED.

If the requested access to the specified set of members of the specified class is denied, the method should throw a SecurityException. If the requested access to the set is granted, standard Java language access control will be enforced when using a reflected member from this set. This is when a Field is used to get or set a field value, when a Method is used to invoke a method, or when a Constructor used to create and initialize a new instance of a class. If access is denied at that point, the reflected member will throw an IllegalAccessException.

Java Language Policy

The Java language security policy for applications is that any code may gain reflective access to all the members and constructors (including non-public members and constructors) of any class it may link against. Application code that gains reflective access to a member or constructor may only use the reflected member or constructor with standard Java language access control.

JDK 1.1 Security Policy

In Sun's JDK 1.1 (but not part of the language specification itself), class AppletSecurity implements the following policy:

Untrusted (applet) code is granted access to
- All public members of all public classes loaded by the same class loader as the untrusted code;
- All public members of public system classes;
- All declared (including non-public) members of all classes loaded by the same class loader as the untrusted code.
Trusted (applet) code, defined as code signed by a trusted entity, is additionally granted access to all members of system classes.
System code, defined as code loaded from CLASSPATH, is additionally granted access to all classes loaded by all class loaders.

Any code that gains reflective access to a member may only use it with standard Java language access control. There is no notion of privileged code, and no means to override the standard language access control checks.

This policy is conservative with respect to untrusted code-it is more restrictive than the Java Virtual Machine's linker. For example, an untrusted class cannot, by itself, access a protected member of a system superclass via reflection, although it can via the linker. (However, system code may access such members and pass them to untrusted code.)

The JDK security policy is expected to evolve with Java's security framework.

Data Conversions

Certain methods in the reflection package perform automatic data conversions between values of primitive types and objects of class types. These are the generic methods for getting and setting field and array component values, and the methods for method and constructor invocation. Wrapping conversions are used to convert from values of primitive types to objects of class types. Unwrapping conversions are used to convert objects of class types to values of primitive types. The rules for these are defined below.

Additionally, field access and method invocation permit widening conversions on primitive and reference types. These conversions are documented in The Java Language Specification, section 5, and are detailed below.

Wrapping and Unwrapping Conversions

A primitive value is automatically wrapped in an object when it is retrieved via Field.get or Array.get, as is a primitive value returned by a method invoked via Method.invoke.

Similarly, an object value is automatically unwrapped when supplied as a parameter in a context that requires a value of a primitive type. The contexts are

Field.set, where the underlying field has a primitive type,
Array.set, where the underlying array has a primitive element type,
Method.invoke or Constructor.newInstance, where the corresponding formal parameter of the underlying method or constructor has a primitive type.

The following table shows the correspondences between primitive types and class (wrapper) types:


`boolean`	`java.lang.Boolean`
`char`	`java.lang.Character`
`byte`	`java.lang.Byte`
`short`	`java.lang.Short`
`int`	`java.lang.Integer`
`long`	`java.lang.Long`
`float`	`java.lang.Float`
`double`	`java.lang.Double`

A method that returns void returns the special reference null when invoked via Method.invoke.

Widening Conversions

The widening conversions permitted at run-time by the reflection package are those permitted at compile time in method invocation contexts as defined in The Java Language Specification, section 5.3.

Widening conversions are performed in the following situations.

When a value is retrieved from a field or an array via the methods of Field and Array;
When a value is stored into a field or an array via the methods of Field and Array;
When an unwrapped actual parameter value is converted to the type of its corresponding formal parameter during method or constructor invocation via Method.invoke or Constructor.newInstance.

The permitted widening primitive conversions¹ are:

From byte to short, int, long, float, or double
From short to int, long, float, or double
From char to int, long, float, or double
From int to long, float, or double
From long to float or double
From float to double.

The permitted widening reference conversions² are:

From a class type S to a class type T, provided that S is a subclass of T
From a class type S to an interface type K, provided that S implements K
From an interface type J to an interface type K, provided that J is a subinterface of K
From any interface type to type Object
From any array type to type Object
From any array type to type Cloneable
From an array type S[] to an array type T[], provided S and T are reference types and there is a widening conversion from S to T
From the null type to any reference type.

Packaging

The reflection API is in a new subpackage of java.lang named java.lang.reflect. This avoids compatibility problems caused by Java's default package importation rules.

Contents | Prev | Next

¹ See The Java Language Specification, section 5.1.2.

² See The Java Language Specification, section 5.1.4.

reflection-comments@worthy.eng.sun.com