io.dropwizard.views.common.ViewBundle Maven / Gradle / Ivy

Go to download
package io.dropwizard.views.common;

import io.dropwizard.core.ConfiguredBundle;
import io.dropwizard.core.setup.Environment;

import java.util.Collections;
import java.util.HashSet;
import java.util.Map;
import java.util.ServiceLoader;
import java.util.Set;


/**
 * A {@link ConfiguredBundle}, which by default, enables the rendering of FreeMarker & Mustache views by your application.
 *
 * Other instances of {@link ViewRenderer} can be used by initializing your {@link ViewBundle} with a
 * {@link Iterable} of the {@link ViewRenderer} instances to be used when configuring your {@link ConfiguredBundle}:
 *
 * 
 * new ViewBundle(ImmutableList.of(myViewRenderer))
 * 
 *
 * A view combines a Freemarker or Mustache template with a set of Java objects:
 *
 * 
 * public class PersonView extends View {
 *     private final Person person;
 *
 *     public PersonView(Person person) {
 *         super("profile.ftl"); // or super("profile.mustache"); for a Mustache template
 *         this.person = person;
 *     }
 *
 *     public Person getPerson() {
 *         return person;
 *     }
 * }
 * 
 *
 * The {@code "profile.ftl[hx]"} or {@code "profile.mustache"} is the path of the template relative to the class name. If
 * this class was {@code com.example.application.PersonView}, Freemarker or Mustache would then look for the file
 * {@code src/main/resources/com/example/application/profile.ftl} or {@code
 * src/main/resources/com/example/application/profile.mustache} respectively. If the template path
 * starts with a slash (e.g., {@code "/hello.ftl"} or {@code "/hello.mustache"}), Freemarker or Mustache will look for
 * the file {@code src/main/resources/hello.ftl} or {@code src/main/resources/hello.mustache} respectively.
 *
 * 
A resource method with a view would looks something like this:
 *
 *  * @GET
 * public PersonView getPerson(@PathParam("id") String id) {
 *     return new PersonView(dao.find(id));
 * }
 * 
 *
 * Freemarker templates look something like this:
 *
 * {@code
 * <#-- @ftlvariable name="" type="com.example.application.PersonView" -->
 * 
 *     
 *         Hello, ${person.name?html}!
 *     
 * 
 * }
 *
 * In this template, {@code ${person.name}} calls {@code getPerson().getName()}, and the
 * {@code ?html} escapes all HTML control characters in the result. The {@code ftlvariable} comment
 * at the top indicate to Freemarker (and your IDE) that the root object is a {@code Person},
 * allowing for better type-safety in your templates.
 *
 * See Also: FreeMarker Manual
 *
 * Mustache templates look something like this:
 *
 * {@code
 * 
 *     
 *         Hello, {{person.name}}!
 *     
 * 
 * }
 *
 * In this template, {@code {{person.name}}} calls {@code getPerson().getName()}.
 *
 * See Also: Mustache Manual
 */
public class ViewBundle implements ConfiguredBundle, ViewConfigurable {
    private final Iterable viewRenderers;

    public ViewBundle() {
        this(ServiceLoader.load(ViewRenderer.class));
    }

    public ViewBundle(Iterable viewRenderers) {
        final Set viewRendererSet = new HashSet<>();

        viewRenderers.forEach(viewRendererSet::add);

        this.viewRenderers = Collections.unmodifiableSet(viewRendererSet);
    }

    @Override
    public Map> getViewConfiguration(T configuration) {
        return Map.of();
    }

    @Override
    public void run(T configuration, Environment environment) throws Exception {
        final Map> options = getViewConfiguration(configuration);
        for (ViewRenderer viewRenderer : viewRenderers) {
            final Map viewOptions = options.get(viewRenderer.getConfigurationKey());
            viewRenderer.configure(viewOptions == null ? Map.of() : viewOptions);
        }
        environment.jersey().register(new ViewMessageBodyWriter(environment.metrics(), viewRenderers));
    }
}