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.IOException;
20 import java.io.InputStream;
23 * Provides an input stream for reading binary data from a client request,
24 * including an efficient <code>readLine</code> method for reading data one line
25 * at a time. With some protocols, such as HTTP POST and PUT, a
26 * <code>ServletInputStream</code> object can be used to read data sent from the
29 * A <code>ServletInputStream</code> object is normally retrieved via the
30 * {@link ServletRequest#getInputStream} method.
32 * This is an abstract class that a servlet container implements. Subclasses of
33 * this class must implement the <code>java.io.InputStream.read()</code> method.
37 public abstract class ServletInputStream extends InputStream {
40 * Does nothing, because this is an abstract class.
42 protected ServletInputStream() {
47 * Reads the input stream, one line at a time. Starting at an offset, reads
48 * bytes into an array, until it reads a certain number of bytes or reaches
49 * a newline character, which it reads into the array as well.
51 * This method returns -1 if it reaches the end of the input stream before
52 * reading the maximum number of bytes.
55 * an array of bytes into which data is read
57 * an integer specifying the character at which this method
60 * an integer specifying the maximum number of bytes to read
61 * @return an integer specifying the actual number of bytes read, or -1 if
62 * the end of the stream is reached
63 * @exception IOException
64 * if an input or output exception has occurred
66 public int readLine(byte[] b, int off, int len) throws IOException {
73 while ((c = read()) != -1) {
76 if (c == '\n' || count == len) {
80 return count > 0 ? count : -1;
84 * Returns <code>true</code> if all the data has been read from the stream,
85 * else <code>false</code>.
89 public abstract boolean isFinished();
92 * Returns <code>true</code> if data can be read without blocking, else
93 * <code>false</code>. If this method is called and returns false, the
94 * container will invoke {@link ReadListener#onDataAvailable()} when data is
99 public abstract boolean isReady();
102 * Sets the {@link ReadListener} for this {@link ServletInputStream} and
103 * thereby switches to non-blocking IO. It is only valid to switch to
104 * non-blocking IO within async processing or HTTP upgrade processing.
106 * @param listener The non-blocking IO read listener
108 * @throws IllegalStateException If this method is called if neither
109 * async nor HTTP upgrade is in progress or
110 * if the {@link ReadListener} has already
112 * @throws NullPointerException If listener is null
116 public abstract void setReadListener(ReadListener listener);