Package io.micronaut.json

Interface JsonMapper

All Known Implementing Classes:

JacksonDatabindMapper

public interface JsonMapper

Common abstraction for mapping json to data structures.

Since:

3.1

Author:

Jonas Konrad

Method Summary

Modifier and Type	Method	Description
default @NonNull JsonMapper	cloneWithFeatures(@NonNull JsonFeatures features)	Create a copy of this mapper with the given json features as returned by detectFeatures(io.micronaut.core.annotation.AnnotationMetadata).
default @NonNull JsonMapper	cloneWithViewClass(@NonNull Class<?> viewClass)	Create a copy of this mapper with the given view class.
static @NonNull JsonMapper	createDefault()	Resolves the default JsonMapper.
default @NonNull Processor<byte[],JsonNode>	createReactiveParser(@NonNull Consumer<Processor<byte[],JsonNode>> onSubscribe, boolean streamArray)	Deprecated.
default @NonNull JsonMapper	createSpecific(@NonNull Argument<?> type)	Specialize this mapper for the given type.
default @NonNull Optional<JsonFeatures>	detectFeatures(@NonNull AnnotationMetadata annotations)	Detect JsonFeatures from the given annotation data.
@NonNull JsonStreamConfig	getStreamConfig()
<T> T	readValue(byte @NonNull [] byteArray, @NonNull Argument<T> type)	Parse and map json from the given byte array.
default <T> T	readValue(byte @NonNull [] byteArray, @NonNull Class<T> type)	Read a value from the byte array for the given type.
default <T> T	readValue(@NonNull ByteBuffer<?> byteBuffer, @NonNull Argument<T> type)	Parse and map json from the given byte buffer.
<T> T	readValue(@NonNull InputStream inputStream, @NonNull Argument<T> type)	Parse and map json from the given stream.
default <T> T	readValue(@NonNull InputStream inputStream, @NonNull Class<T> type)	Read a value from the given input stream for the given type.
default <T> T	readValue(@NonNull String string, @NonNull Argument<T> type)	Parse and map json from the given string.
default <T> T	readValue(@NonNull String string, @NonNull Class<T> type)	Read a value from the given string for the given type.
<T> T	readValueFromTree(@NonNull JsonNode tree, @NonNull Argument<T> type)	Transform a JsonNode to a value of the given type.
default <T> T	readValueFromTree(@NonNull JsonNode tree, @NonNull Class<T> type)	Transform a JsonNode to a value of the given type.
default void	updateValueFromTree(Object value, @NonNull JsonNode tree)	Update an object from json data.
<T> void	writeValue(@NonNull OutputStream outputStream, @NonNull Argument<T> type, T object)	Write an object as json.
void	writeValue(@NonNull OutputStream outputStream, @Nullable Object object)	Write an object as json.
<T> byte[]	writeValueAsBytes(@NonNull Argument<T> type, T object)	Write an object as json.
byte[]	writeValueAsBytes(@Nullable Object object)	Write an object as json.
default <T> @NonNull String	writeValueAsString(@NonNull Argument<T> type, T object)	Write the given value as a string.
default <T> @NonNull String	writeValueAsString(@NonNull Argument<T> type, T object, Charset charset)	Write the given value as a string.
default @NonNull String	writeValueAsString(@NonNull Object object)	Write the given value as a string.
<T> @NonNull JsonNode	writeValueToTree(@NonNull Argument<T> type, T value)	Transform an object value to a json tree.
@NonNull JsonNode	writeValueToTree(@Nullable Object value)	Transform an object value to a json tree.

Method Details

createSpecific

@NonNull
default @NonNull JsonMapper createSpecific(@NonNull
 @NonNull Argument<?> type)

Specialize this mapper for the given type. Read and write operations on the returned mapper may only be called with that type.

Parameters:

type - The type to read or write

Returns:

The specialized JsonMapper.

readValueFromTree

<T> T readValueFromTree(@NonNull
 @NonNull JsonNode tree,
 @NonNull
 @NonNull Argument<T> type)
                 throws IOException

Transform a JsonNode to a value of the given type.

Type Parameters:

T - Type variable of the return type.

Parameters:

tree - The input json data.

type - The type to deserialize.

Returns:

The deserialized value.

Throws:

IOException - IOException

readValueFromTree

