org.xmlfield.core

Class XmlField

java.lang.Object

org.xmlfield.core.XmlField

public class XmlField
extends Object

This class is the entry point of XmlField. It can convert xml data to objects (both ways).

 // Source Xml
 String xml ="<modelRootTag></modelRootTag>"; 
 
 // Read doc
 XmlField xf = new XmlField();
 IModel model = xf.xmlToObject(xmlRessource, IModel.class)
 
 // Back to XML.
 xml = xf.objectToXml( model);
 

This class and return objects are not thread safe. If the same objects are used concurrently in multiple threads, be sure to synchronize or use XmlFieldFactory with ThreadLocal enabled.

Author:

Guillaume Mary , Nicolas Richeton

Constructor Summary

Constructors

Constructor and Description
XmlField() Create XmlField object for xml/object manipulations.
XmlField(Map<String,String> parserConfiguration) Create XmlField object for xml/object manipulations.

Method Summary

Methods

Modifier and Type	Method and Description
XmlFieldNodeModifier	_getModifier() Returns the modifier associated with this XmlField object.
XmlFieldNodeParser	_getParser() Returns the parser associated with this XmlField object.
XmlFieldSelector	_getSelector() Returns the selector associated with this XmlField object.
<T> T	castObject(Object o, Class<T> type) Changes interface of an already attached node.
Map<String,String>	getParserConfiguration() Returns the current parser configuration.
boolean	isGetterCache()
<T> T	newObject(Class<T> type) instantiate a new XmlField interface.
<T> T[]	nodeToArray(String resourceXPath, XmlFieldNode node, Class<T> type)
<T> T[]	nodeToArray(XmlFieldNode node, Class<T> type)
Object[]	nodeToExplicitArray(String resourceXPath, XmlFieldNode node, Map<String,Class<?>> explicitCollection) Function to attach an array of different objects type .
<T> T	nodeToObject(String resourceXPath, XmlFieldNode node, Class<T> resourceType) Bind a node located by the xpath expression to the specified type
<T> T	nodeToObject(XmlFieldNode node, Class<T> type) Bind an xml field node to the specified type.
String	nodeToXml(XmlFieldNode node)
void	nodeToXml(XmlFieldNode node, Writer writer)
XmlFieldNode	objectToNode(Object o)
String	objectToXml(Object o)
void	objectToXml(Object o, Writer writer)
void	setGetterCache(boolean getterCache) Enables caching for get methods.
<T> T[]	xmlToArray(String xml, Class<T> type) Bind an xml string to an array of entities.
XmlFieldNode	xmlToNode(InputStream xmlInputStream) Load the XML document from an input stream, load it internally in a tree and return the root node.
XmlFieldNode	xmlToNode(String xml) Load the XML document from a string, load it internally in a tree and return the root node.
<T> T	xmlToObject(InputStream xmlContent, Class<T> type)
<T> T	xmlToObject(String xml, Class<T> type) Create an interface for the given xml and matching the given interface.

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlField

public XmlField()

Create XmlField object for xml/object manipulations.

Use default configuration.

XmlField

public XmlField(Map<String,String> parserConfiguration)

Create XmlField object for xml/object manipulations. This constructor can be used to gain fine control over xmlfield output for example (indentation, xml declaration etc. ).

Configuration is forwarded to xml transformer.

See OutputKeys for universal valid keys and values.

For specific transformer implementation see available documentation, for exemple, if xalan is used see org.apache.xml.serializer.OutputPropertiesFactory

BEWARE : if OutputKeys.MEDIA_TYPE is set to anything but xml, it can defeat XmlField purpose. this is applicable to other configuration too.

Parameters:

parserConfiguration - parser configuration. Allowed keys are specific to the parser implementations. See DomNodeParser for default implementation.

Method Detail

_getModifier

public XmlFieldNodeModifier _getModifier()

Returns the modifier associated with this XmlField object.

XmlFieldNodeModifier instance is created on demand at the first call.

Returns:

_getParser

public XmlFieldNodeParser _getParser()

Returns the parser associated with this XmlField object.

XmlFieldNodeParser instance is created on demand at the first call.

Returns:

_getSelector

public XmlFieldSelector _getSelector()

Returns the selector associated with this XmlField object.

XmlFieldSelector instance is created on demand at the first call.

Returns:

castObject

public <T> T castObject(Object o,
               Class<T> type)

Changes interface of an already attached node.

Parameters:

o - an object obtained by any #attach call.

type - the new interface for dom manipulation.

Returns:

an objet implementing the given interface.

getParserConfiguration

public Map<String,String> getParserConfiguration()

Returns the current parser configuration.

The returned object is cannot be updated.

Returns:

isGetterCache

public boolean isGetterCache()

newObject

public <T> T newObject(Class<T> type)
            throws XmlFieldParsingException

instantiate a new XmlField interface. the return object can be manipulated by Xmlfield like any object obtained by #bind methods

Type Parameters:

