001    // Copyright 2005 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.web;
016    
017    import java.io.IOException;
018    import java.io.OutputStream;
019    import java.io.PrintWriter;
020    
021    import org.apache.tapestry.util.ContentType;
022    
023    /**
024     * Controls the response to the client, and specifically allows for creating the output stream (or
025     * print writer) to which content is sent. This is essentially a generic version of
026     * {@link javax.servlet.http.HttpServletResponse}. Some operations may be unsupported in some
027     * implementations (for example, the portlet implementation can't handle any of the setHeader
028     * methods).
029     * 
030     * @author Howard M. Lewis Ship
031     * @since 4.0
032     */
033    public interface WebResponse
034    {
035        /**
036         * Returns a output stream to which output should be sent. This method should only be invoked
037         * once on a response.
038         * 
039         * @return the output stream, configured for the given type.
040         */
041    
042        public OutputStream getOutputStream(ContentType contentType) throws IOException;
043    
044        /**
045         * Returns a {@link PrintWriter} to which output should be sent. This method should be invoked
046         * once on a response. A second call is expected to be so that an exception page can be
047         * rendered, and the underlying request data is reset.
048         */
049    
050        public PrintWriter getPrintWriter(ContentType contentType) throws IOException;
051    
052        /**
053         * Encodes a URL, which adds information to the URL needed to ensure that the request triggered
054         * by the URL will be associated with the current session (if any). In most cases, the string is
055         * returned unchanged.
056         */
057    
058        public String encodeURL(String url);
059    
060        /**
061         * Resets any buffered content. This may be used after an error to radically change what the
062         * output will be.
063         */
064    
065        public void reset();
066    
067        public void setContentLength(int contentLength);
068    
069        /**
070         * Returns a value to be prefixed or suffixed with any client-side JavaScript elements
071         * (variables and function names) to ensure that they are unique with the context of the entire
072         * page. For servlets, this is the empty string.
073         */
074    
075        public String getNamespace();
076    
077        /**
078         * Sets a response header as a date.
079         * 
080         * @param name
081         *            the name of the header to set
082         * @param date
083         *            the date value to set, in milliseconds since the epoch
084         */
085        public void setDateHeader(String name, long date);
086    
087        /**
088         * Sets a response header as a string.
089         * 
090         * @param name
091         *            the name of the header to set
092         * @param value
093         *            the value for the named header
094         */
095    
096        public void setHeader(String name, String value);
097    
098        /**
099         * Sets a response header with the given name and integer value.
100         * 
101         * @param name
102         *            the name of the header to set
103         * @param value
104         *            the value for the named header
105         */
106        public void setIntHeader(String name, int value);
107    
108        /**
109         * Sets the status code for this response.
110         */
111        public void setStatus(int status);
112    
113        /**
114         * Sends an error response.
115         */
116    
117        public void sendError(int statusCode, String message) throws IOException;
118    }