default <T> T readValueFromTree(@NonNull
 @NonNull JsonNode tree,
 @NonNull
 @NonNull Class<T> type)
                         throws IOException

Transform a JsonNode to a value of the given type.

Type Parameters:

T - Type variable of the return type.

Parameters:

tree - The input json data.

type - The type to deserialize.

Returns:

The deserialized value.

Throws:

IOException - IOException

readValue

<T> T readValue(@NonNull
 @NonNull InputStream inputStream,
 @NonNull
 @NonNull Argument<T> type)
         throws IOException

Parse and map json from the given stream.

Type Parameters:

T - Type variable of the return type.

Parameters:

inputStream - The input data.

type - The type to deserialize to.

Returns:

The deserialized object.

Throws:

IOException - IOException

readValue

@Nullable
default <T> T readValue(@NonNull
 @NonNull InputStream inputStream,
 @NonNull
 @NonNull Class<T> type)
                 throws IOException

Read a value from the given input stream for the given type.

Type Parameters:

T - The generic type

Parameters:

inputStream - The input stream

type - The type

Returns:

The value or null if it decodes to null

Throws:

IOException - If an unrecoverable error occurs

readValue

<T> T readValue(byte @NonNull [] byteArray,
 @NonNull
 @NonNull Argument<T> type)
         throws IOException

Parse and map json from the given byte array.

Type Parameters:

T - Type variable of the return type.

Parameters:

byteArray - The input data.

type - The type to deserialize to.

Returns:

The deserialized object.

Throws:

IOException - IOException

readValue

default <T> T readValue(@NonNull
 @NonNull ByteBuffer<?> byteBuffer,
 @NonNull
 @NonNull Argument<T> type)
                 throws IOException

Parse and map json from the given byte buffer.

Type Parameters:

T - Type variable of the return type.

Parameters:

byteBuffer - The input data.

type - The type to deserialize to.

Returns:

The deserialized object.

Throws:

IOException - IOException

readValue

default <T> T readValue(@NonNull
 @NonNull String string,
 @NonNull
 @NonNull Argument<T> type)
                 throws IOException

Parse and map json from the given string.

Type Parameters:

T - Type variable of the return type.

Parameters:

string - The input data.

type - The type to deserialize to.

Returns:

The deserialized object.

Throws:

IOException - IOException

readValue

@Nullable
default <T> T readValue(byte @NonNull [] byteArray,
 @NonNull
 @NonNull Class<T> type)
                 throws IOException

Read a value from the byte array for the given type.

Type Parameters:

T - The generic type

Parameters:

byteArray - The byte array

type - The type

Returns:

The value or null if it decodes to null

Throws:

IOException - If an unrecoverable error occurs

Since:

4.0.0

readValue

@Nullable
default <T> T readValue(@NonNull
 @NonNull String string,
 @NonNull
 @NonNull Class<T> type)
                 throws IOException

Read a value from the given string for the given type.

Type Parameters:

T - The generic type

Parameters:

string - The string

type - The type

Returns:

The value or null if it decodes to null

Throws:

IOException - If an unrecoverable error occurs

createReactiveParser

@NonNull
@Deprecated
default @NonNull Processor<byte[],JsonNode> createReactiveParser(@NonNull
 @NonNull Consumer<Processor<byte[],JsonNode>> onSubscribe,
 boolean streamArray)

Deprecated.

Create a reactive Processor that accepts json bytes and parses them as JsonNodes.

Parameters:

onSubscribe - An additional function to invoke with this processor when the returned processor is subscribed to.

streamArray - Whether to return a top-level json array as a stream of elements rather than a single array.

Returns:

The reactive processor.

writeValueToTree

@NonNull
@NonNull JsonNode writeValueToTree(@Nullable
 @Nullable Object value)
                            throws IOException

Transform an object value to a json tree.

Parameters:

value - The object value to transform.

Returns:

The json representation.

Throws:

IOException - If there are any mapping exceptions (e.g. illegal values).

writeValueToTree

@NonNull
<T> @NonNull JsonNode writeValueToTree(@NonNull
 @NonNull Argument<T> type,
 @Nullable
 T value)
                                throws IOException

Transform an object value to a json tree.

Type Parameters:

T - The type variable of the type.

Parameters:

type - The object type

value - The object value to transform.

Returns:

The json representation.

Throws:

