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}