Package org.apache.juneau.marshall.marshaller

Class Marshaller

java.lang.Object

org.apache.juneau.marshall.marshaller.Marshaller

Direct Known Subclasses:

CharMarshaller, StreamMarshaller

public abstract class Marshaller
extends Object

Top-level class for a pairing of a Serializer and Parser into a single class with convenience read/write methods.

The general idea is to combine a single serializer and parser inside a simplified API for reading and writing POJOs.

Examples:

// Using instance. Marshaller json = new Json(); MyPojo myPojo = json.read(string, MyPojo.class); String string = json.write(myPojo);

// Using DEFAULT instance. MyPojo myPojo = Json.DEFAULT.read(string, MyPojo.class); String string = Json.DEFAULT.write(myPojo);

See Also:

• Marshallers

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Marshaller(Serializer s, Parser p)	Constructor.

Method Summary

Modifier and Type	Method	Description
Parser	getParser()	Returns the parser associated with this marshaller.
Serializer	getSerializer()	Returns the serializer associated with this marshaller.
final <T> T	read(Object input, Class<T> type)	Same as read(Object, Type, Type...) except optimized for a non-parameterized class.
final <T> T	read(Object input, Type type, Type... args)	Parses input into the specified object type.
RecordReader	readArrayRecords(Object input)	Opens a RecordReader that yields each element of a top-level wire array as a separate record.
RecordReader	readRecords(Object input)	Opens a low-level RecordReader cursor that yields each top-level value as a record.
TokenReader	readTokens(Object input)	Opens a low-level TokenReader cursor over the specified input.
final void	write(Object object, Object output)	Serializes a POJO to the specified output stream or writer.
RecordWriter	writeArrayRecords(Object output)	Opens a RecordWriter that wraps each written value as one element of a top-level wire array.
RecordWriter	writeRecords(Object output)	Opens a low-level RecordWriter cursor that emits each whole value as a record.
TokenWriter	writeTokens(Object output)	Opens a low-level push generator that emits structural events one at a time.

Methods inherited from class java.lang.Object

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

Constructor Details

Marshaller

protected Marshaller(Serializer s,
 Parser p)

Constructor.

Parameters:

s - The serializer to use for serializing output.
Must not be null.

p - The parser to use for parsing input.
Must not be null.

Method Details

getParser

public Parser getParser()

Returns the parser associated with this marshaller.

Returns:

The parser associated with this marshaller.

getSerializer

public Serializer getSerializer()

Returns the serializer associated with this marshaller.

Returns:

The serializer associated with this marshaller.

read

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

