com.openharbor.beck.map
Class DefaultMapper

java.lang.Object
  extended bycom.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.