com.alipay.sofa.common.xmap

Class XMap

java.lang.Object

com.alipay.sofa.common.xmap.XMap

Direct Known Subclasses:

XMapSpring

public class XMap
extends Object

XMap maps an XML file to a java object. The mapping is described by annotations on java objects. The following annotations are supported:

• XObject Mark the object as being mappable to an XML node
• XNode Map an XML node to a field of a mappable object
• XNodeList Map an list of XML nodes to a field of a mappable object
• XNodeMap Map an map of XML nodes to a field of a mappable object
• XContent Map an XML node content to a field of a mappable object
• XParent Map a field of the current mappable object to the parent object if any exists The parent object is the mappable object containing the current object as a field

The mapping is done in 2 steps:

• The XML file is loaded as a DOM document
• The DOM document is parsed and the nodes mapping is resolved

Author:

Bogdan Stefanescu, xi.hux@alipay.com, ruoshan

Field Summary

Fields

Modifier and Type	Field and Description
protected Map<Class,XValueFactory>	factories
protected Map<Class,XAnnotatedObject>	objects
protected Map<String,XAnnotatedObject>	roots

Constructor Summary

Constructors

Constructor and Description
XMap() Creates a new XMap object.

Method Summary

Modifier and Type	Method and Description
Document	asXml(Object contribution, List<String> filters)
String	asXmlString(Object contribution, String encoding, List<String> filters)
String	asXmlString(Object contribution, String encoding, List<String> filters, boolean pretty)
protected static Annotation	checkMemberAnnotation(AnnotatedElement ae)
protected static XObject	checkObjectAnnotation(AnnotatedElement ae, ClassLoader classLoader)
XAnnotatedMember	createFieldMember(Field field, Annotation annotation)
XAnnotatedMember	createMethodMember(Method method, Class<?> clazz, Annotation annotation)
Method	getGetterMethod(Class<?> clazz, String name)
Collection<XAnnotatedObject>	getRootObjects() Gets the root objects.
Collection<XAnnotatedObject>	getScannedObjects() Gets a list of scanned objects.
XValueFactory	getValueFactory(Class type) Gets the value factory used for objects of the given class.
Object	load(Context ctx, Element root) Processes the given DOM element and return the first mappable object found in the element.
Object	load(Context ctx, InputStream in) Processes the XML content from the given input stream using the given context.
Object	load(Context ctx, URL url) Processes the XML file at the given URL and using the given contexts.
Object	load(Element root) Processes the given DOM element and return the first mappable object found in the element.
Object	load(InputStream in) Processes the XML content from the given input stream using a default context.
<T> T	load(Map<String,Object> map, String keyPrefix, Class<T> klass)
Object	load(URL url) Processes the XML file at the given URL using a default context.
Object[]	loadAll(Context ctx, Element root) Processes the given DOM element and return a list with all top-level mappable objects found in the element.
void	loadAll(Context ctx, Element root, Collection<Object> result) Same as loadAll(Context, Element) but put collected objects in the given collection.
Object[]	loadAll(Context ctx, InputStream in) Processes the XML from the given input stream using the given context.
Object[]	loadAll(Context ctx, URL url) Processes the XML file at the given URL using the given context Return a list with all registered top level objects that are found in the file.
Object[]	loadAll(Element root) Processes the given DOM element and return a list with all top-level mappable objects found in the element.
void	loadAll(Element root, Collection<Object> result) Same as loadAll(Element) but put collected objects in the given collection.
Object[]	loadAll(InputStream in) Processes the XML from the given input stream using the given context.
Object[]	loadAll(URL url) Processes the XML file at the given URL using a default context.
XAnnotatedObject	register(Class klass) Registers a mappable object class.
XAnnotatedObject	register(Class klass, boolean isParent) Registers a mappable object class.
void	setValueFactory(Class type, XValueFactory factory) Sets a custom value factory for the given class.

Methods inherited from class java.lang.Object

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

Field Detail

roots

protected final Map<String,XAnnotatedObject> roots

objects

protected final Map<Class,XAnnotatedObject> objects

factories

protected final Map<Class,XValueFactory> factories

Constructor Detail

XMap

public XMap()

Creates a new XMap object.

Method Detail

getValueFactory

public XValueFactory getValueFactory(Class type)

Gets the value factory used for objects of the given class. Value factories are used to decode values from XML strings.

Parameters:

type - the object type

Returns:

the value factory if any, null otherwise

setValueFactory

public void setValueFactory(Class type,
                            XValueFactory factory)

Sets a custom value factory for the given class. Value factories are used to decode values from XML strings.

Parameters:

type - the object type

factory - the value factory to use for the given type

getScannedObjects

public Collection<XAnnotatedObject> getScannedObjects()

Gets a list of scanned objects. Scanned objects are annotated objects that was registered by this XMap instance.

Returns:

list of scanned objects.

getRootObjects

public Collection<XAnnotatedObject> getRootObjects()

Gets the root objects. Root objects are scanned objects that can be mapped to XML elements that are not part from other objects.

Returns:

the root objects

register

public XAnnotatedObject register(Class klass)

Registers a mappable object class. The class will be scanned for XMap annotations and a mapping description is created.

Parameters:

klass - the object class

Returns:

the mapping description

register

public XAnnotatedObject register(Class klass,
                                 boolean isParent)

