com.dslplatform.json
Class DslJson<TContext>

java.lang.Object
  com.dslplatform.json.DslJson<TContext>

Type Parameters:

TContext - used for library specialization. If unsure, use Object

public class DslJson<TContext>
extends Object

Main DSL-JSON class. Easiest way to use the library is to create an DslJson<Object> instance and reuse it within application. DslJson has optional constructor for specifying default readers/writers.

During initialization DslJson will use ServiceLoader API to load registered services. This is done through `META-INF/services/com.dslplatform.json.CompiledJson` file.

DslJson can fallback to another serializer in case when it doesn't know how to handle specific type. This can be specified by Fallback interface during initialization.

If you wish to use compile time databinding @CompiledJson annotation must be specified on the target class or implicit reference to target class must exists from a class with @CompiledJson annotation.

Usage example:

     DslJson<Object> dsl = new DslJson<>();
     dsl.serialize(instance, OutputStream);
     POJO pojo = dsl.deserialize(POJO.class, InputStream);
 

For best performance use serialization API with JsonWriter and byte[] as target. JsonWriter is reused via thread local variable. When custom JsonWriter's are used, reusing them will yield maximum performance. JsonWriter can be reused via reset methods. For best deserialization performance prefer byte[] API instead of InputStream API. JsonReader is reused via thread local variable. When custom JsonReaders are used, reusing them will yield maximum performance. JsonReader can be reused via process methods.

During deserialization TContext can be used to pass data into deserialized classes. This is useful when deserializing domain objects which require state or service provider. For example DSL Platform entities require service locator to be able to perform lazy load.

DslJson doesn't have a String or Reader API since it's optimized for processing bytes and streams. If you wish to process String, use String.getBytes("UTF-8") as argument for DslJson. Only UTF-8 is supported for encoding and decoding JSON.

     DslJson<Object> dsl = new DslJson<>();
     JsonWriter writer = dsl.newWriter();
     dsl.serialize(writer, instance);
     String json = writer.toString(); //JSON as string - avoid using JSON as Strings whenever possible
     byte[] input = json.getBytes("UTF-8");
     POJO pojo = dsl.deserialize(POJO.class, input, input.length);
 

Nested Class Summary

static interface	DslJson.ConverterFactory<T>
static interface	DslJson.Fallback<TContext>
static class	DslJson.Settings<TContext> Configuration for DslJson options.
static class	DslJson.SimpleStringCache Simplistic string cache implementation.

Field Summary

boolean	allowArrayFormat When object supports array format, eg.
protected List<DslJson.ConverterFactory<JsonReader.BindObject>>	binderFactories
TContext	context The context of this instance.
protected DslJson.Fallback<TContext>	fallback
protected StringCache	keyCache
protected ThreadLocal<JsonReader>	localReader
protected ThreadLocal<JsonWriter>	localWriter
boolean	omitDefaults Should properties with default values be omitted from the resulting JSON?
protected List<DslJson.ConverterFactory<JsonReader.ReadObject>>	readerFactories
protected StringCache	valuesCache
protected List<DslJson.ConverterFactory<JsonWriter.WriteObject>>	writerFactories

Constructor Summary

DslJson()
Simple initialization entry point.

DslJson(DslJson.Settings<TContext> settings)
Fully configurable entry point.

DslJson(TContext context, boolean javaSpecifics, DslJson.Fallback<TContext> fallback, boolean omitDefaults, StringCache keyCache, Iterable<Configuration> serializers)
Deprecated.

Method Summary

