org.oddjob.arooa.reflect
Class IntrospectionHelper

java.lang.Object
  org.oddjob.arooa.reflect.IntrospectionHelper

public final class IntrospectionHelper

extends java.lang.Object

Helper class that collects the methods a component or nested element holds to set attributes, create nested elements or hold PCDATA elements. The class is final as it has a private constructor.

Based on the original by Stefan Bodewig and Peter Reilly.

Method Summary

void	addText(java.lang.Object element, java.lang.String text) Adds PCDATA to an element, using the element's void addText(String) method, if it has one.
java.lang.Object	createElement(java.lang.String uri, java.lang.Object parent, java.lang.String elementName) Creates a named nested element.
void	dump(java.io.PrintStream out) Useful debug method to dump the internals of this class.
java.lang.Class	getAttributeType(java.lang.String attributeName) Returns the type of a named attribute.
java.lang.Class	getElementType(java.lang.String elementName) Returns the type of a named nested element.
static IntrospectionHelper	getHelper(java.lang.Class c) Returns a helper for the given class, either from the cache or by creating a new instance.
java.util.Enumeration	getNestedElements() Returns an enumeration of the names of the nested elements supported by the introspected class.
static java.lang.String	getPropertyName(java.lang.String methodName, java.lang.String prefix) Extracts the name of a property from a method name by subtracting a given prefix and converting into lower case.
ArooaHandler	provideHandler(java.lang.Object parent, java.lang.String elementName, ArooaContext context) Provide a handler.
static java.lang.Class	selectBestMatchingClass(java.lang.Class match, java.lang.Class[] set)
void	storeComponent(java.lang.Object parent, java.lang.Object child, java.lang.String elementName) Stores a named nested element using a storage method determined by the initial introspection.
void	storeConfiguredElement(java.lang.Object parent, java.lang.Object child, java.lang.String elementName) Stores a named nested element using a storage method determined by the initial introspection.
boolean	supportsCharacters() Returns whether or not the introspected class supports PCDATA.
boolean	supportsNestedElement(java.lang.String elementName) Indicate if this element supports a nested element of the given name.
void	throwNotSupported(java.lang.Object parent, java.lang.String elementName) Utility method to throw a NotSupported exception
static java.lang.Object	valueFor(java.lang.Object from) As with valueFor(Object, Class) but for the default type.
static java.lang.Object	valueFor(java.lang.Object from, java.lang.Class required) Get the value from the given type object if its a type wrapper, or the object itself.

Methods inherited from class java.lang.Object

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

Method Detail

getHelper

public static IntrospectionHelper getHelper(java.lang.Class c)

Returns a helper for the given class, either from the cache or by creating a new instance.

Parameters:

c - The class for which a helper is required. Must not be null.

Returns:

a helper for the specified class

addText

public void addText(java.lang.Object element,
                    java.lang.String text)
             throws ArooaException

Adds PCDATA to an element, using the element's void addText(String) method, if it has one. If no such method is present, a ArooaException is thrown if the given text contains non-whitespace.

Parameters:

element - The element to add the text to. Must not be null.

text - The text to add. Must not be null.

Throws:

ArooaException - if non-whitespace text is provided and no method is available to handle it, or if the handling method fails.

throwNotSupported

public void throwNotSupported(java.lang.Object parent,
                              java.lang.String elementName)

Utility method to throw a NotSupported exception

Parameters:

parent - the object which doesn't support a requested element

elementName - the name of the Element which is trying to be created.

createElement

public java.lang.Object createElement(java.lang.String uri,
                                      java.lang.Object parent,
                                      java.lang.String elementName)
                               throws ArooaException

Creates a named nested element. Depending on the results of the initial introspection, either a method in the given parent instance or a simple no-arg constructor is used to create an instance of the specified element type.

Parameters:

uri - Namespace uri.

parent - Parent object used to create the instance. Must not be null.

elementName - Name of the element to create an instance of. Must not be null.

Returns:

an instance of the specified element type

Throws:

ArooaException - if no method is available to create the element instance, or if the creating method fails.

supportsNestedElement

public boolean supportsNestedElement(java.lang.String elementName)

Indicate if this element supports a nested element of the given name.

Parameters:

