org.apache.juneau.parser

Class ParserSession

java.lang.Object

org.apache.juneau.Session

org.apache.juneau.BeanSession

org.apache.juneau.parser.ParserSession

Direct Known Subclasses:

InputStreamParserSession, ReaderParserSession

public abstract class ParserSession
extends BeanSession

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

This class is NOT thread safe. It is typically discarded after one-time use although it can be reused against multiple inputs.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ParserSession(Parser ctx, ParserSessionArgs args) Create a new session using properties specified in the context.
protected	ParserSession(ParserSessionArgs args) Default constructor.

Method Summary

Modifier and Type	Method and Description
ObjectMap	asMap() Returns the properties defined on this bean context as a simple map for debugging purposes.
protected Object	cast(ObjectMap m, BeanPropertyMeta pMeta, ClassMeta<?> eType) Converts the specified ObjectMap into a bean identified by the "_type" property in the map.
protected <T> T	convertAttrToType(Object outer, String s, ClassMeta<T> type) Converts the specified string to the specified type.
ParserPipe	createPipe(Object input) Wraps the specified input object into a ParserPipe object so that it can be easily converted into a stream or reader.
protected abstract <T> T	doParse(ParserPipe pipe, ClassMeta<T> type) Workhorse method.
protected <E> Collection<E>	doParseIntoCollection(ParserPipe pipe, Collection<E> c, Type elementType) Implementation method.
protected <K,V> Map<K,V>	doParseIntoMap(ParserPipe pipe, Map<K,V> m, Type keyType, Type valueType) Implementation method.
protected ClassMeta<?>	getClassMeta(String typeName, BeanPropertyMeta pMeta, ClassMeta<?> eType) Give the specified dictionary name, resolve it to a class.
protected Method	getJavaMethod() Returns the Java method that invoked this parser.
ObjectMap	getLastLocation() Returns information used to determine at what location in the parse a failure occurred.
ParserListener	getListener() Returns the listener associated with this session.
<T extends ParserListener> T	getListener(Class<T> c) Returns the listener associated with this session.
protected Object	getOuter() Returns the outer object used for instantiating top-level non-static member classes.
abstract boolean	isReaderParser() Returns true if this parser subclasses from ReaderParser.
protected boolean	isStrict() Returns the Parser.PARSER_strict setting value for this session.
protected boolean	isTrimStrings() Returns the Parser.PARSER_trimStrings setting value for this session.
protected <T> void	onUnknownProperty(ParserPipe pipe, String propertyName, BeanMap<T> beanMap, int line, int col) Method that gets called when an unknown bean property name is encountered.
<T> T	parse(Object input, Class<T> type) Same as parse(Object, Type, Type...) except optimized for a non-parameterized class.
<T> T	parse(Object input, ClassMeta<T> type) Same as parse(Object, Type, Type...) except the type has already been converted into a ClassMeta object.
<T> T	parse(Object input, Type type, Type... args) Parses input into the specified object type.
Object[]	parseArgs(Object input, Type[] argTypes) Parses the specified array input with each entry in the object defined by the argTypes argument.
<E> Collection<E>	parseIntoCollection(Object input, Collection<E> c, Type elementType) Parses the contents of the specified reader and loads the results into the specified collection.
<K,V> Map<K,V>	parseIntoMap(Object input, Map<K,V> m, Type keyType, Type valueType) Parses the contents of the specified reader and loads the results into the specified map.
protected void	setCurrentClass(ClassMeta<?> currentClass) Sets the current class being parsed for proper error messages.
protected void	setCurrentProperty(BeanPropertyMeta currentProperty) Sets the current bean property being parsed for proper error messages.
protected static void	setName(ClassMeta<?> cm, Object o, Object name) Convenience method for calling the @NameProperty method on the specified object if it exists.
protected static void	setParent(ClassMeta<?> cm, Object o, Object parent) Convenience method for calling the @ParentProperty method on the specified object if it exists.
protected <K> K	trim(K o) Trims the specified object if it's a String and isTrimStrings() returns true.
protected String	trim(String s) Trims the specified string if isTrimStrings() returns true.

Methods inherited from class org.apache.juneau.BeanSession

