com.yahoo.processing.rendering.Renderer Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of container-core Show documentation
There is a newer version: 8.458.13
// Copyright Yahoo. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.processing.rendering;

import com.yahoo.component.AbstractComponent;
import com.yahoo.processing.Request;
import com.yahoo.processing.Response;
import com.yahoo.processing.execution.Execution;

import java.io.OutputStream;
import java.util.concurrent.CompletableFuture;

/**
 * Renders a response to a stream. The renderers are cloned just before
 * rendering, and must therefore obey the following contract:
 *
 * 
 * At construction time, only final members shall be initialized, and these
 * must refer to immutable data only.
 * State mutated during rendering shall be initialized in the init method.
 * 
 *
 * @author Tony Vaagenes
 * @author Steinar Knutsen
 */
public abstract class Renderer extends AbstractComponent implements Cloneable {

    /**
     * Used to create a separate instance for each result to render.
     */
    @SuppressWarnings("unchecked")
    @Override
    public Renderer clone() {
        return (Renderer) super.clone();
    }

    /**
     * Initializes the mutable state, see the contract in the class
     * documentation. Called on the clone just before rendering.
     */
    public void init() {
    }

    /**
     * Render a response to a stream. The stream also exposes a ByteBuffer API
     * for efficient transactions to JDisc. The returned future will throw the
     * exception causing failure wrapped in an ExecutionException if rendering
     * was not successful.
     *
     * @param stream a stream API bridge to JDisc
     * @param response the response to render
     * @param execution the execution which created this response
     * @param request the request matching the response
     * @return a {@link CompletableFuture} containing a boolean where true indicates a successful rendering
     */
    public abstract CompletableFuture renderResponse(OutputStream stream, RESPONSE response,
                                                              Execution execution, Request request);

    /**
     * Name of the output encoding, if applicable.
     *
     * @return the encoding of the output if applicable, e.g. "utf-8"
     */
    public abstract String getEncoding();

    /**
     * The MIME type of the rendered content sent to the client.
     *
     * @return The mime type of the data written to the writer, e.g. "text/plain"
     */
    public abstract String getMimeType();

}