Contents | Prev | Next Java Core Reflection


Overview

The Java(TM) Core Reflection API provides a small, type-safe, and secure API that supports introspection about the classes and objects in the current Java Virtual Machine*. If permitted by security policy, the API can be used to:

The Core Reflection API defines classes and methods, as follows:

There are also some parts of the java.lang package that support reflection. These are:

Applications

The Core Reflection API accommodates two categories of applications.

One category is comprised of 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 all the public fields, methods, and constructors of an object. Examples in this category are services such as Java(TM) Beans[1], and lightweight tools, such as object inspectors. These applications use the instances of the classes Field, Method, and Constructor obtained through the methods getField, getMethod, getConstructor, getFields, getMethods, and getConstructors of class Class.

The second category consists of 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 interpreters, inspectors, and class browsers, and run-time services, such as Java(TM) Object Serialization[2]. These applications use instances of the classes Field, Method, and Constructor obtained through the methods getDeclaredField, getDeclaredMethod, getDeclaredConstructor, getDeclaredFields, getDeclaredMethods, and getDeclaredConstructors of class Class.


Reflection Model

The three classes Field, Method, and Constructor are final. Only the Java Virtual Machine may create instances of these classes; these objects are used to manipulate the underlying objects; that is, to:

The final uninstantiable class Array provides static methods that permit creating new arrays, and getting and setting the elements of arrays.

Member Interface

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. Identifying information consists of the class or interface that declared the member, the name of the member itself, and the Java language modifiers (such as public, protected, abstract, synchronized, and so on) for the member.

Field Objects

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

Method 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 are used to obtain the formal parameter types, the return type, and the checked exception types of the underlying method. In addition, the invoke method of class Method is used to invoke the underlying method on target 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.

Constructor Objects

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

Array and Modifier Classes

The Array class is an uninstantiable class that exports class methods to create Java arrays with primitive or class component types. Methods of class Array are also used 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. The language modifiers are encoded in an integer, and use the encoding constants defined by The Java Virtual Machine Specification.

Representation of Primitive Java Types

Finally, there are nine Class objects that are used to represent the eight primitive Java types and void at run-time. (Note that these are Class objects, not classes.) The Core Reflection API uses these objects to identify the following:

The Java Virtual Machine creates these nine Class objects. They 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

In particular, these Class objects are not accessible via the forName method of class Class.


Security Model

The Java security manager controls access to the Core Reflection API on a class-by-class basis. There are two levels of checks to enforce security and safety, as follows:

The initial policy decision is centralized in two methods of class SecurityManager:

void checkMemberAccess(Class,int) throws SecurityException

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

void checkPackageAccess(String pkg) throws SecurityException

The policy is determined based on what permissions are granted to the caller. There are two actions of class java.lang.RuntimePermission that affect these policies. These are:

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, the method should return.

As stated earler, standard Java language access control will usually be enforced when a reflected member from this set is used to operate on an underlying object, that is, when:

If access is denied at that point, the reflected member will throw an IllegalAccessException. Java language access control may be suppressed for a particular reflected member by setting a flag using the setAccessible method, as explained below.

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. By default, 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.

The standard policy may be overridden by calling the reflected member's setAccessible method. The ability to call the setAccessible method is in turn controlled by the suppressAccessChecks target of the permission ReflectPermission.


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.

There are two types of automatic data conversions. Wrapping conversions convert from values of primitive types to objects of class types. Unwrapping conversions convert objects of class types to values of primitive types. The rules for these conversions are defined in "Wrapping and Unwrapping Conversions."

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 in "Widening Conversions."

Wrapping and Unwrapping Conversions

A primitive value is automatically wrapped in an object when it is retrieved via Field.get or Array.get, or when it is 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. These contexts are:

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

Primitive Type Class Type
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 is declared void returns the special reference null when it is invoked via Method.invoke.

Widening Conversions

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

Widening conversions are performed at run-time:

The permitted widening primitive conversions are:

The permitted widening reference conversions are:


Packaging

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

*As used on this web site, the terms "Java Virtual Machine" or "JVM" mean a virtual machine for the Java platform.


Contents | Prev | Next
Copyright © 1996, 1997, 1998 Sun Microsystems, Inc. All rights reserved.