View Javadoc

1   /*
2   * Copyright 2004 The Apache Software Foundation
3   *
4   * Licensed under the Apache License, Version 2.0 (the "License");
5   * you may not use this file except in compliance with the License.
6   * You may obtain a copy of the License at
7   *
8   *     http://www.apache.org/licenses/LICENSE-2.0
9   *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16  package javax.servlet;
17  
18  import java.io.InputStream;
19  import java.io.IOException;
20  
21  /**
22   * 
23   * Provides an input stream for reading binary data from a client
24   * request, including an efficient <code>readLine</code> method
25   * for reading data one line at a time. With some protocols, such
26   * as HTTP POST and PUT, a <code>ServletInputStream</code>
27   * object can be used to read data sent from the client.
28   *
29   * <p>A <code>ServletInputStream</code> object is normally retrieved via
30   * the {@link ServletRequest#getInputStream} method.
31   *
32   *
33   * <p>This is an abstract class that a servlet container implements.
34   * Subclasses of this class
35   * must implement the <code>java.io.InputStream.read()</code> method.
36   *
37   *
38   * @author 	Various
39   * @version 	$Version$
40   *
41   * @see		ServletRequest 
42   *
43   */
44  
45  public abstract class ServletInputStream extends InputStream {
46  
47  
48  
49      /**
50       * Does nothing, because this is an abstract class.
51       *
52       */
53  
54      protected ServletInputStream() { }
55  
56    
57    
58      
59      /**
60       *
61       * Reads the input stream, one line at a time. Starting at an
62       * offset, reads bytes into an array, until it reads a certain number
63       * of bytes or reaches a newline character, which it reads into the
64       * array as well.
65       *
66       * <p>This method returns -1 if it reaches the end of the input
67       * stream before reading the maximum number of bytes.
68       *
69       *
70       *
71       * @param b 		an array of bytes into which data is read
72       *
73       * @param off 		an integer specifying the character at which
74       *				this method begins reading
75       *
76       * @param len		an integer specifying the maximum number of 
77       *				bytes to read
78       *
79       * @return			an integer specifying the actual number of bytes 
80       *				read, or -1 if the end of the stream is reached
81       *
82       * @exception IOException	if an input or output exception has occurred
83       *
84       */
85       
86      public int readLine(byte[] b, int off, int len) throws IOException {
87  
88  	if (len <= 0) {
89  	    return 0;
90  	}
91  	int count = 0, c;
92  
93  	while ((c = read()) != -1) {
94  	    b[off++] = (byte)c;
95  	    count++;
96  	    if (c == '\n' || count == len) {
97  		break;
98  	    }
99  	}
100 	return count > 0 ? count : -1;
101     }
102 }
103 
104 
105