diff --git a/src/docbkx/advanced.xml b/src/docbkx/advanced.xml index 32081105d..85378d967 100644 --- a/src/docbkx/advanced.xml +++ b/src/docbkx/advanced.xml @@ -42,80 +42,38 @@ class MyLineParser extends BasicLineParser { @Override public Header parseHeader( - final CharArrayBuffer buffer) throws ParseException { + CharArrayBuffer buffer) throws ParseException { try { return super.parseHeader(buffer); } catch (ParseException ex) { // Suppress ParseException exception - return new BasicHeader("invalid", buffer.toString()); + return new BasicHeader(buffer.toString(), null); } } - + } ]]> - Provide a custom OperatedClientConnection - implementation. Replace default request / response parsers, request / response - formatters with custom ones as required. Implement different message writing / - reading code if necessary. + Provide a custom HttpConnectionFactory + implementation. Replace default request writer and / or response parser + with custom ones as required. connFactory = + new ManagedHttpClientConnectionFactory( + new DefaultHttpRequestWriterFactory(), + new DefaultHttpResponseParserFactory( + new MyLineParser(), new DefaultHttpResponseFactory())); ]]> - Provide a custom ClientConnectionOperator - interface implementation in order to create connections of new class. Implement - different socket initialization code if necessary. + Configure HttpClient to use the custom connection factory. - - - Provide a custom ClientConnectionManager - interface implementation in order to create connection operator of new - class. - @@ -145,73 +103,62 @@ class MyClientConnManager extends SingleClientConnManager { connection based authentication schemes such as NTLM or that of the SSL session with client authentication turned on. If both are unavailable, null token will be returned. + Users can provide a custom implementation if the default one does not satisfy their needs:
- User token and execution context - In the course of HTTP request execution HttpClient adds the following user - identity related objects to the execution context: - - - - <constant>ClientContext.USER_TOKEN</constant>='http.user-token': - Object instance representing the actual user identity, usually - expected to be an instance of Principle - interface - - - - One can find out whether or not the connection used to execute the request was - stateful by examining the content of the local HTTP context after the request has - been executed. + Persistent stateful connections + Please note that a persistent connection that carries a state object can be reused + only if the same state object is bound to the execution context when requests + are executed. So, it is really important to ensure the either same context is + reused for execution of subsequent HTTP requests by the same user or the user + token is bound to the context prior to request execution. -
- Persistent stateful connections - Please note that a persistent connection that carries a state object can be reused - only if the same state object is bound to the execution context when requests - are executed. So, it is really important to ensure the either same context is - reused for execution of subsequent HTTP requests by the same user or the user - token is bound to the context prior to request execution. - -
- - diff --git a/src/docbkx/authentication.xml b/src/docbkx/authentication.xml index 29e8f2351..37a746116 100644 --- a/src/docbkx/authentication.xml +++ b/src/docbkx/authentication.xml @@ -132,100 +132,6 @@ pwd -
- HTTP authentication parameters - These are parameters that be used to customize the HTTP authentication process and - behaviour of individual authentication schemes: - - - - <constant>ClientPNames.HANDLE_AUTHENTICATION</constant>='http.protocol.handle-authentication': - defines whether authentication should be handled automatically. This - parameter expects a value of type java.lang.Boolean. - If this parameter is not set, HttpClient will handle authentication - automatically. - - - - - <constant>AuthPNames.CREDENTIAL_CHARSET</constant>='http.auth.credential-charset': - defines the charset to be used when encoding user credentials. This - parameter expects a value of type java.lang.String. If - this parameter is not set, US-ASCII will be used. - - - - - <constant>AuthPNames.TARGET_AUTH_PREF</constant>='http.auth.target-scheme-pref': - Defines the order of preference for supported - AuthSchemes when authenticating with the - target host. This parameter expects a value of type - java.util.Collection. The collection is expected - to contain java.lang.String instances representing - an id of an authentication scheme. - - - - - <constant>AuthPNames.PROXY_AUTH_PREF</constant>='http.auth.proxy-scheme-pref': - Defines the order of preference for supported - AuthSchemes when authenticating with the - proxy host. This parameter expects a value of type - java.util.Collection. The collection is expected - to contain java.lang.String instances representing - an id of an authentication scheme. - - - - For example, one can force HttpClient to use a different order of preference for - authentication schemes - authpref = new ArrayList(); -authpref.add(AuthPolicy.BASIC); -authpref.add(AuthPolicy.DIGEST); -httpclient.getParams().setParameter(AuthPNames.PROXY_AUTH_PREF, authpref); -]]> -
-
- Authentication scheme registry - HttpClient maintains a registry of available authentication schemes using - the AuthSchemeRegistry class. The following schemes are - registered per default: - - - - AuthPolicy.BASIC: - Basic authentication - - - - - AuthPolicy.DIGEST: - Digest authentication - - - - - AuthPolicy.NTLM: - NTLMv1, NTLMv2, and NTLM2 Session authentication - - - - - AuthPolicy.SPNEGO: - SPNEGO authentication - - - - - AuthPolicy.KERBEROS: - Kerberos authentication - - - -
Credentials provider Credentials providers are intended to maintain a set of user credentials and to be @@ -289,23 +195,20 @@ null - <constant>ClientContext.AUTHSCHEME_REGISTRY</constant>='http.authscheme-registry': - AuthSchemeRegistry instance representing the actual + Lookup instance representing the actual authentication scheme registry. The value of this attribute set in the local context takes precedence over the default one. - <constant>ClientContext.CREDS_PROVIDER</constant>='http.auth.credentials-provider': - CookieSpec instance representing the actual - credentials provider. The value of this attribute set in the local context - takes precedence over the default one. + CredentialsProvider instance representing + the actual credentials provider. The value of this attribute set in the + local context takes precedence over the default one. - <constant>ClientContext.TARGET_AUTH_STATE</constant>='http.auth.target-scope': AuthState instance representing the actual target authentication state. The value of this attribute set in the local context takes precedence over the default one. @@ -313,7 +216,6 @@ null - <constant>ClientContext.PROXY_AUTH_STATE</constant>='http.auth.proxy-scope': AuthState instance representing the actual proxy authentication state. The value of this attribute set in the local context takes precedence over the default one. @@ -321,7 +223,6 @@ null - <constant>ClientContext.AUTH_CACHE</constant>='http.auth.auth-cache': AuthCache instance representing the actual authentication data cache. The value of this attribute set in the local context takes precedence over the default one. @@ -332,18 +233,25 @@ null the HTTP authentication context prior to request execution, or to examine its state after the request has been executed: -AuthState proxyAuthState = (AuthState) localContext.getAttribute( - ClientContext.PROXY_AUTH_STATE); +CredentialsProvider credsProvider = <...> +Lookup authRegistry = <...> +AuthCache authCache = <...> + +HttpClientContext context = HttpClientContext.create(); +context.setCredentialsProvider(credsProvider); +context.setAuthSchemeRegistry(authRegistry); +context.setAuthCache(authCache); +HttpGet httpget = new HttpGet("http://somehost/"); +CloseableHttpResponse response1 = httpclient.execute(httpget, context); +<...> + +AuthState proxyAuthState = context.getProxyAuthState(); System.out.println("Proxy auth state: " + proxyAuthState.getState()); System.out.println("Proxy auth scheme: " + proxyAuthState.getAuthScheme()); System.out.println("Proxy auth credentials: " + proxyAuthState.getCredentials()); -AuthState targetAuthState = (AuthState) localContext.getAttribute( - ClientContext.TARGET_AUTH_STATE); +AuthState targetAuthState = context.getTargetAuthState(); System.out.println("Target auth state: " + targetAuthState.getState()); System.out.println("Target auth scheme: " + targetAuthState.getAuthScheme()); System.out.println("Target auth credentials: " + targetAuthState.getCredentials()); @@ -368,12 +276,12 @@ System.out.println("Target auth credentials: " + targetAuthState.getCredentials( Nonethess one can configure HttpClient to authenticate preemptively by prepopulating the authentication data cache. -DefaultHttpClient httpclient = new DefaultHttpClient(); - -httpclient.getCredentialsProvider().setCredentials( - new AuthScope(targetHost.getHostName(), targetHost.getPort()), +HttpHost targetHost = new HttpHost("localhost", 80, "http"); +CredentialsProvider credsProvider = new BasicCredentialsProvider(); +credsProvider.setCredentials( + new AuthScope(targetHost.getHostName(), targetHost.getPort()), new UsernamePasswordCredentials("username", "password")); // Create AuthCache instance @@ -383,14 +291,19 @@ BasicScheme basicAuth = new BasicScheme(); authCache.put(targetHost, basicAuth); // Add AuthCache to the execution context -BasicHttpContext localcontext = new BasicHttpContext(); -localcontext.setAttribute(ClientContext.AUTH_CACHE, authCache); +HttpClientContext context = HttpClientContext.create(); +context.setCredentialsProvider(credsProvider); HttpGet httpget = new HttpGet("/"); for (int i = 0; i < 3; i++) { - HttpResponse response = httpclient.execute(targetHost, httpget, localcontext); - HttpEntity entity = response.getEntity(); - EntityUtils.consume(entity); + CloseableHttpResponse response = httpclient.execute( + targetHost, httpget, context); + try { + HttpEntity entity = response.getEntity(); + + } finally { + response.close(); + } } ]]>
@@ -428,28 +341,36 @@ for (int i = 0; i < 3; i++) { connection to execute more expensive methods, especially those enclose a request entity, such as POST or PUT. -NTCredentials creds = new NTCredentials("user", "pwd", "myworkstation", "microsoft.com"); -httpclient.getCredentialsProvider().setCredentials(AuthScope.ANY, creds); +CredentialsProvider credsProvider = new BasicCredentialsProvider(); +credsProvider.setCredentials(AuthScope.ANY, + new NTCredentials("user", "pwd", "myworkstation", "microsoft.com")); HttpHost target = new HttpHost("www.microsoft.com", 80, "http"); // Make sure the same context is used to execute logically related requests -HttpContext localContext = new BasicHttpContext(); +HttpClientContext context = HttpClientContext.create(); +context.setCredentialsProvider(credsProvider); // Execute a cheap method first. This will trigger NTLM authentication HttpGet httpget = new HttpGet("/ntlm-protected/info"); -HttpResponse response1 = httpclient.execute(target, httpget, localContext); -HttpEntity entity1 = response1.getEntity(); -EntityUtils.consume(entity1); +CloseableHttpResponse response1 = httpclient.execute(target, httpget, context); +try { + HttpEntity entity1 = response1.getEntity(); +} finally { + response1.close(); +} // Execute an expensive method next reusing the same context (and connection) HttpPost httppost = new HttpPost("/ntlm-protected/form"); httppost.setEntity(new StringEntity("lots and lots of data")); -HttpResponse response2 = httpclient.execute(target, httppost, localContext); -HttpEntity entity2 = response2.getEntity(); -EntityUtils.consume(entity2); +CloseableHttpResponse response2 = httpclient.execute(target, httppost, context); +try { + HttpEntity entity2 = response2.getEntity(); +} finally { + response2.close(); +} ]]> diff --git a/src/docbkx/caching.xml b/src/docbkx/caching.xml index 7b6871540..6cd06c610 100644 --- a/src/docbkx/caching.xml +++ b/src/docbkx/caching.xml @@ -29,29 +29,30 @@ HttpClient Cache provides an HTTP/1.1-compliant caching layer to be used with HttpClient--the Java equivalent of a browser cache. The - implementation follows the Decorator design pattern, where the - CachingHttpClient class is a drop-in replacement for - a DefaultHttpClient; requests that can be satisfied entirely from the cache - will not result in actual origin requests. Stale cache entries are - automatically validated with the origin where possible, using conditional GETs - and the If-Modified-Since and/or If-None-Match request headers. + implementation follows the Chain of Responsibility design pattern, where the + caching HttpClient implementation can serve a drop-in replacement for + the default non-caching HttpClient implementation; requests that can be + satisfied entirely from the cache will not result in actual origin requests. + Stale cache entries are automatically validated with the origin where possible, + using conditional GETs and the If-Modified-Since and/or If-None-Match request + headers. HTTP/1.1 caching in general is designed to be semantically transparent; that is, a cache should not change the meaning of the request-response exchange between client and server. As such, it should - be safe to drop a CachingHttpClient into an existing compliant client-server + be safe to drop a caching HttpClient into an existing compliant client-server relationship. Although the caching module is part of the client from an HTTP protocol point of view, the implementation aims to be compatible with the requirements placed on a transparent caching proxy. - Finally, CachingHttpClient includes support the Cache-Control + Finally, caching HttpClient includes support the Cache-Control extensions specified by RFC 5861 (stale-if-error and stale-while-revalidate). - When CachingHttpClient executes a request, it goes through the + When caching HttpClient executes a request, it goes through the following flow: @@ -90,7 +91,7 @@ - When CachingHttpClient receives a response, it goes through the + When caching HttpClient receives a response, it goes through the following flow: @@ -114,10 +115,10 @@ - It is important to note that CachingHttpClient is not, itself, an - implementation of HttpClient, but that it decorates an instance of an - HttpClient implementation. If you do not provide an implementation, it - will use DefaultHttpClient internally by default. + It is important to note that caching HttpClient is not, itself, + a different implementation of HttpClient, but that it works by inserting + itself as an additonal processing component to the request execution + pipeline.
@@ -135,41 +136,50 @@
Example Usage - This is a simple example of how to set up a basic CachingHttpClient. + This is a simple example of how to set up a basic caching HttpClient. As configured, it will store a maximum of 1000 cached objects, each of which may have a maximum body size of 8192 bytes. The numbers selected here are for example only and not intended to be prescriptive or considered as recommendations. @@ -178,11 +188,11 @@ case VALIDATED:
Configuration - As the CachingHttpClient is a decorator, much of the configuration you may - want to do can be done on the HttpClient used as the "backend" by the HttpClient - (this includes setting options like timeouts and connection pool sizes). For - caching-specific configuration, you can provide a CacheConfig instance to - customize behavior across the following areas: + The caching HttpClient inherits all configuration options and parameters + of the default non-caching implementation (this includes setting options like + timeouts and connection pool sizes). For caching-specific configuration, you can + provide a CacheConfig instance to customize behavior + across the following areas: Cache size. If the backend storage supports these limits, you can specify the maximum number of cache entries as well as the maximum cacheable @@ -217,7 +227,7 @@ case VALIDATED:
Storage Backends - The default implementation of CachingHttpClient stores cache entries and + The default implementation of caching HttpClient stores cache entries and cached response bodies in memory in the JVM of your application. While this offers high performance, it may not be appropriate for your application due to the limitation on size or because the cache entries are ephemeral and don't @@ -227,18 +237,17 @@ case VALIDATED: If none of those options are suitable for your application, it is possible to provide your own storage backend by implementing the HttpCacheStorage - interface and then supplying that to CachingHttpClient at construction time. In + interface and then supplying that to caching HttpClient at construction time. In this case, the cache entries will be stored using your scheme but you will get to reuse all of the logic surrounding HTTP/1.1 compliance and cache handling. Generally speaking, it should be possible to create an HttpCacheStorage implementation out of anything that supports a key/value store (similar to the Java Map interface) with the ability to apply atomic updates. - Finally, because the CachingHttpClient is a decorator for HttpClient, - it's entirely possible to set up a multi-tier caching hierarchy; for example, - wrapping an in-memory CachingHttpClient around one that stores cache entries on - disk or remotely in memcached, following a pattern similar to virtual memory, - L1/L2 processor caches, etc. + Finally, with some extra efforts it's entirely possible to set up + a multi-tier caching hierarchy; for example, wrapping an in-memory caching + HttpClient around one that stores cache entries on disk or remotely in memcached, + following a pattern similar to virtual memory, L1/L2 processor caches, etc.
diff --git a/src/docbkx/connmgmt.xml b/src/docbkx/connmgmt.xml index 794020124..6e84c57c8 100644 --- a/src/docbkx/connmgmt.xml +++ b/src/docbkx/connmgmt.xml @@ -415,12 +415,12 @@ sf.connectSocket(timeout, socket, target, remoteAddress, null, clientContext); LayeredConnectionSocketFactory sslsf = <...> -Registry reg = RegistryBuilder.create() +Registry r = RegistryBuilder.create() .register("http", plainsf) .register("https", sslsf) .build(); -HttpClientConnectionManager cm = new PoolingHttpClientConnectionManager(reg); +HttpClientConnectionManager cm = new PoolingHttpClientConnectionManager(r); HttpClients.custom() .setConnectionManager(cm) .build(); diff --git a/src/docbkx/fluent.xml b/src/docbkx/fluent.xml index 1fb38ceea..eb66d5c44 100644 --- a/src/docbkx/fluent.xml +++ b/src/docbkx/fluent.xml @@ -108,7 +108,8 @@ Document result = Request.Get("http://somehost/content") DocumentBuilder docBuilder = dbfac.newDocumentBuilder(); ContentType contentType = ContentType.getOrDefault(entity); if (!contentType.equals(ContentType.APPLICATION_XML)) { - throw new ClientProtocolException("Unexpected content type:" + contentType); + throw new ClientProtocolException("Unexpected content type:" + + contentType); } String charset = contentType.getCharset(); if (charset == null) { @@ -123,45 +124,6 @@ Document result = Request.Get("http://somehost/content") } }); -]]> - -
-
- Asynchronous execution - The fluent facade API can be used to execute multiple requests asynchronously using - background threads. - - > queue = new LinkedList>(); -for (final Request request: requests) { - Future future = async.execute(request, new FutureCallback() { - - public void failed(final Exception ex) { - System.out.println(ex.getMessage() + ": " + request); - } - - public void completed(final Content content) { - System.out.println("Request completed: " + request); - } - - public void cancelled() { - } - - }); - queue.add(future); -} - -// Process the queue ]]>
diff --git a/src/docbkx/fundamentals.xml b/src/docbkx/fundamentals.xml index d5df169e6..b9f6673e6 100644 --- a/src/docbkx/fundamentals.xml +++ b/src/docbkx/fundamentals.xml @@ -38,7 +38,7 @@ CloseableHttpClient httpclient = HttpClients.createDefault(); HttpGet httpget = new HttpGet("http://localhost/"); CloseableHttpResponse response = httpclient.execute(httpget); try { - + <...> } finally { response.close(); } @@ -283,7 +283,8 @@ important message In order to ensure proper release of system resources one must close either the content stream associated with the entity or the response itself +CloseableHttpClient httpclient = HttpClients.createDefault(); +HttpGet httpget = new HttpGet("http://localhost/"); CloseableHttpResponse response = httpclient.execute(httpget); try { HttpEntity entity = response.getEntity(); @@ -318,7 +319,8 @@ try { remaining content and making the connection reusable is too high, in which case one can terminate the content stream by closing the response. +CloseableHttpClient httpclient = HttpClients.createDefault(); +HttpGet httpget = new HttpGet("http://localhost/"); CloseableHttpResponse response = httpclient.execute(httpget); try { HttpEntity entity = response.getEntity(); @@ -348,7 +350,8 @@ try { strongly discouraged unless the response entities originate from a trusted HTTP server and are known to be of limited length. +CloseableHttpClient httpclient = HttpClients.createDefault(); +HttpGet httpget = new HttpGet("http://localhost/"); CloseableHttpResponse response = httpclient.execute(httpget); try { HttpEntity entity = response.getEntity(); @@ -452,8 +455,8 @@ httppost.setEntity(entity); take care of ensuring release of the connection back to the connection manager regardless whether the request execution succeeds or causes an exception. -HttpRequest request = <...> +CloseableHttpClient httpclient = HttpClients.createDefault(); +HttpGet httpget = new HttpGet("http://localhost/json"); ResponseHandler rh = new ResponseHandler() { @@ -477,7 +480,64 @@ ResponseHandler rh = new ResponseHandler() { return gson.fromJson(reader, MyJsonObject.class); } }; -MyJsonObject myjson = client.execute(request, rh); +MyJsonObject myjson = client.execute(httpget, rh); +]]> +
+
+
+ HttpClient interface + HttpClient interface represents the most essential + contract for HTTP request execution. It imposes no restrictions or particular details on + the request execution process and leaves the specifics of connection management, state + management, authentication and redirect handling up to individual implementations. This + should make it easier to decorate the interface with additional functionality such as + response content caching. + Generally HttpClient implementations act as a facade + to a number of special purpose handler or strategy interface implementations + responsible for handling of a particular aspect of the HTTP protocol such as redirect + or authentication handling or making decision about connection persistence and keep + alive duration. This enables the users to selectively replace default implementation + of those aspects with custom, application specific ones. + +
+ HttpClient thread safety + HttpClient implementations are expected to be + thread safe. It is recommended that the same instance of this class is reused for + multiple request executions. +
+
+ HttpClient resource deallocation + When an instance CloseableHttpClient is no longer needed + and is about to go out of scope the connection manager associated with it must + be shut down by calling the CloseableHttpClient#close() + method. + +} finally { + httpclient.close(); +} ]]>
@@ -497,6 +557,64 @@ MyJsonObject myjson = client.execute(request, rh); HttpContext can contain arbitrary objects and therefore may be unsafe to share between multiple threads. It is recommended that each thread of execution maintains its own context. + In the course of HTTP request execution HttpClient adds the following attributes to + the execution context: + + + + HttpConnection instance representing the + actual connection to the target server. + + + + + HttpHost instance representing the connection + target. + + + + + HttpRoute instance representing the complete + connection route + + + + + HttpRequest instance representing the + actual HTTP request. The final HttpRequest object in the execution context + always represents the state of the message exactly + as it was sent to the target server. Per default HTTP/1.0 and HTTP/1.1 + use relative request URIs. However if the request is sent via a proxy + in a non-tunneling mode then the URI will be absolute. + + + + + HttpResponse instance representing the + actual HTTP response. + + + + + java.lang.Boolean object representing the flag + indicating whether the actual request has been fully transmitted to the + connection target. + + + + + RequestConfig object representing the actual + request configuation. + + + + + URICollection object representing a collection + of all redirect locations received in the process of request + execution. + + + One can use HttpClientContext adaptor class to simplify interractions with the context state. Multiple request sequences that represent a logically related session should be executed with the same HttpContext instance to ensure @@ -514,8 +633,7 @@ HttpResponse response = clientContext.getResponse(); kept in the execution context and get propagatd to the consecutive requests sharing the same context. - +CloseableHttpClient httpclient = HttpClients.createDefault(); RequestConfig requestConfig = RequestConfig.custom() .setSocketTimeout(1000) .setConnectTimeout(1000) @@ -718,6 +836,46 @@ for (int i = 0; i < 10; i++) { response.close(); } } +]]> + +
+ Redirect handling + HttpClient handles all types of redirects automatically, except those explicitly + prohibited by the HTTP specification as requiring user intervention. See + Other (status code 303) redirects on POST and + PUT requests are converted to GET requests as + required by the HTTP specification. One can use a custom redirect strategy to relaxe + restrictions on automatic redirection of POST methods imposed by the HTTP + specification. + + HttpClient often has to rewrite the request message in the process of its execution. + Per default HTTP/1.0 and HTTP/1.1 generally use relative request URIs. Likewise, + original request may get redirected from location to another multiple times. The final + interpreted absolute HTTP location can be built using the original request and + the context. The utility method URIUtils#resolve can be used + to build the interpreted absolute URI used to generate the final request. This method + includes the last fragment identifier from the redirect requests or the original + request. +
diff --git a/src/docbkx/httpagent.xml b/src/docbkx/httpagent.xml deleted file mode 100644 index fd647c6e0..000000000 --- a/src/docbkx/httpagent.xml +++ /dev/null @@ -1,267 +0,0 @@ - - - - - HTTP client service -
- HttpClient facade - HttpClient interface represents the most essential - contract for HTTP request execution. It imposes no restrictions or particular details on - the request execution process and leaves the specifics of connection management, state - management, authentication and redirect handling up to individual implementations. This - should make it easier to decorate the interface with additional functionality such as - response content caching. - DefaultHttpClient is the default implementation of the - HttpClient interface. This class acts as a facade to - a number of special purpose handler or strategy interface implementations responsible - for handling of a particular aspect of the HTTP protocol such as redirect or - authentication handling or making decision about connection persistence and keep alive - duration. This enables the users to selectively replace default implementation of those - aspects with custom, application specific ones. - - DefaultHttpClient also maintains a list of protocol - interceptors intended for processing outgoing requests and incoming responses and - provides methods for managing those interceptors. New protocol interceptors can be - introduced to the protocol processor chain or removed from it if needed. Internally - protocol interceptors are stored in a simple java.util.ArrayList. - They are executed in the same natural order as they are added to the list. - - DefaultHttpClient is thread safe. It is recommended that the - same instance of this class is reused for multiple request executions. When an instance - of DefaultHttpClient is no longer needed and is about to go out - of scope the connection manager associated with it must be shut down by calling the - ClientConnectionManager#shutdown() method. - -
-
- HttpClient parameters - These are parameters that be used to customize the behaviour of the default HttpClient - implementation: - - - - <constant>ClientPNames.HANDLE_REDIRECTS</constant>='http.protocol.handle-redirects': - defines whether redirects should be handled automatically. This parameter - expects a value of type java.lang.Boolean. If this - parameter is not set HttpClient will handle redirects automatically. - - - - - <constant>ClientPNames.REJECT_RELATIVE_REDIRECT</constant>='http.protocol.reject-relative-redirect': - defines whether relative redirects should be rejected. HTTP specification - requires the location value be an absolute URI. This parameter expects a - value of type java.lang.Boolean. If this parameter is - not set relative redirects will be allowed. - - - - - <constant>ClientPNames.MAX_REDIRECTS</constant>='http.protocol.max-redirects': - defines the maximum number of redirects to be followed. The limit on - number of redirects is intended to prevent infinite loops caused by broken - server side scripts. This parameter expects a value of type - java.lang.Integer. If this parameter is not set - no more than 100 redirects will be allowed. - - - - - <constant>ClientPNames.ALLOW_CIRCULAR_REDIRECTS</constant>='http.protocol.allow-circular-redirects': - defines whether circular redirects (redirects to the same location) should - be allowed. The HTTP spec is not sufficiently clear whether circular - redirects are permitted, therefore optionally they can be enabled. This - parameter expects a value of type java.lang.Boolean. - If this parameter is not set circular redirects will be disallowed. - - - - - <constant>ClientPNames.CONNECTION_MANAGER_FACTORY_CLASS_NAME</constant>='http.connection-manager.factory-class-name': - defines the class name of the default - ClientConnectionManager implementation. - This parameter expects a value of type - java.lang.String. If this parameter is not set - SingleClientConnManager will be used per - default. - - - - - <constant>ClientPNames.VIRTUAL_HOST</constant>='http.virtual-host': - defines the virtual host settings to be used in the Host - header instead of the physical host. This parameter expects a value of - type HttpHost. The HttpHost port does not have to - be specified as it will be derived from the target. - If this parameter is not set, the name or - IP address (and port if required) of the target host will be used. - - - - - <constant>ClientPNames.DEFAULT_HEADERS</constant>='http.default-headers': - defines the request headers to be sent per default with each request. This - parameter expects a value of type - java.util.Collection containing - Header objects. - - - - - <constant>ClientPNames.DEFAULT_HOST</constant>='http.default-host': - defines the default host. The default value will be used if the target - host is not explicitly specified in the request URI (relative URIs). This - parameter expects a value of type HttpHost. - - - -
-
- Automatic redirect handling - HttpClient handles all types of redirects automatically, except those explicitly - prohibited by the HTTP specification as requiring user intervention. See - Other (status code 303) redirects on POST and - PUT requests are converted to GET requests as - required by the HTTP specification. -
-
- HTTP client and execution context - The DefaultHttpClient treats HTTP requests as immutable objects - that are never supposed to change in the course of request execution. Instead, it - creates a private mutable copy of the original request object, whose properties can be - updated depending on the execution context. Therefore the final request properties such - as the target host and request URI can be determined by examining the content of the - local HTTP context after the request has been executed. - The final HttpRequest object in the execution context always represents - the state of the message _exactly_ as it was sent to the target server. - Per default HTTP/1.0 and HTTP/1.1 use relative request URIs. However if the request - is sent via a proxy in a non-tunneling mode then the URI will be absolute. - - The final interpreted absolute HTTP location can be built using the original request - and the context. The utility method URIUtils.resolve(URI,HttpHost,URICollection) - can be used to build the interpreted absolute URI used to generate the final request. - This method includes the last fragment identifier from the redirect requests or - the original request. - -
-
- Compressed response content - - The ContentEncodingHttpClient is a simple sub-class of - DefaultHttpClient which adds support indicating to servers that it will - support gzip and deflate compressed responses. It does - this via the existing published APIs of HTTP Protocol - Interceptors . Depending on the type of response (text will compress well versus - images, which are typically already well-compressed), this can speed up responses due to the - smaller amount of network traffic involved, along with saving bandwidth, which can be - important in mobile environments. The RequestAcceptEncoding - and ResponseContentEncoding interceptors used as also part of the - published API and can be used by other DefaultHttpClient - implementations. These provide transparent handling of gzip and - deflate encoding, so it will not be apparent to clients that this - processing has happened. - - - - One can also add the RequestAcceptEncoding and - ResponseContentEncoding interceptors to an instance of the - DefaultHttpClient, if desired. - - -
- diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml index 677f7bc4f..565db83af 100644 --- a/src/docbkx/index.xml +++ b/src/docbkx/index.xml @@ -32,10 +32,14 @@ Oleg Kalnichevski + + Jonathan + Moore + - + Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information @@ -43,18 +47,18 @@ to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - - + + - - + + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + @@ -65,7 +69,6 @@ - diff --git a/src/docbkx/statemgmt.xml b/src/docbkx/statemgmt.xml index 9e63fb423..b4da49600 100644 --- a/src/docbkx/statemgmt.xml +++ b/src/docbkx/statemgmt.xml @@ -205,9 +205,11 @@ CookieSpecProvider easySpecProvider = new CookieSpecProvider() { } }; -Registry cookieSpecReg = RegistryBuilder.create() - .register(CookieSpecs.BEST_MATCH, new BestMatchSpecFactory()) - .register(CookieSpecs.BROWSER_COMPATIBILITY, new BrowserCompatSpecFactory()) +Registry r = RegistryBuilder.create() + .register(CookieSpecs.BEST_MATCH, + new BestMatchSpecFactory()) + .register(CookieSpecs.BROWSER_COMPATIBILITY, + new BrowserCompatSpecFactory()) .register("easy", easySpecProvider) .build(); @@ -216,7 +218,7 @@ RequestConfig requestConfig = RequestConfig.custom() .build(); CloseableHttpClient httpclient = HttpClients.custom() - .setDefaultCookieSpecRegistry(cookieSpecReg) + .setDefaultCookieSpecRegistry(r) .setDefaultRequestConfig(requestConfig) .build(); ]]> @@ -253,7 +255,7 @@ CloseableHttpClient httpclient = HttpClients.custom() - CookieSpecRegistry instance representing the actual + Lookup instance representing the actual cookie specification registry. The value of this attribute set in the local context takes precedence over the default one. @@ -287,13 +289,13 @@ CloseableHttpClient httpclient = HttpClients.custom() -Registry cookieSpecReg = <...> +Lookup cookieSpecReg = <...> CookieStore cookieStore = <...> HttpClientContext context = HttpClientContext.create(); context.setCookieSpecRegistry(cookieSpecReg); context.setCookieStore(cookieStore); -HttpGet httpget = new HttpGet("http://localhost/1"); +HttpGet httpget = new HttpGet("http://somehost/"); CloseableHttpResponse response1 = httpclient.execute(httpget, context); <...> // Cookie origin details