boolean	canDeserialize(Type manifest) Check if DslJson knows how to deserialize a type.
boolean	canSerialize(Type manifest) Check if DslJson knows how to serialize a type.
<TResult> TResult	deserialize(Class<TResult> manifest, byte[] body, int size) Convenient deserialize API for working with bytes.
<TResult> TResult	deserialize(Class<TResult> manifest, InputStream stream) Convenient deserialize API for working with streams.
<TResult> TResult	deserialize(Class<TResult> manifest, InputStream stream, byte[] buffer) Convenient deserialize API for working with streams.
<T> T	deserialize(JsonReader.ReadObject<T> converter, JsonReader<TContext> input) Reusable deserialize API.
Object	deserialize(Type manifest, byte[] body, int size) Deserialize API for working with bytes.
Object	deserialize(Type manifest, InputStream stream) Deserialize API for working with streams.
Object	deserialize(Type manifest, InputStream stream, byte[] buffer) Deserialize API for working with streams.
<TResult> List<TResult>	deserializeList(Class<TResult> manifest, byte[] body, int size) Convenient deserialize list API for working with bytes.
<TResult> List<TResult>	deserializeList(Class<TResult> manifest, InputStream stream) Convenient deserialize list API for working with streams.
<TResult> List<TResult>	deserializeList(Class<TResult> manifest, InputStream stream, byte[] buffer) This is deprecated to avoid using it.
static ArrayList<Object>	deserializeList(JsonReader reader) Deprecated.
static LinkedHashMap<String,Object>	deserializeMap(JsonReader reader) Deprecated.
static Object	deserializeObject(JsonReader reader) Deprecated.
Object	getDefault(Type manifest)
protected JsonReader.ReadJsonObject<JsonObject>	getObjectReader(Class<?> manifest)
Set<Type>	getRegisteredBinders()
Set<Type>	getRegisteredDecoders()
Set<Type>	getRegisteredEncoders()
<TResult> Iterator<TResult>	iterateOver(Class<TResult> manifest, InputStream stream) Streaming API for collection deserialization.
<TResult> Iterator<TResult>	iterateOver(Class<TResult> manifest, InputStream stream, byte[] buffer) Streaming API for collection deserialization.
<T> void	iterateOver(Iterator<T> iterator, Class<T> manifest, OutputStream stream, JsonWriter writer) Streaming API for collection serialization.
<T> void	iterateOver(Iterator<T> iterator, OutputStream stream, JsonWriter writer) Streaming API for collection serialization.
JsonReader<TContext>	newReader() Create a reader bound to this DSL-JSON.
JsonReader<TContext>	newReader(byte[] bytes) Create a reader bound to this DSL-JSON.
JsonReader<TContext>	newReader(byte[] bytes, int length) Create a reader bound to this DSL-JSON.
JsonReader<TContext>	newReader(byte[] bytes, int length, char[] tmp) Create a reader bound to this DSL-JSON.
JsonReader<TContext>	newReader(InputStream stream, byte[] buffer) Create a reader bound to this DSL-JSON.
JsonReader<TContext>	newReader(String input) Deprecated.
JsonWriter	newWriter() Create a writer bound to this DSL-JSON.
JsonWriter	newWriter(byte[] buffer) Create a writer bound to this DSL-JSON.
JsonWriter	newWriter(int size) Create a writer bound to this DSL-JSON.
<T,S extends T> void	registerBinder(Class<T> manifest, JsonReader.BindObject<S> binder) Register custom binder for specific type (JSON -> instance conversion).
void	registerBinder(Type manifest, JsonReader.BindObject<?> binder) Register custom binder for specific type (JSON -> instance conversion).
boolean	registerBinderFactory(DslJson.ConverterFactory<? extends JsonReader.BindObject> factory)
<T> void	registerDefault(Class<T> manifest, T instance)
<T,S extends T> void	registerReader(Class<T> manifest, JsonReader.ReadObject<S> reader) Register custom reader for specific type (JSON -> instance conversion).
JsonReader.ReadObject	registerReader(Type manifest, JsonReader.ReadObject<?> reader) Register custom reader for specific type (JSON -> instance conversion).
boolean	registerReaderFactory(DslJson.ConverterFactory<? extends JsonReader.ReadObject> factory)
<T> void	registerWriter(Class<T> manifest, JsonWriter.WriteObject<T> writer) Register custom writer for specific type (instance -> JSON conversion).
JsonWriter.WriteObject	registerWriter(Type manifest, JsonWriter.WriteObject<?> writer) Register custom writer for specific type (instance -> JSON conversion).
boolean	registerWriterFactory(DslJson.ConverterFactory<? extends JsonWriter.WriteObject> factory)
<T extends JsonObject> void	serialize(JsonWriter writer, Collection<T> collection) Deprecated.
<T extends JsonObject> void	serialize(JsonWriter writer, List<T> list) Deprecated.
void	serialize(JsonWriter writer, Object value) Main serialization API.
<T extends JsonObject> void	serialize(JsonWriter writer, T[] array) Deprecated.
<T extends JsonObject> void	serialize(JsonWriter writer, T[] array, int len) Deprecated.
boolean	serialize(JsonWriter writer, Type manifest, Object value) Generic serialize API.
void	serialize(Object value, OutputStream stream) Convenient serialize API.
void	serializeMap(Map<String,Object> value, JsonWriter sw)
<T> JsonReader.BindObject<T>	tryFindBinder(Class<T> manifest) Try to find registered binder for provided type.
JsonReader.BindObject<?>	tryFindBinder(Type manifest) Try to find registered binder for provided type.
<T> JsonReader.ReadObject<T>	tryFindReader(Class<T> manifest) Try to find registered reader for provided type.
JsonReader.ReadObject<?>	tryFindReader(Type manifest) Try to find registered reader for provided type.
<T> JsonWriter.WriteObject<T>	tryFindWriter(Class<T> manifest) Try to find registered writer for provided type.
JsonWriter.WriteObject<?>	tryFindWriter(Type manifest) Try to find registered writer for provided type.