T - Class of interface to instantiate

Parameters:

type - Class of interface to instantiate

Returns:

an object implementing Class type and XmlFieldObject

Throws:

ParserConfigurationException

SAXException

IOException

XmlFieldParsingException

nodeToArray

public <T> T[] nodeToArray(String resourceXPath,
                  XmlFieldNode node,
                  Class<T> type)
                throws XmlFieldXPathException

Throws:

XmlFieldXPathException

nodeToArray

public <T> T[] nodeToArray(XmlFieldNode node,
                  Class<T> type)
                throws XmlFieldXPathException

Throws:

XmlFieldXPathException

nodeToExplicitArray

public Object[] nodeToExplicitArray(String resourceXPath,
                           XmlFieldNode node,
                           Map<String,Class<?>> explicitCollection)
                             throws XmlFieldXPathException

Function to attach an array of different objects type .

Parameters:

resourceXPath - Xpath to the collection.

explicitCollection - Hashmap for matching name of xpath and clas.

node - node of java object.

Throws:

XmlFieldXPathException

nodeToObject

public <T> T nodeToObject(String resourceXPath,
                 XmlFieldNode node,
                 Class<T> resourceType)

Bind a node located by the xpath expression to the specified type

Parameters:

resourceXPath - xpath expression used to locate the node to bind

node - the root node XmlFieldNode

resourceType - the expected interface class

Returns:

null for non matching xml/type.

nodeToObject

public <T> T nodeToObject(XmlFieldNode node,
                 Class<T> type)

Bind an xml field node to the specified type. This type should have some xpath annotations.

Type Parameters:

T - interface type

Parameters:

node - node

type - interface to bind to

Returns:

instance binded to the xml

nodeToXml

public String nodeToXml(XmlFieldNode node)
                 throws XmlFieldParsingException

Throws:

XmlFieldParsingException

nodeToXml

public void nodeToXml(XmlFieldNode node,
             Writer writer)
               throws XmlFieldParsingException

Throws:

XmlFieldParsingException

objectToNode

public XmlFieldNode objectToNode(Object o)

objectToXml

public String objectToXml(Object o)
                   throws XmlFieldParsingException

Throws:

XmlFieldParsingException

objectToXml

public void objectToXml(Object o,
               Writer writer)
                 throws XmlFieldParsingException

Throws:

XmlFieldParsingException

setGetterCache

public void setGetterCache(boolean getterCache)

Enables caching for get methods.

Warning : this cache is experimental and cannot get changes mades when using different objects to access the same XML Node. The use of this cache is NOT recommended at the moment.

Parameters:

getterCache -

xmlToArray

public <T> T[] xmlToArray(String xml,
                 Class<T> type)
               throws XmlFieldException

Bind an xml string to an array of entities. the xml should be a list of entities enclosed by a root element.

Type Parameters:

T - interface type

Parameters:

xml - an xml string with a root element enclosing a list of node to bind

type - interface to bind to

Returns:

an array

Throws:

XmlFieldParsingException

XmlFieldXPathException

XmlFieldException

xmlToNode

public XmlFieldNode xmlToNode(InputStream xmlInputStream)
                       throws XmlFieldParsingException

Load the XML document from an input stream, load it internally in a tree and return the root node.

As XmlField supports multiple XML parsing engines, the return object is a generic type which wraps the actual implementation of the tree.

The document root is intended to be used with XmlField#nodeToObject( XmlFieldNode node, Class type) to get an object instance to read/write the document.

Parameters:

xmlInputStream - Input stream on an XML document.

Returns:

Root node of the XML document tree.

Throws:

XmlFieldParsingException - When document is invalid, and cannot be parsed or when an exception occurs.

xmlToNode

public XmlFieldNode xmlToNode(String xml)
                       throws XmlFieldParsingException

Load the XML document from a string, load it internally in a tree and return the root node.

As XmlField supports multiple XML parsing engines, the return object is a generic type which wraps the actual implementation of the tree.

The document root is intended to be used with XmlField#nodeToObject( XmlFieldNode node, Class type) to get an object instance to read/write the document.

Parameters:

xml - An XML document in a single string

Returns:

Root node of the XML document tree.

Throws:

XmlFieldParsingException - When document is invalid and cannot be parsed.

xmlToObject

public <T> T xmlToObject(InputStream xmlContent,
                Class<T> type)
              throws XmlFieldParsingException

Parameters:

xmlContent -

type -

Returns:

Throws:

XmlFieldParsingException

xmlToObject

public <T> T xmlToObject(String xml,
                Class<T> type)
              throws XmlFieldParsingException

Create an interface for the given xml and matching the given interface.

Parameters:

xml - the xml String to load

type - the expected interface

Returns:

a proxy object responding to given type, return null if type does'n match the xml string.

Throws:

ParserConfigurationException - when parsing xml failed

SAXException - when parsing xml failed

IOException - when parsing xml failed

XmlFieldParsingException