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