org.nuiton.io.xpp3
Class AbstractXpp3Reader<O>

java.lang.Object
  org.nuiton.io.xpp3.AbstractXpp3Reader<O>

Type Parameters:

O - the type of object to be build by the reader

All Implemented Interfaces:

Xpp3Reader<O>

public abstract class AbstractXpp3Reader<O>
extends Object
implements Xpp3Reader<O>

An abstract xpp3Reader based on PropertyMapper to set properties of the objects to build.

To implements a new parser, just implements method initMappers() to see authorized mapping from tag to pojo properties.

The logic of setting properties from xml (tag and attributes) is done in

• read(String, Class, org.codehaus.plexus.util.xml.pull.XmlPullParser, boolean)
• readArray(String, String, Class, org.codehaus.plexus.util.xml.pull.XmlPullParser, boolean)

The default implementation is to map tag text to a pojo's property.

If you want to do something more complex, override these methods.

Since:

1.0.0

Author:

chemit

See Also:

PropertyMapper, Xpp3Reader

Field Summary

protected boolean	addDefaultEntities If set the parser will be loaded with all single characters from the XHTML specification.
protected Map<String,PropertyMapper>	allMappers the univers of mappers availables, initialized in initMappers().
protected String	arrayRootTagName the root tag of an array of objets to retreave from xml streams.
protected String	rootTagName the root tag of an object to retreave from xml streams.
protected Class<O>	type the type of the object to produce from the xml streams.

Constructor Summary

protected	AbstractXpp3Reader(Class<O> type, String rootTagName)
protected	AbstractXpp3Reader(Class<O> type, String arrayRootTagName, String rootTagName)

Method Summary

protected void	checkEndOfXml(org.codehaus.plexus.util.xml.pull.XmlPullParser parser) Checks that a given parser is at the end of the xml document.
protected void	checkNotEndOfXml(org.codehaus.plexus.util.xml.pull.XmlPullParser parser, String tagName) Checks that a given parser is not at the end of the xml document.
String	getArrayRootTagName()
Map<String,PropertyMapper>	getMappers(Class<?> srcType) Obtain all mappers for a given type.
String	getRootTagName()
Class<O>	getType()
protected int	gotoNextOpenTag(String tagName, org.codehaus.plexus.util.xml.pull.XmlPullParser parser)
protected abstract void	initMappers()
boolean	isAddDefaultEntities()
O	read(Reader reader) Read a single instance of the typed object and return it.
O	read(Reader reader, boolean strict) Read a single instance of the typed object and return it.
protected <T> T	read(String rootTagName, Class<T> type, org.codehaus.plexus.util.xml.pull.XmlPullParser parser, boolean strict) Parse the xml stream from the given parser and a build the associated object.
O[]	readArray(Reader reader) Read some instances of the typed object and return it.
O[]	readArray(Reader reader, boolean strict) Read some instances of the typed object and return it.
protected <T> T[]	readArray(String parentRootTagName, String rootTagName, Class<T> type, org.codehaus.plexus.util.xml.pull.XmlPullParser parser, boolean strict) Parse the xml stream from the given parser and a build an array of associated object.
void	setAddDefaultEntities(boolean addDefaultEntities) Set the new value of the defaultEntities flag.
void	setParentRootTagName(String parentRootTagName) Set the name of the root tag for an array of object to read.
void	setRootTagName(String rootTagName) Set the name of the root tag of an object to read.

Methods inherited from class java.lang.Object

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

Field Detail

addDefaultEntities

protected boolean addDefaultEntities

If set the parser will be loaded with all single characters from the XHTML specification. The entities used:

• http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent
• http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent
• http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent

type

protected final Class<O> type

the type of the object to produce from the xml streams.

rootTagName

protected String rootTagName

the root tag of an object to retreave from xml streams.

arrayRootTagName

protected String arrayRootTagName

the root tag of an array of objets to retreave from xml streams.

allMappers

protected Map<String,PropertyMapper> allMappers

the univers of mappers availables, initialized in initMappers().

Each mapper of the dictionary is associated to the fully qualified name of the target class # the tag name or attribute name.

Example :

  org.nuiton.util.MyPojo#my-tag
  org.nuiton.util.MyPojo#my-attribute
 

Constructor Detail

AbstractXpp3Reader

