ratpack.render.Renderer Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of ratpack-core Show documentation
The core HTTP and composition mechanisms of Ratpack
There is a newer version: 2.0.0-rc-1
/*
 * Copyright 2013 the original author or authors.
 *
 * 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 ratpack.render;

import com.google.common.reflect.TypeParameter;
import com.google.common.reflect.TypeToken;
import ratpack.api.NonBlocking;
import ratpack.func.Action;
import ratpack.handling.Context;
import ratpack.registry.RegistrySpec;
import ratpack.util.Types;

import java.util.function.BiConsumer;

/**
 * A renderer is responsible for rendering an object to the response.
 * 
 * Renderers are typically not used directly.
 * Instead, they are used via by {@link Context#render(Object)} method.
 * 

 * See {@link RendererSupport} for support base class for implementations.
 * 

 * An alternative to implementing a renderer for a type is to make the type directly implement {@link Renderable}.
 *
 * @param  The type of object that this renderer knows how to render.
 * @see RendererSupport
 * @see RenderableDecorator
 * @see Renderable
 */
public interface Renderer {

  /**
   * An action that registers this renderer with a registry.
   * 

   * Can be used with the {@link RegistrySpec#with(Action)} method of a registry spec.
   *
   * @return an action that registers this renderer with a registry
   */
  default Action register() {
    return (registrySpec) -> registrySpec.add(typeOf(getType()), this);
  }

  /**
   * Creates a type token for a compatible renderer of the given type of object.
   *
   * @param toRender the type that the renderer renders
   * @param  the type that the renderer renders
   * @return a type token for a compatible renderer of the given type of object
   */
  static  TypeToken> typeCompatibleOf(T toRender) {
    Class clazz = Types.cast(toRender.getClass());
    return new TypeToken>(clazz) {}.where(new TypeParameter() {}, clazz);
  }

  /**
   * Creates a renderer implementation from the given arguments.
   *
   * @param type the type of object-to-render
   * @param impl the implementation of the {@link #render(Context, Object)} method
   * @param  the type of object-to-render
   * @return a renderer implementation
   */
  static  Renderer of(Class type, BiConsumer impl) {
    return new Renderer() {
      @Override
      public Class getType() {
        return type;
      }

      @Override
      public void render(Context context, T object) throws Exception {
        impl.accept(context, object);
      }
    };
  }

  /**
   * Creates a type token for a renderer of the given type of object.
   *
   * @param typeToRender the type that the renderer renders
   * @param  the type that the renderer renders
   * @return a type token for a renderer of the given type of object
   */
  static  TypeToken> typeOf(Class typeToRender) {
    return new TypeToken>(typeToRender) {}.where(new TypeParameter() {}, typeToRender);
  }

  /**
   * The type of object that this renderer can render.
   *
   * @return The type of object that this renderer can render.
   */
  Class getType();

  /**
   * Render the given object to the response.
   * 

   * Calling this method will finalize the processing, sending the response to the client.
   * 
   * Any errors that occur during rendering will be sent to {@link Context#error(Throwable)}.
   *
   * @param context the context for the operation
   * @param object the object to render
   * @throws Exception if anything goes wrong while rendering
   */
  @NonBlocking
  void render(Context context, T object) throws Exception;

}