+ * This class is based on AutoCloseInputStream in HttpClient 3.1,
+ * but has notable differences. It does not allow mark/reset, distinguishes
+ * different kinds of event, and does not always close the underlying stream
+ * on EOF. That decision is left to the {@link EofSensorWatcher watcher}.
+ *
null when the wrapped stream
+ * becomes inaccessible.
+ */
+ protected InputStream wrappedStream;
+
+
+ /**
+ * Indicates whether this stream itself is closed.
+ * If it isn't, but {@link #wrappedStream wrappedStream}
+ * is null, we're running in EOF mode.
+ * All read operations will indicate EOF without accessing
+ * the underlying stream. After closing this stream, read
+ * operations will trigger an {@link IOException IOException}.
+ *
+ * @see #isReadAllowed isReadAllowed
+ */
+ private boolean selfClosed;
+
+ /** The watcher to be notified, if any. */
+ private EofSensorWatcher eofWatcher;
+
+
+ /**
+ * Creates a new EOF sensor.
+ * If no watcher is passed, the underlying stream will simply be
+ * closed when EOF is detected or {@link #close close} is called.
+ * Otherwise, the watcher decides whether the underlying stream
+ * should be closed before detaching from it.
+ *
+ * @param in the wrapped stream
+ * @param watcher the watcher for events, or null for
+ * auto-close behavior without notification
+ */
+ public EofSensorInputStream(final InputStream in,
+ final EofSensorWatcher watcher) {
+ if (in == null) {
+ throw new IllegalArgumentException
+ ("Wrapped stream may not be null.");
+ }
+
+ wrappedStream = in;
+ selfClosed = false;
+ eofWatcher = watcher;
+ }
+
+
+ /**
+ * Checks whether the underyling stream can be read from.
+ *
+ * @return true if the underlying stream is accessible,
+ * false if this stream is in EOF mode and
+ * detached from the underlying stream
+ *
+ * @throws IOException if this stream is already closed
+ */
+ protected boolean isReadAllowed() throws IOException {
+ if (selfClosed) {
+ throw new IOException("Attempted read on closed stream.");
+ }
+ return (wrappedStream != null);
+ }
+
+
+ // non-javadoc, see base class InputStream
+ public int read() throws IOException {
+ int l = -1;
+
+ if (isReadAllowed()) {
+ l = wrappedStream.read();
+ checkEOF(l);
+ }
+
+ return l;
+ }
+
+
+ // non-javadoc, see base class InputStream
+ public int read(byte[] b, int off, int len) throws IOException {
+ int l = -1;
+
+ if (isReadAllowed()) {
+ l = wrappedStream.read(b, off, len);
+ checkEOF(l);
+ }
+
+ return l;
+ }
+
+
+ // non-javadoc, see base class InputStream
+ public int read(byte[] b) throws IOException {
+ int l = -1;
+
+ if (isReadAllowed()) {
+ l = wrappedStream.read(b);
+ checkEOF(l);
+ }
+ return l;
+ }
+
+
+ // non-javadoc, see base class InputStream
+ public int available() throws IOException {
+ int a = 0; // not -1
+
+ if (isReadAllowed()) {
+ a = wrappedStream.available();
+ // no checkEOF() here, available() can't trigger EOF
+ }
+
+ return a;
+ }
+
+
+ // non-javadoc, see base class InputStream
+ public void close() throws IOException {
+ // tolerate multiple calls to close()
+ selfClosed = true;
+ checkClose();
+ }
+
+
+ /**
+ * Detects EOF and notifies the watcher.
+ * This method should only be called while the underlying stream is
+ * still accessible. Use {@link #isReadAllowed isReadAllowed} to
+ * check that condition.
+ * true if wrapped should be closed,
+ * false if it should be left alone
+ *
+ * @throws IOException
+ * in case of an IO problem, for example if the watcher itself
+ * closes the underlying stream. The caller will leave the
+ * wrapped stream alone, as if false was returned.
+ */
+ boolean eofDetected(InputStream wrapped)
+ throws IOException
+ ;
+
+
+ /**
+ * Indicates that the {@link EofSensorInputStream stream} is closed.
+ * This method will be called only if EOF was not detected
+ * before closing. Otherwise, {@link #eofDetected eofDetected} is called.
+ *
+ * @param wrapped the underlying stream which has not reached EOF
+ *
+ * @return true if wrapped should be closed,
+ * false if it should be left alone
+ *
+ * @throws IOException
+ * in case of an IO problem, for example if the watcher itself
+ * closes the underlying stream. The caller will leave the
+ * wrapped stream alone, as if false was returned.
+ */
+ boolean streamClosed(InputStream wrapped)
+ throws IOException
+ ;
+
+} // interface EofSensorWatcher