io.permazen.util

Class AbstractXMLStreaming

java.lang.Object

io.permazen.util.AbstractXMLStreaming

Direct Known Subclasses:

AbstractSchemaItem, ImplementationsReader, SchemaModel, XMLObjectSerializer, XMLSerializer

public abstract class AbstractXMLStreaming
extends Object

Support superclass for classes that serialize and deserialize via XML.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractXMLStreaming()

Method Summary

Modifier and Type	Method and Description
protected boolean	expect(XMLStreamReader reader, boolean closingOK, QName... names) Scan forward until we see an opening or closing tag.
protected void	expectClose(XMLStreamReader reader) Scan forward expecting to see a closing tag.
protected String	getAttr(XMLStreamReader reader, QName name) Get a requried attribute from the current element.
protected String	getAttr(XMLStreamReader reader, QName name, boolean required) Get an attribute from the current element.
protected boolean	getBooleanAttr(XMLStreamReader reader, QName name) Get a requried boolean attribute from the current element.
protected Boolean	getBooleanAttr(XMLStreamReader reader, QName name, boolean required) Get an attribute from the current element and parse as a boolean value.
protected int	getIntAttr(XMLStreamReader reader, QName name) Get a requried integer attribute from the current element.
protected Integer	getIntAttr(XMLStreamReader reader, QName name, boolean required) Get an attribute from the current element and parse as a decimal integer value.
protected Long	getLongAttr(XMLStreamReader reader, QName name, boolean required) Get an attribute from the current element and parse as a decimal long value.
protected XMLStreamException	newInvalidAttributeException(XMLStreamReader reader, QName name, String description, Throwable... cause) Build a XMLStreamException caused by invalid content in an attribute.
protected QName	next(XMLStreamReader reader) Skip forward until either the next opening tag is reached, or the currently open tag is closed.
protected void	skip(XMLStreamReader reader) Skip over the remainder of the current XML element, including any nested elements, until the closing XML tag is seen and consumed.
protected void	writeElement(XMLStreamWriter writer, QName element, String content) Write out a simple XML element containing the given content.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractXMLStreaming

protected AbstractXMLStreaming()

Method Detail

expect

protected boolean expect(XMLStreamReader reader,
                         boolean closingOK,
                         QName... names)
                  throws XMLStreamException

Scan forward until we see an opening or closing tag. If opening tag is seen, it must match one of names and then we return true, if not or if names is empty throw an exception; if a closing tag is seen, return false if closingOK, else throw exception.

Parameters:

reader - XML input

closingOK - true if a closing tag is OK, otherwise false

names - expected opening tag, or null if we expected a closing tag

Returns:

true if matching opening tag seen, false otherwise

Throws:

XMLStreamException - if something unexpected is encountered

next

protected QName next(XMLStreamReader reader)
              throws XMLStreamException

Skip forward until either the next opening tag is reached, or the currently open tag is closed.

Parameters:

reader - XML input

Returns:

the XML opening tag found, or null if a closing tag was seen first

Throws:

XMLStreamException - if no opening tag is found before the current tag closes

XMLStreamException - if something unexpected is encountered

skip

protected void skip(XMLStreamReader reader)
             throws XMLStreamException

Skip over the remainder of the current XML element, including any nested elements, until the closing XML tag is seen and consumed.

Parameters:

reader - XML input

Throws:

XMLStreamException - if something unexpected is encountered

expectClose

protected void expectClose(XMLStreamReader reader)
                    throws XMLStreamException

Scan forward expecting to see a closing tag.

Equivalant to: expect(reader, true).

Parameters:

reader - XML input

Throws:

XMLStreamException - if something other than a closing tag is encountered

writeElement

protected void writeElement(XMLStreamWriter writer,
                            QName element,
                            String content)
                     throws XMLStreamException

Write out a simple XML element containing the given content.

Parameters:

writer - XML output

element - element name

content - simple content

Throws:

XMLStreamException - if error occurs writing output

getAttr

protected String getAttr(XMLStreamReader reader,
                         QName name,
                         boolean required)
                  throws XMLStreamException

Get an attribute from the current element.

Parameters:

reader - XML input

name - attribute name

required - whether attribute must be present

Returns:

attribute value, or null if not required and no attribute is present

Throws:

IllegalStateException - if the current event is not a start element event

XMLStreamException - if required is true and no such attribute is found

getAttr

protected String getAttr(XMLStreamReader reader,
                         QName name)
                  throws XMLStreamException

Get a requried attribute from the current element. Equivalent to: getAttr(reader, name, true).

Parameters:

reader - XML input

name - attribute name

Returns:

attribute value

Throws:

IllegalStateException - if the current event is not a start element event

XMLStreamException - if no such attribute is found

getIntAttr

protected Integer getIntAttr(XMLStreamReader reader,
                             QName name,
                             boolean required)
                      throws XMLStreamException

Get an attribute from the current element and parse as a decimal integer value.

Parameters:

reader - XML input

name - attribute name

required - whether attribute must be present

Returns:

attribute value, or null if not required and no attribute is present

Throws:

IllegalStateException - if the current event is not a start element event

XMLStreamException - if required is true and no such attribute is found

XMLStreamException - if attribute is not an integer value

getLongAttr

protected Long getLongAttr(XMLStreamReader reader,
                           QName name,
                           boolean required)
                    throws XMLStreamException

Get an attribute from the current element and parse as a decimal long value.

Parameters:

reader - XML input

name - attribute name

required - whether attribute must be present

Returns:

attribute value, or null if not required and no attribute is present

Throws:

IllegalStateException - if the current event is not a start element event

XMLStreamException - if required is true and no such attribute is found

XMLStreamException - if attribute is not an integer value

getIntAttr

protected int getIntAttr(XMLStreamReader reader,
                         QName name)
                  throws XMLStreamException

Get a requried integer attribute from the current element. Equivalent to: getIntAttr(reader, name, true).

Parameters:

reader - XML input

name - attribute name

Returns:

attribute value

Throws:

IllegalStateException - if the current event is not a start element event

XMLStreamException - if no such attribute is found

XMLStreamException - if attribute is not an integer value

getBooleanAttr

protected Boolean getBooleanAttr(XMLStreamReader reader,
                                 QName name,
                                 boolean required)
                          throws XMLStreamException

Get an attribute from the current element and parse as a boolean value.

Parameters:

reader - XML input

name - attribute name

required - whether attribute must be present

Returns:

attribute value, or null if not required and no attribute is present

Throws:

IllegalStateException - if the current event is not a start element event

XMLStreamException - if required is true and no such attribute is found

XMLStreamException - if attribute is not "true" or "false"

getBooleanAttr

protected boolean getBooleanAttr(XMLStreamReader reader,
                                 QName name)
                          throws XMLStreamException

Get a requried boolean attribute from the current element. Equivalent to: getBooleanAttr(reader, name, true).

Parameters:

reader - XML input

name - attribute name

Returns:

attribute value

Throws:

IllegalStateException - if the current event is not a start element event

XMLStreamException - if no such attribute is found

XMLStreamException - if attribute is not "true" or "false"

newInvalidAttributeException

protected XMLStreamException newInvalidAttributeException(XMLStreamReader reader,
                                                          QName name,
                                                          String description,
                                                          Throwable... cause)
                                                   throws XMLStreamException

Build a XMLStreamException caused by invalid content in an attribute.

Parameters:

reader - XML input

name - attribute name

description - a description of the problem

cause - optional underlying exception for chaining

Returns:

exception to throw

Throws:

IllegalArgumentException - if more than one cause is given

XMLStreamException - if error occurs accessing the attribute value