Package io.servicetalk.http.api

Class HttpSerializers

java.lang.Object

io.servicetalk.http.api.HttpSerializers

public final class HttpSerializers
extends Object

Factory for creation of HttpSerializerDeserializer and HttpStreamingSerializerDeserializer.

Method Summary

Modifier and Type	Method	Description
static HttpStreamingSerializerDeserializer<String>	appSerializerAsciiFixLen()	Creates a HttpStreamingSerializerDeserializer that serializes Strings with StandardCharsets.US_ASCII encoding using fixed int length delimited framing.
static HttpStreamingSerializerDeserializer<String>	appSerializerAsciiVarLen()	Creates a HttpStreamingSerializerDeserializer that serializes Strings with StandardCharsets.US_ASCII encoding using variable int length delimited framing.
static HttpStreamingSerializerDeserializer<String>	appSerializerFixLen(Charset charset)	Creates a HttpStreamingSerializerDeserializer that serializes Strings with charset encoding using fixed int length delimited framing.
static HttpStreamingSerializerDeserializer<String>	appSerializerUtf8FixLen()	Creates a HttpStreamingSerializerDeserializer that serializes Strings with StandardCharsets.UTF_8 encoding using fixed int length delimited framing.
static HttpStreamingSerializerDeserializer<String>	appSerializerUtf8VarLen()	Creates a HttpStreamingSerializerDeserializer that serializes Strings with StandardCharsets.UTF_8 encoding using variable int length delimited framing.
static HttpStreamingSerializerDeserializer<String>	appSerializerVarLen(Charset charset)	Creates a HttpStreamingSerializerDeserializer that serializes Strings with charset encoding using fixed int length delimited framing.
static HttpStreamingSerializer<byte[]>	bytesStreamingSerializer(Consumer<HttpHeaders> headersSerializeConsumer)	Create a HttpStreamingSerializer that serializes byte[].
static HttpSerializerDeserializer<Map<String,List<String>>>	formUrlEncodedSerializer()	Get a HttpSerializerDeserializer that can serialize a key-values Maps with StandardCharsets.UTF_8 Charset to urlencoded forms.
static HttpSerializerDeserializer<Map<String,List<String>>>	formUrlEncodedSerializer(Charset charset)	Get a HttpSerializerDeserializer that can serialize a key-values Maps with a Charset to urlencoded forms.
static <T> HttpSerializerDeserializer<T>	jsonSerializer(SerializerDeserializer<T> serializer)	Creates an HttpSerializerDeserializer that targets HttpHeaderValues.APPLICATION_JSON.
static <T> HttpStreamingSerializerDeserializer<T>	jsonStreamingSerializer(StreamingSerializerDeserializer<T> serializer)	Creates an HttpStreamingSerializerDeserializer that targets HttpHeaderValues.APPLICATION_JSON.
static <T> HttpSerializerDeserializer<T>	serializer(SerializerDeserializer<T> serializer, Consumer<HttpHeaders> headersSerializeConsumer, Predicate<HttpHeaders> headersDeserializePredicate)	Creates an HttpSerializerDeserializer that uses SerializerDeserializer for serialization.
static <T> HttpStreamingSerializer<T>	streamingSerializer(Serializer<T> serializer, ToIntFunction<T> bytesEstimator, Consumer<HttpHeaders> headersSerializeConsumer)	Create a HttpStreamingSerializer that uses a Serializer for serialization.
static <T> HttpStreamingSerializerDeserializer<T>	streamingSerializer(StreamingSerializerDeserializer<T> serializer, Consumer<HttpHeaders> headersSerializeConsumer, Predicate<HttpHeaders> headersDeserializePredicate)	Creates an HttpStreamingSerializerDeserializer that uses StreamingSerializerDeserializer for serialization.
static HttpStreamingSerializer<String>	stringStreamingSerializer(Charset charset, Consumer<HttpHeaders> headersSerializeConsumer)	Create a HttpStreamingSerializer that serializes String.
static HttpSerializerDeserializer<String>	textSerializer(Charset charset)	Creates an HttpSerializerDeserializer that can serialize Strings with a Charset.
static HttpSerializerDeserializer<String>	textSerializerAscii()	Creates an HttpSerializerDeserializer that can serialize Strings with StandardCharsets.US_ASCII.
static HttpSerializerDeserializer<String>	textSerializerUtf8()	Creates an HttpSerializerDeserializer that can serialize Strings with StandardCharsets.UTF_8.

