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
015package org.apache.tapestry.web;
016
017import java.io.IOException;
018import java.io.OutputStream;
019import java.io.PrintWriter;
020
021import 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 */
033public 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}