IOException - If there are any mapping exceptions (e.g. illegal values).

writeValue

void writeValue(@NonNull
 @NonNull OutputStream outputStream,
 @Nullable
 @Nullable Object object)
         throws IOException

Write an object as json.

Parameters:

outputStream - The stream to write to.

object - The object to serialize.

Throws:

IOException - IOException

writeValue

<T> void writeValue(@NonNull
 @NonNull OutputStream outputStream,
 @NonNull
 @NonNull Argument<T> type,
 @Nullable
 T object)
             throws IOException

Write an object as json.

Type Parameters:

T - The generic type

Parameters:

outputStream - The stream to write to.

type - The object type

object - The object to serialize.

Throws:

IOException - IOException

writeValueAsBytes

byte[] writeValueAsBytes(@Nullable
 @Nullable Object object)
                  throws IOException

Write an object as json.

Parameters:

object - The object to serialize.

Returns:

The serialized encoded json.

Throws:

IOException - IOException

writeValueAsBytes

<T> byte[] writeValueAsBytes(@NonNull
 @NonNull Argument<T> type,
 @Nullable
 T object)
                      throws IOException

Write an object as json.

Type Parameters:

T - The generic type

Parameters:

type - The object type

object - The object to serialize.

Returns:

The serialized encoded json.

Throws:

IOException - IOException

writeValueAsString

@NonNull
default @NonNull String writeValueAsString(@NonNull
 @NonNull Object object)
                                    throws IOException

Write the given value as a string.

Parameters:

object - The object

Returns:

The string

Throws:

IOException - If an unrecoverable error occurs

Since:

4.0.0

writeValueAsString

@NonNull
default <T> @NonNull String writeValueAsString(@NonNull
 @NonNull Argument<T> type,
 @Nullable
 T object)
                                        throws IOException

Write the given value as a string.

Type Parameters:

T - The generic type

Parameters:

type - The type, never null

object - The object

Returns:

The string

Throws:

IOException - If an unrecoverable error occurs

Since:

4.0.0

writeValueAsString

@NonNull
default <T> @NonNull String writeValueAsString(@NonNull
 @NonNull Argument<T> type,
 @Nullable
 T object,
 Charset charset)
                                        throws IOException

Write the given value as a string.

Type Parameters:

T - The generic type

Parameters:

type - The type, never null

object - The object

charset - The charset, never null

Returns:

The string

Throws:

IOException - If an unrecoverable error occurs

Since:

4.0.0

updateValueFromTree

default void updateValueFromTree(Object value,
 @NonNull
 @NonNull JsonNode tree)
                          throws IOException

Update an object from json data.

Parameters:

value - The object to update.

tree - The json data to update from.

Throws:

IOException - If there are any mapping exceptions (e.g. illegal values).

UnsupportedOperationException - If this operation is not supported.

cloneWithFeatures

@NonNull
default @NonNull JsonMapper cloneWithFeatures(@NonNull
 @NonNull JsonFeatures features)

Create a copy of this mapper with the given json features as returned by detectFeatures(io.micronaut.core.annotation.AnnotationMetadata).

Parameters:

features - The json features to configure.

Returns:

A new mapper.

detectFeatures

@NonNull
default @NonNull Optional<JsonFeatures> detectFeatures(@NonNull
 @NonNull AnnotationMetadata annotations)

Detect JsonFeatures from the given annotation data.

Parameters:

annotations - The annotations to scan.

Returns:

The json features for use in cloneWithFeatures(io.micronaut.json.JsonFeatures), or an empty optional if there were no feature annotations detected (or feature annotations are not supported).

cloneWithViewClass

@NonNull
default @NonNull JsonMapper cloneWithViewClass(@NonNull
 @NonNull Class<?> viewClass)

Create a copy of this mapper with the given view class.

Parameters:

viewClass - The view class to use for serialization and deserialization.

Returns:

A new mapper.

Throws:

UnsupportedOperationException - If views are not supported by this mapper.

getStreamConfig

@NonNull
@NonNull JsonStreamConfig getStreamConfig()

Returns:

The configured stream config.

createDefault

@NonNull
static @NonNull JsonMapper createDefault()

Resolves the default JsonMapper.

Returns:

The default JsonMapper

Throws:

IllegalStateException - If no JsonMapper implementation exists on the classpath.

Since:

4.0.0