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