protected AbstractXpp3Reader(Class<O> type,
                             String rootTagName)

AbstractXpp3Reader

protected AbstractXpp3Reader(Class<O> type,
                             String arrayRootTagName,
                             String rootTagName)

Method Detail

initMappers

protected abstract void initMappers()
                             throws IntrospectionException

Throws:

IntrospectionException

getType

public Class<O> getType()

Specified by:

getType in interface Xpp3Reader<O>

Returns:

the type of main object to read

getRootTagName

public String getRootTagName()

Specified by:

getRootTagName in interface Xpp3Reader<O>

Returns:

the name of the root tag of a object to read

setRootTagName

public void setRootTagName(String rootTagName)

Description copied from interface: Xpp3Reader

Set the name of the root tag of an object to read.

Specified by:

setRootTagName in interface Xpp3Reader<O>

Parameters:

rootTagName - the name of the tag

getArrayRootTagName

public String getArrayRootTagName()

Specified by:

getArrayRootTagName in interface Xpp3Reader<O>

Returns:

the name of the root tag of an array of objets to read

setParentRootTagName

public void setParentRootTagName(String parentRootTagName)

Description copied from interface: Xpp3Reader

Set the name of the root tag for an array of object to read.

Specified by:

setParentRootTagName in interface Xpp3Reader<O>

Parameters:

parentRootTagName - the name of the tag

isAddDefaultEntities

public boolean isAddDefaultEntities()

Specified by:

isAddDefaultEntities in interface Xpp3Reader<O>

Returns:

true if parser will load the default entities, false otherwise.

setAddDefaultEntities

public void setAddDefaultEntities(boolean addDefaultEntities)

Description copied from interface: Xpp3Reader

Set the new value of the defaultEntities flag.

Specified by:

setAddDefaultEntities in interface Xpp3Reader<O>

Parameters:

addDefaultEntities - the new value.

read

public O read(Reader reader)
       throws IOException,
              org.codehaus.plexus.util.xml.pull.XmlPullParserException

Description copied from interface: Xpp3Reader

Read a single instance of the typed object and return it.

Note : this is a convinient method to call Xpp3Reader.read(java.io.Reader, boolean) in strict mode.

In the xml stream, the root tag must be the Xpp3Reader.getRootTagName().

Example :

 <issue>:
    ...
 </issue>:
 

Specified by:

read in interface Xpp3Reader<O>

Parameters:

reader - the xml input reader

Returns:

Settings

Throws:

IOException - if any io pb

org.codehaus.plexus.util.xml.pull.XmlPullParserException - if parsing error

read

public O read(Reader reader,
              boolean strict)
       throws IOException,
              org.codehaus.plexus.util.xml.pull.XmlPullParserException

Description copied from interface: Xpp3Reader

Read a single instance of the typed object and return it.

In the xml stream, the root tag must be the Xpp3Reader.getRootTagName().

Example :

 <issue>:
    ...
 </issue>:
 

Specified by:

read in interface Xpp3Reader<O>

Parameters:

reader - the xml input reader

strict - flag to be strict while parsing

Returns:

the read object

Throws:

IOException - if any io pb

org.codehaus.plexus.util.xml.pull.XmlPullParserException - if any parsing pb

readArray

public O[] readArray(Reader reader)
              throws IOException,
                     org.codehaus.plexus.util.xml.pull.XmlPullParserException

Description copied from interface: Xpp3Reader

Read some instances of the typed object and return it.

In the xml stream, the root tag must be the Xpp3Reader.getArrayRootTagName().

Note : this is a convinient method to call : Xpp3Reader.readArray(java.io.Reader, boolean) in stritc mode.

Example :

 <issues>:
   <issue>:
    ...
   </issue>:
 </issues>:
 

Specified by:

readArray in interface Xpp3Reader<O>

Parameters:

reader - the xml input reader

Returns:

the array of read objects.

Throws:

IOException - if any io pb

org.codehaus.plexus.util.xml.pull.XmlPullParserException - if any parsing pb

readArray

public O[] readArray(Reader reader,
                     boolean strict)
              throws IOException,
                     org.codehaus.plexus.util.xml.pull.XmlPullParserException

Description copied from interface: Xpp3Reader

Read some instances of the typed object and return it.

In the xml stream, the root tag must be the Xpp3Reader.getArrayRootTagName().

