com.owlike.genson

Class Genson

java.lang.Object

com.owlike.genson.Genson

public final class Genson
extends Object

Main class of the library. Instances of this class are intended to be reused. You can instantiate it multiple times but it is better to have an instance per configuration so you can benefit of better performances. This class is immutable and thread safe. For more examples have a look at the wiki.

To create a new instance of Genson you can use the default no arg constructor or the Genson.Builder class to have control over Gensons configuration.
A basic usage of Genson would be:

 Genson genson = new Genson();
 String json = genson.serialize(new int[] { 1, 2, 3 });
 int[] arrayOfInt = genson.deserialize(json, int[].class);
 // (multi-dimensional arrays are also supported)
 
 // genson can also deserialize primitive types without class information
 Number[] arrayOfNumber = genson.deserialize("[1, 2.03, 8877463]", Number[].class);
 // or even
 Object[] arrayOfUnknownTypes = genson
                .deserialize("[1, false, null, 4.05, \"hey this is a string!\"]");
 // it can also deserialize json objects of unknown type to maps!
 Map<String, Object> map = (Map<String, Object>) genson.deserialize("{\"foo\":1232}", Object.class);
 

Every object serialized with Genson, can be deserialized back into its concrete type! Have a look at ClassMetadataConverter for an explanation and examples.

Author:

eugen

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Genson.Builder Use the Builder class when you want to create a custom Genson instance.

Constructor Summary

Constructors

Constructor and Description
Genson() The default constructor will use the default configuration provided by the Genson.Builder.
Genson(Factory<Converter<?>> converterFactory, BeanDescriptorProvider beanDescProvider, Converter<Object> nullConverter, boolean skipNull, boolean htmlSafe, Map<String,Class<?>> classAliases, boolean withClassMetadata, boolean strictDoubleParse, boolean indent, boolean withMetadata) Instead of using this constructor you should use Genson.Builder.

Method Summary

Methods

Modifier and Type	Method and Description
<T> String	aliasFor(Class<T> clazz) Searches if an alias has been registered for clazz.
Class<?>	classFor(String alias) Searches for the class matching this alias, if none will try to use the alias as the class name.
ObjectReader	createReader(byte[] in) Creates a new ObjectWriter with this Genson instance configuration.
ObjectReader	createReader(InputStream is) Creates a new ObjectReader with this Genson instance configuration and default encoding to UTF8.
ObjectReader	createReader(InputStream is, Charset charset) Creates a new ObjectReader with this Genson instance configuration.
ObjectReader	createReader(Reader reader) Creates a new ObjectReader with this Genson instance configuration.
ObjectWriter	createWriter(OutputStream os) Creates a new ObjectWriter with this Genson instance configuration and default encoding to UTF8.
ObjectWriter	createWriter(OutputStream os, Charset charset) Creates a new ObjectWriter with this Genson instance configuration.
ObjectWriter	createWriter(Writer writer) Creates a new ObjectWriter with this Genson instance configuration.
<T> T	deserialize(byte[] input, Class<T> toType) Deserializes the incoming json byte array into an instance of T.
<T> T	deserialize(byte[] input, GenericType<T> toType) Deserializes the incoming json byte array into an instance of T.
<T> T	deserialize(GenericType<T> type, ObjectReader reader, Context ctx)
<T> T	deserialize(GenericType<T> type, Reader reader, Class<? extends BeanView<?>>... withViews)
<T> T	deserialize(InputStream input, Class<T> toType) Deserializes the incoming json stream into an instance of T.
<T> T	deserialize(InputStream input, GenericType<T> toType) Deserializes the incoming json stream into an instance of T.
<T> T	deserialize(Reader reader, Class<T> toType) Deserializes the incoming json stream into an instance of T.
<T> T	deserialize(Reader reader, GenericType<T> toType) Deserializes the incoming json stream into an instance of T.
<T> T	deserialize(String fromSource, Class<T> toClass) Deserializes fromSource String into an instance of toClass.
<T> T	deserialize(String fromSource, Class<T> toType, Class<? extends BeanView<?>>... withViews)
<T> T	deserialize(String fromSource, GenericType<T> toType) Deserializes to an instance of T.
<T> T	deserialize(String fromSource, GenericType<T> toType, Class<? extends BeanView<?>>... withViews)
BeanDescriptorProvider	getBeanDescriptorFactory()
Converter<Object>	getNullConverter()
boolean	isHtmlSafe()
boolean	isSkipNull()
boolean	isWithClassMetadata()
<T> Converter<T>	provideConverter(Type forType) Provides an instance of Converter capable of handling objects of type forType.
String	serialize(Object object) Serializes the object into a json string.
String	serialize(Object object, Class<? extends BeanView<?>>... withViews) Serializes the object using the specified BeanViews.
String	serialize(Object object, GenericType<?> type) Serializes the object using the type of GenericType instead of using its runtime type.
void	serialize(Object object, ObjectWriter writer, Class<? extends BeanView<?>>... withViews) Serializes this object and writes its representation to writer.
void	serialize(Object object, OutputStream output) Serializes this object to the passed OutputStream, as Genson did not instantiate it, you are responsible of calling close on it.
void	serialize(Object object, Type type, ObjectWriter writer, Context ctx) Serializes this object and writes its representation to writer.
void	serialize(Object object, Writer writer) Serializes this object to the passed Writer, as Genson did not instantiate it, you are responsible of calling close on it.
byte[]	serializeBytes(Object object) Serializes this object to its json form in a byte array.

