• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/conn/EofSensorInputStream.java $
3  * $Revision: 672367 $
4  * $Date: 2008-06-27 12:49:20 -0700 (Fri, 27 Jun 2008) $
5  *
6  * ====================================================================
7  *
8  *  Licensed to the Apache Software Foundation (ASF) under one or more
9  *  contributor license agreements.  See the NOTICE file distributed with
10  *  this work for additional information regarding copyright ownership.
11  *  The ASF licenses this file to You under the Apache License, Version 2.0
12  *  (the "License"); you may not use this file except in compliance with
13  *  the License.  You may obtain a copy of the License at
14  *
15  *      http://www.apache.org/licenses/LICENSE-2.0
16  *
17  *  Unless required by applicable law or agreed to in writing, software
18  *  distributed under the License is distributed on an "AS IS" BASIS,
19  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  *  See the License for the specific language governing permissions and
21  *  limitations under the License.
22  * ====================================================================
23  *
24  * This software consists of voluntary contributions made by many
25  * individuals on behalf of the Apache Software Foundation.  For more
26  * information on the Apache Software Foundation, please see
27  * <http://www.apache.org/>.
28  *
29  */
30 
31 package org.apache.http.conn;
32 
33 import java.io.InputStream;
34 import java.io.IOException;
35 
36 
37 /**
38  * A stream wrapper that triggers actions on {@link #close close()} and EOF.
39  * Primarily used to auto-release an underlying
40  * {@link ManagedClientConnection connection}
41  * when the response body is consumed or no longer needed.
42  *
43  * <p>
44  * This class is based on <code>AutoCloseInputStream</code> in HttpClient 3.1,
45  * but has notable differences. It does not allow mark/reset, distinguishes
46  * different kinds of event, and does not always close the underlying stream
47  * on EOF. That decision is left to the {@link EofSensorWatcher watcher}.
48  * </p>
49  *
50  * @see EofSensorWatcher EofSensorWatcher
51  *
52  * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
53  * @author Ortwin Glueck
54  * @author Eric Johnson
55  * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
56  *
57  *
58  * <!-- empty lines to avoid svn diff problems -->
59  * @version $Revision: 672367 $
60  *
61  * @since 4.0
62  *
63  * @deprecated Please use {@link java.net.URL#openConnection} instead.
64  *     Please visit <a href="http://android-developers.blogspot.com/2011/09/androids-http-clients.html">this webpage</a>
65  *     for further details.
66  */
67 @Deprecated
68 // don't use FilterInputStream as the base class, we'd have to
69 // override markSupported(), mark(), and reset() to disable them
70 public class EofSensorInputStream extends InputStream
71     implements ConnectionReleaseTrigger {
72 
73     /**
74      * The wrapped input stream, while accessible.
75      * The value changes to <code>null</code> when the wrapped stream
76      * becomes inaccessible.
77      */
78     protected InputStream wrappedStream;
79 
80 
81     /**
82      * Indicates whether this stream itself is closed.
83      * If it isn't, but {@link #wrappedStream wrappedStream}
84      * is <code>null</code>, we're running in EOF mode.
85      * All read operations will indicate EOF without accessing
86      * the underlying stream. After closing this stream, read
87      * operations will trigger an {@link IOException IOException}.
88      *
89      * @see #isReadAllowed isReadAllowed
90      */
91     private boolean selfClosed;
92 
93     /** The watcher to be notified, if any. */
94     private EofSensorWatcher eofWatcher;
95 
96 
97     /**
98      * Creates a new EOF sensor.
99      * If no watcher is passed, the underlying stream will simply be
100      * closed when EOF is detected or {@link #close close} is called.
101      * Otherwise, the watcher decides whether the underlying stream
102      * should be closed before detaching from it.
103      *
104      * @param in        the wrapped stream
105      * @param watcher   the watcher for events, or <code>null</code> for
106      *                  auto-close behavior without notification
107      */
EofSensorInputStream(final InputStream in, final EofSensorWatcher watcher)108     public EofSensorInputStream(final InputStream in,
109                                 final EofSensorWatcher watcher) {
110         if (in == null) {
111             throw new IllegalArgumentException
112                 ("Wrapped stream may not be null.");
113         }
114 
115         wrappedStream = in;
116         selfClosed = false;
117         eofWatcher = watcher;
118     }
119 
120 
121     /**
122      * Checks whether the underlying stream can be read from.
123      *
124      * @return  <code>true</code> if the underlying stream is accessible,
125      *          <code>false</code> if this stream is in EOF mode and
126      *          detached from the underlying stream
127      *
128      * @throws IOException      if this stream is already closed
129      */
isReadAllowed()130     protected boolean isReadAllowed() throws IOException {
131         if (selfClosed) {
132             throw new IOException("Attempted read on closed stream.");
133         }
134         return (wrappedStream != null);
135     }
136 
137 
138     // non-javadoc, see base class InputStream
139     @Override
read()140     public int read() throws IOException {
141         int l = -1;
142 
143         if (isReadAllowed()) {
144             try {
145                 l = wrappedStream.read();
146                 checkEOF(l);
147             } catch (IOException ex) {
148                 checkAbort();
149                 throw ex;
150             }
151         }
152 
153         return l;
154     }
155 
156 
157     // non-javadoc, see base class InputStream
158     @Override
read(byte[] b, int off, int len)159     public int read(byte[] b, int off, int len) throws IOException {
160         int l = -1;
161 
162         if (isReadAllowed()) {
163             try {
164                 l = wrappedStream.read(b,  off,  len);
165                 checkEOF(l);
166             } catch (IOException ex) {
167                 checkAbort();
168                 throw ex;
169             }
170         }
171 
172         return l;
173     }
174 
175 
176     // non-javadoc, see base class InputStream
177     @Override
read(byte[] b)178     public int read(byte[] b) throws IOException {
179         int l = -1;
180 
181         if (isReadAllowed()) {
182             try {
183                 l = wrappedStream.read(b);
184                 checkEOF(l);
185             } catch (IOException ex) {
186                 checkAbort();
187                 throw ex;
188             }
189         }
190         return l;
191     }
192 
193 
194     // non-javadoc, see base class InputStream
195     @Override
available()196     public int available() throws IOException {
197         int a = 0; // not -1
198 
199         if (isReadAllowed()) {
200             try {
201                 a = wrappedStream.available();
202                 // no checkEOF() here, available() can't trigger EOF
203             } catch (IOException ex) {
204                 checkAbort();
205                 throw ex;
206             }
207         }
208 
209         return a;
210     }
211 
212 
213     // non-javadoc, see base class InputStream
214     @Override
close()215     public void close() throws IOException {
216         // tolerate multiple calls to close()
217         selfClosed = true;
218         checkClose();
219     }
220 
221 
222     /**
223      * Detects EOF and notifies the watcher.
224      * This method should only be called while the underlying stream is
225      * still accessible. Use {@link #isReadAllowed isReadAllowed} to
226      * check that condition.
227      * <br/>
228      * If EOF is detected, the watcher will be notified and this stream
229      * is detached from the underlying stream. This prevents multiple
230      * notifications from this stream.
231      *
232      * @param eof       the result of the calling read operation.
233      *                  A negative value indicates that EOF is reached.
234      *
235      * @throws IOException
236      *          in case of an IO problem on closing the underlying stream
237      */
checkEOF(int eof)238     protected void checkEOF(int eof) throws IOException {
239 
240         if ((wrappedStream != null) && (eof < 0)) {
241             try {
242                 boolean scws = true; // should close wrapped stream?
243                 if (eofWatcher != null)
244                     scws = eofWatcher.eofDetected(wrappedStream);
245                 if (scws)
246                     wrappedStream.close();
247             } finally {
248                 wrappedStream = null;
249             }
250         }
251     }
252 
253 
254     /**
255      * Detects stream close and notifies the watcher.
256      * There's not much to detect since this is called by {@link #close close}.
257      * The watcher will only be notified if this stream is closed
258      * for the first time and before EOF has been detected.
259      * This stream will be detached from the underlying stream to prevent
260      * multiple notifications to the watcher.
261      *
262      * @throws IOException
263      *          in case of an IO problem on closing the underlying stream
264      */
checkClose()265     protected void checkClose() throws IOException {
266 
267         if (wrappedStream != null) {
268             try {
269                 boolean scws = true; // should close wrapped stream?
270                 if (eofWatcher != null)
271                     scws = eofWatcher.streamClosed(wrappedStream);
272                 if (scws)
273                     wrappedStream.close();
274             } finally {
275                 wrappedStream = null;
276             }
277         }
278     }
279 
280 
281     /**
282      * Detects stream abort and notifies the watcher.
283      * There's not much to detect since this is called by
284      * {@link #abortConnection abortConnection}.
285      * The watcher will only be notified if this stream is aborted
286      * for the first time and before EOF has been detected or the
287      * stream has been {@link #close closed} gracefully.
288      * This stream will be detached from the underlying stream to prevent
289      * multiple notifications to the watcher.
290      *
291      * @throws IOException
292      *          in case of an IO problem on closing the underlying stream
293      */
checkAbort()294     protected void checkAbort() throws IOException {
295 
296         if (wrappedStream != null) {
297             try {
298                 boolean scws = true; // should close wrapped stream?
299                 if (eofWatcher != null)
300                     scws = eofWatcher.streamAbort(wrappedStream);
301                 if (scws)
302                     wrappedStream.close();
303             } finally {
304                 wrappedStream = null;
305             }
306         }
307     }
308 
309 
310     /**
311      * Same as {@link #close close()}.
312      */
releaseConnection()313     public void releaseConnection() throws IOException {
314         this.close();
315     }
316 
317     /**
318      * Aborts this stream.
319      * This is a special version of {@link #close close()} which prevents
320      * re-use of the underlying connection, if any. Calling this method
321      * indicates that there should be no attempt to read until the end of
322      * the stream.
323      */
abortConnection()324     public void abortConnection() throws IOException {
325         // tolerate multiple calls
326         selfClosed = true;
327         checkAbort();
328     }
329 
330 } // class EOFSensorInputStream
331 
332