Example :

 <issues>:
   <issue>:
    ...
   </issue>:
 </issues>:
 

Specified by:

readArray in interface Xpp3Reader<O>

Parameters:

reader - the xml input reader

strict - flag to be strict while parsing

Returns:

the array of read objects.

Throws:

IOException - if any io pb

org.codehaus.plexus.util.xml.pull.XmlPullParserException - if any parsing pb

getMappers

public Map<String,PropertyMapper> getMappers(Class<?> srcType)

Obtain all mappers for a given type.

In the result, the keys are now the tag-name of attribute-name.

Example :

  my-tag
  my-attribute
 

Parameters:

srcType - the target type of the searched mappers

Returns:

the dictionnary of mappers for the given type.

read

protected <T> T read(String rootTagName,
                     Class<T> type,
                     org.codehaus.plexus.util.xml.pull.XmlPullParser parser,
                     boolean strict)
          throws org.codehaus.plexus.util.xml.pull.XmlPullParserException,
                 IOException

Parse the xml stream from the given parser and a build the associated object.

This default implementation just match a tag text content to a pojo property.

No work is done on attribute values here.

Note: The parser must accept as a next open tag the required one .

the next node name is given by getRootTagName()

Example :

 ...
 <my-pojo>
   <my-property>myValue</my-property>
 </my-pojo>
 

Type Parameters:

T - the type of object to build

Parameters:

rootTagName - the name of the root tag matching the object to build

type - the type of object to build

parser - the xpp3 parser

strict - flag to indicate if should fail if a unknown tag (or attribute ?) is scanned

Returns:

the single object build from the xml stream.

Throws:

IOException - if any io pb

org.codehaus.plexus.util.xml.pull.XmlPullParserException - if any parsing pb

readArray

protected <T> T[] readArray(String parentRootTagName,
                            String rootTagName,
                            Class<T> type,
                            org.codehaus.plexus.util.xml.pull.XmlPullParser parser,
                            boolean strict)
                 throws org.codehaus.plexus.util.xml.pull.XmlPullParserException,
                        IOException

Parse the xml stream from the given parser and a build an array of associated object.

This default implementation just match a tag text content to a pojo property.

No work is done on attribute values here.

Note: The next node of the parser must be the one given by parentRootTagName and sub nodes with names rootTagName.

Example :

 ...
 <my-pojos>
   <my-pojo>
     <my-property>myValue</my-property>
   </my-pojo>
   <my-pojo>
     <my-property>myValue2</my-property>
   </my-pojo>
 </my-pojos>
 

Type Parameters:

T - the type of objects to build

Parameters:

parentRootTagName - the tag's name of the array container

rootTagName - the tag's name of each object to build

type - the type of objects to build

parser - the xpp3 parser

strict - flag to indicate if should fail if a unknown tag (or attribute ?) is scanned

Returns:

the single object build from the xml stream.

Throws:

IOException - if any io pb

org.codehaus.plexus.util.xml.pull.XmlPullParserException - if any parsing pb

gotoNextOpenTag

protected int gotoNextOpenTag(String tagName,
                              org.codehaus.plexus.util.xml.pull.XmlPullParser parser)
                       throws org.codehaus.plexus.util.xml.pull.XmlPullParserException,
                              IOException

Throws:

org.codehaus.plexus.util.xml.pull.XmlPullParserException

IOException

checkNotEndOfXml

protected void checkNotEndOfXml(org.codehaus.plexus.util.xml.pull.XmlPullParser parser,
                                String tagName)
                         throws org.codehaus.plexus.util.xml.pull.XmlPullParserException

Checks that a given parser is not at the end of the xml document.

Parameters:

parser - the parser to check

tagName - the endign tag's name

Throws:

org.codehaus.plexus.util.xml.pull.XmlPullParserException - if the parser is at the end of the xml stream, instead of the tagName ending tag

checkEndOfXml

protected void checkEndOfXml(org.codehaus.plexus.util.xml.pull.XmlPullParser parser)
                      throws org.codehaus.plexus.util.xml.pull.XmlPullParserException

Checks that a given parser is at the end of the xml document.

Parameters:

parser - the parser to check

Throws:

org.codehaus.plexus.util.xml.pull.XmlPullParserException - if the parser is not at the end of the xml stream.