001/*
002 * ====================================================================
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *   http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing,
014 * software distributed under the License is distributed on an
015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
016 * KIND, either express or implied.  See the License for the
017 * specific language governing permissions and limitations
018 * under the License.
019 * ====================================================================
020 *
021 * This software consists of voluntary contributions made by many
022 * individuals on behalf of the Apache Software Foundation.  For more
023 * information on the Apache Software Foundation, please see
024 * <http://www.apache.org/>.
025 *
026 */
027package org.apache.http.conn;
028
029import java.io.IOException;
030import java.io.InputStream;
031
032/**
033 * A watcher for {@link EofSensorInputStream}. Each stream will notify its
034 * watcher at most once.
035 *
036 * @since 4.0
037 */
038public interface EofSensorWatcher {
039
040    /**
041     * Indicates that EOF is detected.
042     *
043     * @param wrapped   the underlying stream which has reached EOF
044     *
045     * @return  {@code true} if {@code wrapped} should be closed,
046     *          {@code false} if it should be left alone
047     *
048     * @throws IOException
049     *         in case of an IO problem, for example if the watcher itself
050     *         closes the underlying stream. The caller will leave the
051     *         wrapped stream alone, as if {@code false} was returned.
052     */
053    boolean eofDetected(InputStream wrapped)
054        throws IOException;
055
056    /**
057     * Indicates that the {@link EofSensorInputStream stream} is closed.
058     * This method will be called only if EOF was <i>not</i> detected
059     * before closing. Otherwise, {@link #eofDetected eofDetected} is called.
060     *
061     * @param wrapped   the underlying stream which has not reached EOF
062     *
063     * @return  {@code true} if {@code wrapped} should be closed,
064     *          {@code false} if it should be left alone
065     *
066     * @throws IOException
067     *         in case of an IO problem, for example if the watcher itself
068     *         closes the underlying stream. The caller will leave the
069     *         wrapped stream alone, as if {@code false} was returned.
070     */
071    boolean streamClosed(InputStream wrapped)
072        throws IOException;
073
074    /**
075     * Indicates that the {@link EofSensorInputStream stream} is aborted.
076     * This method will be called only if EOF was <i>not</i> detected
077     * before aborting. Otherwise, {@link #eofDetected eofDetected} is called.
078     * <p>
079     * This method will also be invoked when an input operation causes an
080     * IOException to be thrown to make sure the input stream gets shut down.
081     * </p>
082     *
083     * @param wrapped   the underlying stream which has not reached EOF
084     *
085     * @return  {@code true} if {@code wrapped} should be closed,
086     *          {@code false} if it should be left alone
087     *
088     * @throws IOException
089     *         in case of an IO problem, for example if the watcher itself
090     *         closes the underlying stream. The caller will leave the
091     *         wrapped stream alone, as if {@code false} was returned.
092     */
093    boolean streamAbort(InputStream wrapped)
094        throws IOException;
095
096}