Methods inherited from class java.lang.Object

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

Method Details

formUrlEncodedSerializer

public static HttpSerializerDeserializer<Map<String,List<String>>> formUrlEncodedSerializer()

Get a HttpSerializerDeserializer that can serialize a key-values Maps with StandardCharsets.UTF_8 Charset to urlencoded forms.

Returns:

HttpSerializerDeserializer that could serialize key-value Map.

See Also:

• x-www-form-urlencoded specification

formUrlEncodedSerializer

public static HttpSerializerDeserializer<Map<String,List<String>>> formUrlEncodedSerializer(Charset charset)

Get a HttpSerializerDeserializer that can serialize a key-values Maps with a Charset to urlencoded forms.

Parameters:

charset - The Charset to use for value encoding.

Returns:

HttpSerializerDeserializer that could serialize key-value Map.

See Also:

• x-www-form-urlencoded specification

textSerializerUtf8

public static HttpSerializerDeserializer<String> textSerializerUtf8()

Creates an HttpSerializerDeserializer that can serialize Strings with StandardCharsets.UTF_8.

Returns:

HttpSerializerDeserializer that can serialize Strings.

textSerializerAscii

public static HttpSerializerDeserializer<String> textSerializerAscii()

Creates an HttpSerializerDeserializer that can serialize Strings with StandardCharsets.US_ASCII.

Returns:

HttpSerializerDeserializer that can serialize Strings.

textSerializer

public static HttpSerializerDeserializer<String> textSerializer(Charset charset)

Creates an HttpSerializerDeserializer that can serialize Strings with a Charset.

Parameters:

charset - The Charset to use for encoding.

Returns:

HttpSerializerDeserializer that can serialize Strings.

appSerializerUtf8FixLen

public static HttpStreamingSerializerDeserializer<String> appSerializerUtf8FixLen()

Creates a HttpStreamingSerializerDeserializer that serializes Strings with StandardCharsets.UTF_8 encoding using fixed int length delimited framing. The framing is required so the same String objects can be deserialized by the peer, otherwise the boundaries aren't known. If the desire is to serialize raw data contained in the String, see stringStreamingSerializer(Charset, Consumer). The HttpHeaderNames.CONTENT_TYPE value prefix is "application/text-fix-int".

Returns:

a HttpStreamingSerializerDeserializer that serializes Strings with StandardCharsets.UTF_8 encoding using fixed int length delimited framing.

See Also:

• FixedLengthStreamingSerializer

appSerializerUtf8VarLen

public static HttpStreamingSerializerDeserializer<String> appSerializerUtf8VarLen()

Creates a HttpStreamingSerializerDeserializer that serializes Strings with StandardCharsets.UTF_8 encoding using variable int length delimited framing. The framing is required so the same String objects can be deserialized by the peer, otherwise the boundaries aren't known. If the desire is to serialize raw data contained in the String, see stringStreamingSerializer(Charset, Consumer). The HttpHeaderNames.CONTENT_TYPE value prefix is "application/text-var-int".

Returns:

a HttpStreamingSerializerDeserializer that serializes Strings with StandardCharsets.UTF_8 encoding using variable int length delimited framing.

See Also:

• VarIntLengthStreamingSerializer

appSerializerAsciiFixLen

public static HttpStreamingSerializerDeserializer<String> appSerializerAsciiFixLen()

Creates a HttpStreamingSerializerDeserializer that serializes Strings with StandardCharsets.US_ASCII encoding using fixed int length delimited framing. The framing is required so the same String objects can be deserialized by the peer, otherwise the boundaries aren't known. If the desire is to serialize raw data contained in the String, see stringStreamingSerializer(Charset, Consumer). The HttpHeaderNames.CONTENT_TYPE value prefix is "application/text-fix-int".

