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    }