net.sf.kdgcommons.bean

Class Introspection

java.lang.Object

net.sf.kdgcommons.bean.Introspection

public class Introspection
extends Object

A replacement for java.beans.Introspector that is tailored to conversion of bean data into other forms. Uses the following rules to find the getters and setters of an introspected class:

Identifies multiple accessor methods

javax.beans.Introspector looks at parameter type, and attempts to match getters and setters. This method looks only at the method name, and will return any method whose name starts with "get" or "is".

Ignores case in name comparison

javax.beans.Introspector has camel-casing rules that do not always correspond to programmer intent -- in particular, two initial capitals are not camelcased.

Resolves multiple setter methods for same property

In the case where there are multiple getters/setters with the same name, the following ranking is applied:

1. Methods defined by subclass, over those defined by superclass. The subclass is assumed to be more specific.
2. Methods that get/take primitive values.
3. Methods that get/take primitive wrappers.
4. Methods that get/take String. Driven by the use of this introspector to translate to/from a text format.
5. Methods that get/take arbitrary objects.

Resolves multiple getter methods for same property

For class hierarchies that define covariant return types, will use the most specific type.

Ignores properties defined by Object

javax.beans.Introspector allows specific control over the parts of the class hierarchy to be introspected; by default, it will include methods defined by Object. We don't care about those, but assume any other class in the hierarchy to be important.

Does not cache introspections.

javax.beans.Introspector maintains its own cache of methods. Since it is loaded by the bootstrap classloader, and thus never released, this can wreak havoc when used by a library in an application server. We separate introspection and caching; see IntrospectionCache for the latter.

Does not rely on setAccessible()

Introspects only the public getter and setter methods. In a perfect world, these will be sufficient to marshall and unmarshall an object, and we can use the introspected methods in a sandbox (applet or security-managed container). In the real world, you can have a public method on a private class, and get an access exception if you attempt to invoke that method. If you live in that world, you can instruct Introspector to mark each method as accessible (but then you can't run in sandboxes).

Instances of this class are read-only (and thus threadsafe) once constructed.

Since:

1.0.5

Constructor Summary

Constructors

Constructor and Description
Introspection(Class<?> klass) Introspects the specified class, per the rules above.
Introspection(Class<?> klass, boolean setAccessible) Introspects the specified class, per the rules above.

Method Summary

Modifier and Type	Method and Description
Method	getter(String propName) Returns the getter method for the named property, null no method is known (all properties returned by propertyNames() must have getters, but may not have setters).
Set<String>	propertyNames() Returns the property names for the specified class.
Method	setter(String propName) Returns the setter method for the named property, null if unable to find a method.
Class<?>	type(String propName) Returns the type of the named property, taken from the return type of the property's getter.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Introspection

public Introspection(Class<?> klass)

Introspects the specified class, per the rules above.

Throws:

IntrospectionException - on any error (this will always wrap an underlying exception, typically one of the checked exceptions thrown by the reflection mechanism).

Introspection

public Introspection(Class<?> klass,
                     boolean setAccessible)

Introspects the specified class, per the rules above. Optionally sets each introspected method as accessible. This avoids exceptions caused by public methods in private classes, but will throw a security exception if running in a sandbox.

Since:

1.0.12

Method Detail

propertyNames

public Set<String> propertyNames()

Returns the property names for the specified class. These names are generated from getter methods -- any method beginning with "get" or "is". The returned set is unmodifiable, and will be empty if there are no properties with bean-style getter methods.

Names are processed by Introspector.decapitalize(), so will be consistent with the bean specification.

getter

public Method getter(String propName)

Returns the getter method for the named property, null no method is known (all properties returned by propertyNames() must have getters, but may not have setters).

setter

public Method setter(String propName)

Returns the setter method for the named property, null if unable to find a method.

type

public Class<?> type(String propName)

Returns the type of the named property, taken from the return type of the property's getter. Will be null if the property isn't known.