Package org.nuxeo.common.xmap

Class XMap

java.lang.Object

org.nuxeo.common.xmap.XMap

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

Constructor Summary

Constructors

Constructor	Description
XMap()	Creates a new XMap object.

Method Summary

Modifier and Type	Method	Description
protected static Annotation	checkMemberAnnotation(AnnotatedElement ae)
protected static XObject	checkObjectAnnotation(AnnotatedElement ae)
XAnnotatedMember	createFieldMember(Field field, Annotation annotation)
XAnnotatedMember	createMethodMember(Method method, Annotation annotation, Class<?> klass)
static DocumentBuilderFactory	getFactory()
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(InputStream in)	Processes the XML content from the given input stream using a default context.
Object	load(URL url)	Processes the XML file at the given URL using a default context.
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(Context ctx, Element root)	Processes the given DOM element and return the first mappable object found in the element.
Object	load(Element root)	Processes the given DOM element and return the first mappable object found in the element.
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.
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
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(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.
XAnnotatedObject	register(Class<?> klass)	Registers a mappable object class.
void	setValueFactory(Class<?> type, XValueFactory factory)	Sets a custom value factory for the given class.
String	toXML(Object object)
void	toXML(Object object, File file)
void	toXML(Object object, OutputStream os)
void	toXML(Object object, Element root)

Methods inherited from class java.lang.Object

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

Constructor Detail

XMap

public XMap()

Creates a new XMap object.

Method Detail

getFactory

public static DocumentBuilderFactory getFactory()

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 were registered by this XMap instance.

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

load

public Object load(URL url)
            throws IOException

Processes the XML file at the given URL using a default context.

Parameters:

url - the XML file url

Returns:

the first registered top level object that is found in the file, or null if no objects are found.

Throws:

IOException

load

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

Processes the XML file at the given URL and using the given contexts.

Parameters:

ctx - the context to use

url - the XML file url

Returns:

the first registered top level object that is found in the file.

Throws:

IOException

load

public Object load(InputStream in)
            throws IOException

Processes the XML content from the given input stream using a default context.

Parameters:

in - the XML input source

Returns:

the first registered top level object that is found in the file.

Throws:

IOException

load

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

Processes the XML content from the given input stream using the given context.

Parameters:

ctx - the context to use

in - the input stream

Returns:

the first registered top level object that is found in the file.

Throws:

IOException

loadAll

public Object[] loadAll(URL url)
                 throws IOException

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:

IOException

loadAll

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

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 retoruned.

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:

IOException

loadAll

public Object[] loadAll(InputStream in)
                 throws IOException

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:

IOException

loadAll

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

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:

IOException

load

public Object load(Element root)

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

load

public Object load(Context ctx,
                   Element root)

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

loadAll

public 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.

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

loadAll

public Object[] loadAll(Element root)

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

loadAll

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

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

loadAll

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

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

checkMemberAnnotation

protected static Annotation checkMemberAnnotation(AnnotatedElement ae)

checkObjectAnnotation

protected static XObject checkObjectAnnotation(AnnotatedElement ae)

createFieldMember

public final XAnnotatedMember createFieldMember(Field field,
                                                Annotation annotation)

createMethodMember

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

toXML

public String toXML(Object object)
             throws IOException

Throws:

IOException

toXML

public void toXML(Object object,
                  OutputStream os)
           throws IOException

Throws:

IOException

toXML

public void toXML(Object object,
                  File file)
           throws IOException

Throws:

IOException

toXML

public void toXML(Object object,
                  Element root)