View Javadoc

1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  package org.apache.http.conn;
28  
29  import java.io.IOException;
30  import java.io.InputStream;
31  
32  /**
33   * A watcher for {@link EofSensorInputStream}. Each stream will notify its
34   * watcher at most once.
35   *
36   * @since 4.0
37   */
38  public interface EofSensorWatcher {
39  
40      /**
41       * Indicates that EOF is detected.
42       *
43       * @param wrapped   the underlying stream which has reached EOF
44       *
45       * @return  {@code true} if {@code wrapped} should be closed,
46       *          {@code false} if it should be left alone
47       *
48       * @throws IOException
49       *         in case of an IO problem, for example if the watcher itself
50       *         closes the underlying stream. The caller will leave the
51       *         wrapped stream alone, as if {@code false} was returned.
52       */
53      boolean eofDetected(InputStream wrapped)
54          throws IOException;
55  
56      /**
57       * Indicates that the {@link EofSensorInputStream stream} is closed.
58       * This method will be called only if EOF was <i>not</i> detected
59       * before closing. Otherwise, {@link #eofDetected eofDetected} is called.
60       *
61       * @param wrapped   the underlying stream which has not reached EOF
62       *
63       * @return  {@code true} if {@code wrapped} should be closed,
64       *          {@code false} if it should be left alone
65       *
66       * @throws IOException
67       *         in case of an IO problem, for example if the watcher itself
68       *         closes the underlying stream. The caller will leave the
69       *         wrapped stream alone, as if {@code false} was returned.
70       */
71      boolean streamClosed(InputStream wrapped)
72          throws IOException;
73  
74      /**
75       * Indicates that the {@link EofSensorInputStream stream} is aborted.
76       * This method will be called only if EOF was <i>not</i> detected
77       * before aborting. Otherwise, {@link #eofDetected eofDetected} is called.
78       * <p>
79       * This method will also be invoked when an input operation causes an
80       * IOException to be thrown to make sure the input stream gets shut down.
81       * </p>
82       *
83       * @param wrapped   the underlying stream which has not reached EOF
84       *
85       * @return  {@code true} if {@code wrapped} should be closed,
86       *          {@code false} if it should be left alone
87       *
88       * @throws IOException
89       *         in case of an IO problem, for example if the watcher itself
90       *         closes the underlying stream. The caller will leave the
91       *         wrapped stream alone, as if {@code false} was returned.
92       */
93      boolean streamAbort(InputStream wrapped)
94          throws IOException;
95  
96  }