Methods inherited from class java.lang.Object

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

Field Detail

context

@Nullable
public final TContext context

The context of this instance. Can be used for library specialization

fallback

@Nullable
protected final DslJson.Fallback<TContext> fallback

omitDefaults

public final boolean omitDefaults

Should properties with default values be omitted from the resulting JSON? This will leave out nulls, empty collections, zeros and other attributes with default values which can be reconstructed from schema information

allowArrayFormat

public final boolean allowArrayFormat

When object supports array format, eg. [prop1, prop2, prop3] this value must be enabled before object will be serialized in such a way. Regardless of this value deserialization will support all formats.

keyCache

protected final StringCache keyCache

valuesCache

protected final StringCache valuesCache

writerFactories

protected final List<DslJson.ConverterFactory<JsonWriter.WriteObject>> writerFactories

readerFactories

protected final List<DslJson.ConverterFactory<JsonReader.ReadObject>> readerFactories

binderFactories

protected final List<DslJson.ConverterFactory<JsonReader.BindObject>> binderFactories

localWriter

protected final ThreadLocal<JsonWriter> localWriter

localReader

protected final ThreadLocal<JsonReader> localReader

Constructor Detail

DslJson

public DslJson()

Simple initialization entry point. Will provide null for TContext Java graphics readers/writers will not be registered. Fallback will not be configured. Key cache will be enables, values cache will be disabled. Default ServiceLoader.load method will be used to setup services from META-INF

DslJson

@Deprecated
public DslJson(@Nullable
                          TContext context,
                          boolean javaSpecifics,
                          @Nullable
                          DslJson.Fallback<TContext> fallback,
                          boolean omitDefaults,
                          @Nullable
                          StringCache keyCache,
                          Iterable<Configuration> serializers)

Deprecated.

Will be removed. Use DslJson(Settings) instead. Fully configurable entry point.

Parameters:

context - context instance which can be provided to deserialized objects. Use null if not sure

javaSpecifics - register Java graphics specific classes such as java.awt.Point, Image, ...

fallback - in case of unsupported type, try serialization/deserialization through external API

omitDefaults - should serialization produce minified JSON (omit nulls and default values)

keyCache - parsed keys can be cached (this is only used in small subset of parsing)

serializers - additional serializers/deserializers which will be immediately registered into readers/writers

DslJson

public DslJson(DslJson.Settings<TContext> settings)

Fully configurable entry point. Provide settings for DSL-JSON initialization.

Parameters:

settings - DSL-JSON configuration

Method Detail

newWriter

public JsonWriter newWriter()

Create a writer bound to this DSL-JSON. Ideally it should be reused. Bound writer can use lookups to find custom writers. This can be used to serialize unknown types such as Object.class

Returns:

bound writer

newWriter

public JsonWriter newWriter(int size)

Create a writer bound to this DSL-JSON. Ideally it should be reused. Bound writer can use lookups to find custom writers. This can be used to serialize unknown types such as Object.class

Parameters:

size - initial buffer size

Returns:

bound writer

newWriter

public JsonWriter newWriter(byte[] buffer)

Create a writer bound to this DSL-JSON. Ideally it should be reused. Bound writer can use lookups to find custom writers. This can be used to serialize unknown types such as Object.class

Parameters:

buffer - initial buffer

Returns:

bound writer

newReader

public JsonReader<TContext> newReader()

Create a reader bound to this DSL-JSON. Bound reader can reuse key cache (which is used during Map deserialization) This reader can be reused via process method.

Returns:

bound reader

newReader

public JsonReader<TContext> newReader(byte[] bytes)

Create a reader bound to this DSL-JSON. Bound reader can reuse key cache (which is used during Map deserialization) This reader can be reused via process method.

Parameters:

bytes - input bytes

Returns:

bound reader

newReader

public JsonReader<TContext> newReader(byte[] bytes,
                                      int length)

Create a reader bound to this DSL-JSON. Bound reader can reuse key cache (which is used during Map deserialization) This reader can be reused via process method.

