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 }