org.webbitserver.handler.TemplateEngine Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of webbit Show documentation

A Java event based WebSocket and HTTP server

There is a newer version: 0.4.15

package org.webbitserver.handler;

/**
 * Abstract interface for template engines. It can be passed as an argument to the constructors of
 * {@link StaticFileHandler} and {@link EmbeddedResourceHandler}.
 * 
 * Webbit itself doesn't provide any template engines. Look at Webbit-REST
 * for implementations.
 */
public interface TemplateEngine {
    String TEMPLATE_CONTEXT = "TEMPLATE_CONTEXT";

    /**
     * Renders a template.
     * 

     * Most template engines merge a {@code templateContext} with a template to produce output. What constitutes a valid
     * context is template-engine specific.
     * 

     * Rendering happens on your main thread, so it is important that this method is not IO-bound. For example,
     * rendering a template using a context that is some sort of active record
     * that makes trips to the database will block Webbit preventing it from handling other requests. It's important to
     * make sure any remote data is pre-fetched.
     * 
     * Webbit will pass the request data value keyed with {@link #TEMPLATE_CONTEXT} as the {@code templateContext} argument.
     * It's the programmer's responsibility to make sure the data value is set before the template is rendered,
     * i.e. before the {@link StaticFileHandler} or {@link EmbeddedResourceHandler} handler instance handles a request.
     *
     * @param length          number of bytes in the template
     * @param template        the template source
     * @param templatePath    the path the template is read from. Allows implementations to cache compiled templates.
     * @param templateContext object to merge into the template
     * @return a rendered template
     * @see org.webbitserver.HttpRequest#data(String)
     * @see org.webbitserver.HttpRequest#data(String, Object)
     */
    byte[] process(byte[] template, String templatePath, Object templateContext) throws RuntimeException;
}