elementName - the name of the nested element being checked

Returns:

true if the given nested element is supported

storeConfiguredElement

public void storeConfiguredElement(java.lang.Object parent,
                                   java.lang.Object child,
                                   java.lang.String elementName)
                            throws ArooaException

Stores a named nested element using a storage method determined by the initial introspection. If no appropriate storage method is available, this method returns immediately.

Parameters:

parent - Parent instance to store the child in. Must not be null.

child - Child instance to store in the parent. Should not be null.

elementName - Name of the child element to store. May be null, in which case this method returns immediately.

Throws:

ArooaException - if the storage method fails.

provideHandler

public ArooaHandler provideHandler(java.lang.Object parent,
                                   java.lang.String elementName,
                                   ArooaContext context)
                            throws ArooaException

Provide a handler.

Parameters:

parent - Parent instance. Must not be null.

elementName - Name of the child the handler is for. May not be null.

Throws:

ArooaException - if the storage method fails.

storeComponent

public void storeComponent(java.lang.Object parent,
                           java.lang.Object child,
                           java.lang.String elementName)
                    throws ArooaException

Stores a named nested element using a storage method determined by the initial introspection. If no appropriate storage method is available, this method returns immediately.

Parameters:

parent - Parent instance to store the child in. Must not be null.

child - Child instance to store in the parent. Should not be null.

elementName - Name of the child element to store. May be null, in which case this method returns immediately.

Throws:

ArooaException - if the storage method fails.

getElementType

public java.lang.Class getElementType(java.lang.String elementName)
                               throws ArooaException

Returns the type of a named nested element.

Parameters:

elementName - The name of the element to find the type of. Must not be null.

Returns:

the type of the nested element with the specified name. This will never be null.

Throws:

ArooaException - if the introspected class does not support the named nested element.

getAttributeType

public java.lang.Class getAttributeType(java.lang.String attributeName)
                                 throws ArooaException

Returns the type of a named attribute.

Parameters:

attributeName - The name of the attribute to find the type of. Must not be null.

Returns:

the type of the attribute with the specified name. This will never be null.

Throws:

ArooaException - if the introspected class does not support the named attribute.

supportsCharacters

public boolean supportsCharacters()

Returns whether or not the introspected class supports PCDATA.

Returns:

whether or not the introspected class supports PCDATA.

getNestedElements

public java.util.Enumeration getNestedElements()

Returns an enumeration of the names of the nested elements supported by the introspected class.

Returns:

an enumeration of the names of the nested elements supported by the introspected class.

getPropertyName

public static java.lang.String getPropertyName(java.lang.String methodName,
                                               java.lang.String prefix)

Extracts the name of a property from a method name by subtracting a given prefix and converting into lower case. It is up to calling code to make sure the method name does actually begin with the specified prefix - no checking is done in this method.

Parameters:

methodName - The name of the method in question. Must not be null.

prefix - The prefix to remove. Must not be null.

Returns:

the lower-cased method name with the prefix removed.

valueFor

public static java.lang.Object valueFor(java.lang.Object from,
                                        java.lang.Class required)
                                 throws java.lang.ClassCastException,
                                        OddjobException

Get the value from the given type object if its a type wrapper, or the object itself.

The returned object may not be of the required type but a defualt type which a later org.appache.commons.beanutils.Converter might be able to use (Probably a Sring).

Parameters:

from - The object which might have a valueFor method.

required - The required class.

Returns:

The value which may or may not be of the required class.

Throws:

OddjobException - If the given object getValue() method can't be invoked.

java.lang.ClassCastException

valueFor

public static java.lang.Object valueFor(java.lang.Object from)
                                 throws java.lang.ClassCastException,
                                        OddjobException

As with valueFor(Object, Class) but for the default type.

Parameters:

from - The object which might have a valueFor method.

Returns:

The value which may or may not be of the required class.

Throws:

OddjobException - If the given object getValue() method can't be invoked.

java.lang.ClassCastException

dump

public void dump(java.io.PrintStream out)

Useful debug method to dump the internals of this class.

Parameters:

out - The stream to dump to.

selectBestMatchingClass

public static java.lang.Class selectBestMatchingClass(java.lang.Class match,
                                                      java.lang.Class[] set)