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 */ 027 028package org.apache.http; 029 030import java.io.Closeable; 031import java.io.IOException; 032 033/** 034 * A generic HTTP connection, useful on client and server side. 035 * 036 * @since 4.0 037 */ 038public interface HttpConnection extends Closeable { 039 040 /** 041 * Closes this connection gracefully. 042 * This method will attempt to flush the internal output 043 * buffer prior to closing the underlying socket. 044 * This method MUST NOT be called from a different thread to force 045 * shutdown of the connection. Use {@link #shutdown shutdown} instead. 046 */ 047 @Override 048 void close() throws IOException; 049 050 /** 051 * Checks if this connection is open. 052 * @return true if it is open, false if it is closed. 053 */ 054 boolean isOpen(); 055 056 /** 057 * Checks whether this connection has gone down. 058 * Network connections may get closed during some time of inactivity 059 * for several reasons. The next time a read is attempted on such a 060 * connection it will throw an IOException. 061 * This method tries to alleviate this inconvenience by trying to 062 * find out if a connection is still usable. Implementations may do 063 * that by attempting a read with a very small timeout. Thus this 064 * method may block for a small amount of time before returning a result. 065 * It is therefore an <i>expensive</i> operation. 066 * 067 * @return {@code true} if attempts to use this connection are 068 * likely to succeed, or {@code false} if they are likely 069 * to fail and this connection should be closed 070 */ 071 boolean isStale(); 072 073 /** 074 * Sets the socket timeout value. 075 * 076 * @param timeout timeout value in milliseconds 077 */ 078 void setSocketTimeout(int timeout); 079 080 /** 081 * Returns the socket timeout value. 082 * 083 * @return positive value in milliseconds if a timeout is set, 084 * {@code 0} if timeout is disabled or {@code -1} if 085 * timeout is undefined. 086 */ 087 int getSocketTimeout(); 088 089 /** 090 * Force-closes this connection. 091 * This is the only method of a connection which may be called 092 * from a different thread to terminate the connection. 093 * This method will not attempt to flush the transmitter's 094 * internal buffer prior to closing the underlying socket. 095 */ 096 void shutdown() throws IOException; 097 098 /** 099 * Returns a collection of connection metrics. 100 * 101 * @return HttpConnectionMetrics 102 */ 103 HttpConnectionMetrics getMetrics(); 104 105}