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 java.util.Map;
024
025import javax.annotation.Nonnull;
026import javax.annotation.Nullable;
027import javax.annotation.ParametersAreNonnullByDefault;
028
029import org.shredzone.commons.view.exception.ViewContextException;
030
031/**
032 * Provides a context of the View that is to be rendered in this request.
033 * <p>
034 * A {@link ViewContext} is request scoped and only valid in threads that ran
035 * {@link ViewService#handleRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)}.
036 *
037 * @author Richard "Shred" Körber
038 */
039@ParametersAreNonnullByDefault
040public interface ViewContext {
041
042    /**
043     * Returns the server URL the request was sent to. The URL contains the protocol, the
044     * domain and (optionally) the port.
045     *
046     * @return the server URL (e.g. "http://www.shredzone.de")
047     */
048    @Nonnull String getRequestServerUrl();
049
050    /**
051     * Returns the name of the servlet that processed the request.
052     *
053     * @return the servlet name (e.g. "/cilla")
054     */
055    @Nonnull String getRequestServletName();
056
057    /**
058     * Adds a typed argument to this context. Typed arguments are available to the view
059     * handler's parameter list.
060     *
061     * @param type
062     *            Type this argument is to be registered with (may be the value's type or
063     *            a supertype)
064     * @param value
065     *            the value to register, may be {@code null}
066     */
067    <T> void putTypedArgument(Class<T> type, @Nullable T value);
068
069    /**
070     * Gets a value that matches the requested type.
071     *
072     * @param <T>
073     *            the requested type
074     * @param type
075     *            type to get a value for
076     * @return a value for that type, may be {@code null} if the type's value was set to
077     *         {@code null}.
078     * @throws ViewContextException
079     *             if there was no data satisfying that type
080     */
081    <T> T getValueOfType(@Nullable Class<T> type) throws ViewContextException;
082
083    /**
084     * Sets the path parts from resolving the view URL. Should only be invoked from the
085     * {@link ViewService}.
086     *
087     * @param pathParts
088     *            Map of path parts
089     */
090    void setPathParts(Map<String, String> pathParts);
091
092    /**
093     * Gets a map of all path parts. This map is immutable.
094     *
095     * @return Map of path parts
096     */
097    @Nonnull Map<String, String> getPathParts();
098
099    /**
100     * Gets a parameter from the request URL's search part.
101     *
102     * @param name
103     *            the parameter name
104     * @return parameter value, or {@code null} if there is no such parameter
105     */
106    String getParameter(String name);
107
108    /**
109     * Sets a View qualifier.
110     *
111     * @param qualifier
112     *            qualifier to be used, or {@code null} for the standard qualifier
113     */
114    void setQualifier(@Nullable String qualifier);
115
116    /**
117     * Gets a View qualifier.
118     *
119     * @return qualifier to be used, or {@code null} for the standard qualifier
120     */
121    String getQualifier();
122
123}