001: /*
002: * Copyright (c) JForum Team
003: * All rights reserved.
004: *
005: * Redistribution and use in source and binary forms,
006: * with or without modification, are permitted provided
007: * that the following conditions are met:
008: *
009: * 1) Redistributions of source code must retain the above
010: * copyright notice, this list of conditions and the
011: * following disclaimer.
012: * 2) Redistributions in binary form must reproduce the
013: * above copyright notice, this list of conditions and
014: * the following disclaimer in the documentation and/or
015: * other materials provided with the distribution.
016: * 3) Neither the name of "Rafael Steil" nor
017: * the names of its contributors may be used to endorse
018: * or promote products derived from this software without
019: * specific prior written permission.
020: *
021: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT
022: * HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
023: * EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
024: * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
025: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR
026: * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
027: * THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
028: * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
029: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES
030: * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
031: * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
032: * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
033: * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
034: * IN CONTRACT, STRICT LIABILITY, OR TORT
035: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
036: * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
037: * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
038: *
039: * The JForum Project
040: * http://www.jforum.net
041: */
042: package net.jforum.context;
043:
044: import javax.servlet.ServletOutputStream;
045: import javax.servlet.http.Cookie;
046: import java.io.IOException;
047: import java.io.PrintWriter;
048:
049: /**
050: * User: SergeMaslyukov Date: 20.08.2006 Time: 18:48:56 <p/> $Id: WebContextResponse.java,v 1.1
051: * 2006/08/20 15:30:30 sergemaslyukov Exp $
052: */
053: public interface ResponseContext {
054: /**
055: * Sets the length of the content body in the response In HTTP servlets, this method sets the
056: * HTTP Content-Length header.
057: *
058: * @param len an integer specifying the length of the content being returned to the client;
059: * sets the Content-Length header
060: */
061: public void setContentLength(int len);
062:
063: /**
064: * Returns a boolean indicating whether the named response header has already been set.
065: *
066: * @param name the header name
067: * @return <code>true</code> if the named response header has already been set;
068: * <code>false</code> otherwise
069: */
070: public boolean containsHeader(String name);
071:
072: /**
073: * Sets a response header with the given name and value. If the header had already been set, the
074: * new value overwrites the previous one. The <code>containsHeader</code> method can be used
075: * to test for the presence of a header before setting its value.
076: *
077: * @param name the name of the header
078: * @param value the header value If it contains octet string, it should be encoded
079: * according to RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)
080: *
081: * @see #containsHeader
082: * @see #addHeader
083: */
084: public void setHeader(String name, String value);
085:
086: /**
087: * Adds the specified cookie to the response. This method can be called multiple times to set
088: * more than one cookie.
089: *
090: * @param cookie the Cookie to return to the client
091: */
092: public void addCookie(Cookie cookie);
093:
094: /**
095: * Encodes the specified URL for use in the <code>sendRedirect</code> method or, if encoding
096: * is not needed, returns the URL unchanged. The implementation of this method includes the
097: * logic to determine whether the session ID needs to be encoded in the URL. Because the rules
098: * for making this determination can differ from those used to decide whether to encode a normal
099: * link, this method is separated from the <code>encodeURL</code> method.
100: *
101: * <p>
102: * All URLs sent to the <code>HttpServletResponse.sendRedirect</code> method should be run
103: * through this method. Otherwise, URL rewriting cannot be used with browsers which do not
104: * support cookies.
105: *
106: * @param url the url to be encoded.
107: * @return the encoded URL if encoding is needed; the unchanged URL otherwise.
108: *
109: * @see #sendRedirect
110: * @see #encodeUrl
111: */
112: public String encodeRedirectURL(String url);
113:
114: /**
115: * Returns the name of the character encoding (MIME charset) used for the body sent in this
116: * response. The character encoding may have been specified explicitly using the
117: * {@link #setCharacterEncoding} or {@link #setContentType} methods, or implicitly using the
118: * {@link #setLocale} method. Explicit specifications take precedence over implicit
119: * specifications. Calls made to these methods after <code>getWriter</code> has been called or
120: * after the response has been committed have no effect on the character encoding. If no
121: * character encoding has been specified, <code>ISO-8859-1</code> is returned.
122: * <p>
123: * See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) for more information about character
124: * encoding and MIME.
125: *
126: * @return a <code>String</code> specifying the name of the character encoding, for example,
127: * <code>UTF-8</code>
128: *
129: */
130: public String getCharacterEncoding();
131:
132: /**
133: * Sends a temporary redirect response to the client using the specified redirect location URL.
134: * This method can accept relative URLs; the servlet container must convert the relative URL to
135: * an absolute URL before sending the response to the client. If the location is relative
136: * without a leading '/' the container interprets it as relative to the current request URI. If
137: * the location is relative with a leading '/' the container interprets it as relative to the
138: * servlet container root.
139: *
140: * <p>
141: * If the response has already been committed, this method throws an IllegalStateException.
142: * After using this method, the response should be considered to be committed and should not be
143: * written to.
144: *
145: * @param location the redirect location URL
146: * @exception IOException If an input or output exception occurs
147: * @exception IllegalStateException If the response was committed or if a partial
148: * URL is given and cannot be converted into a valid URL
149: */
150: public void sendRedirect(String location) throws IOException;
151:
152: /**
153: * Returns a {@link javax.servlet.ServletOutputStream} suitable for writing binary data in the
154: * response. The servlet container does not encode the binary data.
155: *
156: * <p>
157: * Calling flush() on the ServletOutputStream commits the response.
158: *
159: * Either this method or {@link #getWriter} may be called to write the body, not both.
160: *
161: * @return a {@link javax.servlet.ServletOutputStream} for writing binary data
162: * @exception IllegalStateException if the <code>getWriter</code> method has
163: * been called on this response
164: * @exception IOException if an input or output exception occurred
165: * @see #getWriter
166: */
167:
168: public ServletOutputStream getOutputStream() throws IOException;
169:
170: /**
171: * Returns a <code>PrintWriter</code> object that can send character text to the client. The
172: * <code>PrintWriter</code> uses the character encoding returned by
173: * {@link #getCharacterEncoding}. If the response's character encoding has not been specified
174: * as described in <code>getCharacterEncoding</code> (i.e., the method just returns the
175: * default value <code>ISO-8859-1</code>), <code>getWriter</code> updates it to
176: * <code>ISO-8859-1</code>.
177: * <p>
178: * Calling flush() on the <code>PrintWriter</code> commits the response.
179: * <p>
180: * Either this method or {@link #getOutputStream} may be called to write the body, not both.
181: *
182: * @return a <code>PrintWriter</code> object that can return character data to the client
183: *
184: * @exception java.io.UnsupportedEncodingException if the character encoding
185: * returned by <code>getCharacterEncoding</code> cannot be used
186: * @exception IllegalStateException if the <code>getOutputStream</code> method has
187: * already been called for this response object
188: * @exception IOException if an input or output exception occurred
189: *
190: * @see #getOutputStream
191: * @see #setCharacterEncoding
192: *
193: */
194: public PrintWriter getWriter() throws IOException;
195:
196: /**
197: * Sets the content type of the response being sent to the client, if the response has not been
198: * committed yet. The given content type may include a character encoding specification, for
199: * example, <code>text/html;charset=UTF-8</code>. The response's character encoding is only
200: * set from the given content type if this method is called before <code>getWriter</code> is
201: * called.
202: * <p>
203: * This method may be called repeatedly to change content type and character encoding. This
204: * method has no effect if called after the response has been committed. It does not set the
205: * response's character encoding if it is called after <code>getWriter</code> has been called
206: * or after the response has been committed.
207: * <p>
208: * Containers must communicate the content type and the character encoding used for the servlet
209: * response's writer to the client if the protocol provides a way for doing so. In the case of
210: * HTTP, the <code>Content-Type</code> header is used.
211: *
212: * @param type a <code>String</code> specifying the MIME type of the content
213: *
214: * @see #setLocale
215: * @see #setCharacterEncoding
216: * @see #getOutputStream
217: * @see #getWriter
218: */
219: public void setContentType(String type);
220:
221: /**
222: * Encodes the specified URL by including the session ID in it, or, if encoding is not needed,
223: * returns the URL unchanged. The implementation of this method includes the logic to determine
224: * whether the session ID needs to be encoded in the URL. For example, if the browser supports
225: * cookies, or session tracking is turned off, URL encoding is unnecessary.
226: *
227: * <p>
228: * For robust session tracking, all URLs emitted by a servlet should be run through this method.
229: * Otherwise, URL rewriting cannot be used with browsers which do not support cookies.
230: *
231: * @param url the url to be encoded.
232: * @return the encoded URL if encoding is needed; the unchanged URL otherwise.
233: */
234: public String encodeURL(String url);
235:
236: /**
237: * Adds a response header with the given name and value. This method allows response headers to
238: * have multiple values.
239: *
240: * @param name the name of the header
241: * @param value the additional header value If it contains octet string,
242: * it should be encoded according to RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)
243: */
244: public void addHeader(String name, String value);
245:
246: /**
247: * Sends an error response to the client using the specified status code and clearing the
248: * buffer.
249: * <p>
250: * If the response has already been committed, this method throws an IllegalStateException.
251: * After using this method, the response should be considered to be committed and should not be
252: * written to.
253: *
254: * @param sc the error status code
255: * @exception java.io.IOException If an input or output exception occurs
256: * @exception IllegalStateException If the response was committed before this method call
257: */
258: public void sendError(int sc) throws IOException;
259: }
|