001: /*
002: * HttpSocketPool.java
003: *
004: * Brazil project web application Framework,
005: * export version: 1.1
006: * Copyright (c) 1999 Sun Microsystems, Inc.
007: *
008: * Sun Public License Notice
009: *
010: * The contents of this file are subject to the Sun Public License Version
011: * 1.0 (the "License"). You may not use this file except in compliance with
012: * the License. A copy of the License is included as the file "license.terms",
013: * and also available at http://www.sun.com/
014: *
015: * The Original Code is from:
016: * Brazil project web application Framework release 1.1.
017: * The Initial Developer of the Original Code is: cstevens.
018: * Portions created by cstevens are Copyright (C) Sun Microsystems, Inc.
019: * All Rights Reserved.
020: *
021: * Contributor(s): cstevens, suhler.
022: *
023: * Version: 1.6
024: * Created by cstevens on 99/09/15
025: * Last modified by cstevens on 99/10/14 13:23:44
026: */
027:
028: package sunlabs.brazil.util.http;
029:
030: import java.io.IOException;
031:
032: /**
033: * This interface represents a cache of idle sockets. Once a request has
034: * been handled, the now-idle socket can be remembered and reused later in
035: * case another HTTP request is made to the same remote host. Currently, the
036: * only instance of this interface is used by the <code>HttpRequest</code>
037: * class.
038: *
039: * @author Colin Stevens (colin.stevens@sun.com)
040: * @version 1.6 99/10/14
041: */
042: public interface HttpSocketPool {
043: /**
044: * Returns an <code>HttpSocket</code> that can be used to communicate
045: * with the specified port on the named host.
046: * <p>
047: * It is this method's responsibility to to fill in all the public
048: * member variables of the <code>HttpSocket</code> before returning.
049: * <p>
050: * For each call to this method, there should eventually be a call to
051: * <code>close</code> when the <code>HttpSocket</code> isn't needed
052: * anymore.
053: *
054: * @param host
055: * The host name.
056: *
057: * @param port
058: * The port number.
059: *
060: * @param reuse
061: * <code>true</code> to request that this pool attempt to find
062: * and reuse an existing idle connection, <code>false</code>
063: * to request that this pool establish a new connection to
064: * the named host.
065: *
066: * @return The <code>HttpSocket</code>.
067: *
068: * @throws IOException
069: * if there is a problem connecting to the specified port on
070: * the named host. The <code>IOException</code>s (and
071: * subclasses) that might be thrown depend upon how the
072: * socket connection is established. See the socket
073: * documentation for further details. Some subclasses that
074: * might be thrown are as follows:
075: *
076: * @throws java.io.UnknownHostException
077: * if the host name cannot be resolved.
078: *
079: * @throws java.io.ConnectionException
080: * if the named host is not listening on the specified port.
081: *
082: * @throws java.io.InterruptedIOException
083: * if the connection times out or this thread is interrupted by
084: * <code>Thread.interrupt</code>.
085: */
086: public HttpSocket get(String host, int port, boolean reuse)
087: throws IOException;
088:
089: /**
090: * Releases an <code>HttpSocket</code> to this pool when it is not
091: * in use any more.
092: * <p>
093: * It is this method's responsibility to release resources used
094: * by the <code>HttpSocket</code>, such as closing the underlying socket.
095: * <p>
096: * After calling this method, the user should not refer to the specified
097: * <code>HttpSocket</code> any more.
098: *
099: * @param hs
100: * The <code>HttpSocket</code> to release.
101: *
102: * @param reuse
103: * <code>true</code> if the specified <code>HttpSocket</code>
104: * should be put back into the idle pool, <code>false</code>
105: * if it should be released immediately.
106: */
107: public void close(HttpSocket hs, boolean reuse);
108: }
|