com.openharbor.beck.map
Class DefaultMapper

java.lang.Object
  com.openharbor.beck.map.DefaultMapper

All Implemented Interfaces:

MapFromXML, MapToXML, Prefixer

Direct Known Subclasses:

MappingMapper

public class DefaultMapper

extends java.lang.Object

implements MapFromXML, MapToXML, Prefixer

Maps between Java and XML in a flexible, configurable way. This class is not thread-safe.

Nested Class Summary

Nested classes inherited from class com.openharbor.beck.map.MapFromXML

MapFromXML.Aware, MapFromXML.Source

Nested classes inherited from class com.openharbor.beck.map.MapToXML

MapToXML.Source

Field Summary

protected Marshaller	arrayMarshaller
protected static java.util.Map	CLASS_TO_PROPERTY_TO_SETTER Maps the Class of an unmarshalled object to Setters for properties of that class.
protected java.util.Map	class2property2setter Maps the Class of an unmarshalled object to Setters for properties of that class.
protected Marshaller	collectionMarshaller
protected java.util.Map	configurationMemo Maps a Selector s to the result of getMapperSource().get(s).
protected Marshaller	dateMarshaller
protected Marshaller	defaultMarshaller
protected Configuration.Selector	globalSelector
protected Marshaller	listMarshaller
protected org.apache.commons.logging.Log	log
protected Marshaller	mapMarshaller
protected Configuration.MarshalSelector	marshalSelector
protected Marshaller	primitiveMarshaller
protected java.util.Map	primitiveUnmarshallers A map from a Class that has no members or properties to a Unmarshaller for that class.
protected static XMLName	PROPERTIES
protected java.util.Map	singletons Maps the result of getMapperSource().get X to the result of newInstance(X).
protected Marshaller	stringMarshaller
protected java.util.Map	unmarshallerClass2Pool Maps the Class of a Unmarshaller to a Stack of unused instances of that class.
protected Configuration.UnmarshalSelector	unmarshalSelector

Constructor Summary

protected

DefaultMapper(Configuration configuration) Most applications should call newInstance instead of this constructor.

Method Summary

