Package org.apache.juneau.marshall.xml

Class XmlParserSession

java.lang.Object

org.apache.juneau.marshall.ContextSession

org.apache.juneau.marshall.MarshallingSession

org.apache.juneau.marshall.parser.ParserSession

org.apache.juneau.marshall.parser.ReaderParserSession

org.apache.juneau.marshall.xml.XmlParserSession

All Implemented Interfaces:

BeanSession, ConverterSession, ArrayRecordReadable, RecordReadable

Direct Known Subclasses:

HtmlParserSession

public class XmlParserSession
extends ReaderParserSession
implements RecordReadable, ArrayRecordReadable

Session object that lives for the duration of a single use of XmlParser.

Notes:

• This class is not thread safe and is typically discarded after one use.

See Also:

• XML

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	XmlParserSession.Builder<SELF extends XmlParserSession.Builder<SELF>>	Builder class.
static final class	XmlParserSession.DefaultBuilder	Concrete default builder leaf for the non-subclassed create() path (CRTP terminal).

Field Summary

Fields inherited from class org.apache.juneau.marshall.parser.ParserSession

DEFAULT_MAX_PARSE_DEPTH

Fields inherited from class org.apache.juneau.marshall.MarshallingSession

NAME_PROPERTY_NAME

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	XmlParserSession(XmlParserSession.Builder<?> builder)	Constructor.

Method Summary

Modifier and Type	Method	Description
static XmlParserSession.Builder<?>	create(XmlParser ctx)	Creates a new builder for this object.
protected final String	decodeString(String s)	Decodes and trims the specified string.
protected <T> T	doRead(ParserPipe pipe, ClassMeta<T> type)	Workhorse method.
protected <E> Collection<E>	doReadIntoCollection(ParserPipe pipe, Collection<E> c, Type elementType)	Implementation method.
protected <K, V> Map<K,V>	doReadIntoMap(ParserPipe pipe, Map<K,V> m, Type keyType, Type valueType)	Implementation method.
protected String	getElementText(XmlReader r)	Returns the text content of the current XML element.
protected final XMLEventAllocator	getEventAllocator()	XML event allocator.
protected final XMLReporter	getReporter()	XML reporter.
protected final XMLResolver	getResolver()	XML resolver.
protected XmlBeanMeta	getXmlBeanMeta(BeanMeta<?> bm)	Returns the language-specific metadata on the specified bean.
protected XmlBeanPropertyMeta	getXmlBeanPropertyMeta(BeanPropertyMeta bpm)	Returns the language-specific metadata on the specified bean property.
protected XmlClassMeta	getXmlClassMeta(ClassMeta<?> cm)	Returns the language-specific metadata on the specified class.
protected final XmlReader	getXmlReader(ParserPipe pipe)	Wrap the specified reader in a STAX reader based on settings in this context.
boolean	isArrayRecordStreaming()	The XML array-record cursor is buffered/RecordAdapter-backed, not O(1) streaming.
protected final boolean	isPreserveRootElement()	Preserve root element during generalized parsing.
boolean	isRecordStreaming()	The XML record cursor is buffered/RecordAdapter-backed, not O(1) streaming.
protected final boolean	isValidating()	Enable validation.
protected boolean	isWhitespaceElement(XmlReader r)	Returns true if the current element is a whitespace element.
protected <T> T	readAnything(ClassMeta<T> eType, String currAttr, XmlReader r, Object outer, boolean isRoot, BeanPropertyMeta pMeta)	Workhorse method.
RecordReader	readArrayRecords(Object input)	Buffered array-element RecordReader for XML, bound to this live session.
RecordReader	readArrayRecords(Object input, String rootElementName)	Buffered array-element RecordReader that honors the caller-specified root element name.
RecordReader	readRecords(Object input)	Opens a whole-value pull-parser cursor over an XML document, bound to this live session.
protected String	readText(XmlReader r)	Parses the current element as text.
protected String	readWhitespaceElement(XmlReader r)	Parses the current whitespace element.

Methods inherited from class org.apache.juneau.marshall.parser.ReaderParserSession

create, createPipe, getStreamCharset, isReaderParser, properties

Methods inherited from class org.apache.juneau.marshall.parser.ParserSession