Parameters:

bytes - input bytes

length - use input bytes up to specified length

Returns:

bound reader

newReader

public JsonReader<TContext> newReader(byte[] bytes,
                                      int length,
                                      char[] tmp)

Create a reader bound to this DSL-JSON. Bound reader can reuse key cache (which is used during Map deserialization) Pass in initial string buffer. This reader can be reused via process method.

Parameters:

bytes - input bytes

length - use input bytes up to specified length

tmp - string parsing buffer

Returns:

bound reader

newReader

public JsonReader<TContext> newReader(InputStream stream,
                                      byte[] buffer)
                               throws IOException

Create a reader bound to this DSL-JSON. Bound reader can reuse key cache (which is used during Map deserialization) Created reader can be reused (using process method). This is convenience method for creating a new reader and binding it to stream.

Parameters:

stream - input stream

buffer - temporary buffer

Returns:

bound reader

Throws:

IOException - unable to read from stream

newReader

@Deprecated
public JsonReader<TContext> newReader(String input)

Deprecated.

Create a reader bound to this DSL-JSON. Bound reader can reuse key cache (which is used during Map deserialization) This method id Deprecated since it should be avoided. It's better to use byte[] or InputStream based readers

Parameters:

input - JSON string

Returns:

bound reader

registerDefault

public <T> void registerDefault(Class<T> manifest,
                                T instance)

registerWriterFactory

public boolean registerWriterFactory(DslJson.ConverterFactory<? extends JsonWriter.WriteObject> factory)

registerReaderFactory

public boolean registerReaderFactory(DslJson.ConverterFactory<? extends JsonReader.ReadObject> factory)

registerBinderFactory

public boolean registerBinderFactory(DslJson.ConverterFactory<? extends JsonReader.BindObject> factory)

getDefault

@Nullable
public final Object getDefault(@Nullable
                                        Type manifest)

getRegisteredDecoders

public final Set<Type> getRegisteredDecoders()

getRegisteredBinders

public final Set<Type> getRegisteredBinders()

getRegisteredEncoders

public final Set<Type> getRegisteredEncoders()

registerReader

public <T,S extends T> void registerReader(Class<T> manifest,
                                           @Nullable
                                           JsonReader.ReadObject<S> reader)

Register custom reader for specific type (JSON -> instance conversion). Reader is used for conversion from input byte[] -> target object instance

Types registered through @CompiledJson annotation should be registered automatically through ServiceLoader.load method and you should not be registering them manually.

If null is registered for a reader this will disable deserialization of specified type

Type Parameters:

T - type

S - type or subtype

Parameters:

manifest - specified type

reader - provide custom implementation for reading JSON into an object instance

registerReader

@Nullable
public JsonReader.ReadObject registerReader(Type manifest,
                                                     @Nullable
                                                     JsonReader.ReadObject<?> reader)

Register custom reader for specific type (JSON -> instance conversion). Reader is used for conversion from input byte[] -> target object instance

Types registered through @CompiledJson annotation should be registered automatically through ServiceLoader.load method and you should not be registering them manually.

If null is registered for a reader this will disable deserialization of specified type

Parameters:

manifest - specified type

reader - provide custom implementation for reading JSON into an object instance

Returns:

old registered value

registerBinder

public <T,S extends T> void registerBinder(Class<T> manifest,
                                           @Nullable
                                           JsonReader.BindObject<S> binder)

Register custom binder for specific type (JSON -> instance conversion). Binder is used for conversion from input byte[] -> existing target object instance. It's similar to reader, with the difference that it accepts target instance.

Types registered through @CompiledJson annotation should be registered automatically through ServiceLoader.load method and you should not be registering them manually.

If null is registered for a binder this will disable binding of specified type

Type Parameters:

T - type

S - type or subtype

Parameters:

manifest - specified type

binder - provide custom implementation for binding JSON to an object instance

registerBinder

public void registerBinder(Type manifest,
                           @Nullable
                           JsonReader.BindObject<?> binder)

Register custom binder for specific type (JSON -> instance conversion). Binder is used for conversion from input byte[] -> existing target object instance. It's similar to reader, with the difference that it accepts target instance.

Types registered through @CompiledJson annotation should be registered automatically through ServiceLoader.load method and you should not be registering them manually.

If null is registered for a binder this will disable binding of specified type

Parameters:

manifest - specified type

binder - provide custom implementation for binding JSON to an object instance

registerWriter

public <T> void registerWriter(Class<T> manifest,
                               @Nullable
                               JsonWriter.WriteObject<T> writer)

