001 // Copyright 2006, 2007 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.tapestry.services;
016
017 import org.apache.tapestry.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 */
026 public interface Response
027 {
028 /**
029 * Returns a PrintWriter object to which output may be sent. Invoking flush() on the writer will commit the output.
030 *
031 * @param contentType the MIME content type for the output, typically "text/html"
032 */
033 PrintWriter getPrintWriter(String contentType) throws IOException;
034
035 /**
036 * Returns an OutputStream to which byte-oriented output may be sent. Invoking flush() on the stream will commit the
037 * output.
038 *
039 * @param contentType the MIME content type for the output, often "application/octet-stream" or "text/plain" or one
040 * of several others
041 */
042 OutputStream getOutputStream(String contentType) throws IOException;
043
044 /**
045 * Sends a redirect to the client.
046 *
047 * @param URL full or partial (relative) URL to send to the client
048 * @see #encodeRedirectURL(String)
049 */
050 void sendRedirect(String URL) throws IOException;
051
052 /**
053 * Sends a redirect to a link.
054 *
055 * @param link link to redirect to.
056 */
057 void sendRedirect(Link link) throws IOException;
058
059 /**
060 * Sends an error response to the client using the specified status. The server defaults to creating the response to
061 * look like an HTML-formatted server error page containing the specified message, setting the content type to
062 * "text/html", leaving cookies and other headers unmodified. If an error-page declaration has been made for the web
063 * application corresponding to the status code passed in, it will be served back in preference to the suggested msg
064 * parameter.
065 * <p/>
066 * If the response has already been committed, this method throws an IllegalStateException. After using this method,
067 * the response should be considered to be committed and should not be written to.
068 *
069 * @param sc the error status code
070 * @param message the descriptive message
071 * @throws IOException If an input or output exception occurs
072 * @throws IllegalStateException If the response was committed
073 */
074 void sendError(int sc, String message) throws IOException;
075
076 /**
077 * Sets the length of the content body in the response; this method sets the HTTP Content-Length header.
078 *
079 * @param length the length of the content
080 */
081 void setContentLength(int length);
082
083 /**
084 * Sets a response header with the given name and date-value. The date is specified in terms of milliseconds since
085 * the epoch. If the header had already been set, the new value overwrites the previous one.
086 *
087 * @param name the name of the header to set
088 * @param date the assigned date value
089 */
090 void setDateHeader(String name, long date);
091
092 /**
093 * Sets a response header with the given name and value. If the header had already been set, the new value
094 * overwrites the previous one.
095 *
096 * @param name the name of the header to set
097 * @param value the assigned value
098 */
099 void setHeader(String name, String value);
100
101 /**
102 * Sets a response header with the given name and integer value. If the header had already been set, the new value
103 * overwrites the previous one.
104 *
105 * @param name the name of the header to set
106 * @param value the assigned integer value
107 */
108 void setIntHeader(String name, int value);
109
110 /**
111 * Encodes the URL, ensuring that a session id is included (if a session exists, and as necessary depending on the
112 * client browser's use of cookies).
113 *
114 * @param URL
115 * @return the same URL or a different one with additional information to track the user session
116 */
117 String encodeURL(String URL);
118
119 /**
120 * Encodes the URL for use as a redirect, ensuring that a session id is included (if a session exists, and as
121 * necessary depending on the client browser's use of cookies).
122 *
123 * @param URL
124 * @return the same URL or a different one with additional information to track the user session
125 */
126 String encodeRedirectURL(String URL);
127
128 /**
129 * Returns true if the response has already been sent, either as a redirect or as a stream of content.
130 *
131 * @return true if response already sent
132 */
133 boolean isCommitted();
134 }