allocateLocal, cast, checkRequired, convertAttrToType, create, doReadToBeanConsumer, enterParseDepth, exitParseDepth, getCalendarFormat, getClassMeta, getDateFormat, getDebugOutputLines, getDurationFormat, getInputAsString, getJavaMethod, getLastLocation, getListener, getListener, getListenerClass, getLocaleFormat, getNulls, getOuter, getPeriodFormat, getPosition, getSchema, getStringBuilder, getTemporalFormat, getTimeZoneFormat, isAutoCloseStreams, isTrimStrings, isUnbuffered, mark, onBeanSetterException, onUnknownProperty, parentBean, read, read, read, read, read, read, readArgs, readCalendar, readDate, readDuration, readIntoCollection, readIntoMap, readPeriod, readTemporal, readToBeanConsumer, returnStringBuilder, setCurrentClass, setCurrentProperty, setName, setParent, setPipe, swapParentBean, trim, trim, unmark, unswap

Methods inherited from class org.apache.juneau.marshall.MarshallingSession

addWarning, convertToMemberType, convertToMemberType, convertToMemberType, convertToType, convertToType, convertToType, convertToType, create, get, getActiveView, getAnnotationProvider, getArgsClassMeta, getBeanClassVisibility, getBeanConstructorVisibility, getBeanDictionary, getBeanFieldVisibility, getBeanMeta, getBeanMethodVisibility, getBeanRegistry, getBeanTypePropertyName, getBeanTypePropertyName, getClassLoader, getClassMeta, getClassMeta, getClassMetaForObject, getClassMetaForObject, getLocale, getMarshallingContext, getMediaType, getNotBeanClasses, getNotBeanPackagesNames, getPropertyNamer, getSwaps, getTimeZone, getTimeZoneId, isBean, isBean, isBeanMapPutReturnsOldValue, isBeansRequireDefaultConstructor, isBeansRequireSerializable, isBeansRequireSettersForGetters, isBeansRequireSomeProperties, isFindFluentSetters, isIgnoreInvocationExceptionsOnGetters, isIgnoreInvocationExceptionsOnSetters, isIgnoreMissingSetters, isIgnoreUnknownBeanProperties, isIgnoreUnknownNullBeanProperties, isPropertyInActiveView, isRecordComponentOrder, isUnsortedProperties, isUseInterfaceProxies, isUseJavaBeanIntrospector, isValidateSchema, newBean, newBean, newBeanMap, newBeanMap, newGenericList, newGenericMap, newGenericMap, object, parseToList, parseToMap, string, toArray, toBeanMap, toBeanMap, toBeanMap

Methods inherited from class org.apache.juneau.marshall.ContextSession

checkForWarnings, getContext, getSessionProperties, getWarnings, isDebug, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.juneau.commons.conversion.ConverterSession

get

Constructor Details

XmlParserSession

protected XmlParserSession(XmlParserSession.Builder<?> builder)

Constructor.

Parameters:

builder - The builder for this object.

Method Details

create

public static XmlParserSession.Builder<?> create(XmlParser ctx)

Creates a new builder for this object.

Parameters:

ctx - The context creating this session.
Cannot be null.

Returns:

A new builder.

decodeString

protected final String decodeString(String s)

Decodes and trims the specified string.

Any '_x####_' sequences in the string will be decoded.

Parameters:

s - The string to be decoded.
Can be null (returns null).

Returns:

The decoded string, or null if the input was null.

doRead

protected <T> T doRead(ParserPipe pipe,
 ClassMeta<T> type)
                throws IOException,
ParseException,
ExecutableException

Description copied from class: ParserSession

Workhorse method.

Subclasses are expected to implement this method or Parser.doRead(ParserSession,ParserPipe,ClassMeta).

The default implementation of this method simply calls Parser.doRead(ParserSession,ParserPipe,ClassMeta).

Overrides:

doRead in class ParserSession

Type Parameters:

T - The class type of the object to create.

Parameters:

pipe - Where to get the input from.

type - The class type of the object to create. If null or Object.class, object type is based on what's being parsed. For example, when parsing JSON text, it may return a String, Number, JsonMap, etc...

Returns:

The parsed object.

Throws:

IOException - Thrown by underlying stream.

ParseException - Malformed input encountered.

ExecutableException - Exception occurred on invoked constructor/method/field.

doReadIntoCollection

protected <E> Collection<E> doReadIntoCollection(ParserPipe pipe,
 Collection<E> c,
 Type elementType)
                                          throws Exception

Description copied from class: ParserSession

Implementation method.

Default implementation throws an UnsupportedOperationException.

Overrides:

doReadIntoCollection in class ParserSession

Type Parameters:

E - The element type.