Register custom writer for specific type (instance -> JSON conversion). Writer is used for conversion from object instance -> output byte[]

Types registered through @CompiledJson annotation should be registered automatically through ServiceLoader.load method and you should not be registering them manually.

If null is registered for a writer this will disable serialization of specified type

Type Parameters:

T - type

Parameters:

manifest - specified type

writer - provide custom implementation for writing JSON from object instance

registerWriter

@Nullable
public JsonWriter.WriteObject registerWriter(Type manifest,
                                                      @Nullable
                                                      JsonWriter.WriteObject<?> writer)

Register custom writer for specific type (instance -> JSON conversion). Writer is used for conversion from object instance -> output byte[]

Types registered through @CompiledJson annotation should be registered automatically through ServiceLoader.load method and you should not be registering them manually.

If null is registered for a writer this will disable serialization of specified type

Parameters:

manifest - specified type

writer - provide custom implementation for writing JSON from object instance

Returns:

old registered value

tryFindWriter

@Nullable
public JsonWriter.WriteObject<?> tryFindWriter(Type manifest)

Try to find registered writer for provided type. If writer is not found, null will be returned. If writer for exact type is not found, type hierarchy will be scanned for base writer.

Writer is used for conversion from object instance into JSON representation.

Parameters:

manifest - specified type

Returns:

writer for specified type if found

tryFindReader

@Nullable
public JsonReader.ReadObject<?> tryFindReader(Type manifest)

Try to find registered reader for provided type. If reader is not found, null will be returned. Exact match must be found, type hierarchy will not be scanned for alternative readers.

If you wish to use alternative reader for specific type, register it manually with something along the lines of

     DslJson dslJson = ...
     dslJson.registerReader(Interface.class, dslJson.tryFindReader(Implementation.class));
 

Parameters:

manifest - specified type

Returns:

found reader for specified type

tryFindBinder

@Nullable
public JsonReader.BindObject<?> tryFindBinder(Type manifest)

Try to find registered binder for provided type. If binder is not found, null will be returned. Exact match must be found, type hierarchy will not be scanned for alternative binders.

If you wish to use alternative binder for specific type, register it manually with something along the lines of

     DslJson dslJson = ...
     dslJson.registerBinder(Interface.class, dslJson.tryFindBinder(Implementation.class));
 

Parameters:

manifest - specified type

Returns:

found reader for specified type

tryFindWriter

@Nullable
public <T> JsonWriter.WriteObject<T> tryFindWriter(Class<T> manifest)

Try to find registered writer for provided type. If writer is not found, null will be returned. If writer for exact type is not found, type hierarchy will be scanned for base writer.

Writer is used for conversion from object instance into JSON representation.

Type Parameters:

T - specified type

Parameters:

manifest - specified class

Returns:

found writer for specified class or null

tryFindReader

@Nullable
public <T> JsonReader.ReadObject<T> tryFindReader(Class<T> manifest)

Try to find registered reader for provided type. If reader is not found, null will be returned. Exact match must be found, type hierarchy will not be scanned for alternative reader.

If you wish to use alternative reader for specific type, register it manually with something along the lines of

     DslJson dslJson = ...
     dslJson.registerReader(Interface.class, dslJson.tryFindReader(Implementation.class));
 

Type Parameters:

T - specified type

Parameters:

manifest - specified class

Returns:

found reader for specified class or null

tryFindBinder

@Nullable
public <T> JsonReader.BindObject<T> tryFindBinder(Class<T> manifest)

Try to find registered binder for provided type. If binder is not found, null will be returned. Exact match must be found, type hierarchy will not be scanned for alternative binder.

If you wish to use alternative binder for specific type, register it manually with something along the lines of

     DslJson dslJson = ...
     dslJson.registerBinder(Interface.class, dslJson.tryFindBinder(Implementation.class));
 

Type Parameters:

T - specified type

Parameters:

manifest - specified class

Returns:

found reader for specified class or null

getObjectReader

@Nullable
protected final JsonReader.ReadJsonObject<JsonObject> getObjectReader(Class<?> manifest)

serializeMap

public void serializeMap(Map<String,Object> value,
                         JsonWriter sw)
                  throws IOException

Throws:

IOException

deserializeObject

@Deprecated
@Nullable
public static Object deserializeObject(JsonReader reader)
                                throws IOException

Deprecated.

Throws:

IOException

deserializeList

@Deprecated
public static ArrayList<Object> deserializeList(JsonReader reader)
                                         throws IOException

