Package io.permazen.util

Class AbstractXMLStreaming

java.lang.Object

io.permazen.util.AbstractXMLStreaming

Direct Known Subclasses:

SchemaItem, SchemaModel, XMLObjectSerializer, XMLSerializer

public abstract class AbstractXMLStreaming
extends Object

Support superclass for classes that serialize and deserialize via XML.

Field Summary

Fields

Modifier and Type	Field	Description
protected final Logger	log

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractXMLStreaming()

Method Summary

Modifier and Type	Method	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 XMLStreamException	newInvalidInputException(XMLStreamReader reader, String format, Object... args)	Build a XMLStreamException caused by invalid input.
protected XMLStreamException	newInvalidInputException(XMLStreamReader reader, Throwable cause, String format, Object... args)	Build a XMLStreamException caused by invalid input.
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	writeAttr(XMLStreamWriter writer, QName name, Object value)	Write out an attribute, and also verify that no illegal characters are written.
protected void	writeCData(XMLStreamWriter writer, String text)	Write out CDATA text with proper escaping of nested ]]> sequences, and also verify that no illegal characters are written.
protected void	writeCharacters(XMLStreamWriter writer, String text)	Write out text, and also verify that no illegal characters are written.
protected void	writeElement(XMLStreamWriter writer, QName name, String content)	Write out a simple XML element containing the given content.
protected void	writeEmptyElement(XMLStreamWriter writer, QName name)	Start an empty XML element.
protected void	writeStartElement(XMLStreamWriter writer, QName name)	Start a non-empty XML element.

Methods inherited from class java.lang.Object

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

Field Details

log

protected final Logger log

Constructor Details

AbstractXMLStreaming

protected AbstractXMLStreaming()

Method Details

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

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

newInvalidInputException

protected XMLStreamException newInvalidInputException(XMLStreamReader reader,
 String format,
 Object... args)

Build a XMLStreamException caused by invalid input.

Parameters:

reader - XML input

format - format string for String.format()

args - format arguments for String.format()

Returns:

exception to throw

newInvalidInputException

protected XMLStreamException newInvalidInputException(XMLStreamReader reader,
 Throwable cause,
 String format,
 Object... args)

Build a XMLStreamException caused by invalid input.

This method exists to help workaround JDK-8322027.

Parameters:

reader - XML input

cause - optional underlying exception for chaining, or null for none

format - format string for String.format()

args - format arguments for String.format()

Returns:

exception to throw

writeElement

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

Write out a simple XML element containing the given content.

Parameters:

writer - XML output

name - element name

content - simple content

Throws:

XMLStreamException - if error occurs writing output

IllegalArgumentException - if any parameter is null

IllegalArgumentException - if name is invalid

writeEmptyElement

protected void writeEmptyElement(XMLStreamWriter writer,
 QName name)
                          throws XMLStreamException

Start an empty XML element.

Parameters:

writer - XML output

name - element name

Throws:

XMLStreamException - if error occurs writing output

IllegalArgumentException - if any parameter is null

IllegalArgumentException - if name is invalid

writeStartElement

protected void writeStartElement(XMLStreamWriter writer,
 QName name)
                          throws XMLStreamException

Start a non-empty XML element.

Parameters:

writer - XML output

name - element name

Throws:

XMLStreamException - if error occurs writing output

IllegalArgumentException - if any parameter is null

IllegalArgumentException - if name is invalid

writeAttr

protected void writeAttr(XMLStreamWriter writer,
 QName name,
 Object value)
                  throws XMLStreamException

Write out an attribute, and also verify that no illegal characters are written.

Parameters:

writer - XML output

name - attribute qualified name

value - attribute value

Throws:

XMLStreamException - if error occurs writing output

IllegalArgumentException - if any parameter is null

IllegalArgumentException - if name is invalid

IllegalArgumentException - if the String value of value contains an illegal character

writeCharacters

protected void writeCharacters(XMLStreamWriter writer,
 String text)
                        throws XMLStreamException

Write out text, and also verify that no illegal characters are written.

Parameters:

writer - XML output

text - text to output

Throws:

XMLStreamException - if error occurs writing output

IllegalArgumentException - if any parameter is null

IllegalArgumentException - if text contains an illegal character

writeCData

protected void writeCData(XMLStreamWriter writer,
 String text)
                   throws XMLStreamException

Write out CDATA text with proper escaping of nested ]]> sequences, and also verify that no illegal characters are written.

Note: The method XMLStreamWriter.writeCData(java.lang.String) does not escape nested ]]> sequences. This method handles them.

Parameters:

writer - XML output

text - text to output

Throws:

XMLStreamException - if error occurs writing output

IllegalArgumentException - if any parameter is null

IllegalArgumentException - if text contains an illegal character