    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005// http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5.http.services;
    014
    015import org.apache.tapestry5.http.Link;
    016import org.apache.tapestry5.ioc.annotations.IncompatibleChange;
    017
    018import java.io.IOException;
    019import java.io.OutputStream;
    020import java.io.PrintWriter;
    021
    022/**
    023 * API agnostic wrapper for generating a response. Bridges the gaps between the Servlet API and the Portlet API.
    024 *
    025 *
    026 * The Response service is a {@linkplain org.apache.tapestry5.ioc.services.PropertyShadowBuilder shadow} of the current
    027 * thread's response object.
    028 */
    029public interface Response
    030{
    031    /**
    032     * Returns a PrintWriter object to which output may be sent. Invoking flush() on the writer will commit the output.
    033     *
    034     * @param contentType
    035     *            the MIME content type for the output, typically "text/html"
    036     */
    037    PrintWriter getPrintWriter(String contentType) throws IOException;
    038
    039    /**
    040     * Returns an OutputStream to which byte-oriented output may be sent. Invoking flush() on the stream will commit the
    041     * output.
    042     *
    043     * @param contentType
    044     *            the MIME content type for the output, often "application/octet-stream" or "text/plain" or one
    045     *            of several others
    046     */
    047    OutputStream getOutputStream(String contentType) throws IOException;
    048
    049    /**
    050     * Sends a redirect to the client.
    051     *
    052     * @param URL
    053     *            full or partial (relative) URL to send to the client
    054     * @see #encodeRedirectURL(String)
    055     */
    056    void sendRedirect(String URL) throws IOException;
    057
    058    /**
    059     * Sends a redirect to a link.
    060     *
    061     * @param link
    062     *            link to redirect to.
    063     */
    064    void sendRedirect(Link link) throws IOException;
    065
    066    /**
    067     * Sets the status code for this response. This method is used to set the return status code when there is no error
    068     * (for example, for the status codes SC_OK or SC_MOVED_TEMPORARILY). If there is an error, and the caller wishes
    069     * to invoke an error-page defined in the web applicaion, the <code>sendError</code> method should be used instead.
    070     *
    071     * @param sc
    072     *            the status code
    073     */
    074    public void setStatus(int sc);
    075
    076    /**
    077     * Sends an error response to the client using the specified status. The server defaults to creating the response to
    078     * look like an HTML-formatted server error page containing the specified message, setting the content type to
    079     * "text/html", leaving cookies and other headers unmodified. If an error-page declaration has been made for the web
    080     * application corresponding to the status code passed in, it will be served back in preference to the suggested msg
    081     * parameter.
    082     *
    083     * If the response has already been committed, this method throws an IllegalStateException. After using this method,
    084     * the response should be considered to be committed and should not be written to.
    085     *
    086     * @param sc
    087     *            the error status code
    088     * @param message
    089     *            the descriptive message
    090     * @throws IOException
    091     *             If an input or output exception occurs
    092     * @throws IllegalStateException
    093     *             If the response was committed
    094     */
    095    void sendError(int sc, String message) throws IOException;
    096
    097    /**
    098     * Sets the length of the content body in the response; this method sets the HTTP Content-Length header.
    099     *
    100     * @param length
    101     *            the length of the content
    102     */
    103    void setContentLength(int length);
    104
    105    /**
    106     * Sets a response header with the given name and date-value. The date is specified in terms of milliseconds since
    107     * the epoch. If the header had already been set, the new value overwrites the previous one.
    108     *
    109     * @param name
    110     *            the name of the header to set
    111     * @param date
    112     *            the assigned date value
    113     */
    114    void setDateHeader(String name, long date);
    115
    116    /**
    117     * Sets a response header with the given name and value. If the header had already been set, the new value
    118     * overwrites the previous one.
    119     *
    120     * @param name
    121     *            the name of the header to set
    122     * @param value
    123     *            the assigned value
    124     */
    125    void setHeader(String name, String value);
    126
    127    /**
    128     * Adds a response header with the given name and value, not overwriting any previous values which
    129     * may have already been added.
    130     *
    131     * @param name
    132     *            the name of the header to add
    133     * @param value
    134     *            the assigned value
    135     * @since 5.4
    136     */
    137    @IncompatibleChange(release = "5.4", details = "Added method")
    138    void addHeader(String name, String value);
    139
    140    /**
    141     * Sets a response header with the given name and integer value. If the header had already been set, the new value
    142     * overwrites the previous one.
    143     *
    144     * @param name
    145     *            the name of the header to set
    146     * @param value
    147     *            the assigned integer value
    148     */
    149    void setIntHeader(String name, int value);
    150
    151    /**
    152     * Encodes the URL, ensuring that a session id is included (if a session exists, and as necessary depending on the
    153     * client browser's use of cookies).
    154     *
    155     * @param URL
    156     * @return the same URL or a different one with additional information to track the user session
    157     */
    158    String encodeURL(String URL);
    159
    160    /**
    161     * Encodes the URL for use as a redirect, ensuring that a session id is included (if a session exists, and as
    162     * necessary depending on the client browser's use of cookies).
    163     *
    164     * @param URL
    165     * @return the same URL or a different one with additional information to track the user session
    166     */
    167    String encodeRedirectURL(String URL);
    168
    169    /**
    170     * Returns true if the response has already been sent, either as a redirect or as a stream of content.
    171     *
    172     * @return true if response already sent
    173     */
    174    boolean isCommitted();
    175
    176    /**
    177     * Invoked to indicate that the response content is either already compressed, or is not compressable.
    178     *
    179     * @since 5.2.1
    180     */
    181    void disableCompression();
    182}