com.palantir.conjure.java.undertow.runtime.Encoding Maven / Gradle / Ivy
/*
* (c) Copyright 2018 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.undertow.runtime;
import com.palantir.conjure.java.undertow.lib.Endpoint;
import com.palantir.conjure.java.undertow.lib.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);
default Serializer serializer(TypeMarker type, Endpoint _endpoint) {
return serializer(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);
default Deserializer deserializer(TypeMarker type, Endpoint _endpoint) {
return deserializer(type);
}
/**
* Returns the value used in response
*
* Content-Type
*
* header.
*/
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 are
* case-insensitive, see RFC 7231, and 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, but must not close it.
* 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;
}
}