Parameters:

pipe - The parser input.

c - The collection being loaded.

elementType - The class type of the elements, or null to default to whatever is being parsed.

Returns:

The same collection that was passed in to allow this method to be chained.

Throws:

Exception - If thrown from underlying stream, or if the input contains a syntax error or is malformed.

doReadIntoMap

protected <K,
V> Map<K,V> doReadIntoMap(ParserPipe pipe,
 Map<K,V> m,
 Type keyType,
 Type valueType)
                                throws Exception

Description copied from class: ParserSession

Implementation method.

Default implementation throws an UnsupportedOperationException.

Overrides:

doReadIntoMap in class ParserSession

Type Parameters:

K - The key type.

V - The value type.

Parameters:

pipe - The parser input.

m - The map being loaded.

keyType - The class type of the keys, or null to default to String.class.

valueType - The class type of the values, or null to default to whatever is being parsed.

Returns:

The same map that was passed in to allow this method to be chained.

Throws:

Exception - If thrown from underlying stream, or if the input contains a syntax error or is malformed.

readRecords

public RecordReader readRecords(Object input)
                         throws IOException

Opens a whole-value pull-parser cursor over an XML document, bound to this live session.

Because XML's wire format (attributes, namespaces, mixed content) is non-trivial to expose as a fine-grained token cursor, this implementation supports only the cursor-level POJO bridge — read(...) delegates to the polymorphic ParserSession.read(Object, Class) entry point.

Specified by:

readRecords in interface RecordReadable

Parameters:

input - The input.

Returns:

A new RecordReader cursor.

Throws:

IOException - If a problem occurred opening the underlying input.

readArrayRecords

public RecordReader readArrayRecords(Object input)
                              throws IOException

Buffered array-element RecordReader for XML, bound to this live session. Calls parse(input, List.class, Object.class) once and iterates the result.

For caller-specified-root semantics use readArrayRecords(Object, String).

Specified by:

readArrayRecords in interface ArrayRecordReadable

Parameters:

input - The input.

Returns:

A buffered RecordReader.

Throws:

IOException - If a problem occurred reading the input.

readArrayRecords

public RecordReader readArrayRecords(Object input,
 String rootElementName)
                              throws IOException

Buffered array-element RecordReader that honors the caller-specified root element name.

The document is parsed once into a generic structure and the records to yield are selected by the supplied rootElementName:

