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  
28  package org.apache.http;
29  
30  import java.io.Closeable;
31  import java.io.IOException;
32  
33  /**
34   * A generic HTTP connection, useful on client and server side.
35   *
36   * @since 4.0
37   */
38  public interface HttpConnection extends Closeable {
39  
40      /**
41       * Closes this connection gracefully.
42       * This method will attempt to flush the internal output
43       * buffer prior to closing the underlying socket.
44       * This method MUST NOT be called from a different thread to force
45       * shutdown of the connection. Use {@link #shutdown shutdown} instead.
46       */
47      @Override
48      void close() throws IOException;
49  
50      /**
51       * Checks if this connection is open.
52       * @return true if it is open, false if it is closed.
53       */
54      boolean isOpen();
55  
56      /**
57       * Checks whether this connection has gone down.
58       * Network connections may get closed during some time of inactivity
59       * for several reasons. The next time a read is attempted on such a
60       * connection it will throw an IOException.
61       * This method tries to alleviate this inconvenience by trying to
62       * find out if a connection is still usable. Implementations may do
63       * that by attempting a read with a very small timeout. Thus this
64       * method may block for a small amount of time before returning a result.
65       * It is therefore an <i>expensive</i> operation.
66       *
67       * @return  {@code true} if attempts to use this connection are
68       *          likely to succeed, or {@code false} if they are likely
69       *          to fail and this connection should be closed
70       */
71      boolean isStale();
72  
73      /**
74       * Sets the socket timeout value.
75       *
76       * @param timeout timeout value in milliseconds
77       */
78      void setSocketTimeout(int timeout);
79  
80      /**
81       * Returns the socket timeout value.
82       *
83       * @return positive value in milliseconds if a timeout is set,
84       * {@code 0} if timeout is disabled or {@code -1} if
85       * timeout is undefined.
86       */
87      int getSocketTimeout();
88  
89      /**
90       * Force-closes this connection.
91       * This is the only method of a connection which may be called
92       * from a different thread to terminate the connection.
93       * This method will not attempt to flush the transmitter's
94       * internal buffer prior to closing the underlying socket.
95       */
96      void shutdown() throws IOException;
97  
98      /**
99       * Returns a collection of connection metrics.
100      *
101      * @return HttpConnectionMetrics
102      */
103     HttpConnectionMetrics getMetrics();
104 
105 }