Returns:

a HttpStreamingSerializerDeserializer that serializes Strings with StandardCharsets.US_ASCII encoding using fixed int length delimited framing.

See Also:

• FixedLengthStreamingSerializer

appSerializerAsciiVarLen

public static HttpStreamingSerializerDeserializer<String> appSerializerAsciiVarLen()

Creates a HttpStreamingSerializerDeserializer that serializes Strings with StandardCharsets.US_ASCII encoding using variable int length delimited framing. The framing is required so the same String objects can be deserialized by the peer, otherwise the boundaries aren't known. If the desire is to serialize raw data contained in the String, see stringStreamingSerializer(Charset, Consumer). The HttpHeaderNames.CONTENT_TYPE value prefix is "application/text-var-int".

Returns:

a HttpStreamingSerializerDeserializer that serializes Strings with StandardCharsets.US_ASCII encoding using variable int length delimited framing.

See Also:

• VarIntLengthStreamingSerializer

appSerializerFixLen

public static HttpStreamingSerializerDeserializer<String> appSerializerFixLen(Charset charset)

Creates a HttpStreamingSerializerDeserializer that serializes Strings with charset encoding using fixed int length delimited framing. The framing is required so the same String objects can be deserialized by the peer, otherwise the boundaries aren't known. If the desire is to serialize raw data contained in the String, see stringStreamingSerializer(Charset, Consumer). The HttpHeaderNames.CONTENT_TYPE value prefix is "application/text-fix-int".

Parameters:

charset - The character encoding to use for serialization.

Returns:

a HttpStreamingSerializerDeserializer that serializes Strings with charset encoding using fixed int length delimited framing.

See Also:

• FixedLengthStreamingSerializer

appSerializerVarLen

public static HttpStreamingSerializerDeserializer<String> appSerializerVarLen(Charset charset)

Creates a HttpStreamingSerializerDeserializer that serializes Strings with charset encoding using fixed int length delimited framing. The framing is required so the same String objects can be deserialized by the peer, otherwise the boundaries aren't known. If the desire is to serialize raw data contained in the String, see stringStreamingSerializer(Charset, Consumer). The HttpHeaderNames.CONTENT_TYPE value prefix is "application/text-var-int".

Parameters:

charset - The character encoding to use for serialization.

Returns:

a HttpStreamingSerializerDeserializer that serializes Strings with charset encoding using fixed int length delimited framing.

See Also:

• VarIntLengthStreamingSerializer

stringStreamingSerializer

public static HttpStreamingSerializer<String> stringStreamingSerializer(Charset charset,
 Consumer<HttpHeaders> headersSerializeConsumer)

Create a HttpStreamingSerializer that serializes String. This method is useful if the payload body is provided in String and the HttpHeaderNames.CONTENT_TYPE is known a-priori (e.g. streaming raw json data from a stream of Strings). Deserialization should be done using the a-priori knowledge to use a compatible HttpStreamingDeserializer. To elaborate why a-priori knowledge of how content is consumed/deserialized is required consider the following caveats of this method:

• Lack of framing - There is no guarantee deserialization will be able to recover the same String objects. For example, if ("foo", "bar") is serialized the deserialization may not be able to reliably return "foo" and "bar". If the result of the serialization is sent as a stream of bytes (e.g. TCP over a network) the deserialization will produce Strings as read from the stream. For example, if the deserialization is done in a streaming fashion this is a valid result: ("f", "o", "oba", "r"). If the receiver always aggregates data before deserialization they will reliably get "foobar".
• Broken encoding - If your String encoding represents a single character with multiple bytes (e.g. StandardCharsets.UTF_8) the deserialization may encounter errors if the results are processed as a stream of bytes (see description above).

Note appSerializerFixLen(Charset) and appSerializerVarLen(Charset) introduce a framing and therefore are not subject to the above caveats.

Parameters:

charset - The character encoding to use for serialization.

headersSerializeConsumer - Sets the headers to indicate the appropriate encoding and content type.

Returns:

a HttpStreamingSerializer that uses a Serializer for serialization.

