001    /*
002    * Copyright 2004 The Apache Software Foundation
003    *
004    * Licensed under the Apache License, Version 2.0 (the "License");
005    * you may not use this file except in compliance with the License.
006    * You may obtain a copy of the License at
007    *
008    *     http://www.apache.org/licenses/LICENSE-2.0
009    *
010    * Unless required by applicable law or agreed to in writing, software
011    * distributed under the License is distributed on an "AS IS" BASIS,
012    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013    * See the License for the specific language governing permissions and
014    * limitations under the License.
015    */
016    package javax.servlet;
017    
018    import java.io.InputStream;
019    import java.io.IOException;
020    
021    /**
022     * 
023     * Provides an input stream for reading binary data from a client
024     * request, including an efficient <code>readLine</code> method
025     * for reading data one line at a time. With some protocols, such
026     * as HTTP POST and PUT, a <code>ServletInputStream</code>
027     * object can be used to read data sent from the client.
028     *
029     * <p>A <code>ServletInputStream</code> object is normally retrieved via
030     * the {@link ServletRequest#getInputStream} method.
031     *
032     *
033     * <p>This is an abstract class that a servlet container implements.
034     * Subclasses of this class
035     * must implement the <code>java.io.InputStream.read()</code> method.
036     *
037     *
038     * @author      Various
039     * @version     $Version$
040     *
041     * @see         ServletRequest 
042     *
043     */
044    
045    public abstract class ServletInputStream extends InputStream {
046    
047    
048    
049        /**
050         * Does nothing, because this is an abstract class.
051         *
052         */
053    
054        protected ServletInputStream() { }
055    
056      
057      
058        
059        /**
060         *
061         * Reads the input stream, one line at a time. Starting at an
062         * offset, reads bytes into an array, until it reads a certain number
063         * of bytes or reaches a newline character, which it reads into the
064         * array as well.
065         *
066         * <p>This method returns -1 if it reaches the end of the input
067         * stream before reading the maximum number of bytes.
068         *
069         *
070         *
071         * @param b                 an array of bytes into which data is read
072         *
073         * @param off               an integer specifying the character at which
074         *                          this method begins reading
075         *
076         * @param len               an integer specifying the maximum number of 
077         *                          bytes to read
078         *
079         * @return                  an integer specifying the actual number of bytes 
080         *                          read, or -1 if the end of the stream is reached
081         *
082         * @exception IOException   if an input or output exception has occurred
083         *
084         */
085         
086        public int readLine(byte[] b, int off, int len) throws IOException {
087    
088            if (len <= 0) {
089                return 0;
090            }
091            int count = 0, c;
092    
093            while ((c = read()) != -1) {
094                b[off++] = (byte)c;
095                count++;
096                if (c == '\n' || count == len) {
097                    break;
098                }
099            }
100            return count > 0 ? count : -1;
101        }
102    }
103    
104    
105