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}