Same as read(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:

Marshaller marshaller = Json.DEFAULT; // Parse into a string. String string = marshaller .read(json, String.class); // Parse into a bean. MyBean bean = marshaller .read(json, MyBean.class); // Parse into a bean array. MyBean[] beanArray = marshaller .read(json, MyBean[].class); // Parse into a linked-list of objects. List list = marshaller .read(json, LinkedList.class); // Parse into a map of object keys/values. Map map = marshaller .read(json, TreeMap.class);

Type Parameters:

T - The class type of the object being created.

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

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

• null
• InputStream
• byte[]
• File
• CharSequence containing encoded bytes according to the InputStreamParser.Builder#binaryFormat(BinaryFormat) setting.

type - The object type to create.

Returns:

The parsed object.

Throws:

ParseException - Malformed input encountered.

IOException - Thrown by underlying stream.

read

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

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:

Marshaller marshaller = Json.DEFAULT; // Parse into a linked-list of strings. List list1 = marshaller .read(json, LinkedList.class, String.class); // Parse into a linked-list of beans. List list2 = marshaller .read(json, LinkedList.class, MyBean.class); // Parse into a linked-list of linked-lists of strings. List list3 = marshaller .read(json, LinkedList.class, LinkedList.class, String.class); // Parse into a map of string keys/values. Map map1 = marshaller .read(json, TreeMap.class, String.class, String.class); // Parse into a map containing string keys and values of lists containing beans. Map map2 = marshaller .read(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 read(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 ReaderParser.Builder#streamCharset(Charset) property value).
• byte[] containing UTF-8 encoded text (or charset defined by ReaderParser.Builder#streamCharset(Charset) property value).
• File containing system encoded text.

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

• null
• InputStream
• byte[]
• File
• CharSequence containing encoded bytes according to the InputStreamParser.Builder#binaryFormat(BinaryFormat) setting.

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 - Malformed input encountered.

IOException - Thrown by underlying stream.

See Also:

• for argument syntax for maps and collections.

write

public final void write(Object object,
 Object output)
                 throws SerializeException,
IOException

Serializes a POJO to the specified output stream or writer.

Equivalent to calling serializer.createSession().write(o, output);

Parameters:

object - The object to serialize.

output - The output object.
Character-based serializers can handle the following output class types:

• Writer
• OutputStream - Output will be written as UTF-8 encoded stream.
• File - Output will be written as system-default encoded stream.
• StringBuilder - Output will be written to the specified string builder.

Stream-based serializers can handle the following output class types:

• OutputStream
• File

Throws:

SerializeException - If a problem occurred trying to convert the output.

IOException - Thrown by underlying stream.

readTokens

public TokenReader readTokens(Object input)
                       throws IOException

Opens a low-level TokenReader cursor over the specified input.

Shortcut for ((TokenReadable)getParser()).readTokens(input). See TokenReader for the cursor contract.

Notes:

• This capability depends on the underlying parser. Formats whose parser does not implement TokenReadable (the structural-token role) yield a ClassCastException.

Parameters:

input - The input. Accepts Reader, CharSequence, InputStream, byte[], or File.

Returns:

A new TokenReader cursor.

Throws:

IOException - If a problem occurred opening the underlying input.

writeTokens

public TokenWriter writeTokens(Object output)
                        throws IOException

Opens a low-level push generator that emits structural events one at a time.

Shortcut for ((TokenWritable)getSerializer()).writeTokens(output). See TokenWriter for the generator contract.

Notes:

• This capability depends on the underlying serializer. Formats whose serializer does not implement TokenWritable (the structural-token role) yield a ClassCastException.

Parameters:

output - The output. Accepts Writer, OutputStream, File, or StringBuilder.

Returns:

A new TokenWriter.

Throws:

IOException - If the output type is not supported or could not be opened.

readRecords

public RecordReader readRecords(Object input)
                         throws IOException

Opens a low-level RecordReader cursor that yields each top-level value as a record.

Shortcut for ((RecordReadable)getParser()).readRecords(input). See RecordReader for the cursor contract.

Notes:

• This capability depends on the underlying parser. Formats whose parser does not implement RecordReadable yield a ClassCastException.

Parameters:

input - The input. Accepts Reader, CharSequence, InputStream, byte[], or File.

Returns:

A new RecordReader cursor.

Throws:

IOException - If a problem occurred opening the underlying input.

writeRecords

public RecordWriter writeRecords(Object output)
                          throws IOException

Opens a low-level RecordWriter cursor that emits each whole value as a record.

Shortcut for ((RecordWritable)getSerializer()).writeRecords(output). See RecordWriter for the cursor contract.

Notes:

• This capability depends on the underlying serializer. Formats whose serializer does not implement RecordWritable yield a ClassCastException.

Parameters:

output - The output. Accepts Writer, OutputStream, File, or StringBuilder.

Returns:

A new RecordWriter cursor.

Throws:

IOException - If a problem occurred opening the underlying output.

readArrayRecords

public RecordReader readArrayRecords(Object input)
                              throws IOException

Opens a RecordReader that yields each element of a top-level wire array as a separate record.

Shortcut for ((ArrayRecordReadable)getParser()).readArrayRecords(input).

Notes:

• This capability depends on the underlying parser. Formats whose parser does not implement ArrayRecordReadable yield a ClassCastException.

Parameters:

input - The input. Accepts Reader, CharSequence, InputStream, byte[], or File.

Returns:

A new element-streamed RecordReader cursor.

Throws:

IOException - If a problem occurred opening the underlying input.

writeArrayRecords

public RecordWriter writeArrayRecords(Object output)
                               throws IOException

Opens a RecordWriter that wraps each written value as one element of a top-level wire array.

Shortcut for ((ArrayRecordWritable)getSerializer()).writeArrayRecords(output).

Notes:

• This capability depends on the underlying serializer. Formats whose serializer does not implement ArrayRecordWritable yield a ClassCastException.

Parameters:

output - The output. Accepts Writer, OutputStream, File, or StringBuilder.

Returns:

A new element-streamed RecordWriter cursor.

Throws:

IOException - If a problem occurred opening the underlying output.