com.palantir.conjure.java.dialogue.serde.Encoding Maven / Gradle / Ivy
/*
* (c) Copyright 2019 Palantir Technologies Inc. All rights reserved.
*
* Licensed 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.
*/
package com.palantir.conjure.java.dialogue.serde;
import com.palantir.dialogue.TypeMarker;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
/**
* An encoding provides support for a Content-Type
corresponding with the conjure wire format. Encodings
* provide a {@link Encoding#getContentType() content type} string as well as factories for typed {@link Serializer}
* and {@link Deserializer} objects.
*
* This interface is considered internal API and may change without a major version rev. Custom implementations
* are not recommended, but may be implemented to test custom encodings without a fork of the runtime.
*/
public interface Encoding {
/**
* Creates a new {@link Serializer} for the requested type. It is recommended to reuse instances over requesting
* new ones for each request.
*/
Serializer serializer(TypeMarker type);
/**
* Creates a new {@link Deserializer} for the requested type. It is recommended to reuse instances over requesting
* new ones for each request.
*/
Deserializer deserializer(TypeMarker type);
/** Returns the value used in request Content-Type
headers. */
String getContentType();
/**
* Checks if a Content-Type
or Accept
value is supported by this encoding. This is not an
* exact match on {@link #getContentType()} because values may contain additional metadata, for
* example Content-Type: application/json; charset=utf-8
may be supported by an {@link Encoding}
* which returns application/json
from {@link #getContentType()}.
*/
boolean supportsContentType(String contentType);
interface Deserializer {
/**
* Reads a serialized type-{@link T} object representation from the given input stream and returns the
* corresponding object. Implementations should read the entire input stream and must close it (unless they
* return the raw InputStream, e.g. for a binary response type).
*
* Format-related deserialization errors surface as {@link IllegalArgumentException}. Inputs and outputs
* must never be null.
*/
T deserialize(InputStream input) throws IOException;
}
interface Serializer {
/**
* Serializes the given object and writes the serialized representation to the given output stream.
* Implementations must not close the stream. Inputs must never be null.
*/
void serialize(T value, OutputStream output) throws IOException;
}
}