Deprecated.

Will be removed

Parameters:

reader - JSON reader

Returns:

deseralized list

Throws:

IOException - error during parsing

deserializeMap

@Deprecated
public static LinkedHashMap<String,Object> deserializeMap(JsonReader reader)
                                                   throws IOException

Deprecated.

Will be removed

Parameters:

reader - JSON reader

Returns:

deserialized map

Throws:

IOException - error during parsing

canSerialize

public final boolean canSerialize(Type manifest)

Check if DslJson knows how to serialize a type. It will check if a writer for such type exists or can be used.

Parameters:

manifest - type to check

Returns:

can serialize this type into JSON

canDeserialize

public final boolean canDeserialize(Type manifest)

Check if DslJson knows how to deserialize a type. It will check if a reader for such type exists or can be used.

Parameters:

manifest - type to check

Returns:

can read this type from JSON

deserialize

@Nullable
public <T> T deserialize(JsonReader.ReadObject<T> converter,
                                  JsonReader<TContext> input)
              throws IOException

Reusable deserialize API. For maximum performance `JsonReader` should be reused (otherwise small buffer will be allocated for processing) and `JsonReader.ReadObject` should be prepared (otherwise a lookup will be required).

This is mostly convenience API since it starts the processing of the JSON by calling getNextToken on JsonReader, checks for null and calls converter.read(input).

Type Parameters:

T - specified type

Parameters:

converter - target reader

input - input JSON

Returns:

deserialized instance

Throws:

IOException - error during deserialization

deserialize

@Nullable
public <TResult> TResult deserialize(Class<TResult> manifest,
                                              byte[] body,
                                              int size)
                    throws IOException

Convenient deserialize API for working with bytes. Deserialize provided byte input into target object.

Since JSON is often though of as a series of char, most libraries will convert inputs into a sequence of chars and do processing on them. DslJson will treat input as a sequence of bytes which allows for various optimizations.

Type Parameters:

TResult - target type

Parameters:

manifest - target type

body - input JSON

size - length

Returns:

deserialized instance

Throws:

IOException - error during deserialization

deserialize

@Nullable
public Object deserialize(Type manifest,
                                   byte[] body,
                                   int size)
                   throws IOException

Deserialize API for working with bytes. Deserialize provided byte input into target object.

Since JSON is often though of as a series of char, most libraries will convert inputs into a sequence of chars and do processing on them. DslJson will treat input as a sequence of bytes which allows for various optimizations.

Parameters:

manifest - target type

body - input JSON

size - length

Returns:

deserialized instance

Throws:

IOException - error during deserialization

deserializeList

@Nullable
public <TResult> List<TResult> deserializeList(Class<TResult> manifest,
                                                        byte[] body,
                                                        int size)
                              throws IOException

Convenient deserialize list API for working with bytes. Deserialize provided byte input into target object.

Since JSON is often though of as a series of char, most libraries will convert inputs into a sequence of chars and do processing on them. DslJson will treat input as a sequence of bytes which allows for various optimizations.

Type Parameters:

TResult - target element type

Parameters:

manifest - target type

body - input JSON

size - length

Returns:

deserialized list instance

Throws:

IOException - error during deserialization

deserializeList

@Nullable
public <TResult> List<TResult> deserializeList(Class<TResult> manifest,
                                                        InputStream stream,
                                                        byte[] buffer)
                              throws IOException

This is deprecated to avoid using it. Use deserializeList method without the buffer argument instead. Convenient deserialize list API for working with streams. Deserialize provided stream input into target object. Use buffer for internal conversion from stream into byte[] for partial processing. This method creates a new instance of JsonReader. There is also deserializeList without the buffer which reuses thread local reader.

Since JSON is often though of as a series of char, most libraries will convert inputs into a sequence of chars and do processing on them. DslJson will treat input as a sequence of bytes which allows for various optimizations.

When working on InputStream DslJson will process JSON in chunks of byte[] inputs. Provided buffer will be used as input for partial processing.

For best performance buffer should be reused.

Type Parameters:

TResult - target element type

Parameters:

manifest - target type

stream - input JSON

buffer - buffer used for InputStream -> byte[] conversion

Returns:

deserialized list

Throws:

IOException - error during deserialization

deserializeList

@Nullable
public <TResult> List<TResult> deserializeList(Class<TResult> manifest,
                                                        InputStream stream)
                              throws IOException

Convenient deserialize list API for working with streams. Deserialize provided stream input into target object.

