/**
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you 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 org.jooby;
import java.io.InputStream;
import java.io.Reader;
import java.nio.ByteBuffer;
import java.nio.CharBuffer;
import java.nio.channels.FileChannel;
import java.nio.charset.Charset;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import com.google.common.base.CaseFormat;
import com.google.inject.Key;
import com.google.inject.TypeLiteral;
/**
* Write a value into the HTTP response and apply a format, if need it.
*
* Renderers are executed in the order they were registered. The first renderer that write a
* response wins!
*
* There are two ways of registering a rendering:
*
* <pre>
* {
* renderer((value, ctx) {@literal ->} {
* ...
* });
* }
* </pre>
*
* Or from inside a module:
*
* <pre>
* {
* use((env, conf, binder) {@literal ->} {
* Multibinder.newSetBinder(binder, Renderer.class)
* .addBinding()
* .toInstance((value, ctx) {@literal ->} {
* ...
* }));
* });
* }
* </pre>
*
* Inside a {@link Renderer} you can do whatever you want. For example you can check for a specific
* type:
*
* <pre>
* renderer((value, ctx) {@literal ->} {
* if (value instanceof MyObject) {
* ctx.send(value.toString());
* }
* });
* </pre>
*
* Or check for the <code>Accept</code> header:
*
* <pre>
* renderer((value, ctx) {@literal ->} {
* if (ctx.accepts("json")) {
* ctx.send(toJson(value));
* }
* });
* </pre>
*
* API is simple and powerful!
*
* @author edgar
* @since 0.6.0
*/
public interface Renderer {
/**
* Contains a few utility methods for doing the actual rendering and writing.
*
* @author edgar
* @since 0.6.0
*/
interface Context {
/**
* Request locale or default locale.
*
* @return Request locale or default locale.
*/
Locale locale();
/**
* @return Request local attributes.
*/
Map<String, Object> locals();
/**
* True if the given type matches the <code>Accept</code> header.
*
* @param type The type to check for.
* @return True if the given type matches the <code>Accept</code> header.
*/
default boolean accepts(final String type) {
return accepts(MediaType.valueOf(type));
}
/**
* True if the given type matches the <code>Accept</code> header.
*
* @param type The type to check for.
* @return True if the given type matches the <code>Accept</code> header.
*/
boolean accepts(final MediaType type);
/**
* Set the <code>Content-Type</code> header IF and ONLY IF, no <code>Content-Type</code> was set
* yet.
*
* @param type A suggested type to use if one is missing.
* @return This context.
*/
default Context type(final String type) {
return type(MediaType.valueOf(type));
}
/**
* Set the <code>Content-Type</code> header IF and ONLY IF, no <code>Content-Type</code> was set
* yet.
*
* @param type A suggested type to use if one is missing.
* @return This context.
*/
Context type(MediaType type);
/**
* Set the <code>Content-Length</code> header IF and ONLY IF, no <code>Content-Length</code> was
* set yet.
*
* @param length A suggested length to use if one is missing.
* @return This context.
*/
Context length(long length);
/**
* @return Charset to use while writing text responses.
*/
Charset charset();
/**
* Write bytes into the HTTP response body.
*
* It will set a <code>Content-Length</code> if none was set
* It will set a <code>Content-Type</code> to {@link MediaType#octetstream} if none was set.
*
* @param bytes A bytes to write.
* @throws Exception When the operation fails.
*/
void send(byte[] bytes) throws Exception;
/**
* Write byte buffer into the HTTP response body.
*
* It will set a <code>Content-Length</code> if none was set.
* It will set a <code>Content-Type</code> to {@link MediaType#octetstream} if none was set.
*
* @param buffer A buffer to write.
* @throws Exception When the operation fails.
*/
void send(ByteBuffer buffer) throws Exception;
/**
* Write text into the HTTP response body.
*
* It will set a <code>Content-Length</code> if none was set.
* It will set a <code>Content-Type</code> to {@link MediaType#html} if none was set.
*
* @param text A text to write.
* @throws Exception When the operation fails.
*/
void send(String text) throws Exception;
/**
* Write bytes into the HTTP response body.
*
* It will set a <code>Content-Length</code> if the response size is less than the
* <code>server.ResponseBufferSize</code> (default is: 16k). If the response is larger than the
* buffer size, it will set a <code>Transfer-Encoding: chunked</code> header.
*
* It will set a <code>Content-Type</code> to {@link MediaType#octetstream} if none was set.
*
* This method will check if the given input stream has a {@link FileChannel} and redirect to
* file
*
* @param stream Bytes to write.
* @throws Exception When the operation fails.
*/
void send(InputStream stream) throws Exception;
/**
* Write text into the HTTP response body.
*
* It will set a <code>Content-Length</code> if none was set.
* It will set a <code>Content-Type</code> to {@link MediaType#html} if none was set.
*
* @param buffer A text to write.
* @throws Exception When the operation fails.
*/
void send(CharBuffer buffer) throws Exception;
/**
* Write text into the HTTP response body.
*
* It will set a <code>Content-Length</code> if the response size is less than the
* <code>server.ResponseBufferSize</code> (default is: 16k). If the response is larger than the
* buffer size, it will set a <code>Transfer-Encoding: chunked</code> header.
*
* It will set a <code>Content-Type</code> to {@link MediaType#html} if none was set.
*
* @param reader Text to write.
* @throws Exception When the operation fails.
*/
void send(Reader reader) throws Exception;
/**
* Write file into the HTTP response body, using OS zero-copy transfer (if possible).
*
* It will set a <code>Content-Length</code> if none was set.
* It will set a <code>Content-Type</code> to {@link MediaType#html} if none was set.
*
* @param file A text to write.
* @throws Exception When the operation fails.
*/
void send(FileChannel file) throws Exception;
}
/** Renderer key. */
Key<Set<Renderer>> KEY = Key.get(new TypeLiteral<Set<Renderer>>() {
});
/**
* @return Renderer's name.
*/
default String name() {
String name = getClass().getSimpleName()
.replace("renderer", "")
.replace("render", "");
return CaseFormat.UPPER_CAMEL.to(CaseFormat.LOWER_HYPHEN, name);
}
/**
* Render the given value and write the response (if possible). If no response is written, the
* next renderer in the chain will be invoked.
*
* @param value Object to render.
* @param ctx Rendering context.
* @throws Exception If rendering fails.
*/
void render(Object value, Context ctx) throws Exception;
/**
* Renderer factory method.
*
* @param name Renderer's name.
* @param renderer Renderer's function.
* @return A new renderer.
*/
static Renderer of(final String name, final Renderer renderer) {
return new Renderer() {
@Override
public void render(final Object value, final Context ctx) throws Exception {
renderer.render(value, ctx);
}
@Override
public String name() {
return name;
}
};
}
}