Registers a mappable object class. The class will be scanned for XMap annotations and a mapping description is created.

Parameters:

klass - the object class

Returns:

the mapping description

load

public Object load(URL url)
            throws Exception

Processes the XML file at the given URL using a default context. Returns the first registered top level object that is found in the file. If not objects are found null is returned.

Parameters:

url - the XML file url

Returns:

the first register top level object

Throws:

Exception

load

public Object load(Context ctx,
                   URL url)
            throws Exception

Processes the XML file at the given URL and using the given contexts. Returns the first registered top level object that is found in the file.

Parameters:

ctx - the context to use

url - the XML file url

Returns:

the first register top level object

Throws:

Exception - any exception

load

public Object load(InputStream in)
            throws Exception

Processes the XML content from the given input stream using a default context. Returns the first registered top level object that is found in the file.

Parameters:

in - the XML input source

Returns:

the first register top level object

Throws:

Exception

load

public Object load(Context ctx,
                   InputStream in)
            throws Exception

Processes the XML content from the given input stream using the given context. Return the first registered top level object that is found in the file.

Parameters:

ctx - the context to use

in - the input stream

Returns:

the first register top level object

Throws:

Exception - any exception

loadAll

public Object[] loadAll(URL url)
                 throws Exception

Processes the XML file at the given URL using a default context. Returns a list with all registered top level objects that are found in the file. If not objects are found, an empty list is returned.

Parameters:

url - the XML file url

Returns:

a list with all registered top level objects that are found in the file

Throws:

Exception

loadAll

public Object[] loadAll(Context ctx,
                        URL url)
                 throws Exception

Processes the XML file at the given URL using the given context Return a list with all registered top level objects that are found in the file. If not objects are found an empty list is returned.

Parameters:

ctx - the context to use

url - the XML file url

Returns:

a list with all registered top level objects that are found in the file

Throws:

Exception - any exception

loadAll

public Object[] loadAll(InputStream in)
                 throws Exception

Processes the XML from the given input stream using the given context. Returns a list with all registered top level objects that are found in the file. If not objects are found, an empty list is returned.

Parameters:

in - the XML input stream

Returns:

a list with all registered top level objects that are found in the file

Throws:

Exception - any exception

loadAll

public Object[] loadAll(Context ctx,
                        InputStream in)
                 throws Exception

Processes the XML from the given input stream using the given context. Returns a list with all registered top level objects that are found in the file. If not objects are found, an empty list is returned.

Parameters:

ctx - the context to use

in - the XML input stream

Returns:

a list with all registered top level objects that are found in the file

Throws:

Exception

load

public Object load(Element root)
            throws Exception

Processes the given DOM element and return the first mappable object found in the element. A default context is used.

Parameters:

root - the element to process

Returns:

the first object found in this element or null if none

Throws:

Exception

load

public Object load(Context ctx,
                   Element root)
            throws Exception

Processes the given DOM element and return the first mappable object found in the element. The given context is used.

Parameters:

ctx - the context to use

root - the element to process

Returns:

the first object found in this element or null if none

Throws:

Exception

load

public <T> T load(Map<String,Object> map,
                  String keyPrefix,
                  Class<T> klass)
           throws Exception

Throws:

Exception

loadAll

public Object[] loadAll(Context ctx,
                        Element root)
                 throws Exception

Processes the given DOM element and return a list with all top-level mappable objects found in the element. The given context is used.

Parameters:

ctx - the context to use

root - the element to process

Returns:

the list of all top level objects found

Throws:

Exception

loadAll

public Object[] loadAll(Element root)
                 throws Exception

Processes the given DOM element and return a list with all top-level mappable objects found in the element. The default context is used.

Parameters:

root - the element to process

Returns:

the list of all top level objects found

Throws:

Exception

loadAll

public void loadAll(Element root,
                    Collection<Object> result)
             throws Exception

Same as loadAll(Element) but put collected objects in the given collection.

Parameters:

root - the element to process

result - the collection where to collect objects

Throws:

Exception

asXml

public Document asXml(Object contribution,
                      List<String> filters)
               throws Exception

Throws:

Exception

asXmlString

public String asXmlString(Object contribution,
                          String encoding,
                          List<String> filters)
                   throws Exception

Throws:

Exception

asXmlString

public String asXmlString(Object contribution,
                          String encoding,
                          List<String> filters,
                          boolean pretty)
                   throws Exception

Throws:

Exception

loadAll

public void loadAll(Context ctx,
                    Element root,
                    Collection<Object> result)
             throws Exception

Same as loadAll(Context, Element) but put collected objects in the given collection.

Parameters:

ctx - the context to use

root - the element to process

result - the collection where to collect objects

Throws:

Exception

checkMemberAnnotation

protected static Annotation checkMemberAnnotation(AnnotatedElement ae)

checkObjectAnnotation

protected static XObject checkObjectAnnotation(AnnotatedElement ae,
                                               ClassLoader classLoader)

createFieldMember

public final XAnnotatedMember createFieldMember(Field field,
                                                Annotation annotation)

createMethodMember

public final XAnnotatedMember createMethodMember(Method method,
                                                 Class<?> clazz,
                                                 Annotation annotation)

getGetterMethod

public Method getGetterMethod(Class<?> clazz,
                              String name)