Since JSON is often though of as a series of char, most libraries will convert inputs into a sequence of chars and do processing on them. DslJson will treat input as a sequence of bytes which allows for various optimizations.

When working on InputStream DslJson will process JSON in chunks of byte[] inputs.

Type Parameters:

TResult - target element type

Parameters:

manifest - target type

stream - input JSON

Returns:

deserialized list

Throws:

IOException - error during deserialization

deserialize

@Nullable
public <TResult> TResult deserialize(Class<TResult> manifest,
                                              InputStream stream,
                                              byte[] buffer)
                    throws IOException

Convenient deserialize API for working with streams. Deserialize provided stream input into target object. This method accepts a buffer and will create a new reader using provided buffer. This buffer is used for internal conversion from stream into byte[] for partial processing. There is also method without the buffer which reuses local thread reader for processing.

Since JSON is often though of as a series of char, most libraries will convert inputs into a sequence of chars and do processing on them. DslJson will treat input as a sequence of bytes which allows for various optimizations.

When working on InputStream DslJson will process JSON in chunks of byte[] inputs. Provided buffer will be used as input for partial processing.

For best performance buffer should be reused.

Type Parameters:

TResult - target type

Parameters:

manifest - target type

stream - input JSON

buffer - buffer used for InputStream -> byte[] conversion

Returns:

deserialized instance

Throws:

IOException - error during deserialization

deserialize

@Nullable
public <TResult> TResult deserialize(Class<TResult> manifest,
                                              InputStream stream)
                    throws IOException

Convenient deserialize API for working with streams. Deserialize provided stream input into target object. This method reuses thread local reader for processing input stream.

Since JSON is often though of as a series of char, most libraries will convert inputs into a sequence of chars and do processing on them. DslJson will treat input as a sequence of bytes which allows for various optimizations.

When working on InputStream DslJson will process JSON in chunks of byte[] inputs.

Type Parameters:

TResult - target type

Parameters:

manifest - target type

stream - input JSON

Returns:

deserialized instance

Throws:

IOException - error during deserialization

deserialize

@Nullable
public Object deserialize(Type manifest,
                                   InputStream stream,
                                   byte[] buffer)
                   throws IOException

Deserialize API for working with streams. Deserialize provided stream input into target object. Use buffer for internal conversion from stream into byte[] for partial processing. This method creates a new instance of JsonReader for processing the stream. There is also a method without the byte[] buffer which reuses thread local reader.

Since JSON is often though of as a series of char, most libraries will convert inputs into a sequence of chars and do processing on them. DslJson will treat input as a sequence of bytes which allows for various optimizations.

When working on InputStream DslJson will process JSON in chunks of byte[] inputs. Provided buffer will be used as input for partial processing.

For best performance buffer should be reused.

Parameters:

manifest - target type

stream - input JSON

buffer - buffer used for InputStream -> byte[] conversion

Returns:

deserialized instance

Throws:

IOException - error during deserialization

deserialize

@Nullable
public Object deserialize(Type manifest,
                                   InputStream stream)
                   throws IOException

Deserialize API for working with streams. Deserialize provided stream input into target object. This method reuses thread local reader for processing JSON input.

Since JSON is often though of as a series of char, most libraries will convert inputs into a sequence of chars and do processing on them.

When working on InputStream DslJson will process JSON in chunks of byte[] inputs.

Parameters:

manifest - target type

stream - input JSON

Returns:

deserialized instance

Throws:

IOException - error during deserialization

iterateOver

@Nullable
public <TResult> Iterator<TResult> iterateOver(Class<TResult> manifest,
                                                        InputStream stream)
                              throws IOException

Streaming API for collection deserialization. DslJson will create iterator based on provided manifest info. It will attempt to deserialize from stream on each next() invocation. This method requires buffer instance for partial stream processing. It will create a new instance of JsonReader. There is also a method without the buffer which will reuse thread local reader.

Useful for processing very large streams if only one instance from collection is required at once.

Stream will be processed in chunks of specified buffer byte[]. It will block on reading until buffer is full or end of stream is detected.

Type Parameters:

TResult - type info

Parameters:

manifest - type info

stream - JSON data stream

Returns:

Iterator to instances deserialized from input JSON

Throws:

IOException - if reader is not found or there is an error processing input stream

iterateOver

@Nullable
public <TResult> Iterator<TResult> iterateOver(Class<TResult> manifest,
                                                        InputStream stream,
                                                        byte[] buffer)
                              throws IOException

