1 /* 2 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpConnection.java $ 3 * $Revision: 548031 $ 4 * $Date: 2007-06-17 04:28:38 -0700 (Sun, 17 Jun 2007) $ 5 * 6 * ==================================================================== 7 * Licensed to the Apache Software Foundation (ASF) under one 8 * or more contributor license agreements. See the NOTICE file 9 * distributed with this work for additional information 10 * regarding copyright ownership. The ASF licenses this file 11 * to you under the Apache License, Version 2.0 (the 12 * "License"); you may not use this file except in compliance 13 * with the License. You may obtain a copy of the License at 14 * 15 * http://www.apache.org/licenses/LICENSE-2.0 16 * 17 * Unless required by applicable law or agreed to in writing, 18 * software distributed under the License is distributed on an 19 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 20 * KIND, either express or implied. See the License for the 21 * specific language governing permissions and limitations 22 * under the License. 23 * ==================================================================== 24 * 25 * This software consists of voluntary contributions made by many 26 * individuals on behalf of the Apache Software Foundation. For more 27 * information on the Apache Software Foundation, please see 28 * <http://www.apache.org/>. 29 * 30 */ 31 32 package org.apache.http; 33 34 import java.io.IOException; 35 36 /** 37 * A generic HTTP connection, useful on client and server side. 38 * 39 * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a> 40 * 41 * @version $Revision: 548031 $ 42 * 43 * @since 4.0 44 */ 45 public interface HttpConnection { 46 47 /** 48 * Closes this connection gracefully. 49 * This method will attempt to flush the transmitter's 50 * internal buffer prior to closing the underlying socket. 51 * This method MUST NOT be called from a different thread to force 52 * shutdown of the connection. Use {@link #shutdown shutdown} instead. 53 */ 54 public void close() throws IOException; 55 56 /** 57 * Checks if this connection is open. 58 * @return true if it is open, false if it is closed. 59 */ 60 public boolean isOpen(); 61 62 /** 63 * Checks whether this connection has gone down. 64 * Network connections may get closed during some time of inactivity 65 * for several reasons. The next time a read is attempted on such a 66 * connection it will throw an IOException. 67 * This method tries to alleviate this inconvenience by trying to 68 * find out if a connection is still usable. Implementations may do 69 * that by attempting a read with a very small timeout. Thus this 70 * method may block for a small amount of time before returning a result. 71 * It is therefore an <i>expensive</i> operation. 72 * 73 * @return <code>true</code> if attempts to use this connection are 74 * likely to succeed, or <code>false</code> if they are likely 75 * to fail and this connection should be closed 76 */ 77 public boolean isStale(); 78 79 /** 80 * Sets the socket timeout value. 81 * 82 * @param timeout timeout value in milliseconds 83 */ 84 void setSocketTimeout(int timeout); 85 86 /** 87 * Returns the socket timeout value. 88 * 89 * @return positive value in milliseconds if a timeout is set, 90 * <code>0</code> if timeout is disabled or <code>-1</code> if 91 * timeout is undefined. 92 */ 93 int getSocketTimeout(); 94 95 /** 96 * Force-closes this connection. 97 * This is the only method of a connection which may be called 98 * from a different thread to terminate the connection. 99 * This method will not attempt to flush the transmitter's 100 * internal buffer prior to closing the underlying socket. 101 */ 102 public void shutdown() throws IOException; 103 104 /** 105 * Returns a collection of connection metrcis 106 * @return HttpConnectionMetrics 107 */ 108 HttpConnectionMetrics getMetrics(); 109 110 } 111
