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;
018
019import java.io.IOException;
020import java.io.OutputStream;
021import 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 */
030public 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}