001/*
002 * Shredzone Commons
003 *
004 * Copyright (C) 2012 Richard "Shred" Körber
005 *   http://commons.shredzone.org
006 *
007 * This program is free software: you can redistribute it and/or modify
008 * it under the terms of the GNU Library General Public License as
009 * published by the Free Software Foundation, either version 3 of the
010 * License, or (at your option) any later version.
011 *
012 * This program is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
015 * GNU General Public License for more details.
016 *
017 * You should have received a copy of the GNU Library General Public License
018 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
019 */
020
021package org.shredzone.commons.view;
022
023import javax.annotation.Nonnull;
024import javax.annotation.ParametersAreNonnullByDefault;
025import javax.servlet.http.HttpServletRequest;
026import javax.servlet.http.HttpServletResponse;
027
028import org.shredzone.commons.view.exception.PageNotFoundException;
029import org.shredzone.commons.view.exception.ViewException;
030
031/**
032 * Service for rendering views, creating links to views, and handling servlet requests.
033 * <p>
034 * <em>Note:</em> A servlet delegates a request to
035 * {@link #handleRequest(HttpServletRequest, HttpServletResponse)}. The other methods are
036 * request scoped and must only be invoked from the same thread that invoked
037 * {@link #handleRequest(HttpServletRequest, HttpServletResponse) handleRequest()}.
038 *
039 * @author Richard "Shred" Körber
040 */
041@ParametersAreNonnullByDefault
042public interface ViewService {
043
044    /**
045     * Handles a HTTP request. This method is usually invoked from a servlet.
046     *
047     * @param req
048     *            {@link HttpServletRequest}
049     * @param resp
050     *            {@link HttpServletResponse}
051     * @throws ViewException
052     *             if the request could not be handled
053     */
054    void handleRequest(HttpServletRequest req, HttpServletResponse resp) throws ViewException;
055
056    /**
057     * Gets the {@link ViewContext} of the current request.
058     *
059     * @return {@link ViewContext}
060     */
061    ViewContext getViewContext();
062
063    /**
064     * Builds an URL path to a view that is able to render the provided data.
065     *
066     * @param context
067     *            {@link PathContext} containing all the data for the path
068     * @param view
069     *            name of the view to build a path to
070     * @param type
071     *            {@link PathType} to be built
072     * @return the URL path that was built, or {@code null} if no view was found to be
073     *         able to render the provided data
074     */
075    String buildPath(PathContext context, String view, PathType type);
076
077    /**
078     * Analyzes the given path, and invokes a view handler for processing the request.
079     *
080     * @param path
081     *            the requested path
082     * @return String returned by the view handler, usually the name of a JSP template to
083     *         forward the request to. May be {@code null} if the handler already took
084     *         care for the response itself.
085     * @throws PageNotFoundException
086     *             if no view was matching the given path
087     * @throws ViewException
088     *             if the view handler could not be invoked or could not handle the
089     *             request
090     */
091    String invokeView(String path) throws ViewException;
092
093    /**
094     * Gets the path to a template resource with the given name. It is not checked if the
095     * template actually exists.
096     *
097     * @param template
098     *            Template name
099     * @return Template path
100     */
101    @Nonnull String getTemplatePath(String template);
102
103}