org.apache.juneau.parser

Class Parser

java.lang.Object

org.apache.juneau.Context

org.apache.juneau.BeanContext

org.apache.juneau.parser.Parser

Direct Known Subclasses:

InputStreamParser, ReaderParser

public abstract class Parser
extends BeanContext

Parent class for all Juneau parsers.

Valid data conversions

Parsers can parse any parsable POJO types, as specified in the POJO Categories.

Some examples of conversions are shown below...

Data type	Class type	JSON example	XML example	Class examples
object	Maps, Java beans	{name:'John Smith',age:21}	<object> <name type='string'>John Smith</name> <age type='number'>21</age> </object>	HashMap, TreeMap<String,Integer>
array	Collections, Java arrays	[1,2,3]	<array> <number>1</number> <number>2</number> <number>3</number> </array>	List<Integer>, int[], Float[], Set<Person>
number	Numbers	123	<number>123</number>	Integer, Long, Float, int
boolean	Booleans	true	<boolean>true</boolean>	Boolean
string	CharSequences	'foobar'	<string>foobar</string>	String, StringBuilder

In addition, any class types with PojoSwaps associated with them on the registered bean context can also be passed in.

For example, if the CalendarSwap transform is used to generalize Calendar objects to String objects. When registered with this parser, you can construct Calendar objects from Strings using the following syntax...

Calendar c = parser.parse("'Sun Mar 03 04:05:06 EST 2001'", GregorianCalendar.class);

If Object.class is specified as the target type, then the parser automatically determines the data types and generates the following object types...

JSON type	Class type
object	ObjectMap
array	ObjectList
number	Number (depending on length and format, could be Integer, Double, Float, etc...)
boolean	Boolean
string	String

Field Summary

Fields

Modifier and Type	Field and Description
static String	PARSER_autoCloseStreams Configuration property: Auto-close streams.
static String	PARSER_fileCharset Configuration property: File charset.
static String	PARSER_inputStreamCharset Configuration property: Input stream charset.
static String	PARSER_listener Configuration property: Parser listener.
static String	PARSER_strict Configuration property: Strict mode.
static String	PARSER_trimStrings Configuration property: Trim parsed strings.
static String	PARSER_unbuffered Configuration property: Unbuffered.

Fields inherited from class org.apache.juneau.BeanContext

BEAN_beanClassVisibility, BEAN_beanConstructorVisibility, BEAN_beanDictionary, BEAN_beanDictionary_add, BEAN_beanDictionary_remove, BEAN_beanFieldVisibility, BEAN_beanFilters, BEAN_beanFilters_add, BEAN_beanFilters_remove, BEAN_beanMapPutReturnsOldValue, BEAN_beanMethodVisibility, BEAN_beansRequireDefaultConstructor, BEAN_beansRequireSerializable, BEAN_beansRequireSettersForGetters, BEAN_beansRequireSomeProperties, BEAN_beanTypePropertyName, BEAN_debug, BEAN_excludeProperties, BEAN_ignoreInvocationExceptionsOnGetters, BEAN_ignoreInvocationExceptionsOnSetters, BEAN_ignorePropertiesWithoutSetters, BEAN_ignoreUnknownBeanProperties, BEAN_ignoreUnknownNullBeanProperties, BEAN_implClasses, BEAN_includeProperties, BEAN_locale, BEAN_mediaType, BEAN_notBeanClasses, BEAN_notBeanClasses_add, BEAN_notBeanClasses_remove, BEAN_notBeanPackages, BEAN_notBeanPackages_add, BEAN_notBeanPackages_remove, BEAN_pojoSwaps, BEAN_pojoSwaps_add, BEAN_pojoSwaps_remove, BEAN_propertyNamer, BEAN_sortProperties, BEAN_timeZone, BEAN_useInterfaceProxies, BEAN_useJavaBeanIntrospector, DEFAULT_SORTED

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.
ParserBuilder	builder() Creates a builder from this context object.
static ParserBuilder	create() Instantiates a new clean-slate ParserBuilder object.
ParserSessionArgs	createDefaultSessionArgs() Defines default session arguments used when calling the Context.createSession() method.
ParserSession	createSession() Create a new bean session based on the properties defined on this context.
abstract ParserSession	createSession(ParserSessionArgs args) Create the session object that will be passed in to the parse method.
MediaType[]	getMediaTypes() Returns the media types handled based on the values passed to the consumes constructor parameter.
MediaType	getPrimaryMediaType() Returns the first media type handled based on the values passed to the consumes constructor parameter.
boolean	isReaderParser() Returns true if this parser subclasses from ReaderParser.
<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.