Streaming API for collection deserialization. DslJson will create iterator based on provided manifest info. It will attempt to deserialize from stream on each next() invocation. This method requires buffer instance for partial stream processing. It will create a new instance of JsonReader. There is also a method without the buffer which will reuse thread local reader.

Useful for processing very large streams if only one instance from collection is required at once.

Stream will be processed in chunks of specified buffer byte[]. It will block on reading until buffer is full or end of stream is detected.

Type Parameters:

TResult - type info

Parameters:

manifest - type info

stream - JSON data stream

buffer - size of processing chunk

Returns:

Iterator to instances deserialized from input JSON

Throws:

IOException - if reader is not found or there is an error processing input stream

iterateOver

public <T> void iterateOver(Iterator<T> iterator,
                            OutputStream stream,
                            @Nullable
                            JsonWriter writer)
                 throws IOException

Streaming API for collection serialization.

It will iterate over entire iterator and serialize each instance into target output stream. After each instance serialization it will copy JSON into target output stream. During each serialization reader will be looked up based on next() instance which allows serializing collection with different types. If collection contains all instances of the same type, prefer the other streaming API.

If reader is not found an IOException will be thrown

If JsonWriter is provided it will be used, otherwise a new instance will be internally created.

Type Parameters:

T - input data type

Parameters:

iterator - input data

stream - target JSON stream

writer - temporary buffer for serializing a single item. Can be null

Throws:

IOException - reader is not found, there is an error during serialization or problem with writing to target stream

iterateOver

public <T> void iterateOver(Iterator<T> iterator,
                            Class<T> manifest,
                            OutputStream stream,
                            @Nullable
                            JsonWriter writer)
                 throws IOException

Streaming API for collection serialization.

It will iterate over entire iterator and serialize each instance into target output stream. After each instance serialization it will copy JSON into target output stream.

If reader is not found an IOException will be thrown

If JsonWriter is provided it will be used, otherwise a new instance will be internally created.

Type Parameters:

T - input data type

Parameters:

iterator - input data

manifest - type of elements in collection

stream - target JSON stream

writer - temporary buffer for serializing a single item. Can be null

Throws:

IOException - reader is not found, there is an error during serialization or problem with writing to target stream

serialize

@Deprecated
public <T extends JsonObject> void serialize(JsonWriter writer,
                                                        @Nullable
                                                        T[] array)

Deprecated.

Use writer.serialize instead

Type Parameters:

T - type

Parameters:

writer - writer

array - items

serialize

@Deprecated
public <T extends JsonObject> void serialize(JsonWriter writer,
                                                        T[] array,
                                                        int len)

Deprecated.

Use writer.serialize instead

Type Parameters:

T - type

Parameters:

writer - writer

array - items

len - part of array

serialize

@Deprecated
public <T extends JsonObject> void serialize(JsonWriter writer,
                                                        @Nullable
                                                        List<T> list)

Deprecated.

Use writer.serialize instead

Type Parameters:

T - type

Parameters:

writer - writer

list - items

serialize

@Deprecated
public <T extends JsonObject> void serialize(JsonWriter writer,
                                                        @Nullable
                                                        Collection<T> collection)

Deprecated.

Use writer.serialize instead

Type Parameters:

T - type

Parameters:

writer - writer

collection - items

serialize

public boolean serialize(JsonWriter writer,
                         Type manifest,
                         @Nullable
                         Object value)

Generic serialize API. Based on provided type manifest converter will be chosen. If converter is not found method will return false.

Resulting JSON will be written into provided writer argument. In case of successful serialization true will be returned.

For best performance writer argument should be reused.

Parameters:

writer - where to write resulting JSON

manifest - type manifest

value - instance to serialize

Returns:

successful serialization

serialize

public final void serialize(@Nullable
                            Object value,
                            OutputStream stream)
                     throws IOException

Convenient serialize API. In most cases JSON is serialized into target `OutputStream`. This method will reuse thread local instance of `JsonWriter` and serialize JSON into it.

Parameters:

value - instance to serialize

stream - where to write resulting JSON

Throws:

IOException - error when unable to serialize instance

serialize

public final void serialize(JsonWriter writer,
                            @Nullable
                            Object value)
                     throws IOException

Main serialization API. Convert object instance into JSON.

JsonWriter contains a growable byte[] where JSON will be serialized. After serialization JsonWriter can be copied into OutputStream or it's byte[] can be obtained

For best performance reuse `JsonWriter` or even better call `JsonWriter.WriteObject` directly

Parameters:

writer - where to write resulting JSON

value - object instance to serialize

Throws:

IOException - error when unable to serialize instance