protected Getter[]	add(java.lang.Class sourceClass, Getter[] x, java.util.Set y)
protected void	addDefault(XMLName key, java.lang.Class componentClass)
protected XMLThing	addType(XMLThing result, XMLWriter writer) Determine the result's type, if possible.
protected Unmarshaller	allocateUnmarshaller(java.lang.Class unmarshallerClass)
protected void	configure(java.lang.Object object)
protected void	configureUnmarshaller(Unmarshaller unmarshaller, java.lang.Class objectClass, XMLContext context) This method must be thread-safe, because it's inherited into Configuration.MAP_FROM_XML which is required to be thread-safe.
protected java.util.Map	findConfiguredSetters(java.lang.Class objectClass) Find setters for configured supplemental properties of the given Class.
protected static java.util.Map	findDefaultSetters(java.lang.Class parentClass) Find the default setters for properties of the given Class.
protected static void	findNonPublicSetterFields(java.lang.Class parentClass, java.util.Map result)
protected static void	findNonPublicSetterMethods(java.lang.Class parentClass, java.util.Map result)
protected static void	findNonPublicSetters(java.lang.Class parentClass, java.util.Map result)
protected static void	findPublicSetterFields(java.lang.Class parentClass, java.util.Map result)
protected static void	findPublicSetterMethods(java.lang.Class parentClass, java.util.Map result)
protected static void	findPublicSetters(java.lang.Class parentClass, java.util.Map result)
Configuration	getConfiguration()
protected java.lang.Object	getConfigurationValue(Configuration.Selector selector)
protected Setter	getConfiguredSetter(java.lang.Class parentClass, java.lang.String propertyName) Get the configured setter (if any) for the given property of the given Class.
protected Setter	getConfiguredSetter(Unmarshaller parent, XMLThing source, Unmarshaller child) Get the configured setter (if any) for unmarshalling from the given XML source.
protected Unmarshaller	getConfiguredUnmarshaller(Unmarshaller parent, XMLThing source, java.lang.Class objectClass)
protected Setter	getDefaultSetter(java.lang.Class parentClass, java.lang.String propertyName) Get the default setter (if any) for the given property of the given Class.
protected Getter	getGetter(java.lang.Class parentClass, java.lang.Class sourceClass, java.lang.String propertyName)
Getter	getGetter(java.lang.Object parent, java.lang.Object source)
Identifier	getIdentifier(java.lang.Object parent, Getter getter) Choose the XML representation of repeated references to an object.
Identifier	getIdentifier(Unmarshaller parent, XMLThing source, java.lang.Class objectClass)
protected java.util.List	getList(java.util.Map map, java.lang.Object key)
protected java.util.Map	getMap(java.util.Map map, java.lang.Object key)
Marshaller	getMarshaller(java.lang.Object parent, XMLThing parentElement, Getter getter) Choose the Marshaller object for a given source Java object.
protected Namer	getNamer(java.lang.Object source)
java.lang.Class	getObjectClass(Unmarshaller parent, XMLThing source) Choose the Java class for an XML attribute or element.
protected XMLName	getParentElement(XMLWriter writer)
java.lang.String	getPrefix(java.lang.String namespace)
Prefixer	getPrefixer() This method must be thread-safe, because it's inherited into Configuration.MAP_FROM_XML which is required to be thread-safe.
protected Getter[]	getProperties(java.lang.Class sourceClass)
Getter[]	getProperties(java.lang.Object parent, Getter getter, java.lang.Object source) Find the properties of a given Java object that can be mapped to XML.
java.lang.String	getPropertyName(Unmarshaller parent, XMLThing source) Choose the JavaBean property name for an XML attribute or element.
protected Configuration.UnmarshalSelector	getSelector(Unmarshaller parent, XMLThing source, Unmarshaller child) Set the fields of this.unmarshalSelector to describe the given situation.
Setter	getSetter(Unmarshaller parent, XMLThing source, Unmarshaller child) Choose the algorithm for creating a reference from a parent object to a child object.
protected XMLName	getSignificantPart(XMLThing source) Ignore XML data that don't affect mapping.
protected java.lang.Object	getSingleton(Configuration.Selector selector)
protected java.lang.Class	getSourceClass(java.lang.Object parent, Getter getter, java.lang.Object source)
java.lang.String	getText(java.lang.Object parent, Marshaller marshaller, XMLWriter writer) Choose the Java property to be copied to XML text.
java.lang.String	getText(Unmarshaller parent) Choose the Java property to be copied from XML text.
Unmarshaller	getUnmarshaller(Unmarshaller parent, XMLThing source, XMLContext context) Engage an unmarshaller for the given XML source.
XMLThing	getXML(java.lang.Object parent, Getter getter, Marshaller marshaller, XMLWriter writer) Choose the XML element or attribute name for a Java object.
SAXContentHandler	newContentHandler() This method must be thread-safe, because it's inherited into Configuration.MAP_FROM_XML which is required to be thread-safe.
org.xml.sax.ErrorHandler	newErrorHandler()
protected java.lang.Object	newInstance(Configuration.Selector selector)
static DefaultMapper	newInstance(Configuration configuration)
protected java.lang.Object	newInstance(java.util.Map chosen)
java.lang.Object	newObject(Unmarshaller child) Instantiate an object for the given unmarshaller.
XMLReceiver	newReceiver(XMLThing source)
void	putUnmarshaller(Unmarshaller unmarshaller) Disengage an Unmarshaller from its XML source.
void	recycle(Unmarshaller unmarshaller) Make a Unmarshaller available for serial re-use.
protected Getter[]	subtract(java.lang.Class sourceClass, Getter[] x, java.util.Set y)

Methods inherited from class java.lang.Object

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

Field Detail

log

protected final org.apache.commons.logging.Log log

globalSelector

protected final Configuration.Selector globalSelector

marshalSelector

protected final Configuration.MarshalSelector marshalSelector

unmarshalSelector

protected final Configuration.UnmarshalSelector unmarshalSelector

configurationMemo

protected java.util.Map configurationMemo

Maps a Selector s to the result of getMapperSource().get(s). This improves performance, by avoiding repetitive calls to getMapperSource().get.

singletons

protected java.util.Map singletons

Maps the result of getMapperSource().get X to the result of newInstance(X). This improves performance, by avoiding repetitive object construction.

primitiveMarshaller

protected Marshaller primitiveMarshaller

stringMarshaller

protected Marshaller stringMarshaller

dateMarshaller

protected Marshaller dateMarshaller

arrayMarshaller

protected Marshaller arrayMarshaller

mapMarshaller