Methods inherited from class org.apache.juneau.BeanContext

_class, createBeanSession, createBeanSession, createDefaultBeanSessionArgs, createSession, createSession, dumpCacheStats, getBeanMeta, getBeanRegistry, getBeanTypePropertyName, getClassMeta, getClassMeta, getClassMetaForObject, getExcludeProperties, getImplClassConstructor, getIncludeProperties, hasSameCache, isBean, isNotABean, newInstance, newInstance, newInstanceFromOuter, object, resolveClassMeta, string

Methods inherited from class org.apache.juneau.Context

equals, getArrayProperty, getArrayProperty, getBooleanProperty, getClassArrayProperty, getClassArrayProperty, getClassArrayProperty, getClassListProperty, getClassListProperty, getClassMapProperty, getClassMapProperty, getClassProperty, getClassSetProperty, getClassSetProperty, getInstanceArrayProperty, getInstanceArrayProperty, getInstanceArrayProperty, getInstanceProperty, getInstanceProperty, getInstanceProperty, getIntegerProperty, getListProperty, getListProperty, getLongProperty, getMapProperty, getProperty, getProperty, getPropertyKeys, getPropertyStore, getSetProperty, getSetProperty, getStringProperty, hashCode, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

PARSER_autoCloseStreams

public static final String PARSER_autoCloseStreams

Configuration property: Auto-close streams.

Property:

• Name: "Parser.autoCloseStreams.b"
• Data type: Boolean
• Default: false
• Session-overridable: true
• Methods:
  • ParserBuilder.autoCloseStreams(boolean)
  • ParserBuilder.autoCloseStreams()

Description:

If true, InputStreams and Readers passed into parsers will be closed after parsing is complete.

Example:

// Create a parser using strict mode. ReaderParser p = JsonParser. .create() .autoCloseStreams() .build(); // Same, but use property. ReaderParser p = JsonParser. .create() .set(PARSER_autoCloseStreams, true) .build(); Reader r = new FileReader("/tmp/myfile.json"); MyBean myBean = p.parse(r, MyBean.class); assertTrue(r.isClosed());

See Also:

Constant Field Values

PARSER_fileCharset

public static final String PARSER_fileCharset

Configuration property: File charset.

Property:

• Name: "Parser.fileCharset.s"
• Data type: String
• Default: "DEFAULT"
• Session-overridable: true
• Methods:
  • ParserBuilder.fileCharset(String)
  • ParserBuilder.fileCharset(Charset)

Description:

The character set to use for reading Files from the file system.

Used when passing in files to parse(Object, Class).

"DEFAULT" can be used to indicate the JVM default file system charset.

Example:

// Create a parser that reads UTF-8 files. ReaderParser p = JsonParser. .create() .fileCharset("UTF-8") .build(); // Same, but use property. ReaderParser p = JsonParser. .create() .set(PARSER_fileCharset, "UTF-8") .build(); // Use it to read a UTF-8 encoded file. MyBean myBean = p.parse(new File("MyBean.txt"), MyBean.class);

See Also:

Constant Field Values

PARSER_inputStreamCharset

public static final String PARSER_inputStreamCharset

Configuration property: Input stream charset.

Property:

• Name: "Parser.inputStreamCharset.s"
• Data type: String
• Default: "UTF-8"
• Session-overridable: true
• Methods:
  • ParserBuilder.inputStreamCharset(String)
  • ParserBuilder.inputStreamCharset(Charset)

