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.IOException;
31  
32  /**
33   * A client-side HTTP connection, which can be used for sending
34   * requests and receiving responses.
35   *
36   * @since 4.0
37   */
38  public interface HttpClientConnection extends HttpConnection {
39  
40      /**
41       * Checks if response data is available from the connection. May wait for
42       * the specified time until some data becomes available. Note that some
43       * implementations may completely ignore the timeout parameter.
44       *
45       * @param timeout the maximum time in milliseconds to wait for data
46       * @return true if data is available; false if there was no data available
47       *         even after waiting for {@code timeout} milliseconds.
48       * @throws IOException if an error happens on the connection
49       */
50      boolean isResponseAvailable(int timeout)
51          throws IOException;
52  
53      /**
54       * Sends the request line and all headers over the connection.
55       * @param request the request whose headers to send.
56       * @throws HttpException in case of HTTP protocol violation
57       * @throws IOException in case of an I/O error
58       */
59      void sendRequestHeader(HttpRequest request)
60          throws HttpException, IOException;
61  
62      /**
63       * Sends the request entity over the connection.
64       * @param request the request whose entity to send.
65       * @throws HttpException in case of HTTP protocol violation
66       * @throws IOException in case of an I/O error
67       */
68      void sendRequestEntity(HttpEntityEnclosingRequest request)
69          throws HttpException, IOException;
70  
71      /**
72       * Receives the request line and headers of the next response available from
73       * this connection. The caller should examine the HttpResponse object to
74       * find out if it should try to receive a response entity as well.
75       *
76       * @return a new HttpResponse object with status line and headers
77       *         initialized.
78       * @throws HttpException in case of HTTP protocol violation
79       * @throws IOException in case of an I/O error
80       */
81      HttpResponse receiveResponseHeader()
82          throws HttpException, IOException;
83  
84      /**
85       * Receives the next response entity available from this connection and
86       * attaches it to an existing HttpResponse object.
87       *
88       * @param response the response to attach the entity to
89       * @throws HttpException in case of HTTP protocol violation
90       * @throws IOException in case of an I/O error
91       */
92      void receiveResponseEntity(HttpResponse response)
93          throws HttpException, IOException;
94  
95      /**
96       * Writes out all pending buffered data over the open connection.
97       *
98       * @throws IOException in case of an I/O error
99       */
100     void flush() throws IOException;
101 
102 }