Methods inherited from class java.lang.Object

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

Constructor Detail

Genson

public Genson()

The default constructor will use the default configuration provided by the Genson.Builder. In most cases using this default constructor will suffice.

Genson

public Genson(Factory<Converter<?>> converterFactory,
      BeanDescriptorProvider beanDescProvider,
      Converter<Object> nullConverter,
      boolean skipNull,
      boolean htmlSafe,
      Map<String,Class<?>> classAliases,
      boolean withClassMetadata,
      boolean strictDoubleParse,
      boolean indent,
      boolean withMetadata)

Instead of using this constructor you should use Genson.Builder.

Parameters:

converterFactory - providing instance of converters.

beanDescProvider - providing instance of BeanDescriptor used during bean serialization and deserialization.

nullConverter - handling null objects. If its serialize/deserialize methods are called you are sure that it is a null value. This converter is used in NullConverter

skipNull - indicates whether null values should be serialized. False by default, null values will be serialized.

htmlSafe - indicates whether \,<,>,&,= characters should be replaced by their Unicode representation.

classAliases - association map between classes and their aliases, used if withClassMetadata is true.

withClassMetadata - indicates whether class name should be serialized and used during deserialization to determine the type. False by default.

strictDoubleParse - indicates whether to use or not double approximation. If false (by default) it enables Genson custom double parsing algorithm, that is an approximation of Double.parse but is a lot faster. If true, Double.parse method will be usead instead. In most cases you should be fine with Genson algorithm, but if for some reason you need to have 100% match with Double.parse, then enable strict parsing.

indent - true if outputed json must be indented (pretty printed).

withMetadata - true if ObjectReader instances must be configured with metadata feature enabled. if withClassMetadata is true withMetadata will be automatically true.

Method Detail

provideConverter

public <T> Converter<T> provideConverter(Type forType)

Provides an instance of Converter capable of handling objects of type forType.

Parameters:

forType - the type for which a converter is needed.

Returns:

the converter instance.

Throws:

JsonBindingException - if a problem occurs during converters lookup/construction.

serialize

public String serialize(Object object)

Serializes the object into a json string.

Parameters:

object - object to be serialized.

Returns:

the serialized object as a string.

Throws:

JsonBindingException - if there was any kind of error during serialization.

JsonStreamException - if there was a problem during writing of the object to the output.

serialize

public String serialize(Object object,
               GenericType<?> type)

Serializes the object using the type of GenericType instead of using its runtime type.

Parameters:

object - object to be serialized.

type - the type of the object to be serialized.

Returns:

json string representation.

Throws:

JsonBindingException

JsonStreamException

serialize

public String serialize(Object object,
               Class<? extends BeanView<?>>... withViews)

Serializes the object using the specified BeanViews.

Parameters:

object -

withViews - the BeanViews to apply during this serialization.

Returns:

Throws:

JsonBindingException

JsonStreamException

See Also:

BeanView

serialize

public void serialize(Object object,
             Writer writer)

Serializes this object to the passed Writer, as Genson did not instantiate it, you are responsible of calling close on it.

serialize

public void serialize(Object object,
             OutputStream output)

Serializes this object to the passed OutputStream, as Genson did not instantiate it, you are responsible of calling close on it.

serializeBytes

public byte[] serializeBytes(Object object)

Serializes this object to its json form in a byte array.

serialize