Description:

The character set to use for converting InputStreams and byte arrays to readers.

Used when passing in input streams and byte arrays to parse(Object, Class).

Example:

// Create a parser that reads UTF-8 files. ReaderParser p = JsonParser. .create() .inputStreamCharset("UTF-8") .build(); // Same, but use property. ReaderParser p = JsonParser. .create() .set(PARSER_inputStreamCharset, "UTF-8") .build(); // Use it to read a UTF-8 encoded input stream. MyBean myBean = p.parse(new FileInputStream("MyBean.txt"), MyBean.class);

See Also:

Constant Field Values

PARSER_listener

public static final String PARSER_listener

Configuration property: Parser listener.

Property:

• Name: "Parser.listener.c"
• Data type: Class<? extends ParserListener>
• Default: null
• Session-overridable: true
• Methods:
  • ParserBuilder.listener(Class)

Description:

Class used to listen for errors and warnings that occur during parsing.

Example:

// Define our parser listener. // Simply captures all unknown bean property events. public class MyParserListener extends ParserListener { // A simple property to store our events. public List<String> events = new LinkedList<>(); @Override public <T> void onUnknownBeanProperty(ParserSession session, ParserPipe pipe, String propertyName, Class<T> beanClass, T bean, int line, int col) { events.add(propertyName + "," + line + "," + col); } } // Create a parser using our listener. ReaderParser p = JsonParser. .create() .listener(MyParserListener.class) .build(); // Same, but use property. ReaderParser p = JsonParser. .create() .set(PARSER_listener, MyParserListener.class) .build(); // Create a session object. // Needed because listeners are created per-session. try (ReaderParserSession s = p.createSession()) { // Parse some JSON object. MyBean myBean = s.parse("{...}", MyBean.class); // Get the listener. MyParserListener l = s.getListener(MyParserListener.class); // Dump the results to the console. JsonSerializer.DEFAULT_LAX.println(l.events); }

See Also:

Constant Field Values

PARSER_strict

public static final String PARSER_strict

Configuration property: Strict mode.

Property:

• Name: "Parser.strict.b"
• Data type: Boolean
• Default: false
• Session-overridable: true
• Methods:
  • ParserBuilder.strict(boolean)
  • ParserBuilder.strict()

Description:

If true, strict mode for the parser is enabled.

Strict mode can mean different things for different parsers.

Parser class	Strict behavior
All reader-based parsers	When enabled, throws ParseExceptions on malformed charset input. Otherwise, malformed input is ignored.
JsonParser	When enabled, throws exceptions on the following invalid JSON syntax: Unquoted attributes. Missing attribute values. Concatenated strings. Javascript comments. Numbers and booleans when Strings are expected. Numbers valid in Java but not JSON (e.g. octal notation, etc...)

Example:

// Create a parser using strict mode. ReaderParser p = JsonParser. .create() .strict() .build(); // Same, but use property. ReaderParser p = JsonParser. .create() .set(PARSER_strict, true) .build(); // Use it. try { String json = "{unquotedAttr:'value'}"; MyBean myBean = p.parse(json, MyBean.class); } catch (ParseException e) { assertTrue(e.getMessage().contains("Unquoted attribute detected."); }

See Also:

Constant Field Values

PARSER_trimStrings

public static final String PARSER_trimStrings

Configuration property: Trim parsed strings.

Property:

• Name: "Parser.trimStrings.b"
• Data type: Boolean
• Default: false
• Session-overridable: true
• Methods:
  • ParserBuilder.trimStrings(boolean)
  • ParserBuilder.trimStrings()

Description:

If true, string values will be trimmed of whitespace using String.trim() before being added to the POJO.

Example:

// Create a parser with trim-strings enabled. ReaderParser p = JsonParser. .create() .trimStrings() .build(); // Same, but use property. ReaderParser p = JsonParser. .create() .set(PARSER_trimStrings, true) .build(); // Use it. String json = "{foo:' bar '}"; Map<String,String> m = p.parse(json, HashMap.class, String.class, String.class); assertEquals("bar", m.get("foo"));