_class, checkForWarnings, convertToMemberType, convertToMemberType, convertToType, convertToType, convertToType, getArgsClassMeta, getBeanMeta, getBeanRegistry, getBeanTypePropertyName, getClassMeta, getClassMeta, getClassMetaForObject, getLocale, getMediaType, getStringBuilder, getTimeZone, isBean, isBean, isDebug, isIgnoreUnknownBeanProperties, newBean, newBean, newBeanMap, newBeanMap, newInstance, newInstance, newInstanceFromOuter, object, returnStringBuilder, string, toArray, toBeanMap, toBeanMap

Methods inherited from class org.apache.juneau.Session

addToCache, addToCache, addWarning, getClassProperty, getFromCache, getInstanceArrayProperty, getInstanceProperty, getLogger, getProperties, getProperty, getProperty, getProperty, getPropertyKeys, getWarnings, hasWarnings, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

ParserSession

protected ParserSession(Parser ctx,
                        ParserSessionArgs args)

Create a new session using properties specified in the context.

Parameters:

ctx - The context creating this session object. The context contains all the configuration settings for this object.

args - Runtime session arguments.

ParserSession

protected ParserSession(ParserSessionArgs args)

Default constructor.

Parameters:

args - Runtime session arguments.

Method Detail

asMap

public ObjectMap asMap()

Description copied from class: Session

Returns the properties defined on this bean context as a simple map for debugging purposes.

Overrides:

asMap in class BeanSession

Returns:

A new map containing the properties defined on this context.

doParse

protected abstract <T> T doParse(ParserPipe pipe,
                                 ClassMeta<T> type)
                          throws Exception

Workhorse method. Subclasses are expected to implement this method.

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, ObjectMap, etc...

Returns:

The parsed object.

Throws:

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

isReaderParser

public abstract boolean isReaderParser()

Returns true if this parser subclasses from ReaderParser.

Returns:

true if this parser subclasses from ReaderParser.

createPipe

public final ParserPipe createPipe(Object input)

Wraps the specified input object into a ParserPipe object so that it can be easily converted into a stream or reader.

Parameters:

input - The input.
For character-based parsers, this can be any of the following types:

• null
• Reader
• CharSequence
• InputStream containing UTF-8 encoded text (or whatever the encoding specified by Parser.PARSER_inputStreamCharset).
• byte[] containing UTF-8 encoded text (or whatever the encoding specified by Parser.PARSER_inputStreamCharset).
• File containing system encoded text (or whatever the encoding specified by Parser.PARSER_fileCharset).

For byte-based parsers, this can be any of the following types:

• null
• InputStream
• byte[]
• File

Returns:

A new ParserPipe wrapper around the specified input object.

getLastLocation

public final ObjectMap getLastLocation()

Returns information used to determine at what location in the parse a failure occurred.

Returns:

A map, typically containing something like {line:123,column:456,currentProperty:"foobar"}

getJavaMethod

protected final Method getJavaMethod()

Returns the Java method that invoked this parser.

When using the REST API, this is the Java method invoked by the REST call. Can be used to access annotations defined on the method or class.

Returns:

The Java method that invoked this parser.

getOuter

protected final Object getOuter()

Returns the outer object used for instantiating top-level non-static member classes.

When using the REST API, this is the servlet object.

Returns:

The outer object.

setCurrentProperty

protected final void setCurrentProperty(BeanPropertyMeta currentProperty)

Sets the current bean property being parsed for proper error messages.

Parameters:

currentProperty - The current property being parsed.

setCurrentClass

protected final void setCurrentClass(ClassMeta<?> currentClass)

Sets the current class being parsed for proper error messages.

Parameters:

currentClass - The current class being parsed.

isTrimStrings

protected final boolean isTrimStrings()

Returns the Parser.PARSER_trimStrings setting value for this session.

Returns:

The Parser.PARSER_trimStrings setting value for this session.

isStrict

protected final boolean isStrict()

Returns the Parser.PARSER_strict setting value for this session.

Returns:

The Parser.PARSER_strict setting value for this session.

trim

protected final <K> K trim(K o)

Trims the specified object if it's a String and isTrimStrings() returns true.

Parameters:

o - The object to trim.

Returns:

The trimmed string if it's a string.

trim

protected final String trim(String s)

Trims the specified string if isTrimStrings() returns true.

Parameters:

s - The input string to trim.

Returns:

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

cast

protected final Object cast(ObjectMap m,
                            BeanPropertyMeta pMeta,
                            ClassMeta<?> eType)