protected Marshaller mapMarshaller

listMarshaller

protected Marshaller listMarshaller

collectionMarshaller

protected Marshaller collectionMarshaller

defaultMarshaller

protected Marshaller defaultMarshaller

PROPERTIES

protected static final XMLName PROPERTIES

primitiveUnmarshallers

protected java.util.Map primitiveUnmarshallers

A map from a Class that has no members or properties to a Unmarshaller for that class.

unmarshallerClass2Pool

protected java.util.Map unmarshallerClass2Pool

Maps the Class of a Unmarshaller to a Stack of unused instances of that class.

CLASS_TO_PROPERTY_TO_SETTER

protected static final java.util.Map CLASS_TO_PROPERTY_TO_SETTER

Maps the Class of an unmarshalled object to Setters for properties of that class. This improves performance, by avoiding repeated calls to findDefaultSetters(Class).

class2property2setter

protected java.util.Map class2property2setter

Maps the Class of an unmarshalled object to Setters for properties of that class. This improves performance, by avoiding repeated calls to findConfiguredSetters(Class).

Constructor Detail

DefaultMapper

protected DefaultMapper(Configuration configuration)

Most applications should call newInstance instead of this constructor.

Parameters:

configuration - must not be modified after passing it to this constructor. The implementation of this class presumes that the result of configuration.get is entirely a function of its parameters (and memoizes it to improve performance).

Method Detail

newInstance

public static DefaultMapper newInstance(Configuration configuration)
                                 throws java.lang.Exception

Parameters:

configuration - must not be modified after passing it to this constructor. The implementation of this class presumes that the result of configuration.get is entirely a function of its parameters (and memoizes it to improve performance).

Throws:

java.lang.Exception

getConfiguration

public Configuration getConfiguration()

getConfigurationValue

protected java.lang.Object getConfigurationValue(Configuration.Selector selector)

addDefault

protected void addDefault(XMLName key,
                          java.lang.Class componentClass)

getNamer

protected Namer getNamer(java.lang.Object source)

getPrefixer

public Prefixer getPrefixer()

This method must be thread-safe, because it's inherited into Configuration.MAP_FROM_XML which is required to be thread-safe.

Specified by:

getPrefixer in interface MapFromXML

Returns:

the configured Prefixer, or null if none is configured.

newContentHandler

public SAXContentHandler newContentHandler()

This method must be thread-safe, because it's inherited into Configuration.MAP_FROM_XML which is required to be thread-safe.

Specified by:

newContentHandler in interface MapFromXML

newErrorHandler

public org.xml.sax.ErrorHandler newErrorHandler()

Specified by:

newErrorHandler in interface MapFromXML

newReceiver

public XMLReceiver newReceiver(XMLThing source)

Specified by:

newReceiver in interface MapFromXML

getIdentifier

public Identifier getIdentifier(java.lang.Object parent,
                                Getter getter)

Description copied from interface: MapToXML

Choose the XML representation of repeated references to an object.

Specified by:

getIdentifier in interface MapToXML

Parameters:

getter - to be mapped to XML

parent - contains source. null if source is the root object.

Returns:

the chosen Identifier, or null to map repeated references to copies of the XML.

getPrefix

public java.lang.String getPrefix(java.lang.String namespace)

Specified by:

getPrefix in interface Prefixer

getParentElement

protected XMLName getParentElement(XMLWriter writer)

getXML

public XMLThing getXML(java.lang.Object parent,
                       Getter getter,
                       Marshaller marshaller,
                       XMLWriter writer)
                throws java.lang.Exception

Description copied from interface: MapToXML

Choose the XML element or attribute name for a Java object. If the returned thing is an element with a null value, the caller should output the element and also additional attributes and/or content mapped from the source object. If the returned thing is an attribute or an element with a non-null value, the caller should output the returned thing without additions.

Specified by:

getXML in interface MapToXML

Parameters:

getter - to be mapped to XML

parent - contains source

Returns:

an attribute name and value or an element name with a set of conditions, or null to indicate that this source should not be marshalled.

Throws:

java.lang.Exception

getText

public java.lang.String getText(Unmarshaller parent)

Description copied from interface: MapFromXML

Choose the Java property to be copied from XML text.

Specified by:

getText in interface MapFromXML

Returns:

the property name, or null to indicate no such property is configured.

getText

