001: /*
002: * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/httpcore/tags/4.0-beta1/module-main/src/main/java/org/apache/http/HttpConnection.java $
003: * $Revision: 548031 $
004: * $Date: 2007-06-17 13:28:38 +0200 (Sun, 17 Jun 2007) $
005: *
006: * ====================================================================
007: * Licensed to the Apache Software Foundation (ASF) under one
008: * or more contributor license agreements. See the NOTICE file
009: * distributed with this work for additional information
010: * regarding copyright ownership. The ASF licenses this file
011: * to you under the Apache License, Version 2.0 (the
012: * "License"); you may not use this file except in compliance
013: * with the License. You may obtain a copy of the License at
014: *
015: * http://www.apache.org/licenses/LICENSE-2.0
016: *
017: * Unless required by applicable law or agreed to in writing,
018: * software distributed under the License is distributed on an
019: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
020: * KIND, either express or implied. See the License for the
021: * specific language governing permissions and limitations
022: * under the License.
023: * ====================================================================
024: *
025: * This software consists of voluntary contributions made by many
026: * individuals on behalf of the Apache Software Foundation. For more
027: * information on the Apache Software Foundation, please see
028: * <http://www.apache.org/>.
029: *
030: */
031:
032: package org.apache.http;
033:
034: import java.io.IOException;
035:
036: /**
037: * A generic HTTP connection, useful on client and server side.
038: *
039: * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
040: *
041: * @version $Revision: 548031 $
042: *
043: * @since 4.0
044: */
045: public interface HttpConnection {
046:
047: /**
048: * Closes this connection gracefully.
049: * This method will attempt to flush the transmitter's
050: * internal buffer prior to closing the underlying socket.
051: * This method MUST NOT be called from a different thread to force
052: * shutdown of the connection. Use {@link #shutdown shutdown} instead.
053: */
054: public void close() throws IOException;
055:
056: /**
057: * Checks if this connection is open.
058: * @return true if it is open, false if it is closed.
059: */
060: public boolean isOpen();
061:
062: /**
063: * Checks whether this connection has gone down.
064: * Network connections may get closed during some time of inactivity
065: * for several reasons. The next time a read is attempted on such a
066: * connection it will throw an IOException.
067: * This method tries to alleviate this inconvenience by trying to
068: * find out if a connection is still usable. Implementations may do
069: * that by attempting a read with a very small timeout. Thus this
070: * method may block for a small amount of time before returning a result.
071: * It is therefore an <i>expensive</i> operation.
072: *
073: * @return <code>true</code> if attempts to use this connection are
074: * likely to succeed, or <code>false</code> if they are likely
075: * to fail and this connection should be closed
076: */
077: public boolean isStale();
078:
079: /**
080: * Sets the socket timeout value.
081: *
082: * @param timeout timeout value in milliseconds
083: */
084: void setSocketTimeout(int timeout);
085:
086: /**
087: * Returns the socket timeout value.
088: *
089: * @return positive value in milliseconds if a timeout is set,
090: * <code>0</code> if timeout is disabled or <code>-1</code> if
091: * timeout is undefined.
092: */
093: int getSocketTimeout();
094:
095: /**
096: * Force-closes this connection.
097: * This is the only method of a connection which may be called
098: * from a different thread to terminate the connection.
099: * 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: }
|