Converts the specified ObjectMap into a bean identified by the "_type" property in the map.

Parameters:

m - The map to convert to a bean.

pMeta - The current bean property being parsed.

eType - The current expected type being parsed.

Returns:

The converted bean, or the same map if the "_type" entry wasn't found or didn't resolve to a bean.

getClassMeta

protected final ClassMeta<?> getClassMeta(String typeName,
                                          BeanPropertyMeta pMeta,
                                          ClassMeta<?> eType)

Give the specified dictionary name, resolve it to a class.

Parameters:

typeName - The dictionary name to resolve.

pMeta - The bean property we're currently parsing.

eType - The expected type we're currently parsing.

Returns:

The resolved class, or null if the type name could not be resolved.

onUnknownProperty

protected final <T> void onUnknownProperty(ParserPipe pipe,
                                           String propertyName,
                                           BeanMap<T> beanMap,
                                           int line,
                                           int col)
                                    throws ParseException

Method that gets called when an unknown bean property name is encountered.

Type Parameters:

T - The class type of the bean map that doesn't have the expected property.

Parameters:

pipe - The parser input.

propertyName - The unknown bean property name.

beanMap - The bean that doesn't have the expected property.

line - The line number where the property was found. -1 if line numbers are not available.

col - The column number where the property was found. -1 if column numbers are not available.

Throws:

ParseException - Automatically thrown if BeanContext.BEAN_ignoreUnknownBeanProperties setting on this parser is false

parse

public final <T> T parse(Object input,
                         Type type,
                         Type... args)
                  throws ParseException

Parses input into the specified object type.

The type can be a simple type (e.g. beans, strings, numbers) or parameterized type (collections/maps).

Examples:

ReaderParser p = JsonParser.DEFAULT; // Parse into a linked-list of strings. List l = p.parse(json, LinkedList.class, String.class); // Parse into a linked-list of beans. List l = p.parse(json, LinkedList.class, MyBean.class); // Parse into a linked-list of linked-lists of strings. List l = p.parse(json, LinkedList.class, LinkedList.class, String.class); // Parse into a map of string keys/values. Map m = p.parse(json, TreeMap.class, String.class, String.class); // Parse into a map containing string keys and values of lists containing beans. Map m = p.parse(json, TreeMap.class, String.class, List.class, MyBean.class);

Collection classes are assumed to be followed by zero or one objects indicating the element type.

Map classes are assumed to be followed by zero or two meta objects indicating the key and value types.

The array can be arbitrarily long to indicate arbitrarily complex data structures.

Notes:

• Use the parse(Object, Class) method instead if you don't need a parameterized map/collection.

Type Parameters:

T - The class type of the object to create.

Parameters:

input - The input.
Character-based parsers can handle the following input class types:

• null
• Reader
• CharSequence
• InputStream containing UTF-8 encoded text (or charset defined by Parser.PARSER_inputStreamCharset property value).
• byte[] containing UTF-8 encoded text (or charset defined by Parser.PARSER_inputStreamCharset property value).
• File containing system encoded text (or charset defined by Parser.PARSER_fileCharset property value).

Stream-based parsers can handle the following input class types:

• null
• InputStream
• byte[]
• File

type - The object type to create.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType

args - The type arguments of the class if it's a collection or map.
Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType
Ignored if the main type is not a map or collection.

Returns:

The parsed object.

Throws:

ParseException - If the input contains a syntax error or is malformed, or is not valid for the specified type.

See Also:

for argument syntax for maps and collections.

parse

public final <T> T parse(Object input,
                         Class<T> type)
                  throws ParseException

Same as parse(Object, Type, Type...) except optimized for a non-parameterized class.

This is the preferred parse method for simple types since you don't need to cast the results.

Examples:

ReaderParser p = JsonParser.DEFAULT; // Parse into a string. String s = p.parse(json, String.class); // Parse into a bean. MyBean b = p.parse(json, MyBean.class); // Parse into a bean array. MyBean[] ba = p.parse(json, MyBean[].class); // Parse into a linked-list of objects. List l = p.parse(json, LinkedList.class); // Parse into a map of object keys/values. Map m = p.parse(json, TreeMap.class);

Type Parameters:

T - The class type of the object being created.

Parameters:

input - The input. See parse(Object, Type, Type...) for details.

type - The object type to create.

Returns:

