Dear Wiki user, You have subscribed to a wiki page or wiki category on "Httpcomponents Wiki" for change notification.
The following page has been changed by OlegKalnichevski: http://wiki.apache.org/HttpComponents/HttpClientTutorial ------------------------------------------------------------------------------ null }}} + == HTTP request execution parameters == + + These are parameters that can impact the process of request execution: + + * '''http.protocol.version''': defines HTTP protocol version used if not set explicitly on the request object. This parameter expects a value of type ProtocolVersion. If this parameter is not set HTTP/1.1 will be used. + + * '''http.protocol.element-charset''': defines the charset to be used for encoding HTTP protocol elements. This parameter expects a value of type java.lang. String. If this parameter is not set US-ASCII will be used. + + * '''http.protocol.content-charset''': defines the charset to be used per default for content body coding. This parameter expects a value of type java.lang.String. If this parameter is not set ISO-8859-1 will be used. + + * '''http.useragent''': defines the content of the {{{User-Agent}}} header. This parameter expects a value of type java.lang.String. If this parameter is not set, HttpClient will automatically generate a value for it. + + * '''http.protocol.strict-transfer-encoding''': defines whether responses with an invalid {{{Transfer-Encoding}}} header should be rejected. This parameter expects a value of type java.lang.Boolean. If this parameter is not set invalid {{{Transfer-Encoding}}} values will be ignored. + + * '''http.protocol.expect-continue''': activates 'Expect: 100-Continue' handshake for the entity enclosing methods. The purpose of the {{{Expect: 100-Continue}}} handshake is to allow a client that is sending a request message with a request body to determine if the origin server is willing to accept the request (based on the request headers) before the client sends the request body. The use of the {{{Expect: 100-continue}}} handshake can result in a noticeable performance improvement for entity enclosing requests (such as POST and PUT) that require the target server's authentication. {{{Expect: 100-continue}}} handshake should be used with caution, as it may cause problems with HTTP servers and proxies that do not support HTTP/1.1 protocol. This parameter expects a value of type java.lang.Boolean. If this parameter is not set HttpClient will attempt to use the handshake. + + * '''http.protocol.wait-for-continue''': defines the maximum period of time in milliseconds the client should spend waiting for a 100-continue response. This parameter expects a value of type java.lang.Integer. If this parameter is not set HttpClient will wait 3 seconds for a confirmation before resuming the transmission of the request body. + = Connection management = + HttpClient has a complete control over the process of connection initialization and termination as well as I/O operations on active connections. However various aspects of connection operations can be controlled using a number of parameters: + + == Connection parameters == + + These are parameters that can influence connection operations: + + * '''http.socket.timeout''': defines the socket timeout ({{{SO_TIMEOUT}}}) in milliseconds, which is the timeout for waiting for data or, put differently, a maximum period inactivity between two consecutive data packets). A timeout value of zero is interpreted as an infinite timeout. This parameter expects a value of type java.lang.Integer}. If this parameter is not set read operations will not time out (infinite timeout). + + * '''http.tcp.nodelay''': determines whether Nagle's algorithm is to be used. The Nagle's algorithm tries to conserve bandwidth by minimizing the number of segments that are sent. When applications wish to decrease network latency and increase performance, they can disable Nagle's algorithm (that is enable {{{TCP_NODELAY}}}. Data will be sent earlier, at the cost of an increase in bandwidth consumption. This parameter expects a value of type java.lang.Boolean. If this parameter is not, {{{TCP_NODELAY}}} will be enabled (no delay). + + * '''http.socket.buffer-size''': determines the size of the internal socket buffer used to buffer data while receiving / transmitting HTTP messages. This parameter expects a value of type java.lang.Integer. If this parameter is not set HttpClient will allocate 8192 byte socket buffers. + + * '''http.socket.linger''': sets {{{SO_LINGER}}} with the specified linger time in seconds. The maximum timeout value is platform specific. Value 0 implies that the option is disabled. Value -1 implies that the JRE default is used. The setting only affects the socket close operation. If this parameter is not set value -1 (JRE default) will be assumed. + + * '''http.connection.timeout''': determines the timeout in milliseconds until a connection is established. A timeout value of zero is interpreted as an infinite timeout. This parameter expects a value of type java.lang.Integer. If this parameter is not set connect operations will not time out (infinite timeout). + + * '''http.connection.stalecheck''': determines whether stale connection check is to be used. Disabling stale connection check may result in a noticeable performance improvement (the check can cause up to 30 millisecond overhead per request) at the risk of getting an I/O error when executing a request over a connection that has been closed at the server side. This parameter expects a value of type java.lang.Boolean. For performance critical operations the check should be disabled. If this parameter is not set the stale connection will be performed before each request execution. + + * '''http.connection.max-line-length''': Determines the maximum line length limit. If set to a positive value, any HTTP line exceeding this limit will cause an IOException. A negative or zero value will effectively disable the check. This parameter expects a value of type java.lang.Integer. If this parameter is not set, no limit will be enforced. + + * '''http.connection.max-header-count''': determines the maximum HTTP header count allowed. If set to a positive value, the number of HTTP headers received from the data stream exceeding this limit will cause an IOException. A negative or zero value will effectively disable the check. This parameter expects a value of type java.long.Integer. If this parameter is not set, no limit will be enforced. + + * '''http.connection.max-status-line-garbage''': defines the maximum number of ignorable lines before we expect a HTTP response's status line. With HTTP/1.1 persistent connections, the problem arises that broken scripts could return a wrong {{{Content-Length}}} (there are more bytes sent than specified). Unfortunately, in some cases, this cannot be detected after the bad response, but only before the next one. So HttpClient must be able to skip those surplus lines this way. This parameter expects a value of type java.lang.Integer. 0 disallows all garbage/empty lines before the status line. Use java.lang.Integer#MAX_VALUE for unlimited number. If this parameter is not set unlimited number will be assumed. + == Connection persistence == + The process of establishing a connection from one host to another is quite complex and involves multiple packet exchanges between two endpoints, which can be quite time consuming. The overhead of connection handshaking can be significant, especially for small HTTP messages. One can achieve a much higher data throughput if open connections can be re-used to execute multiple requests. - Benefits of connection re-use. - - == Route planning == - Types of connections: plain, tunnelled, layered. Route planners. + HTTP/1.1 states that HTTP connections can be re-used for multiple requests per default. HTTP/1.0 compliant endpoints can also use similar mechanism to explicitly communicate their preference to keep connection alive and use it for multiple requests. HTTP agents can also keep idle connections alive for a certain period time in case a connection to the same target host may be needed for subsequent requests. The ability to keep connections alive is usually refered to as connection persistence. HttpClient fully supports connection persistence. + + == HTTP connection routing == + + HttpClient can establish connections to the target host either directly or via a complex route that involves multiple intermediate connections also referred to as hops. HttpClient differentiates connections of a route into plain, tunneled and layered. + + Plain routes are established by connecting to the target or the first proxy. Tunnelled routes are established by connecting to the first and tunnelling through all proxies to the target. Routes without a proxy cannot be tunnelled. Layered routes are established by layering a protocol over an existing connection. Protocols can only be layered over a tunnel to the target, or or over a direct connection without proxies. + + === Route computation === + + RouteInfo interface represents information about a definitive route to a target host involving one or more intermediate steps or hops. HttpRoute is a concrete implementation of RouteInfo, which cannot be changed (is immutable). HttpTracker is a mutable RouteInfo implementation used internally by HttpClient to track the remaining hops to the ultimate route target. HttpTracker can be updated after a successful execution of the next hop towards to route target. HttpRouteDirector is a helper class that can be used to compute the next step in a route. This class is used internally by HttpClient. + + HttpRoutePlanner is an interface representing a strategy to compute a complete route to a given target based on the execution context. HttpClient ships with two default HttpRoutePlanner implementation. ProxySelectorRoutePlanner is based on java.net.ProxySelector. By default, it will pick up the proxy settings of the JVM, either from system properties or from the browser running the application. DefaultHttpRoutePlanner implementation does not make use of any Java system properties, nor of system or browser proxy settings. It computes routes based exclusively on HTTP parameters described below. + + === HTTP route parameters === + + These are parameters that can influence route computation: + + * '''http.route.default-proxy''': defines a proxy host to be used by default route planners that do not make use of JRE settings. This parameter expects a value of type HttpHost. If this parameter is not set direct connections to the target will be attempted. + + * '''http.route.local-address''': defines a local address to be used by all default route planner. On machines with multiple network interfaces, this parameter can be used to select the network interface from which the connection originates. This parameter expects a value of type java.net.InetAddress. If this parameter is not set a default local address will be used automatically. + + * '''http.route.forced-route''': defines an forced route to be used by all default route planner. Instead of computing a route, the given forced route will be returned, even if it points to a completely different target host. This parameter expects a value of type HttpRoute. + + === Proxy chaining === + + HttpClient is aware of the fact that there can be multiple intermediate proxies involved in establishing an end to end connection to the target host. This kind of technique is referred to as proxy chaining. + + === Secure HTTP connections === + + HTTP connections can be considered secure if information transmitted between two connection endpoints cannot be read or tampered with by unauthorized third party. The SSL/TLS protocol is the most widely used technique to ensure HTTP transport security. However, other encryption techniques could be employed as well. Usually, HTTP transport is layered over the SSL/TLS encrypted connection. == Managed connections == --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
