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}