The parsed object.

Throws:

ParseException - If the input contains a syntax error or is malformed, or is not valid for the specified type.

parse

public final <T> T parse(Object input,
                         ClassMeta<T> type)
                  throws ParseException

Same as parse(Object, Type, Type...) except the type has already been converted into a ClassMeta object.

This is mostly an internal method used by the framework.

Type Parameters:

T - The class type of the object being created.

Parameters:

input - The input. See parse(Object, Type, Type...) for details.

type - The object type to create.

Returns:

The parsed object.

Throws:

ParseException - If the input contains a syntax error or is malformed, or is not valid for the specified type.

parseIntoMap

public final <K,V> Map<K,V> parseIntoMap(Object input,
                                         Map<K,V> m,
                                         Type keyType,
                                         Type valueType)
                                  throws ParseException

Parses the contents of the specified reader and loads the results into the specified map.

Reader must contain something that serializes to a map (such as text containing a JSON object).

Used in the following locations:

• The various character-based constructors in ObjectMap (e.g. ObjectMap.ObjectMap(CharSequence,Parser)).

Type Parameters:

K - The key class type.

V - The value class type.

Parameters:

input - The input. See parse(Object, ClassMeta) for supported input types.

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:

ParseException - If the input contains a syntax error or is malformed, or is not valid for the specified type.

UnsupportedOperationException - If not implemented.

doParseIntoMap

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

Implementation method.

Default implementation throws an UnsupportedOperationException.

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.

parseIntoCollection

public final <E> Collection<E> parseIntoCollection(Object input,
                                                   Collection<E> c,
                                                   Type elementType)
                                            throws ParseException

Parses the contents of the specified reader and loads the results into the specified collection.

Used in the following locations:

• The various character-based constructors in ObjectList (e.g. ObjectList.ObjectList(CharSequence,Parser).

Type Parameters:

E - The element class type.

Parameters:

input - The input. See parse(Object, ClassMeta) for supported input types.

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:

ParseException - If the input contains a syntax error or is malformed, or is not valid for the specified type.

UnsupportedOperationException - If not implemented.

doParseIntoCollection

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

Implementation method.

Default implementation throws an UnsupportedOperationException.

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.

parseArgs

public final Object[] parseArgs(Object input,
                                Type[] argTypes)
                         throws ParseException

Parses the specified array input with each entry in the object defined by the argTypes argument.

Used for converting arrays (e.g. "[arg1,arg2,...]") into an Object[] that can be passed to the Method.invoke(target, args) method.

Used in the following locations:

• Used to parse argument strings in the PojoIntrospector.invokeMethod(Method, Reader) method.

Parameters:

input - The input. Subclasses can support different input types.

argTypes - Specifies the type of objects to create for each entry in the array.

Returns:

An array of parsed objects.

Throws:

ParseException - If the input contains a syntax error or is malformed, or is not valid for the specified type.

convertAttrToType

protected final <T> T convertAttrToType(Object outer,
                                        String s,
                                        ClassMeta<T> type)
                                 throws Exception

Converts the specified string to the specified type.

Type Parameters:

T - The class type to convert the string to.

Parameters:

outer - The outer object if we're converting to an inner object that needs to be created within the context of an outer object.

s - The string to convert.

type - The class type to convert the string to.

Returns:

The string converted as an object of the specified type.

Throws:

Exception - If the input contains a syntax error or is malformed, or is not valid for the specified type.

setParent

protected static final void setParent(ClassMeta<?> cm,
                                      Object o,
                                      Object parent)
                               throws Exception

Convenience method for calling the @ParentProperty method on the specified object if it exists.

Parameters:

cm - The class type of the object.

o - The object.

parent - The parent to set.

Throws:

Exception

setName

protected static final void setName(ClassMeta<?> cm,
                                    Object o,
                                    Object name)
                             throws Exception

Convenience method for calling the @NameProperty method on the specified object if it exists.

Parameters:

cm - The class type of the object.

o - The object.

name - The name to set.

Throws:

Exception

getListener

public ParserListener getListener()

Returns the listener associated with this session.

Returns:

The listener associated with this session, or null if there is no listener.

getListener

public <T extends ParserListener> T getListener(Class<T> c)

Returns the listener associated with this session.

Parameters:

c - The listener class to cast to.

Returns:

The listener associated with this session, or null if there is no listener.