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      void close() throws IOException;
48  
49      /**
50       * Checks if this connection is open.
51       * @return true if it is open, false if it is closed.
52       */
53      boolean isOpen();
54  
55      /**
56       * Checks whether this connection has gone down.
57       * Network connections may get closed during some time of inactivity
58       * for several reasons. The next time a read is attempted on such a
59       * connection it will throw an IOException.
60       * This method tries to alleviate this inconvenience by trying to
61       * find out if a connection is still usable. Implementations may do
62       * that by attempting a read with a very small timeout. Thus this
63       * method may block for a small amount of time before returning a result.
64       * It is therefore an <i>expensive</i> operation.
65       *
66       * @return  <code>true</code> if attempts to use this connection are
67       *          likely to succeed, or <code>false</code> if they are likely
68       *          to fail and this connection should be closed
69       */
70      boolean isStale();
71  
72      /**
73       * Sets the socket timeout value.
74       *
75       * @param timeout timeout value in milliseconds
76       */
77      void setSocketTimeout(int timeout);
78  
79      /**
80       * Returns the socket timeout value.
81       *
82       * @return positive value in milliseconds if a timeout is set,
83       * <code>0</code> if timeout is disabled or <code>-1</code> if
84       * timeout is undefined.
85       */
86      int getSocketTimeout();
87  
88      /**
89       * Force-closes this connection.
90       * This is the only method of a connection which may be called
91       * from a different thread to terminate the connection.
92       * This method will not attempt to flush the transmitter's
93       * internal buffer prior to closing the underlying socket.
94       */
95      void shutdown() throws IOException;
96  
97      /**
98       * Returns a collection of connection metrics.
99       *
100      * @return HttpConnectionMetrics
101      */
102     HttpConnectionMetrics getMetrics();
103 
104 }