bytesStreamingSerializer

public static HttpStreamingSerializer<byte[]> bytesStreamingSerializer(Consumer<HttpHeaders> headersSerializeConsumer)

Create a HttpStreamingSerializer that serializes byte[]. This method is useful if the payload body is provided in byte[] and the HttpHeaderNames.CONTENT_TYPE is known a-priori (e.g. streaming raw json data from a stream of byte[]s). Deserialization should be done using the a-priori knowledge to use a compatible HttpStreamingDeserializer.

Parameters:

headersSerializeConsumer - Sets the headers to indicate the appropriate encoding and content type.

Returns:

a HttpStreamingSerializer that uses a Serializer for serialization.

jsonSerializer

public static <T> HttpSerializerDeserializer<T> jsonSerializer(SerializerDeserializer<T> serializer)

Creates an HttpSerializerDeserializer that targets HttpHeaderValues.APPLICATION_JSON.

Type Parameters:

T - Type of object to serialize.

Parameters:

serializer - Used to serialize each HttpSerializers.

Returns:

HttpSerializerDeserializer that targets HttpHeaderValues.APPLICATION_JSON.

jsonStreamingSerializer

public static <T>
HttpStreamingSerializerDeserializer<T> jsonStreamingSerializer(StreamingSerializerDeserializer<T> serializer)

Creates an HttpStreamingSerializerDeserializer that targets HttpHeaderValues.APPLICATION_JSON.

Type Parameters:

T - Type of object to serialize.

Parameters:

serializer - Used to serialize each HttpSerializers.

Returns:

HttpStreamingSerializerDeserializer that targets HttpHeaderValues.APPLICATION_JSON.

serializer

public static <T> HttpSerializerDeserializer<T> serializer(SerializerDeserializer<T> serializer,
 Consumer<HttpHeaders> headersSerializeConsumer,
 Predicate<HttpHeaders> headersDeserializePredicate)

Creates an HttpSerializerDeserializer that uses SerializerDeserializer for serialization.

Type Parameters:

T - Type of object to serialize.

Parameters:

serializer - Used to serialize each HttpSerializers.

headersSerializeConsumer - Sets the headers to indicate the appropriate encoding and content type.

headersDeserializePredicate - Validates the headers are of the supported encoding and content type.

Returns:

HttpSerializerDeserializer that uses a SerializerDeserializer for serialization.

streamingSerializer

public static <T>
HttpStreamingSerializerDeserializer<T> streamingSerializer(StreamingSerializerDeserializer<T> serializer,
 Consumer<HttpHeaders> headersSerializeConsumer,
 Predicate<HttpHeaders> headersDeserializePredicate)

Creates an HttpStreamingSerializerDeserializer that uses StreamingSerializerDeserializer for serialization.

Type Parameters:

T - Type of object to serialize.

Parameters:

serializer - Used to serialize each HttpSerializers.

headersSerializeConsumer - Sets the headers to indicate the appropriate encoding and content type.

headersDeserializePredicate - Validates the headers are of the supported encoding and content type.

Returns:

HttpStreamingSerializerDeserializer that uses a StreamingSerializerDeserializer for serialization.

streamingSerializer

public static <T> HttpStreamingSerializer<T> streamingSerializer(Serializer<T> serializer,
 ToIntFunction<T> bytesEstimator,
 Consumer<HttpHeaders> headersSerializeConsumer)

Create a HttpStreamingSerializer that uses a Serializer for serialization. This method is useful if the payload body is provided in non-Buffer type and the HttpHeaderNames.CONTENT_TYPE is known a-priori (e.g. streaming raw json data from a stream of Strings). Deserialization should be done using the a-priori knowledge to use a compatible HttpStreamingDeserializer.

Type Parameters:

T - Type of object to serialize.

Parameters:

serializer - Used to serialize each HttpSerializers chunk.

bytesEstimator - Provides an estimate of how many bytes to allocate for each Buffer to serialize to.

headersSerializeConsumer - Sets the headers to indicate the appropriate encoding and content type.

Returns:

a HttpStreamingSerializer that uses a Serializer for serialization.