• If the document root is a wrapper element (parses to a Map) that contains a child named rootElementName, that child's value supplies the records (a repeated child element parses to a List; a single occurrence yields one record). Sibling elements with other names are ignored.
• If the document root is an array wrapper (parses to a List, e.g. Juneau's <array> envelope), its already-unwrapped elements are the records and the hint is a no-op.
• A scalar root yields a single record.

A null rootElementName is equivalent to readArrayRecords(Object). The cursor is buffered (RecordReader.isStreaming() == false); see 175ab Item 3 for why true element-at-a-time XML streaming is left for a demand-driven StAX cursor.

Specified by:

readArrayRecords in interface ArrayRecordReadable

Parameters:

input - The input.

rootElementName - The name of the wrapping/child element whose occurrences are the records. null defers to readArrayRecords(Object).

Returns:

A buffered RecordReader.

Throws:

IOException - If a problem occurred reading the input.

isRecordStreaming

public boolean isRecordStreaming()

The XML record cursor is buffered/RecordAdapter-backed, not O(1) streaming.

Specified by:

isRecordStreaming in interface RecordReadable

Returns:

Always false.

isArrayRecordStreaming

public boolean isArrayRecordStreaming()

The XML array-record cursor is buffered/RecordAdapter-backed, not O(1) streaming.

Specified by:

isArrayRecordStreaming in interface ArrayRecordReadable

Returns:

Always false.

getElementText

protected String getElementText(XmlReader r)
                         throws XMLStreamException,
IOException,
ParseException

Returns the text content of the current XML element.

Any '_x####_' sequences in the string will be decoded.

Leading and trailing whitespace (unencoded) will be trimmed from the result.

Parameters:

r - The reader to read the element text from.
Must not be null.

Returns:

The decoded text. null if the text consists of the sequence '_x0000_'.

Throws:

XMLStreamException - Thrown by underlying reader.

IOException - Thrown by underlying stream.

ParseException - Malformed input encountered.

getEventAllocator

protected final XMLEventAllocator getEventAllocator()

XML event allocator.

Returns:

The XMLEventAllocator associated with this parser, or null if there isn't one.

See Also:

• XmlParser.Builder.eventAllocator(Class)

getReporter

protected final XMLReporter getReporter()

XML reporter.

Returns:

The XMLReporter associated with this parser, or null if there isn't one.

See Also:

• XmlParser.Builder.reporter(Class)

getResolver

protected final XMLResolver getResolver()

XML resolver.

Returns:

The XMLResolver associated with this parser, or null if there isn't one.

See Also:

• XmlParser.Builder.resolver(Class)

getXmlBeanMeta

protected XmlBeanMeta getXmlBeanMeta(BeanMeta<?> bm)

Returns the language-specific metadata on the specified bean.

Parameters:

bm - The bean to return the metadata on.

Returns:

The metadata.

getXmlBeanPropertyMeta

protected XmlBeanPropertyMeta getXmlBeanPropertyMeta(BeanPropertyMeta bpm)

Returns the language-specific metadata on the specified bean property.

Parameters:

bpm - The bean property to return the metadata on.

Returns:

The metadata.

getXmlClassMeta

protected XmlClassMeta getXmlClassMeta(ClassMeta<?> cm)

Returns the language-specific metadata on the specified class.

Parameters:

cm - The class to return the metadata on.

Returns:

The metadata.

getXmlReader

protected final XmlReader getXmlReader(ParserPipe pipe)
                                throws IOException,
XMLStreamException

Wrap the specified reader in a STAX reader based on settings in this context.

Parameters:

pipe - The parser input.
Must not be null.

Returns:

The new STAX reader.

Throws:

IOException - Thrown by underlying stream.

XMLStreamException - Unexpected XML processing error.

isPreserveRootElement

protected final boolean isPreserveRootElement()

Preserve root element during generalized parsing.

Returns:

true if when parsing into a generic JsonMap, the map will contain a single entry whose key is the root element name.

See Also:

• XmlParser.Builder.preserveRootElement()

isValidating

protected final boolean isValidating()

Enable validation.

Returns:

true if XML document will be validated.

See Also:

• XmlParser.Builder.validating()

isWhitespaceElement

protected boolean isWhitespaceElement(XmlReader r)

Returns true if the current element is a whitespace element.

For the XML parser, this always returns false. However, the HTML parser defines various whitespace elements such as "br" and "sp".

Parameters:

r - The XML stream reader to read the current event from.

Returns:

true if the current element is a whitespace element.

readAnything

protected <T> T readAnything(ClassMeta<T> eType,
 String currAttr,
 XmlReader r,
 Object outer,
 boolean isRoot,
 BeanPropertyMeta pMeta)
                      throws IOException,
ParseException,
ExecutableException,
XMLStreamException

Workhorse method.

Type Parameters:

T - The expected type of object.

Parameters:

eType - The expected type of object.
Can be null, in which case the generic Object type is used and the actual type is auto-detected from the XML.

currAttr - The current bean property name.
Can be null if not being parsed as a named bean property (e.g. the root value).

r - The reader.
Must not be null.

outer - The outer object.
Can be null if there is no enclosing (outer) object; the parsed object is then not linked to a parent.

isRoot - If true, then we're serializing a root element in the document.

pMeta - The bean property metadata.
Can be null if no bean property metadata applies (e.g. the root value or an unknown property).

Returns:

The parsed object, or null if the element represents a null value.

Throws:

IOException - Thrown by underlying stream.

ParseException - Malformed input encountered.

ExecutableException - Exception occurred on invoked constructor/method/field.

XMLStreamException - Malformed XML encountered.

readText

protected String readText(XmlReader r)
                   throws IOException,
XMLStreamException,
ParseException

Parses the current element as text.

Parameters:

r - The input reader.
Must not be null.

Returns:

The parsed text.

Throws:

XMLStreamException - Thrown by underlying reader.

IOException - Thrown by underlying stream.

ParseException - Malformed input encountered.

readWhitespaceElement

protected String readWhitespaceElement(XmlReader r)
                                throws IOException,
XMLStreamException,
ParseException

Parses the current whitespace element.

For the XML parser, this always returns null since there is no concept of a whitespace element. However, the HTML parser defines various whitespace elements such as "br" and "sp".

Parameters:

r - The XML stream reader to read the current event from.

Returns:

The whitespace character or characters.

Throws:

XMLStreamException - Thrown by underlying reader.

IOException - Thrown by underlying stream.

ParseException - Malformed input encountered.