001: /*
002: * Copyright (c) 1998-2003 Caucho Technology -- all rights reserved
003: *
004: * This file is part of Resin(R) Open Source
005: *
006: * Each copy or derived work must preserve the copyright notice and this
007: * notice unmodified.
008: *
009: * Resin Open Source is free software; you can redistribute it and/or modify
010: * it under the terms of the GNU General Public License as published by
011: * the Free Software Foundation; either version 2 of the License, or
012: * (at your option) any later version.
013: *
014: * Resin Open Source is distributed in the hope that it will be useful,
015: * but WITHOUT ANY WARRANTY; without even the implied warranty of
016: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, or any warranty
017: * of NON-INFRINGEMENT. See the GNU General Public License for more
018: * details.
019: *
020: * You should have received a copy of the GNU General Public License
021: * along with Resin Open Source; if not, write to the
022: * Free SoftwareFoundation, Inc.
023: * 59 Temple Place, Suite 330
024: * Boston, MA 02111-1307 USA
025: *
026: * @author Scott Ferguson
027: */
028:
029: package javax.servlet;
030:
031: import java.io.IOException;
032: import java.io.PrintWriter;
033: import java.util.Locale;
034:
035: /**
036: * ServletReponse control the output to the client.
037: *
038: * <p>A typical servlet will output its response as follows:
039: *
040: * <code><pre>
041: * response.setContentType("text/html; charset=UTF-8");
042: * PrintWriter pw = response.getWriter();
043: * pw.println("Hello, world");
044: * </pre></code>
045: *
046: * <h4>Buffering</h4>
047: *
048: * The servlet engine buffers output before sending it to the client.
049: * Buffering adds efficiency and flexibility. Until data is actually
050: * committed to the client, the servlet can change headers or reset the
051: * entire results.
052: *
053: * <h4>Character encoding</h4>
054: *
055: * Use either <code>setContentType</code> or <code>setLocale</code> to
056: * set the character encoding.
057: *
058: * <code><pre>
059: * response.setContentType("text/html; charset=ISO-8859-2");
060: * </pre></code>
061: */
062: public interface ServletResponse {
063: /**
064: * Sets the response content type. The content type includes
065: * the character encoding. The content type must be set before
066: * calling <code>getWriter()</code> so the writer can use the
067: * proper character encoding.
068: *
069: * <p>To set the output character encoding to ISO-8859-2, use the
070: * following:
071: *
072: * <code><pre>
073: * response.setContentType("text/html; charset=ISO-8859-2");
074: * </pre></code>
075: *
076: * @param type the mime type of the output
077: */
078: public void setContentType(String type);
079:
080: /**
081: * Returns the content type for the response.
082: *
083: * @since 2.4
084: */
085: public String getContentType();
086:
087: /**
088: * Returns the character encoding the response is using for output.
089: * If no character encoding is specified, ISO-8859-1 will be used.
090: */
091: public String getCharacterEncoding();
092:
093: /**
094: * Sets the character encoding the response is using for output.
095: * If no character encoding is specified, ISO-8859-1 will be used.
096: *
097: * @since 2.4
098: */
099: public void setCharacterEncoding(String charset);
100:
101: /**
102: * Sets the output locale. The response will set the character encoding
103: * based on the locale. For example, setting the "kr" locale will set
104: * the character encoding to "EUC_KR".
105: */
106: public void setLocale(Locale locale);
107:
108: /**
109: * Returns the output locale.
110: */
111: public Locale getLocale();
112:
113: /**
114: * Returns an output stream for writing to the client. You can use
115: * the output stream to write binary data.
116: */
117: public ServletOutputStream getOutputStream() throws IOException;
118:
119: /**
120: * Returns a PrintWriter with the proper character encoding for writing
121: * text data to the client.
122: */
123: public PrintWriter getWriter() throws IOException;
124:
125: /**
126: * Sets the output buffer size to <code>size</code>. The servlet engine
127: * may round the size up.
128: *
129: * @param size the new output buffer size.
130: */
131: public void setBufferSize(int size);
132:
133: /**
134: * Returns the size of the output buffer.
135: */
136: public int getBufferSize();
137:
138: /**
139: * Flushes the buffer to the client.
140: */
141: public void flushBuffer() throws IOException;
142:
143: /**
144: * Returns true if some data has actually been send to the client. The
145: * data will be sent if the buffer overflows or if it's explicitly flushed.
146: */
147: public boolean isCommitted();
148:
149: /**
150: * Resets the output stream, clearing headers and the output buffer.
151: * Calling <code>reset()</code> after data has been committed is illegal.
152: *
153: * @throws IllegalStateException if <code>isCommitted()</code> is true.
154: */
155: public void reset();
156:
157: /**
158: * Resets the output stream, clearing headers and the output buffer.
159: * Calling <code>reset()</code> after data has been committed is illegal.
160: *
161: * @throws IllegalStateException if <code>isCommitted()</code> is true.
162: */
163: public void resetBuffer();
164:
165: /**
166: * Explicitly sets the length of the result value. Normally, the servlet
167: * engine will handle this.
168: */
169: public void setContentLength(int len);
170: }
|