See Also:

Constant Field Values

PARSER_unbuffered

public static final String PARSER_unbuffered

Configuration property: Unbuffered.

Property:

• Name: "Parser.unbuffered.b"
• Data type: Boolean
• Default: false
• Session-overridable: true
• Methods:
  • ParserBuilder.unbuffered(boolean)
  • ParserBuilder.unbuffered()

Description:

If true, don't use internal buffering during parsing.

This is useful in cases when you want to parse the same input stream or reader multiple times because it may contain multiple independent POJOs to parse.
Buffering would cause the parser to read past the current POJO in the stream.

Example:

// Create a parser using strict mode. ReaderParser p = JsonParser. .create() .unbuffered() .build(); // Same, but use property. ReaderParser p = JsonParser. .create() .set(PARSER_unbuffered, true) .build(); // If you're calling parse on the same input multiple times, use a session instead of the parser directly. // It's more efficient because we don't need to recalc the session settings again. ReaderParserSession s = p.createSession(); // Read input with multiple POJOs Reader json = new StringReader("{foo:'bar'}{foo:'baz'}"); MyBean myBean1 = s.parse(json, MyBean.class); MyBean myBean2 = s.parse(json, MyBean.class);

Notes:

• This only allows for multi-input streams for the following parsers:
  • JsonParser
  • UonParser
  It has no effect on the following parsers:
  • MsgPackParser - It already doesn't use buffering.
  • XmlParser, HtmlParser - These use StAX which doesn't allow for more than one root element anyway.
  • RDF parsers - These read everything into an internal model before any parsing begins.

If true, don't use internal buffering during parsing.

See Also:

Constant Field Values

Method Detail

builder

public ParserBuilder builder()

Description copied from class: Context

Creates a builder from this context object.

Builders are used to define new contexts (e.g. serializers, parsers) based on existing configurations.

Overrides:

builder in class BeanContext

Returns:

A new ContextBuilder object.

create

public static ParserBuilder create()

Instantiates a new clean-slate ParserBuilder object.

This is equivalent to simply calling new ParserBuilder().

Note that this method creates a builder initialized to all default settings, whereas builder() copies the settings of the object called on.

Returns:

A new ParserBuilder object.

isReaderParser

public boolean isReaderParser()

Returns true if this parser subclasses from ReaderParser.

Returns:

true if this parser subclasses from ReaderParser.

createSession

public abstract ParserSession createSession(ParserSessionArgs args)

Create the session object that will be passed in to the parse method.

It's up to implementers to decide what the session object looks like, although typically it's going to be a subclass of ParserSession.

Parameters:

args - Runtime arguments.

Returns:

The new session.

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_inputStreamCharset property value).
• byte[] containing UTF-8 encoded text (or charset defined by PARSER_inputStreamCharset property value).
• File containing system encoded text (or charset defined by 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.

createSession

public final ParserSession createSession()

Description copied from class: BeanContext

Create a new bean session based on the properties defined on this context.

Use this method for creating sessions if you don't need to override any properties or locale/timezone currently set on this context.

Overrides:

createSession in class BeanContext

Returns:

A new session object.

createDefaultSessionArgs

public final ParserSessionArgs createDefaultSessionArgs()

Description copied from class: Context

Defines default session arguments used when calling the Context.createSession() method.

Overrides:

createDefaultSessionArgs in class BeanContext

Returns:

A SessionArgs object, possibly a read-only reusable instance.

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.

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.

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.

getMediaTypes

public final MediaType[] getMediaTypes()

Returns the media types handled based on the values passed to the consumes constructor parameter.

Returns:

The list of media types. Never null.

getPrimaryMediaType

public final MediaType getPrimaryMediaType()

Returns the first media type handled based on the values passed to the consumes constructor parameter.

Returns:

The media type.

asMap

public ObjectMap asMap()

Description copied from class: Context

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

Overrides:

asMap in class BeanContext

Returns:

A new map containing the properties defined on this context.