public java.lang.String getText(java.lang.Object parent,
                                Marshaller marshaller,
                                XMLWriter writer)

Description copied from interface: MapToXML

Choose the Java property to be copied to XML text.

Specified by:

getText in interface MapToXML

Returns:

the property name, or null to indicate no such property is configured.

addType

protected XMLThing addType(XMLThing result,
                           XMLWriter writer)

Determine the result's type, if possible.

getObjectClass

public java.lang.Class getObjectClass(Unmarshaller parent,
                                      XMLThing source)

Description copied from interface: MapFromXML

Choose the Java class for an XML attribute or element.

Specified by:

getObjectClass in interface MapFromXML

Parameters:

source - to be mapped from XML

parent - mapped from the element that contains source

Returns:

the proposed class of the object to be mapped.

getPropertyName

public java.lang.String getPropertyName(Unmarshaller parent,
                                        XMLThing source)

Description copied from interface: MapFromXML

Choose the JavaBean property name for an XML attribute or element.

Specified by:

getPropertyName in interface MapFromXML

Parameters:

source - to be mapped from XML

parent - mapped from the element that contains source

Returns:

the proposed name of the JavaBean property of the parent whose value is mapped from the source.

getSetter

public Setter getSetter(Unmarshaller parent,
                        XMLThing source,
                        Unmarshaller child)

Description copied from interface: MapFromXML

Choose the algorithm for creating a reference from a parent object to a child object. For example, setting a field or property of the parent, to refer to the child.

Specified by:

getSetter in interface MapFromXML

Parameters:

source - to be mapped to child

child - may be null, e.g. when choosing a child class for instantiation.

getConfiguredSetter

protected Setter getConfiguredSetter(Unmarshaller parent,
                                     XMLThing source,
                                     Unmarshaller child)

Get the configured setter (if any) for unmarshalling from the given XML source.

getDefaultSetter

protected Setter getDefaultSetter(java.lang.Class parentClass,
                                  java.lang.String propertyName)

Get the default setter (if any) for the given property of the given Class.

getConfiguredSetter

protected Setter getConfiguredSetter(java.lang.Class parentClass,
                                     java.lang.String propertyName)

Get the configured setter (if any) for the given property of the given Class.

findDefaultSetters

protected static java.util.Map findDefaultSetters(java.lang.Class parentClass)

Find the default setters for properties of the given Class. That is, a Setter for each public JavaBean setter and public field. If a setter method and field are both accessible, choose the method.

Returns:

a Map from property name (a String) to the Setter for each property.

findPublicSetters

protected static void findPublicSetters(java.lang.Class parentClass,
                                        java.util.Map result)

findPublicSetterMethods

protected static void findPublicSetterMethods(java.lang.Class parentClass,
                                              java.util.Map result)

findPublicSetterFields

protected static void findPublicSetterFields(java.lang.Class parentClass,
                                             java.util.Map result)

findNonPublicSetters

protected static void findNonPublicSetters(java.lang.Class parentClass,
                                           java.util.Map result)

findNonPublicSetterMethods

protected static void findNonPublicSetterMethods(java.lang.Class parentClass,
                                                 java.util.Map result)

findNonPublicSetterFields

protected static void findNonPublicSetterFields(java.lang.Class parentClass,
                                                java.util.Map result)

findConfiguredSetters

protected java.util.Map findConfiguredSetters(java.lang.Class objectClass)

Find setters for configured supplemental properties of the given Class. This implementation gets the includeProperties configured for the Class, and resolves each property name to a field. Access limitations are ignored; that is, the returned Setters may set a non-public field.

Returns:

a Map from property name (a String) to a Setter for that property.

newObject

public java.lang.Object newObject(Unmarshaller child)
                           throws java.lang.Exception

Description copied from interface: MapFromXML

Instantiate an object for the given unmarshaller. The returned object should be assignable to unmarshaller.getObjectClass().

Specified by:

newObject in interface MapFromXML

Throws:

java.lang.Exception

getProperties

public Getter[] getProperties(java.lang.Object parent,
                              Getter getter,
                              java.lang.Object source)

Description copied from interface: MapToXML

Find the properties of a given Java object that can be mapped to XML.

Specified by:

getProperties in interface MapToXML

Parameters:

source - to be mapped to XML

parent - contains source. null if source is the root object.

Returns:

a Getter for each property of the given source object.

subtract

