2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
17 package javax.servlet;
19 import java.io.CharConversionException;
20 import java.io.IOException;
21 import java.io.OutputStream;
22 import java.text.MessageFormat;
23 import java.util.ResourceBundle;
26 * Provides an output stream for sending binary data to the client. A
27 * <code>ServletOutputStream</code> object is normally retrieved via the
28 * {@link ServletResponse#getOutputStream} method.
30 * This is an abstract class that the servlet container implements. Subclasses
31 * of this class must implement the <code>java.io.OutputStream.write(int)</code>
34 * @see ServletResponse
36 public abstract class ServletOutputStream extends OutputStream {
38 private static final String LSTRING_FILE = "javax.servlet.LocalStrings";
39 private static final ResourceBundle lStrings = ResourceBundle.getBundle(LSTRING_FILE);
42 * Does nothing, because this is an abstract class.
44 protected ServletOutputStream() {
49 * Writes a <code>String</code> to the client, without a carriage
50 * return-line feed (CRLF) character at the end.
53 * the <code>String</code> to send to the client
54 * @exception IOException
55 * if an input or output exception occurred
57 public void print(String s) throws IOException {
61 for (int i = 0; i < len; i++) {
65 // XXX NOTE: This is clearly incorrect for many strings,
66 // but is the only consistent approach within the current
67 // servlet framework. It must suffice until servlet output
68 // streams properly encode their output.
70 if ((c & 0xff00) != 0) { // high order byte must be zero
71 String errMsg = lStrings.getString("err.not_iso8859_1");
72 Object[] errArgs = new Object[1];
73 errArgs[0] = Character.valueOf(c);
74 errMsg = MessageFormat.format(errMsg, errArgs);
75 throw new CharConversionException(errMsg);
82 * Writes a <code>boolean</code> value to the client, with no carriage
83 * return-line feed (CRLF) character at the end.
86 * the <code>boolean</code> value to send to the client
87 * @exception IOException
88 * if an input or output exception occurred
90 public void print(boolean b) throws IOException {
93 msg = lStrings.getString("value.true");
95 msg = lStrings.getString("value.false");
101 * Writes a character to the client, with no carriage return-line feed
105 * the character to send to the client
106 * @exception IOException
107 * if an input or output exception occurred
109 public void print(char c) throws IOException {
110 print(String.valueOf(c));
114 * Writes an int to the client, with no carriage return-line feed (CRLF) at
118 * the int to send to the client
119 * @exception IOException
120 * if an input or output exception occurred
122 public void print(int i) throws IOException {
123 print(String.valueOf(i));
127 * Writes a <code>long</code> value to the client, with no carriage
128 * return-line feed (CRLF) at the end.
131 * the <code>long</code> value to send to the client
132 * @exception IOException
133 * if an input or output exception occurred
135 public void print(long l) throws IOException {
136 print(String.valueOf(l));
140 * Writes a <code>float</code> value to the client, with no carriage
141 * return-line feed (CRLF) at the end.
144 * the <code>float</code> value to send to the client
145 * @exception IOException
146 * if an input or output exception occurred
148 public void print(float f) throws IOException {
149 print(String.valueOf(f));
153 * Writes a <code>double</code> value to the client, with no carriage
154 * return-line feed (CRLF) at the end.
157 * the <code>double</code> value to send to the client
158 * @exception IOException
159 * if an input or output exception occurred
161 public void print(double d) throws IOException {
162 print(String.valueOf(d));
166 * Writes a carriage return-line feed (CRLF) to the client.
168 * @exception IOException
169 * if an input or output exception occurred
171 public void println() throws IOException {
176 * Writes a <code>String</code> to the client, followed by a carriage
177 * return-line feed (CRLF).
180 * the <code>String</code> to write to the client
181 * @exception IOException
182 * if an input or output exception occurred
184 public void println(String s) throws IOException {
190 * Writes a <code>boolean</code> value to the client, followed by a carriage
191 * return-line feed (CRLF).
194 * the <code>boolean</code> value to write to the client
195 * @exception IOException
196 * if an input or output exception occurred
198 public void println(boolean b) throws IOException {
204 * Writes a character to the client, followed by a carriage return-line feed
208 * the character to write to the client
209 * @exception IOException
210 * if an input or output exception occurred
212 public void println(char c) throws IOException {
218 * Writes an int to the client, followed by a carriage return-line feed
222 * the int to write to the client
223 * @exception IOException
224 * if an input or output exception occurred
226 public void println(int i) throws IOException {
232 * Writes a <code>long</code> value to the client, followed by a carriage
233 * return-line feed (CRLF).
236 * the <code>long</code> value to write to the client
237 * @exception IOException
238 * if an input or output exception occurred
240 public void println(long l) throws IOException {
246 * Writes a <code>float</code> value to the client, followed by a carriage
247 * return-line feed (CRLF).
250 * the <code>float</code> value to write to the client
251 * @exception IOException
252 * if an input or output exception occurred
254 public void println(float f) throws IOException {
260 * Writes a <code>double</code> value to the client, followed by a carriage
261 * return-line feed (CRLF).
264 * the <code>double</code> value to write to the client
265 * @exception IOException
266 * if an input or output exception occurred
268 public void println(double d) throws IOException {
274 * Checks if a non-blocking write will succeed. If this returns
275 * <code>false</code>, it will cause a callback to
276 * {@link WriteListener#onWritePossible()} when the buffer has emptied. If
277 * this method returns <code>false</code> no further data must be written
278 * until the contain calls {@link WriteListener#onWritePossible()}.
280 * @return <code>true</code> if data can be written, else <code>false</code>
284 public abstract boolean isReady();
287 * Sets the {@link WriteListener} for this {@link ServletOutputStream} and
288 * thereby switches to non-blocking IO. It is only valid to switch to
289 * non-blocking IO within async processing or HTTP upgrade processing.
291 * @param listener The non-blocking IO write listener
293 * @throws IllegalStateException If this method is called if neither
294 * async nor HTTP upgrade is in progress or
295 * if the {@link WriteListener} has already
297 * @throws NullPointerException If listener is null
301 public abstract void setWriteListener(javax.servlet.WriteListener listener);