io.baratine.web.ViewResolver Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of api Show documentation
A reactive Java web server.
The newest version!
/*
 * Copyright (c) 1998-2015 Caucho Technology -- all rights reserved
 *
 * This file is part of Baratine(TM)
 *
 * Each copy or derived work must preserve the copyright notice and this
 * notice unmodified.
 *
 * Baratine is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * Baratine is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, or any warranty
 * of NON-INFRINGEMENT.  See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Baratine; if not, write to the
 *
 *   Free Software Foundation, Inc.
 *   59 Temple Place, Suite 330
 *   Boston, MA 02111-1307  USA
 *
 * @author Scott Ferguson
 */

package io.baratine.web;

/**
 * Interface ViewResolver provides support for custom response presentation
 * 
 * Custom ViewResolvers should be used for rendering of a View response
 * type. View, is a named Map supplied as a result of request processing e.g.
 * 

 * 
 *   @Get
 *   public void indexHtml(RequestWeb request) {
 *     View view = View.newView("index.velocity");
 *     view.put("greeting", "Hello");
 *     //
 *     request.ok(view);
 *   }
 *   ...
 *   public class VelocityViewResolver implements ViewResolver<View>{
 *     public boolean render(RequestWeb request, View view) {
 *       //call to velocity to render the request
 *       return true;
 *     }
 *   }
 * 
 * 
 * A ViewResolver can also support more complicated JavaBean types or simple
 * types such as Strings:
 * 

 * 
 *   @Get
 *   public void getGreeting(RequestWeb request) {
 *     request.ok("Hello World!");
 *   }
 *   ...
 *   public class StringViewResolver implements ViewResolver<String> {
 *     public boolean render(RequestWeb request, String value) {
 *       request.write("greeting: ");
 *       request.write(value);
 *       request.ok();
 *       return true;
 *     }
 *   }
 * 
 * 
 * Along with {@code View} class, ViewResolvers provide convenient base for
 * integrating with a variety of rendering engines. Baratine provides out of the
 * box support for FreeMarker, Velocity, Mustache, JetBrick, Jade and Thymeleaf.
 * 

 * ViewResolvers can be registered in one of the following ways:
 * 

 * 

 * by placing into *.autoconf.* package and calling Web.scanAutoConf() 
 * by calling Web.scan(Package) on the Package where custom ViewResolver reside
 * programmatically via Web.bean(MyViewResolver.class).to(key)
 * 
 * 
 * Register ViewResolver from .autoconf. package
 * 
 *   package org.acme.autoconf.resolvers;
 *   @Include
 *   public class StringViewResolver implements ViewResolver<String> {
 *     ...
 *   }
 *   ...
 *   Web.scanAutoConf();//discovers and registers the StringViewResolver
 * 
 * 
 * Register ViewResolver with scan(Package)
 * 
 *   Web.scan(StringViewResolver.class.getPackage());
 * 
 * Register ViewResolver programmatically
 *  *   Type bindingType = StringViewResolver.class.getGenericInterfaces()[0];
 *   //important to bind to parameterized type ViewResolver<String>
 *   Web.bean(StringViewResolver.class).to(Key.of(bindingType));
 * 
 * 
 *
 * @param  type of value to render
 * @see View
 */
public interface ViewResolver
{
  /**
   * Renders value into request object. Note, that request object provides all
   * capabilities necessary for writing rendering data, such as OutputStream,
   * Writer, etc.
   * 

   * Baratine rendering algorithm will uses return value to determine if other
   * ViewResolvers should be called on the same value.
   * e.g.
   * 
   * public class MyGreetingResolver implements ViewResolver<String>{
   *   public boolean render(RequestWeb request, String value) {
   *     if (value.startsWith("Hello")) {
   *       //render
   *       return true;
   *     }
   *     return false;
   *   }
   * }
   * 
   * Only the greetings will be rendered using the MyGreetingResolver.
   * Other String values will be rendered using remaining matching ViewResolver<String>
   * resolvers.
   * 
   * Resolvers can declare priority using @Priority annotation.
   *
   * @param request original request.
   * @param value   value to render
   * @return true if the ViewResolver rendered the object, false otherwise
   */
  boolean render(RequestWeb request, T value);
}