protected Getter[] subtract(java.lang.Class sourceClass,
                            Getter[] x,
                            java.util.Set y)

add

protected Getter[] add(java.lang.Class sourceClass,
                       Getter[] x,
                       java.util.Set y)

getProperties

protected Getter[] getProperties(java.lang.Class sourceClass)

getGetter

protected Getter getGetter(java.lang.Class parentClass,
                           java.lang.Class sourceClass,
                           java.lang.String propertyName)

getGetter

public Getter getGetter(java.lang.Object parent,
                        java.lang.Object source)

getSourceClass

protected java.lang.Class getSourceClass(java.lang.Object parent,
                                         Getter getter,
                                         java.lang.Object source)

getMarshaller

public Marshaller getMarshaller(java.lang.Object parent,
                                XMLThing parentElement,
                                Getter getter)

Description copied from interface: MapToXML

Choose the Marshaller object for a given source Java object.

Specified by:

getMarshaller in interface MapToXML

Parameters:

getter - to be mapped to XML

parent - contains source. null if source is the root object.

Returns:

a Marshaller configured for this case, or a default if none is configured.

getUnmarshaller

public Unmarshaller getUnmarshaller(Unmarshaller parent,
                                    XMLThing source,
                                    XMLContext context)

Description copied from interface: MapFromXML

Engage an unmarshaller for the given XML source. For best performance, the returned unmarshaller should be passed to MapFromXML.putUnmarshaller(com.openharbor.beck.unmarshal.Unmarshaller) after it has processed the XML source.

Specified by:

getUnmarshaller in interface MapFromXML

Parameters:

source - to be mapped to Java

parent - mapped from the element that contains source. null if source is the root element.

Returns:

the appropriate Unmarshaller for the object mapped from the given source, or null if no appropriate Unmarshaller is available.

getConfiguredUnmarshaller

protected Unmarshaller getConfiguredUnmarshaller(Unmarshaller parent,
                                                 XMLThing source,
                                                 java.lang.Class objectClass)

configure

protected void configure(java.lang.Object object)

configureUnmarshaller

protected void configureUnmarshaller(Unmarshaller unmarshaller,
                                     java.lang.Class objectClass,
                                     XMLContext context)

This method must be thread-safe, because it's inherited into Configuration.MAP_FROM_XML which is required to be thread-safe.

putUnmarshaller

public void putUnmarshaller(Unmarshaller unmarshaller)
                     throws java.lang.Exception

Description copied from interface: MapFromXML

Disengage an Unmarshaller from its XML source. The unmarshaller may subsequently recycle itself, but that's not the caller's concern.

Specified by:

putUnmarshaller in interface MapFromXML

Throws:

java.lang.Exception

getIdentifier

public Identifier getIdentifier(Unmarshaller parent,
                                XMLThing source,
                                java.lang.Class objectClass)

Specified by:

getIdentifier in interface MapFromXML

recycle

public void recycle(Unmarshaller unmarshaller)
             throws java.lang.Exception

Description copied from interface: MapFromXML

Make a Unmarshaller available for serial re-use. This enables a performance optimization: recycyling a Unmarshaller avoids the cost of constructing a new one. This method presumes that all unmarshallers of the same class are fungible. That is, getUnmarshaller may re-use the given unmarshaller instead of any new instance of unmarshaller.getClass().

Specified by:

recycle in interface MapFromXML

Throws:

java.lang.Exception

allocateUnmarshaller

protected Unmarshaller allocateUnmarshaller(java.lang.Class unmarshallerClass)

getList

protected java.util.List getList(java.util.Map map,
                                 java.lang.Object key)

getMap

protected java.util.Map getMap(java.util.Map map,
                               java.lang.Object key)

getSingleton

protected java.lang.Object getSingleton(Configuration.Selector selector)

newInstance

protected java.lang.Object newInstance(Configuration.Selector selector)

newInstance

protected java.lang.Object newInstance(java.util.Map chosen)

getSelector

protected Configuration.UnmarshalSelector getSelector(Unmarshaller parent,
                                                      XMLThing source,
                                                      Unmarshaller child)

Set the fields of this.unmarshalSelector to describe the given situation.

Returns:

this.unmarshalSelector

getSignificantPart

protected XMLName getSignificantPart(XMLThing source)

Ignore XML data that don't affect mapping.

Returns:

a similar thing, except with getValue() == null and getAttributes() either null or empty.