public void serialize(Object object,
             ObjectWriter writer,
             Class<? extends BeanView<?>>... withViews)

Serializes this object and writes its representation to writer. As you are providing the writer instance you also must ensure to call flush and close on it when you are done.

Parameters:

object -

writer - into which to write the serialized object.

withViews -

Throws:

JsonBindingException

JsonStreamException

serialize

public void serialize(Object object,
             Type type,
             ObjectWriter writer,
             Context ctx)

Serializes this object and writes its representation to writer. As you are providing the writer instance you also must ensure to call close on it when you are done.

deserialize

public <T> T deserialize(String fromSource,
                Class<T> toClass)

Deserializes fromSource String into an instance of toClass.

Parameters:

fromSource - source from which to deserialize.

toClass - type into which to deserialize.

Returns:

Throws:

JsonBindingException

JsonStreamException

deserialize

public <T> T deserialize(String fromSource,
                GenericType<T> toType)

Deserializes to an instance of T. GenericType is useful when you want to deserialize to a list or map (or any other type with generics).

Parameters:

fromSource -

toType -

Returns:

Throws:

JsonBindingException

JsonStreamException

See Also:

GenericType

deserialize

public <T> T deserialize(Reader reader,
                GenericType<T> toType)

Deserializes the incoming json stream into an instance of T. Genson did not create the instance of Reader so it will not be closed

deserialize

public <T> T deserialize(Reader reader,
                Class<T> toType)

Deserializes the incoming json stream into an instance of T. Genson did not create the instance of Reader so it will not be closed

deserialize

public <T> T deserialize(InputStream input,
                Class<T> toType)

Deserializes the incoming json stream into an instance of T. Genson did not create the instance of InputStream so it will not be closed

deserialize

public <T> T deserialize(InputStream input,
                GenericType<T> toType)

Deserializes the incoming json stream into an instance of T. Genson did not create the instance of InputStream so it will not be closed.

deserialize

public <T> T deserialize(byte[] input,
                Class<T> toType)

Deserializes the incoming json byte array into an instance of T.

deserialize

public <T> T deserialize(byte[] input,
                GenericType<T> toType)

Deserializes the incoming json byte array into an instance of T.

deserialize

public <T> T deserialize(String fromSource,
                GenericType<T> toType,
                Class<? extends BeanView<?>>... withViews)

deserialize

public <T> T deserialize(String fromSource,
                Class<T> toType,
                Class<? extends BeanView<?>>... withViews)

deserialize

public <T> T deserialize(GenericType<T> type,
                Reader reader,
                Class<? extends BeanView<?>>... withViews)

deserialize

public <T> T deserialize(GenericType<T> type,
                ObjectReader reader,
                Context ctx)

aliasFor

public <T> String aliasFor(Class<T> clazz)

Searches if an alias has been registered for clazz. If not will take the class full name and use it as alias. This method never returns null.

classFor

public Class<?> classFor(String alias)
                  throws ClassNotFoundException

Searches for the class matching this alias, if none will try to use the alias as the class name.

Parameters:

alias -

Returns:

The class matching this alias.

Throws:

ClassNotFoundException - thrown if no class has been registered for this alias and the alias it self does not correspond to the full name of a class.

createWriter

public ObjectWriter createWriter(OutputStream os)

Creates a new ObjectWriter with this Genson instance configuration and default encoding to UTF8.

createWriter

public ObjectWriter createWriter(OutputStream os,
                        Charset charset)

Creates a new ObjectWriter with this Genson instance configuration.

createWriter

public ObjectWriter createWriter(Writer writer)

Creates a new ObjectWriter with this Genson instance configuration.

createReader

public ObjectReader createReader(byte[] in)

Creates a new ObjectWriter with this Genson instance configuration.

createReader

public ObjectReader createReader(InputStream is)

Creates a new ObjectReader with this Genson instance configuration and default encoding to UTF8.

createReader

public ObjectReader createReader(InputStream is,
                        Charset charset)

Creates a new ObjectReader with this Genson instance configuration.

createReader

public ObjectReader createReader(Reader reader)

Creates a new ObjectReader with this Genson instance configuration.

isSkipNull

public boolean isSkipNull()

isHtmlSafe

public boolean isHtmlSafe()

isWithClassMetadata

public boolean isWithClassMetadata()

getBeanDescriptorFactory

public BeanDescriptorProvider getBeanDescriptorFactory()

getNullConverter

public Converter<Object> getNullConverter()