lib/servlet-api/javax/servlet/ServletOutputStream.java

   1 /*
   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
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  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.
  16  */
  17 package javax.servlet;
  18
  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;
  24
  25 /**
  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.
  29  * <p>
  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>
  32  * method.
  33  *
  34  * @see ServletResponse
  35  */
  36 public abstract class ServletOutputStream extends OutputStream {
  37
  38     private static final String LSTRING_FILE = "javax.servlet.LocalStrings";
  39     private static final ResourceBundle lStrings = ResourceBundle.getBundle(LSTRING_FILE);
  40
  41     /**
  42      * Does nothing, because this is an abstract class.
  43      */
  44     protected ServletOutputStream() {
  45         // NOOP
  46     }
  47
  48     /**
  49      * Writes a <code>String</code> to the client, without a carriage
  50      * return-line feed (CRLF) character at the end.
  51      *
  52      * @param s
  53      *            the <code>String</code> to send to the client
  54      * @exception IOException
  55      *                if an input or output exception occurred
  56      */
  57     public void print(String s) throws IOException {
  58         if (s == null)
  59             s = "null";
  60         int len = s.length();
  61         for (int i = 0; i < len; i++) {
  62             char c = s.charAt(i);
  63
  64             //
  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.
  69             //
  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);
  76             }
  77             write(c);
  78         }
  79     }
  80
  81     /**
  82      * Writes a <code>boolean</code> value to the client, with no carriage
  83      * return-line feed (CRLF) character at the end.
  84      *
  85      * @param b
  86      *            the <code>boolean</code> value to send to the client
  87      * @exception IOException
  88      *                if an input or output exception occurred
  89      */
  90     public void print(boolean b) throws IOException {
  91         String msg;
  92         if (b) {
  93             msg = lStrings.getString("value.true");
  94         } else {
  95             msg = lStrings.getString("value.false");
  96         }
  97         print(msg);
  98     }
  99
 100     /**
 101      * Writes a character to the client, with no carriage return-line feed
 102      * (CRLF) at the end.
 103      *
 104      * @param c
 105      *            the character to send to the client
 106      * @exception IOException
 107      *                if an input or output exception occurred
 108      */
 109     public void print(char c) throws IOException {
 110         print(String.valueOf(c));
 111     }
 112
 113     /**
 114      * Writes an int to the client, with no carriage return-line feed (CRLF) at
 115      * the end.
 116      *
 117      * @param i
 118      *            the int to send to the client
 119      * @exception IOException
 120      *                if an input or output exception occurred
 121      */
 122     public void print(int i) throws IOException {
 123         print(String.valueOf(i));
 124     }
 125
 126     /**
 127      * Writes a <code>long</code> value to the client, with no carriage
 128      * return-line feed (CRLF) at the end.
 129      *
 130      * @param l
 131      *            the <code>long</code> value to send to the client
 132      * @exception IOException
 133      *                if an input or output exception occurred
 134      */
 135     public void print(long l) throws IOException {
 136         print(String.valueOf(l));
 137     }
 138
 139     /**
 140      * Writes a <code>float</code> value to the client, with no carriage
 141      * return-line feed (CRLF) at the end.
 142      *
 143      * @param f
 144      *            the <code>float</code> value to send to the client
 145      * @exception IOException
 146      *                if an input or output exception occurred
 147      */
 148     public void print(float f) throws IOException {
 149         print(String.valueOf(f));
 150     }
 151
 152     /**
 153      * Writes a <code>double</code> value to the client, with no carriage
 154      * return-line feed (CRLF) at the end.
 155      *
 156      * @param d
 157      *            the <code>double</code> value to send to the client
 158      * @exception IOException
 159      *                if an input or output exception occurred
 160      */
 161     public void print(double d) throws IOException {
 162         print(String.valueOf(d));
 163     }
 164
 165     /**
 166      * Writes a carriage return-line feed (CRLF) to the client.
 167      *
 168      * @exception IOException
 169      *                if an input or output exception occurred
 170      */
 171     public void println() throws IOException {
 172         print("\r\n");
 173     }
 174
 175     /**
 176      * Writes a <code>String</code> to the client, followed by a carriage
 177      * return-line feed (CRLF).
 178      *
 179      * @param s
 180      *            the <code>String</code> to write to the client
 181      * @exception IOException
 182      *                if an input or output exception occurred
 183      */
 184     public void println(String s) throws IOException {
 185         print(s);
 186         println();
 187     }
 188
 189     /**
 190      * Writes a <code>boolean</code> value to the client, followed by a carriage
 191      * return-line feed (CRLF).
 192      *
 193      * @param b
 194      *            the <code>boolean</code> value to write to the client
 195      * @exception IOException
 196      *                if an input or output exception occurred
 197      */
 198     public void println(boolean b) throws IOException {
 199         print(b);
 200         println();
 201     }
 202
 203     /**
 204      * Writes a character to the client, followed by a carriage return-line feed
 205      * (CRLF).
 206      *
 207      * @param c
 208      *            the character to write to the client
 209      * @exception IOException
 210      *                if an input or output exception occurred
 211      */
 212     public void println(char c) throws IOException {
 213         print(c);
 214         println();
 215     }
 216
 217     /**
 218      * Writes an int to the client, followed by a carriage return-line feed
 219      * (CRLF) character.
 220      *
 221      * @param i
 222      *            the int to write to the client
 223      * @exception IOException
 224      *                if an input or output exception occurred
 225      */
 226     public void println(int i) throws IOException {
 227         print(i);
 228         println();
 229     }
 230
 231     /**
 232      * Writes a <code>long</code> value to the client, followed by a carriage
 233      * return-line feed (CRLF).
 234      *
 235      * @param l
 236      *            the <code>long</code> value to write to the client
 237      * @exception IOException
 238      *                if an input or output exception occurred
 239      */
 240     public void println(long l) throws IOException {
 241         print(l);
 242         println();
 243     }
 244
 245     /**
 246      * Writes a <code>float</code> value to the client, followed by a carriage
 247      * return-line feed (CRLF).
 248      *
 249      * @param f
 250      *            the <code>float</code> value to write to the client
 251      * @exception IOException
 252      *                if an input or output exception occurred
 253      */
 254     public void println(float f) throws IOException {
 255         print(f);
 256         println();
 257     }
 258
 259     /**
 260      * Writes a <code>double</code> value to the client, followed by a carriage
 261      * return-line feed (CRLF).
 262      *
 263      * @param d
 264      *            the <code>double</code> value to write to the client
 265      * @exception IOException
 266      *                if an input or output exception occurred
 267      */
 268     public void println(double d) throws IOException {
 269         print(d);
 270         println();
 271     }
 272
 273     /**
 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()}.
 279      *
 280      * @return <code>true</code> if data can be written, else <code>false</code>
 281      *
 282      * @since Servlet 3.1
 283      */
 284     public abstract boolean isReady();
 285
 286     /**
 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.
 290      *
 291      * @param listener  The non-blocking IO write listener
 292      *
 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
 296      *                                  been set
 297      * @throws NullPointerException     If listener is null
 298      *
 299      * @since Servlet 3.1
 300      */
 301     public abstract void setWriteListener(javax.servlet.WriteListener listener);
 302 }