org.apache.juneau.marshaller.Marshaller Maven / Gradle / Ivy
package org.apache.juneau.marshaller;
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
// * with the License. You may obtain a copy of the License at *
// * *
// * http://www.apache.org/licenses/LICENSE-2.0 *
// * *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
// * specific language governing permissions and limitations under the License. *
// ***************************************************************************************************************************
import java.io.*;
import java.lang.reflect.*;
import java.nio.charset.*;
import org.apache.juneau.*;
import org.apache.juneau.parser.*;
import org.apache.juneau.parser.ParseException;
import org.apache.juneau.serializer.*;
/**
* Top-level class for a pairing of a {@link Serializer} and {@link 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
*
*/
public abstract class Marshaller {
//-----------------------------------------------------------------------------------------------------------------
// Instance
//-----------------------------------------------------------------------------------------------------------------
private final Serializer s;
private final Parser p;
/**
* Constructor.
*
* @param s
* The serializer to use for serializing output.
*
Must not be null .
* @param p
* The parser to use for parsing input.
*
Must not be null .
*/
protected Marshaller(Serializer s, Parser p) {
this.s = s;
this.p = p;
}
/**
* Returns the serializer associated with this marshaller.
*
* @return The serializer associated with this marshaller.
*/
public Serializer getSerializer() {
return s;
}
/**
* Returns the parser associated with this marshaller.
*
* @return The parser associated with this marshaller.
*/
public Parser getParser() {
return p;
}
/**
* Serializes a POJO to the specified output stream or writer.
*
*
* Equivalent to calling serializer.createSession().serialize(o, output);
*
* @param object The object to serialize.
* @param output
* The output object.
*
Character-based serializers can handle the following output class types:
*
* - {@link Writer}
*
- {@link OutputStream} - Output will be written as UTF-8 encoded stream.
*
- {@link File} - Output will be written as system-default encoded stream.
*
- {@link StringBuilder} - Output will be written to the specified string builder.
*
*
Stream-based serializers can handle the following output class types:
*
* - {@link OutputStream}
*
- {@link File}
*
* @throws SerializeException If a problem occurred trying to convert the output.
* @throws IOException Thrown by underlying stream.
*/
public final void write(Object object, Object output) throws SerializeException, IOException {
s.serialize(object, output);
}
/**
* 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 {@link #read(Object, Class)} method instead if you don't need a parameterized map/collection.
*
*
* @param The class type of the object to create.
* @param input
* The input.
*
Character-based parsers can handle the following input class types:
*
* null
* - {@link Reader}
*
- {@link CharSequence}
*
- {@link InputStream} containing UTF-8 encoded text (or charset defined by
* {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value).
*
byte []- {@link File} containing system encoded text (or charset defined by
* {@link org.apache.juneau.parser.ReaderParser.Builder#fileCharset(Charset)} property value).
*
*
Stream-based parsers can handle the following input class types:
*
* null
* - {@link InputStream}
*
byte []- {@link File}
*
- {@link CharSequence} containing encoded bytes according to the {@link org.apache.juneau.parser.InputStreamParser.Builder#binaryFormat(BinaryFormat)} setting.
*
* @param type
* The object type to create.
*
Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
* @param args
* The type arguments of the class if it's a collection or map.
*
Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
*
Ignored if the main type is not a map or collection.
* @return The parsed object.
* @throws ParseException Malformed input encountered.
* @throws IOException Thrown by underlying stream.
* @see BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections.
*/
public final T read(Object input, Type type, Type...args) throws ParseException, IOException {
return p.parse(input, type, args);
}
/**
* Same as {@link #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 );
*
*
* @param The class type of the object being created.
* @param input
* The input.
*
Character-based parsers can handle the following input class types:
*
* null
* - {@link Reader}
*
- {@link CharSequence}
*
- {@link InputStream} containing UTF-8 encoded text (or charset defined by
* {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value).
*
byte []- {@link File} containing system encoded text (or charset defined by
* {@link org.apache.juneau.parser.ReaderParser.Builder#fileCharset(Charset)} property value).
*
*
Stream-based parsers can handle the following input class types:
*
* null
* - {@link InputStream}
*
byte []- {@link File}
*
- {@link CharSequence} containing encoded bytes according to the {@link org.apache.juneau.parser.InputStreamParser.Builder#binaryFormat(BinaryFormat)} setting.
*
* @param type The object type to create.
* @return The parsed object.
* @throws ParseException Malformed input encountered.
* @throws IOException Thrown by underlying stream.
*/
public final T read(Object input, Class type) throws ParseException, IOException {
return p.parse(input, type);
}
}