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