/*
 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/conn/EofSensorInputStream.java $
 * $Revision: 672367 $
 * $Date: 2008-06-27 12:49:20 -0700 (Fri, 27 Jun 2008) $
 *
 * ====================================================================
 *
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 *
 */

package org.apache.http.conn;

import java.io.InputStream;
import java.io.IOException;


/**
 * A stream wrapper that triggers actions on {@link #close close()} and EOF.
 * Primarily used to auto-release an underlying
 * {@link ManagedClientConnection connection}
 * when the response body is consumed or no longer needed.
 *
 * <p>
 * This class is based on <code>AutoCloseInputStream</code> 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}.
 * </p>
 *
 * @see EofSensorWatcher EofSensorWatcher
 *
 * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
 * @author Ortwin Glueck
 * @author Eric Johnson
 * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
 *
 *
 * <!-- empty lines to avoid svn diff problems -->
 * @version $Revision: 672367 $
 *
 * @since 4.0
 */
// don't use FilterInputStream as the base class, we'd have to
// override markSupported(), mark(), and reset() to disable them
public class EofSensorInputStream extends InputStream
    implements ConnectionReleaseTrigger {

    /**
     * The wrapped input stream, while accessible.
     * The value changes to <code>null</code> 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 <code>null</code>, 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 <code>null</code> 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 underlying stream can be read from.
     *
     * @return  <code>true</code> if the underlying stream is accessible,
     *          <code>false</code> 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
    @Override
    public int read() throws IOException {
        int l = -1;

        if (isReadAllowed()) {
            try {
                l = wrappedStream.read();
                checkEOF(l);
            } catch (IOException ex) {
                checkAbort();
                throw ex;
            }
        }

        return l;
    }


    // non-javadoc, see base class InputStream
    @Override
    public int read(byte[] b, int off, int len) throws IOException {
        int l = -1;

        if (isReadAllowed()) {
            try {
                l = wrappedStream.read(b,  off,  len);
                checkEOF(l);
            } catch (IOException ex) {
                checkAbort();
                throw ex;
            }
        }

        return l;
    }


    // non-javadoc, see base class InputStream
    @Override
    public int read(byte[] b) throws IOException {
        int l = -1;

        if (isReadAllowed()) {
            try {
                l = wrappedStream.read(b);
                checkEOF(l);
            } catch (IOException ex) {
                checkAbort();
                throw ex;
            }
        }
        return l;
    }


    // non-javadoc, see base class InputStream
    @Override
    public int available() throws IOException {
        int a = 0; // not -1

        if (isReadAllowed()) {
            try {
                a = wrappedStream.available();
                // no checkEOF() here, available() can't trigger EOF
            } catch (IOException ex) {
                checkAbort();
                throw ex;
            }
        }

        return a;
    }


    // non-javadoc, see base class InputStream
    @Override
    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.
     * <br/>
     * If EOF is detected, the watcher will be notified and this stream
     * is detached from the underlying stream. This prevents multiple
     * notifications from this stream.
     *
     * @param eof       the result of the calling read operation.
     *                  A negative value indicates that EOF is reached.
     *
     * @throws IOException
     *          in case of an IO problem on closing the underlying stream
     */
    protected void checkEOF(int eof) throws IOException {

        if ((wrappedStream != null) && (eof < 0)) {
            try {
                boolean scws = true; // should close wrapped stream?
                if (eofWatcher != null)
                    scws = eofWatcher.eofDetected(wrappedStream);
                if (scws)
                    wrappedStream.close();
            } finally {
                wrappedStream = null;
            }
        }
    }


    /**
     * Detects stream close and notifies the watcher.
     * There's not much to detect since this is called by {@link #close close}.
     * The watcher will only be notified if this stream is closed
     * for the first time and before EOF has been detected.
     * This stream will be detached from the underlying stream to prevent
     * multiple notifications to the watcher.
     *
     * @throws IOException
     *          in case of an IO problem on closing the underlying stream
     */
    protected void checkClose() throws IOException {

        if (wrappedStream != null) {
            try {
                boolean scws = true; // should close wrapped stream?
                if (eofWatcher != null)
                    scws = eofWatcher.streamClosed(wrappedStream);
                if (scws)
                    wrappedStream.close();
            } finally {
                wrappedStream = null;
            }
        }
    }


    /**
     * Detects stream abort and notifies the watcher.
     * There's not much to detect since this is called by
     * {@link #abortConnection abortConnection}.
     * The watcher will only be notified if this stream is aborted
     * for the first time and before EOF has been detected or the
     * stream has been {@link #close closed} gracefully.
     * This stream will be detached from the underlying stream to prevent
     * multiple notifications to the watcher.
     *
     * @throws IOException
     *          in case of an IO problem on closing the underlying stream
     */
    protected void checkAbort() throws IOException {

        if (wrappedStream != null) {
            try {
                boolean scws = true; // should close wrapped stream?
                if (eofWatcher != null)
                    scws = eofWatcher.streamAbort(wrappedStream);
                if (scws)
                    wrappedStream.close();
            } finally {
                wrappedStream = null;
            }
        }
    }


    /**
     * Same as {@link #close close()}.
     */
    public void releaseConnection() throws IOException {
        this.close();
    }

    /**
     * Aborts this stream.
     * This is a special version of {@link #close close()} which prevents
     * re-use of the underlying connection, if any. Calling this method
     * indicates that there should be no attempt to read until the end of
     * the stream.
     */
    public void abortConnection() throws IOException {
        // tolerate multiple calls
        selfClosed = true;
        checkAbort();
    }

} // class EOFSensorInputStream