You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2021/02/22 16:03:37 UTC
[httpcomponents-website] 03/04: Migrated remaining module content
to Markdown
This is an automated email from the ASF dual-hosted git repository.
olegk pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/httpcomponents-website.git
commit cfa79562c9ac5fc102cce0015796c5a11a83563f
Author: Oleg Kalnichevski <ol...@apache.org>
AuthorDate: Mon Feb 22 17:03:01 2021 +0100
Migrated remaining module content to Markdown
---
.../apt/httpcomponents-client-4.5.x/android.apt | 75 ---
.../apt/httpcomponents-client-4.5.x/logging.apt | 284 ----------
src/site/apt/httpcomponents-client-4.5.x/ntlm.apt | 162 ------
.../apt/httpcomponents-client-4.5.x/primer.apt | 631 ---------------------
.../apt/httpcomponents-client-5.0.x/android.apt | 39 --
.../apt/httpcomponents-client-5.0.x/logging.apt | 200 -------
.../related-projects.apt | 54 --
.../apt/httpcomponents-client-5.1.x/android.apt | 39 --
.../apt/httpcomponents-client-5.1.x/logging.apt | 200 -------
.../related-projects.apt | 54 --
.../httpcomponents-core-5.0.x/related-projects.apt | 43 --
.../httpcomponents-core-5.1.x/related-projects.apt | 43 --
.../markdown/httpcomponents-client-4.x/android.md | 64 +++
.../markdown/httpcomponents-client-4.x/logging.md | 259 +++++++++
.../markdown/httpcomponents-client-4.x/ntlm.md | 145 +++++
.../markdown/httpcomponents-client-4.x/primer.md | 487 ++++++++++++++++
.../markdown/httpcomponents-client-5.x/android.md | 26 +
.../markdown/httpcomponents-client-5.x/logging.md | 178 ++++++
.../httpcomponents-client-5.x/related-projects.md | 43 ++
.../httpcomponents-core-5.x/related-projects.md | 33 ++
.../documentation.links | 5 +
.../documentation.links | 4 +
.../documentation.links | 4 +
.../httpcomponents-core-5.0.x/documentation.links | 2 +
.../httpcomponents-core-5.1.x/documentation.links | 2 +
25 files changed, 1252 insertions(+), 1824 deletions(-)
diff --git a/src/site/apt/httpcomponents-client-4.5.x/android.apt b/src/site/apt/httpcomponents-client-4.5.x/android.apt
deleted file mode 100644
index 47c1d27..0000000
--- a/src/site/apt/httpcomponents-client-4.5.x/android.apt
+++ /dev/null
@@ -1,75 +0,0 @@
-~~ ====================================================================
-~~ 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
-~~ regarding copyright ownership. The ASF licenses this file
-~~ 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
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ 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.
-~~ ====================================================================
-~~
-~~ This software consists of voluntary contributions made by many
-~~ individuals on behalf of the Apache Software Foundation. For more
-~~ information on the Apache Software Foundation, please see
-~~ <http://www.apache.org/>.
-
- ----------
- HttpClient for Android
- ----------
- ----------
- ----------
-
-HttpClient for Android
-
- Google Android 1.0 was released with a pre-BETA snapshot of Apache HttpClient. To coincide with
- the first Android release Apache HttpClient 4.0 APIs had to be frozen prematurely, while many
- of interfaces and internal structures were still not fully worked out. As Apache HttpClient 4.0
- was maturing the project was expecting Google to incorporate the latest code improvements into
- their code tree. Unfortunately it did not happen. Version of Apache HttpClient shipped with
- Android has effectively become a fork.
-
- Eventually Google decided to discontinue further development of their fork while refusing to upgrade
- to the stock version of Apache HttpClient citing compatibility concerns as a reason for such decision.
- Google completely removed their fork of Apache HttpClient from Android in version 8.0 (API 26) only.
-
- Those users who want to continue using Apache HttpClient on Android are advised to
- consider
-
- * Apache HttpCLient 5.x stock version, which works well with Android API 19 and newer
-
-----
-dependencies {
- compile group: 'org.apache.httpcomponents.client5' , name: 'httpclient5' , version: '5.0-beta4'
-}
-----
-
- * Apache HttpClient packages for Android {{{https://github.com/smarek/httpclient-android/wiki/Project-Introduction}
- maintained by Marek Sebera}} when targeting Android API 23 and newer
-
-----
-dependencies {
- compile group: 'cz.msebera.android' , name: 'httpclient', version: '4.5.3'
-}
-----
-
- * {{{https://ok2c.github.io/httpclient-android-ext/}Android extensions}} for Apache HttpClient 4.5
- when targeting Android API 26 or newer.
-
- Android extensions for Apache HttpClient provide a replacement for the default <<<HostnameVerifier>>>
- implementation incompatible with Android and provide a builder for <<<PoolingHttpClientConnectionManager>>>
- instances optimized for Android called <<<AndroidHttpClientConnectionManagerBuilder>>>.
-
-----
-dependencies {
- api 'com.github.ok2c.hc4.android:httpclient-android:0.1.0'
-}
-----
diff --git a/src/site/apt/httpcomponents-client-4.5.x/logging.apt b/src/site/apt/httpcomponents-client-4.5.x/logging.apt
deleted file mode 100644
index bd6cdb8..0000000
--- a/src/site/apt/httpcomponents-client-4.5.x/logging.apt
+++ /dev/null
@@ -1,284 +0,0 @@
-~~ ====================================================================
-~~ 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
-~~ regarding copyright ownership. The ASF licenses this file
-~~ 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
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ 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.
-~~ ====================================================================
-~~
-~~ This software consists of voluntary contributions made by many
-~~ individuals on behalf of the Apache Software Foundation. For more
-~~ information on the Apache Software Foundation, please see
-~~ <http://www.apache.org/>.
-
- ----------
- HttpClient Logging Practices
- ----------
- ----------
- ----------
-
-Logging Practices
-
- Being a library HttpClient is not to dictate which logging framework the user has to use.
- Therefore HttpClient utilizes the logging interface provided by the
- {{{http://commons.apache.org/logging/}Commons Logging}} package. <<<Commons Logging>>> provides
- a simple and generalized
- {{{http://commons.apache.org/logging/commons-logging-1.0.4/docs/apidocs/}log interface}} to
- various logging packages. By using <<<Commons Logging>>>, HttpClient can be configured for a
- variety of different logging behaviours. That means the user will have to make a choice which
- logging framework to use. By default <<<Commons Logging>>> supports the following logging
- frameworks:
-
- * {{{http://logging.apache.org/log4j/docs/index.html}Log4J}}
-
- * {{{http://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html}
- java.util.logging}}
-
- * {{{http://commons.apache.org/logging/commons-logging-1.0.4/docs/apidocs/org/apache/commons/logging/impl/SimpleLog.html}
- SimpleLog}} (internal to <<<Commons Logging>>>)
-
- By implementing some simple interfaces <<<Commons Logging>>> can be extended to support
- basically any other custom logging framework. <<<Commons Logging>>> tries to automatically
- discover the logging framework to use. If it fails to select the expected one, you must
- configure <<<Commons Logging>>> by hand. Please refer to the <<<Commons Logging>>>
- documentation for more information.
-
- HttpClient performs three different kinds of logging: the standard context logging used within
- each class, HTTP header logging and full wire logging.
-
-* {Context Logging}
-
- Context logging contains information about the internal operation of HttpClient as it performs
- HTTP requests. Each class has its own log named according to the class's fully qualified name.
- For example the class <<<DefaultHttpClient>>> has a log named
- <<<org.apache.http.impl.client.DefaultHttpClient>>>. Since all classes follow this convention
- it is possible to configure context logging for all classes using the single log named
- <<<org.apache.http.impl.client>>>.
-
-* {Wire Logging}
-
- The wire log is used to log all data transmitted to and from servers when executing HTTP
- requests. The wire log uses the <<<org.apache.http.wire>>> logging category. This log should
- only be enabled to debug problems, as it will produce an extremely large amount of log data.
-
-* {HTTP header Logging}
-
- Because the content of HTTP requests is usually less important for debugging than the HTTP
- headers, the <<<org.apache.http.headers>>> logging category for capturing HTTP headers only.
-
-* {Configuration Examples}
-
- <<<Commons Logging>>> can delegate to a variety of loggers for processing the actual output.
- Below are configuration examples for <<<Commons Logging>>>, <<<Log4j>>> and
- <<<java.util.logging>>>.
-
-** {Commons Logging Examples}
-
- <<<Commons Logging>>> comes with a basic logger called <<<SimpleLog>>>. This logger writes all
- logged messages to <<<System.err>>>. The following examples show how to configure
- <<<Commons Logging>>> via system properties to use <<<SimpleLog>>>. It is strongly recommended
- to configure <<<Commons Logging>>> system properties through JVM process arguments at the
- start up.
-
- * Enable header wire + context logging - <<Best for Debugging>>
-
---------------------------------------
--Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
--Dorg.apache.commons.logging.simplelog.showdatetime=true
--Dorg.apache.commons.logging.simplelog.log.org.apache.http=DEBUG
--Dorg.apache.commons.logging.simplelog.log.org.apache.http.wire=ERROR
---------------------------------------
-
- * Enable full wire + context logging
-
---------------------------------------
--Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
--Dorg.apache.commons.logging.simplelog.showdatetime=true
--Dorg.apache.commons.logging.simplelog.log.org.apache.http=DEBUG
---------------------------------------
-
- * Enable context logging for connection management
-
---------------------------------------
--Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
--Dorg.apache.commons.logging.simplelog.showdatetime=true
--Dorg.apache.commons.logging.simplelog.log.org.apache.http.impl.conn=DEBUG
---------------------------------------
-
- * Enable context logging for connection management / request execution
-
---------------------------------------
--Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
--Dorg.apache.commons.logging.simplelog.showdatetime=true
--Dorg.apache.commons.logging.simplelog.log.org.apache.http.impl.conn=DEBUG
--Dorg.apache.commons.logging.simplelog.log.org.apache.http.impl.client=DEBUG
--Dorg.apache.commons.logging.simplelog.log.org.apache.http.client=DEBUG
---------------------------------------
-
-** {Log4j Examples}
-
- The simplest way to configure <<<Log4j>>> is via a <<<log4j.properties>>> file. <<<Log4j>>>
- will automatically read and configure itself using a file named <<<log4j.properties>>> when
- it's present at the root of the application classpath. Below are some <<<Log4j>>> configuration
- examples.
-
- <<Note:>> <<<Log4j>>> is not included in the <<<HttpClient>>> distribution.
-
- * Enable header wire + context logging - <<Best for Debugging>>
-
---------------------------------------
-log4j.rootLogger=INFO, stdout
-
-log4j.appender.stdout=org.apache.log4j.ConsoleAppender
-log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
-log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n
-
-log4j.logger.org.apache.http=DEBUG
-log4j.logger.org.apache.http.wire=ERROR
---------------------------------------
-
- * Enable full wire + context logging
-
---------------------------------------
-log4j.rootLogger=INFO, stdout
-
-log4j.appender.stdout=org.apache.log4j.ConsoleAppender
-log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
-log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n
-
-log4j.logger.org.apache.http=DEBUG
---------------------------------------
-
- * Enable context logging for connection management
-
---------------------------------------
-log4j.rootLogger=INFO, stdout
-
-log4j.appender.stdout=org.apache.log4j.ConsoleAppender
-log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
-log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n
-
-log4j.logger.org.apache.http.impl.conn=DEBUG
---------------------------------------
-
- * Enable context logging for connection management / request execution
-
---------------------------------------
-log4j.rootLogger=INFO, stdout
-
-log4j.appender.stdout=org.apache.log4j.ConsoleAppender
-log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
-log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n
-
-log4j.logger.org.apache.http.impl.conn=DEBUG
-log4j.logger.org.apache.http.impl.client=DEBUG
-log4j.logger.org.apache.http.client=DEBUG
---------------------------------------
-
- []
-
- Note that the default configuration for Log4J is very inefficient as it causes all the logging
- information to be generated but not actually sent anywhere. The <<<Log4J>>> manual is the
- best reference for how to configure <<<Log4J>>>. It is available at
- {{{http://logging.apache.org/log4j/docs/manual.html}
- http://logging.apache.org/log4j/docs/manual.html}}.
-
-** {java.util.logging Examples}
-
- Since JDK 1.4 there has been a package
- {{{http://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html}
- java.util.logging}} that provides a logging framework similar to <<<Log4J>>>. By default it
- reads a config file from <<<$JAVA_HOME/jre/lib/logging.properties>>> which looks like this
- (comments stripped):
-
---------------------------------------
-handlers=java.util.logging.ConsoleHandler
-.level=INFO
-java.util.logging.FileHandler.pattern = %h/java%u.log
-java.util.logging.FileHandler.limit = 50000
-java.util.logging.FileHandler.count = 1
-java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
-java.util.logging.ConsoleHandler.level = INFO
-java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
-com.xyz.foo.level = SEVERE
---------------------------------------
-
- To customize logging a custom <<<logging.properties>>> file should be created in the project
- directory. The location of this file must be passed to the JVM as asystem property. This can be
- done on the command line like so:
-
---------------------------------------
-$JAVA_HOME/java -Djava.util.logging.config.file=$HOME/myapp/logging.properties
--classpath $HOME/myapp/target/classes com.myapp.Main
---------------------------------------
-
- Alternatively {{{http://docs.oracle.com/javase/7/docs/api/java/util/logging/LogManager.html#readConfiguration(java.io.InputStream)"}
- LogManager#readConfiguration(InputStream)}} can be used to pass it the desired configuration.
-
- * Enable header wire + context logging - <<Best for Debugging>>
-
---------------------------------------
-.level = INFO
-
-handlers=java.util.logging.ConsoleHandler
-java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
-java.util.logging.ConsoleHandler.level = ALL
-
-org.apache.http.level = FINEST
-org.apache.http.wire.level = SEVERE
---------------------------------------
-
- * Enable full wire + context logging
-
---------------------------------------
-.level = INFO
-
-handlers=java.util.logging.ConsoleHandler
-java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
-java.util.logging.ConsoleHandler.level = ALL
-
-org.apache.http.level = FINEST
---------------------------------------
-
- * Enable context logging for connection management
-
---------------------------------------
-.level = INFO
-
-handlers=java.util.logging.ConsoleHandler
-java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
-java.util.logging.ConsoleHandler.level = ALL
-
-org.apache.http.impl.conn.level = FINEST
---------------------------------------
-
- * Enable context logging for connection management / request execution
-
---------------------------------------
-.level = INFO
-
-handlers=java.util.logging.ConsoleHandler
-java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
-java.util.logging.ConsoleHandler.level = ALL
-
-org.apache.http.impl.conn.level = FINEST
-org.apache.http.impl.client.level = FINEST
-org.apache.http.client.level = FINEST
---------------------------------------
-
- []
-
- More detailed information is available from the
- {{{http://docs.oracle.com/javase/7/docs/technotes/guides/logging/overview.html}
- Java Logging documentation}}.
diff --git a/src/site/apt/httpcomponents-client-4.5.x/ntlm.apt b/src/site/apt/httpcomponents-client-4.5.x/ntlm.apt
deleted file mode 100644
index e669d5c..0000000
--- a/src/site/apt/httpcomponents-client-4.5.x/ntlm.apt
+++ /dev/null
@@ -1,162 +0,0 @@
-~~ ====================================================================
-~~ 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
-~~ regarding copyright ownership. The ASF licenses this file
-~~ 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
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ 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.
-~~ ====================================================================
-~~
-~~ This software consists of voluntary contributions made by many
-~~ individuals on behalf of the Apache Software Foundation. For more
-~~ information on the Apache Software Foundation, please see
-~~ <http://www.apache.org/>.
-
- ----------
- NTLM support in HttpClient
- ----------
- ----------
- ----------
-
-NTLM support in HttpClient
-
-* {Background}
-
- NTLM is a proprietary authentication scheme developed by Microsoft and optimized for
- Windows operating system.
-
- Until year 2008 there was no official, publicly available, complete documentation of
- the protocol. {{{http://davenport.sourceforge.net/ntlm.html}Unofficial}} 3rd party
- protocol descriptions existed as a result of reverse-engineering efforts. It was not
- really known whether the protocol based on the reverse-engineering were complete or
- even correct.
-
- Microsoft published {{{http://download.microsoft.com/download/a/e/6/ae6e4142-aa58-45c6-8dcf-a657e5900cd3/%5BMS-NLMP%5D.pdf}MS-NLMP}}
- and {{{http://download.microsoft.com/download/a/e/6/ae6e4142-aa58-45c6-8dcf-a657e5900cd3/%5BMS-NTHT%5D.pdf}MS-NTHT}}
- specifications in February 2008 as a part of its
- {{{http://www.microsoft.com/interop/principles/default.mspx}Interoperability
- Principles initiative}}.
-
- HttpClient as of version 4.1 initially supported NTLMv1, NTLMv2, and NTLM2SessionResponse
- authentication protocols, based on the reverse engineering approach. As of version
- 4.2.3, HttpClient now supports a more correct implementation, based in large part on
- Microsoft's own specifications. This is expected to correct a number of problems, especially
- since Microsoft (as of Windows Server 2008 R2) began using a new implementation of its
- protocols. This new Microsoft implementation has led to authentication failures in some
- cases from some of the older reverse-engineered client implementations of NTLM.
-
- The new HttpClient NTLM implementation is known to have been tried successfully against
- at least the following systems:
-
- * Windows Server 2000 and Server 2003 systems, configured to use LM and NTLMv1 authentication
-
- * Windows Server 2003 systems, configured to use NTLMv2 authentication
-
- * Windows Server 2008 R2 systems, configured to use NTLM2SessionResponse authentication
-
- []
-
- If the current HttpClient NTLM implementation should prove problematic in your environment,
- we'd definitely like to hear about it. You are also welcome to try an alternative NTLM
- implementation, should it seem necessary. One can also use {{{http://jcifs.samba.org/}JCIFS}},
- which includes an NTLM engine developed by members of the Samba project.
-
-* {Using Samba JCIFS as an alternative NTLM engine}
-
- Follow these instructions to build an NTLMEngine implementation using JCIFS library
-
- <<Disclaimer: Use code at your own discretion. Do NOT report any issues related to
- the use of JCIFS library to Apache HttpComponents project>>.
-
- * Download version 1.3.14 or newer of the JCIFS library from the
- {{{http://jcifs.samba.org/}Samba}} web site
-
- * Implement NTLMEngine interface
-
-----------------------------------------
-import java.io.IOException;
-
-import jcifs.ntlmssp.NtlmFlags;
-import jcifs.ntlmssp.Type1Message;
-import jcifs.ntlmssp.Type2Message;
-import jcifs.ntlmssp.Type3Message;
-import jcifs.util.Base64;
-
-import org.apache.http.impl.auth.NTLMEngine;
-import org.apache.http.impl.auth.NTLMEngineException;
-
-public final class JCIFSEngine implements NTLMEngine {
-
- private static final int TYPE_1_FLAGS =
- NtlmFlags.NTLMSSP_NEGOTIATE_56 |
- NtlmFlags.NTLMSSP_NEGOTIATE_128 |
- NtlmFlags.NTLMSSP_NEGOTIATE_NTLM2 |
- NtlmFlags.NTLMSSP_NEGOTIATE_ALWAYS_SIGN |
- NtlmFlags.NTLMSSP_REQUEST_TARGET;
-
- public String generateType1Msg(final String domain, final String workstation)
- throws NTLMEngineException {
- final Type1Message type1Message = new Type1Message(TYPE_1_FLAGS, domain, workstation);
- return Base64.encode(type1Message.toByteArray());
- }
-
- public String generateType3Msg(final String username, final String password,
- final String domain, final String workstation, final String challenge)
- throws NTLMEngineException {
- Type2Message type2Message;
- try {
- type2Message = new Type2Message(Base64.decode(challenge));
- } catch (final IOException exception) {
- throw new NTLMEngineException("Invalid NTLM type 2 message", exception);
- }
- final int type2Flags = type2Message.getFlags();
- final int type3Flags = type2Flags
- & (0xffffffff ^ (NtlmFlags.NTLMSSP_TARGET_TYPE_DOMAIN | NtlmFlags.NTLMSSP_TARGET_TYPE_SERVER));
- final Type3Message type3Message = new Type3Message(type2Message, password, domain,
- username, workstation, type3Flags);
- return Base64.encode(type3Message.toByteArray());
- }
-
-}
-----------------------------------------
-
- * Implement AuthSchemeProvider interface
-
-----------------------------------------
-public class JCIFSNTLMSchemeFactory implements AuthSchemeProvider {
-
- public AuthScheme create(final HttpContext context) {
- return new NTLMScheme(new JCIFSEngine());
- }
-}
-----------------------------------------
-
- * Register NTLMSchemeFactory with the HttpClient instance you want to NTLM
- enable.
-
-----------------------------------------
-Registry<AuthSchemeProvider> authSchemeRegistry = RegistryBuilder.<AuthSchemeProvider>create()
- .register(AuthSchemes.NTLM, new JCIFSNTLMSchemeFactory())
- .register(AuthSchemes.BASIC, new BasicSchemeFactory())
- .register(AuthSchemes.DIGEST, new DigestSchemeFactory())
- .register(AuthSchemes.SPNEGO, new SPNegoSchemeFactory())
- .register(AuthSchemes.KERBEROS, new KerberosSchemeFactory())
- .build();
-CloseableHttpClient httpClient = HttpClients.custom()
- .setDefaultAuthSchemeRegistry(authSchemeRegistry)
- .build();
-----------------------------------------
-
- * Set NTCredentials for the web server you are going to access.
-
-
diff --git a/src/site/apt/httpcomponents-client-4.5.x/primer.apt b/src/site/apt/httpcomponents-client-4.5.x/primer.apt
deleted file mode 100644
index cebcd5f..0000000
--- a/src/site/apt/httpcomponents-client-4.5.x/primer.apt
+++ /dev/null
@@ -1,631 +0,0 @@
-~~ ====================================================================
-~~ 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
-~~ regarding copyright ownership. The ASF licenses this file
-~~ 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
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ 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.
-~~ ====================================================================
-~~
-~~ This software consists of voluntary contributions made by many
-~~ individuals on behalf of the Apache Software Foundation. For more
-~~ information on the Apache Software Foundation, please see
-~~ <http://www.apache.org/>.
-
- ----------
- Client HTTP Programming Primer
- ----------
- ----------
- ----------
-
-Client HTTP Programming Primer
-
-* {About}
-
- This document is intended for people who suddenly have to or want to implement
- an application that automates something usually done with a browser,
- but are missing the background to understand what they actually need to do.
- It provides guidance on the steps required to implement a program that
- interacts with a web site which is designed to be used with a browser.
- It does not save you from eventually learning the background of what
- you are doing, but it should help you to get started quickly and learn
- the details later.
-
- This document has evolved from discussions on the HttpClient mailing lists.
- Although it refers to HttpClient, the concepts described here apply equally
- to HttpComponents or Java's {{{http://docs.oracle.com/javase/7/docs/api/java/net/HttpURLConnection.html}HttpURLConnection}}
- or any other HTTP communication library for any programming language. So you
- might find it useful even if you're not using Java and HttpClient.
-
- The existence of this document does not imply that the HttpClient community
- feels responsible for teaching you how to program a client HTTP application.
- It is merely a way for us to reduce the noise on the mailing list without
- just leaving the newbies out in the cold.
-
-* {Scenario}
-
- Let's assume that you have some kind of repetitive, web-based task that
- you want to automate. Something like:
-
- * goto page http://xxx.yyy.zzz/login.html
-
- * enter username and password in a web form and hit the "login" button
-
- * navigate to a specific page
-
- * check the number/headline/whatever shown on that page
-
- []
-
- At this time, we don't have a specific example which could be developed
- into a sample application. So this document is all bla-bla, and you will
- have to work out the details - all the details - yourself. Such is life.
-
-* {Caveat}
-
- This scenario describes a hobbyist usage of HTTP, in other words:
- <<a bad practice>>. Web sites are designed for user interaction, not
- as an application programming interface (API). The interface of a
- web site is the user interface displayed by a browser. The HTTP
- communication between the browser and the server is an internal API,
- subject to change without notice.
-
- A web site can be redesigned at any point in time. The server then
- sends different documents and a browser will display the new content.
- The user easily adjusts to click the appropriate links, and the browser
- communicates via HTTP as specified by the new documents from the server.
- Your application that only mimicks a browser will simply break.
-
- Nevertheless, implementing this scenario will help you to get
- familiar with HTTP communication. It is also "good enough" for
- hobbyists applications, for example if you want to download the
- latest installment of your favorite daily webcomic to install
- it as the screen background. There is no big damage if such an
- application breaks.
-
- If you want to implement a solid application, you should use only
- published APIs. For example, to check for new mail on your webmail
- account, you should ask the webmail provider for POP or IMAP access.
- These are standardized protocols supported my most EMail client applications.
- If you want to have a newsticker, look for RSS feeds from the provider and
- applications that display them.
-
- As another example, if you want to perform a web search, there are
- search companies that provide an API for using their search engines.
- Unlike the examples before, such APIs are proprietary. You will still
- have to implement an application, but then you are using a published API
- that the provider will not change without notice.
-
-
-* {Not a Browser}
-
- HttpClient is not a browser. It is an HTTP communication library
- and as such it provides only a subset of functions expected from
- a common browser application. The most fundamental difference is
- absence of user interface in HttpClient. The browser needs a rendering
- engine to display pages, and to interpret user input such as mouse clicks
- somewhere on the displayed page. There is a layout engine which computes
- how an HTML page should be displayed, including cascading style sheets
- and images. A JavaScript interpreter runs JavaScript code embedded in
- or referenced from HTML pages. Events from the user interface are passed
- to the JavaScript interpreter for processing. On top of that, there are
- interfaces for plugins that can handle Applets, embedded media objects
- like PDF files, Quicktime movies and Flash animations, or ActiveX
- controls that can do anything. HttpClient can only be used
- programmatically through its APIs to transmit and receive HTTP messages.
- HttpClient is also completely content agnostic. It can transfer message
- content but it is unable to render or process it in any fashion.
-
- Another major difference is tolerance for bad input or HTTP standard
- violations. There needs to be tolerance for invalid user input to make
- the browser user friendly. There also needs to be tolerance for malformed
- documents retrieved from servers, and for flaws in server behavior when
- executing protocols, to make as many websites as possible accessible to
- the user. HttpClient is however strives to adhere to the HTTP standard
- specification and related standards as close and as possible by default.
- It also provides means to relaxing some of the restrictions imposed
- by the specification where permissible or required for compatibility
- with non-compliant HTTP origin or proxy servers.
-
-* {Terminology}
-
- This section introduces some important terms you have to know to
- understand the rest of this document.
-
- <<<{HTTP Message}>>>
-
- consists of a header section and an optional entity. There are two kinds
- of messages, requests and responses. They differ in the format of the
- first line, but both can have header fields and an optional entity.
-
- <<<{HTTP Request}>>>
-
- is sent from a client to a server. The first line includes the URI for
- which the request is sent, and a method that the server should execute
- for the client.
-
- <<<{HTTP Response}>>>
-
- is sent from a server to a client in response to a request. The first
- line includes a status code that tells about success or failure of
- the request. HTTP defines a set of status codes, like 200 for success
- and 404 for not found. Other protocols based on HTTP can define
- additional status codes.
-
- <<<{Method}>>>
-
- is an operation requested from the server. HTTP defines a set of
- operations, the most frequent being GET and POST. Other protocols
- based on HTTP can define additional methods.
-
- <<<{Header Fields}>>>
-
- are name-value pairs, where both name and value are text. The name of
- a header field is not case sensitive. Multiple values can be assigned
- to the same name. RFC 2616 defines a wide range
- of header fields for handling various aspects of the HTTP protocol.
- Other specifications, like RFC 2617 and RFC 2965, define additional
- headers. Some of the defined headers are for general use, others are
- meant for exclusive use with either requests or responses, still others
- are meant for use only with an entity.
-
- <<<{Entity}>>>
-
- is data sent with an HTTP message. For example, a response can contain
- the page or image you are downloading as an entity, or a request can
- include the parameters that you entered into a web form.
- The entity of an HTTP message can have an arbitrary data format, which
- is usually specified as a MIME type in a header field.
-
- <<<{Session}>>>
-
- is a series of requests from a single source to a server. The server
- can keep session data, and needs to recognize the session to which
- each incoming request belongs. For example, if you execute a web search,
- the server will only return one page of search results. But it keeps
- track of the other results and makes them available when you click on
- the link to the "next" page. The server needs to know from the request
- that it is you and your session for which more results are requested,
- and not me and my session. That's because I searched for something else.
-
- <<<{Cookies}>>>
-
- are the preferred way for servers to track sessions. The server supplies
- a piece of data, called a cookie, in response to a request. The server
- expects the client to send that piece of data in a header field with each
- following request of the same session.
- The cookie is different for each session, so the server can identify to
- which session a request belongs by looking at the cookie. If the cookie
- is missing from a request, the server will not respond as expected.
-
-* {Step by Step}
-
-** {GET the Login Page}
-
- Create and execute a GET request for the login page.
- Just use the link you would type into the browser as the URL.
- This is what a browser does when you enter a URL in the address bar
- or when you click on a link that points to another web page.
-
- Inspect the response from the server:
-
- * do you get the page you expected?
-
- []
-
- It should be sent as the entity of the response to your request.
- The entity is also referred to as the response body.
-
- * do you get a session cookie?
-
- []
-
- Cookies are sent in a header field named Set-Cookie or Set-Cookie2.
- It is possible that you don't get a session cookie until you log in.
- If there is no session cookie in the response, you'll have to do perform
- step 2 later, after you reach the point where the cookie is set.
-
- If you do not get the page you expect, check the URL you are requesting.
- If it is correct, the server may use a browser detection. You will have
- to set the header field User-Agent to a value used by a popular browser
- to pretend that the request is coming from that browser.
-
- If you can't get the login page, get the home page instead now.
- Get the login page in the next step, when you establish the session.
-
-** {Establish the Session}
-
- Create and execute another GET request for a page.
- You can simply request the login page again, or some other page
- of which you know the URL. Do NOT try to get a page which would
- be returned in response to submitting a web form. Use something
- you can reach simply by clicking on a link in the browser. Something
- where you can see the URL in the browser status line while the
- mouse pointer is hovering over the link.
-
- This step is important when developing the application. Once you know
- that your application does establish the session correctly, you may
- be able to remove it. Only if you couldn't get the login page directly
- and had to get the home page first, you know you have to leave it in.
-
- Inspect the request being sent to the server.
-
- * is the session cookie sent with the request?
-
- []
-
- You can see what is sent to the server by enabling the wire log
- for HttpClient. You only need to see the request headers, not the body.
- The session cookie should be sent in a header field called Cookie.
- There may be several of those, and other cookies might be sent as well.
-
- Inspect the response from the server:
-
- * do you get another session cookie?
-
- []
-
- You should not get another session cookie. If you get the same session
- cookie as before, the server behaves a little strange but that should
- not be a problem. If you get a new session cookie, then the server did
- not recognize the session for the request. Usually, this happens if the
- request did not contain the session cookie. But servers might use other
- means to track sessions, or to detect session hijacking.
-
- If the session cookie is not sent in the request, one of two things
- has gone wrong. Either the cookie was not detected in the previous
- response, or the cookie was not selected for being sent with the new
- request.
-
- HttpClient automatically parses cookies sent in responses and puts them
- into a cookie store. HttpClient uses a configurable cookie policy
- to decide whether a cookie being sent from a server is correct.
- The default policy complies strictly with RFC 2109, but many servers
- do not. Play around with the cookie policies until the cookie is
- accepted and put into the cookie store.
-
- If the cookie is accepted from the previous response but still not
- sent with the new request, make sure that HttpClient uses the same
- cookie store object. Unless you explicitly manage cookie store
- objects (not recommended for newbies!), this will be the case if you
- use the same HttpClient object to execute both requests.
-
- If the cookie is still not sent with the request, make sure that the
- URL you are requesting is in the scope for the cookie. Cookies are
- only sent to the domain and path specified in the cookie scope.
- A cookie for host "jakarta.apache.org" will not be sent to host
- "tomcat.apache.org". A cookie for domain ".apache.org" will be sent
- to both. A cookie for host "apache.org", without the leading dot,
- will not be sent to "jakarta.apache.org". The latter case can be
- resolved by using a different cookie spec that adds the leading dot.
- In the other cases, use a URL that in the cookie scope to establish
- the session.
-
- If the session cookie is sent with the request, but a new session cookie
- is set in the response anyway, check whether there are cookies other
- than the session cookie in the request. Some servers are incapable of
- detecting multiple cookies sent in individual header fields. HttpClient
- can be advised to put all cookies into a single header field.
-
- If that doesn't help, you are in trouble. The server may use additional
- means to track the session, for example the header field named Referer.
- Set that field to the URL of the previous request.
- ({{{http://mail-archives.apache.org/mod_mbox/jakarta-httpclient-user/200602.mbox/%3c19b.44e04b45.31166eaa@aol.com%3e}see this mail}})
-
- If that doesn't help either, you will have to compare the request from
- your application to a corresponding one generated by a browser. The
- instructions in step 5 for POST requests apply for GET requests as well.
- It's even simpler with GET, since you don't have an entity.
-
-** {Analyze the Form}
-
- Now it is time to analyze the form defined in the HTML markup of the page.
- A form in HTML is a set of name-value-pairs called parameters, where some
- of the values can be entered in the browser. By analyzing the HTML markup,
- you can learn which parameters you have to define and how to send them
- to the server.
-
- Look for the <form> tag in the page source. There may be several forms in
- the page, but they can not be nested. Locate the form you want to submit.
- Locate the matching </form> tag. Everything in between the two may be
- relevant. Let's start with the {attributes of the <form> tag}:
-
- <<<{method}=>>>
-
- specifies the method used for submitting the form. If it is GET or
- not specified at all, then you need to create a GET request. The parameters
- will be added as a query string to the URL. If the method is POST, you
- need to create a POST request. The parameters will be put in the entity
- of the request, also referred to as the request body.
- How to do that is discussed in step 5.
-
- <<<{action}=>>>
-
- specifies the URL to which the request has to be sent. Do not try to
- get this URL from the address bar of your browser! A browser will
- automatically follow redirects and only displays the final URL, which
- can be different from the URL in this attribute.
- It is possible that the URL includes a query string that specifies
- some parameters. If so, keep that in mind.
-
- <<<{enctype}=>>>
-
- specifies the MIME type for the entity of the request generated by the
- form. The two common cases are url-encoded (default) and multipart-mime.
- Note that these terms are just informally used here, the exact values
- that need to be written in an HTML document are specified elsewhere.
- This attribute is only used for the POST method. If the method is GET,
- the parameters will always be url-encoded, but not in an entity.
-
- <<<{accept-charset}=>>>
-
- specifies the character set that the browser should allow for user input.
- It will not be discussed here, but you will have to consider this value
- if you experience charset related problems.
-
- Except for optional query parameters in the action attribute, the parameters
- of a form are specified by HTML tags between <form> and </form>.
- The following is a list of tags that can be used to define parameters.
- Except where stated otherwise, they have a name attribute which specifies
- the name of the parameter. The value of the parameter usually depends on
- user input.
-
-----------------------------------------
-<input type="text" name="...">
-<input type="password" name="...">
-----------------------------------------
-
- specify single-line input fields. Using the return key in one of these
- fields will submit the form, so the value really is a single line of
- input from the user.
-
-----------------------------------------
-<input type="text" readonly name="..." value="...">
-<input type="hidden" name="..." value="...">
-----------------------------------------
-
- specify a parameter that can not be changed by the user.
- The value of the parameter is given by the value attribute.
-
-----------------------------------------
-<input type="radio" name="..." value="...">
-<input type="checkbox" name="..." value="...">
-----------------------------------------
-
- specify a parameter that can be included or omitted. There usually is
- more than one tag with the same name. For radio buttons, only one can
- be selected and the value of the parameter is the value of the selected
- radio button. For checkboxes, more than one can be selected. There will
- be one name-value-pair for each selected checkbox, with the same name
- for all of them.
-
-----------------------------------------
-<input type="submit" name="..." value="...">
-<button type="submit" name="..." value="...">
-----------------------------------------
-
- specify a button to submit the form. The parameter will only be added
- to the form if that button is used to submit. If another button is used,
- or the form is submitted by pressing the return key in a text input field,
- the parameter is not part of the submitted form data. If the name attribute
- is missing, no parameter is added to the form data for that button.
-
-----------------------------------------
-<textarea name="...">
-<textarea value="..." readonly>
-----------------------------------------
-
- specify a multi-line input field. In the readonly case, the value of
- the parameter is the text between the <textarea> and </textarea> tags.
-
-----------------------------------------
-<select name="..." multiple>}}}
- <option value="...">...</option>}}}
- <option value="...">...</option>}}}
- ...
-</select>
-----------------------------------------
-
- specify a selection list or drop-down menu. If the multiple attribute is
- not present, only one option can be selected. There will be one
- name-value-pair for each selected option, with the same name for all of them.
- If there is no value attribute, the value for that option is
- the text between <option> and </option>.
-
-----------------------------------------
-<input type="image" name="...">
-----------------------------------------
-
- specifies an image that can be clicked to submit the form. If that image
- is clicked to submit the form, two parameters are added to the form data.
- The name attribute is suffixed with ".x" and ".y", the values for the
- parameters are the relative coordinates of the mouse pointer within the
- image at the time of the click, in pixel. If the name attribute is missing,
- no parameters will be added to the form data.
-
-----------------------------------------
-<input type="file" name="...">
-----------------------------------------
-
- specifies a file selection box. The user can select a file that should
- be sent as part of the form data. This is only possible if the encoding
- is multipart-mime. Unlike other parameters, the file is not mapped to a
- simple name-value-pair. File upload is not a topic for beginners.
-
- These tags are used to define parameters in static HTML. With dynamic HTML,
- in particular JavaScript, the parameter values can be changed before the
- form is submitted. If that is the case, you are in trouble. Learn JavaScript,
- analyze the code that is executed, and modify your application to match
- that behavior.
-
-
-** {Analyze the Form, Again}
-
- After you have determined the action URL and name-value-pairs of
- a form, you should exit the program you used to get the HTML source,
- start it again and repeat the analysis with the new page.
-
- Most parameters will be the same for both pages. But some parameters,
- in particular those from hidden input fields, may change from session
- to session, or even with every request. The same can be the case with
- the action URL.
-
- Parameters that remain the same can be hard-coded in your program.
- If parameters change (except for user input), then your application
- has to request the page with the form and extract the dynamic parameters
- at runtime. If you're lucky you can locate them by simple string searches.
- If you're unlucky, you need an HTML parser to make sense of the page.
- HTML parsing is out of scope for HttpClient, but you'll find some
- HTML parsers mentioned in the mailing list archives.
-
- Note that a redesign of the form on the server can break your application
- at any time. Whenever that happens, you have to repeat the analysis with
- the new form returned by the server after the redesign, and adjust your
- application accordingly.
-
-
-** {POST the Form}
-
- After analyzing the form, it is time to create a request that matches
- what a browser would generate. If the method is GET, just add the
- name-value-pairs for all parameters to the query string. If the method
- is POST, things are a little more complicated.
-
- It depends on the server how closely you have to match browser behavior.
- For example, a servlet will not distinguish between parameters in the
- query string and url-encoded parameters of the entity. But other server
- side code might make that distinction. The safe way is always to match
- browser behavior exactly.
-
- HttpClient supports both encoding types, url-encoded and multipart-mime.
- To send parameters url-encoded, use the POST request and add the parameters
- directly there. To send parameters in multipart-mime, collect the parameters
- in a multipart-encoded request entity and add set the entity for the
- POST request. You will also find support for file upload in the multipart
- package. Note that these techniques are mutually exclusive, they can not be
- combined. Parameters defined in the query string of the URL can remain there.
-
- Send the request. Inspect the response from the server:
-
- * do you get a status code 303 or 307?
-
- []
-
- That is called a redirect. Follow redirects to the ultimate page
- and inspect that response. See step 6 on following redirects.
-
- * do you get the page you expected?
-
- []
-
- If the server response to your POST request indicates a problem,
- try to enable or disable the expect-continue handshake, or switch
- the protocol version to HTTP/1.0. If that doesn't help...
-
- Inspect the request you are sending:
-
- * are there significant differences to the request of a browser?
-
- []
-
- There is a variety of sniffer programs you can use to grep the
- browser request. Some of them are mentioned in the responses
- to {{{http://mail-archives.apache.org/mod_mbox/jakarta-httpclient-user/200603.mbox/%3c981224FF5B88B349B7C1FED584D2620E02A2CBB2@CORPUSMX50B.corp.emc.com%3e this question}on the mailing list}}.
-
- Candidates for problems are missing or wrong parameters, and differences
- in the header fields. The parameters are all up to you. As a general rule
- for the header fields, you should send the same as the browser does. The
- order of the fields does not matter.
-
- But there's a caveat: some header fields are controlled by HttpClient and
- can not be set explicitly. Other header fields are used to indicate
- capabilities which a browser has, but your application probably has not.
- For these, the request from your application has to and should differ.
- Here is a possibly incomplete {list of headers that need special consideration}:
-
- <<<{Host}:>>>
-
- controlled by HttpClient. The value is usually obtained from the URL
- you are posting to. It is possible to set a different value, called
- a "virtual host".
-
- <<<{Content-Type}:>>>
-
- <<<{Content-Length}:>>>
-
- <<<{Transfer-Encoding}:>>>
-
- controlled by HttpClient. The values are obtained from the request entity.
-
- <<<{Connection}:>>>
-
- usually controlled by HttpClient to handle connection keep-alive.
- Leave it alone or set the value to "close".
-
- <<<{Content-Encoding}:>>>
-
- used to indicate the capability to process compressed responses.
- Do not set this, unless you are prepared to implement decompression.
-
-** {Follow Redirects}
-
- It is quite common for servers to respond with a 303 or 307 status code
- to a POST request. These redirects indicate that your application has to
- send another request to retrieve the actual result of the operation you
- have triggered with the POST request.
-
- HttpClient can be configured to follow some redirects automatically.
- Others it is not allowed to follow automatically, since RFC 2616 specifies
- that a user interaction should take place. We will make sure that HttpClient
- is compliant with this requirement, but we can't stop you from implementing
- a different behavior in your application. The Location header field in the
- redirect response indicates the URL from which to fetch the actual page.
- It is common practice that servers return a relative URL as the location,
- although the specification requires an absolute URL.
-
- Note that there may be more than one redirect in succession. Your
- application then has to follow the redirect for a redirect, but make sure
- that you do not enter an infinite loop. If you find that there are more
- than two redirects in succession, something probably is fishy.
-
-
-** {Logout}
-
- Your application can send as many GET and POST requests and follow as many
- redirects as is required. But you should remember that there is a session
- tracked by the server. Once your application is done, and if the web site
- does provide a logout link, you should send a final request to log out.
- This will tell the server that the session data can be discarded. If the
- server prevents multiple logins with the same user ID and your application
- has to run repeatedly, logout may even be required.
-
-* {Further Reading}
-
- ReferenceMaterials: a list of technical specifications for HTTP and related
- stuff.
-
- * {{{http://www.w3.org/TR/html4/interact/forms.html} HTML 4.01 Specification,
- Section on Forms}}: Includes how browsers have to generate the data to submit
- to the server.
-
- * {{{https://digital.com/tools/html-cheatsheet/} Giving Form to Forms}}:
- Explains how to define HTML forms and what is submitted to the server.
- Probably easier to digest than the HTML 4.01 Specification.
-
- * {{{http://jakarta.apache.org/commons/fileupload/} Commons File Upload}}:
- Server-side library for parsing multipart requests.
-
- * {{{http://www.cs.tut.fi/~jkorpela/forms/file.html} Tutorial on File Upload
- in HTML}}
-
- []
diff --git a/src/site/apt/httpcomponents-client-5.0.x/android.apt b/src/site/apt/httpcomponents-client-5.0.x/android.apt
deleted file mode 100644
index 70fe205..0000000
--- a/src/site/apt/httpcomponents-client-5.0.x/android.apt
+++ /dev/null
@@ -1,39 +0,0 @@
-~~ ====================================================================
-~~ 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
-~~ regarding copyright ownership. The ASF licenses this file
-~~ 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
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ 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.
-~~ ====================================================================
-~~
-~~ This software consists of voluntary contributions made by many
-~~ individuals on behalf of the Apache Software Foundation. For more
-~~ information on the Apache Software Foundation, please see
-~~ <http://www.apache.org/>.
-
- ----------
- HttpClient for Android
- ----------
- ----------
- ----------
-
-HttpClient for Android
-
- Apache HttpCLient 5.x is expected to work well with Android API 19 and newer
-
-----
-dependencies {
- compile group: 'org.apache.httpcomponents.client5' , name: 'httpclient5' , version: '5.0.3'
-}
-----
diff --git a/src/site/apt/httpcomponents-client-5.0.x/logging.apt b/src/site/apt/httpcomponents-client-5.0.x/logging.apt
deleted file mode 100644
index f693e85..0000000
--- a/src/site/apt/httpcomponents-client-5.0.x/logging.apt
+++ /dev/null
@@ -1,200 +0,0 @@
-~~ ====================================================================
-~~ 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
-~~ regarding copyright ownership. The ASF licenses this file
-~~ 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
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ 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.
-~~ ====================================================================
-~~
-~~ This software consists of voluntary contributions made by many
-~~ individuals on behalf of the Apache Software Foundation. For more
-~~ information on the Apache Software Foundation, please see
-~~ <http://www.apache.org/>.
-
- ----------
- HttpClient Logging Practices
- ----------
- ----------
- ----------
-
-Logging Practices
-
- Being a library HttpClient is not to dictate which logging framework the user has to use.
- Therefore HttpClient utilizes the logging facade provided by the
- {{{https://logging.apache.org/log4j/2.x/manual/api.html}Apache Log4j 2}} package.
- <<<Log4j 2>>> provides a simple and generalized
- {{{https://logging.apache.org/log4j/2.x/log4j-api/apidocs/index.html?org/apache/logging/log4j/package-summary.html}log interface}} to
- various logging packages. By using <<<Log4j>>>, HttpClient can be configured for a
- variety of different logging behaviours. That means the user will have to make a choice which
- logging implementation to use. By default <<<Log4j 2>>> supports the following logging
- implementation:
-
- * {{{https://logging.apache.org/log4j/2.x/}Log4J 2}}
-
- * {{{https://logging.apache.org/log4j/2.x/log4j-to-slf4j/index.html}SLF4J}}
-
- * {{{https://logging.apache.org/log4j/2.x/log4j-api/apidocs/org/apache/logging/log4j/simple/SimpleLogger.html}
- SimpleLog}} (internal to <<<Log4J 2>>>)
-
- * {{{https://logging.apache.org/log4j/2.x/log4j-jul/index.html}
- java.util.logging}}
-
- By implementing some simple interfaces <<<Log4J 2>>> can be extended to support
- basically any other custom logging framework. <<<Log4J 2>>> tries to automatically
- discover the logging framework to use. If it fails to select the expected one, you must
- configure <<<Log4J 2>>> by hand. Please refer to the <<<Log4J 2>>>
- documentation for more information.
-
- HttpClient performs three different kinds of logging: the standard context logging used within
- each class, HTTP header logging and full wire logging.
-
-* {Understanding Logger Names}
-
- Most logging implementations use a hierarchical scheme for matching logger names with logging
- configuration. In this scheme, the logger name hierarchy is represented by <<<'.'>>> characters
- in the logger name, in a fashion very similar to the hierarchy used for Java package names. For example,
- <<<org.apache.logging.appender>>> and <<<org.apache.logging.filter>>> both have
- <<<org.apache.logging>>> as their parent. In most cases, applications name their loggers by
- passing the current class's name to <<<LogManager.getLogger(...)>>>.
-
-* {Context Logging}
-
- Context logging contains information about the internal operation of HttpClient as it performs
- HTTP requests. Each class has its own logger named according to the class's fully qualified name.
- For example the class <<<DefaultHttpClient>>> has a logger named
- <<<org.apache.http.impl.client.DefaultHttpClient>>>. Since all classes follow this convention
- it is possible to configure context logging for all classes using the single logger named
- <<<org.apache.hc.client5.http>>>.
-
-* {Wire Logging}
-
- The wire logger is used to log all data transmitted to and from servers when executing HTTP
- requests. The wire logger uses the <<<org.apache.hc.client5.http.wire>>> logger name. This logger should
- only be enabled to debug problems, as it will produce an extremely large amount of log data.
-
-* {HTTP header Logging}
-
- Because the content of HTTP requests is usually less important for debugging than the HTTP
- headers, use the <<<org.apache.hc.client5.http.headers>>> logger for capturing HTTP headers only.
-
-* {Configuration Examples}
-
- <<<Log4j 2>>> can delegate to a variety of logging implementations for processing the actual output.
- Below are configuration examples for <<<Log4j 2>>>, <<<Commons Logging>>>, and
- <<<java.util.logging>>>.
-
-** {Log4j 2 Examples}
-
- The simplest way to {{{https://logging.apache.org/log4j/2.x/manual/configuration.html}configure}} <<<Log4j 2>>>
- is via a <<<log4j2.xml>>> file. <<<Log4j 2>>> will
- {{{https://logging.apache.org/log4j/2.x/manual/configuration.html#AutomaticConfiguration}automatically}}
- configure itself using a file named <<<log4j2.xml>>> when it's present at the root of the application
- classpath. Below are some <<<Log4j>>> configuration examples.
-
- <<Note:>> The <<<Log4j 2>>> implementation a.k.a "core" is not included in the <<<HttpClient>>> distribution.
- You can include it in your project using
- {{{https://logging.apache.org/log4j/2.x/maven-artifacts.html}Maven, Ivy, Gradle, or SBT}}.
-
- * Enable header wire + context logging - <<Best for Debugging>>
-
---------------------------------------
-<Configuration>
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="org.apache.hc.client5.http" level="DEBUG">
- <AppenderRef ref="Console"/>
- </Logger>
- <Logger name="org.apache.hc.client5.http.wire" level="DEBUG">
- <AppenderRef ref="Console"/>
- </Logger>
- <Root level="INFO">
- <AppenderRef ref="STDOUT" />
- </Root>
- </Loggers>
-</Configuration>
---------------------------------------
-
- * Enable full wire + context logging
-
---------------------------------------
-<Configuration>
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="org.apache.hc.client5.http" level="DEBUG">
- <AppenderRef ref="Console"/>
- </Logger>
- <Root level="INFO">
- <AppenderRef ref="STDOUT" />
- </Root>
- </Loggers>
-</Configuration>
---------------------------------------
-
- * Enable context logging for connection management
-
---------------------------------------
-<Configuration>
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="org.apache.hc.client5.http.impl.io" level="DEBUG">
- <AppenderRef ref="Console"/>
- </Logger>
- <Logger name="org.apache.hc.client5.http.impl.nio" level="DEBUG">
- <AppenderRef ref="Console"/>
- </Logger>
- <Root level="INFO">
- <AppenderRef ref="STDOUT" />
- </Root>
- </Loggers>
-</Configuration>
---------------------------------------
-
- * Enable context logging for connection management / request execution
-
---------------------------------------
-<Configuration>
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="org.apache.hc.client5.http.impl" level="DEBUG">
- <AppenderRef ref="Console"/>
- </Logger>
- <Root level="INFO">
- <AppenderRef ref="STDOUT" />
- </Root>
- </Loggers>
-</Configuration>
---------------------------------------
-
- []
-
- The <<<Log4J 2>>> manual is the best reference for how to configure <<<Log4J 2>>>. It is available at
- {{{https://logging.apache.org/log4j/2.x/manual/}
- https://logging.apache.org/log4j/2.x/manual/}}.
-
diff --git a/src/site/apt/httpcomponents-client-5.0.x/related-projects.apt b/src/site/apt/httpcomponents-client-5.0.x/related-projects.apt
deleted file mode 100644
index 9f8efa5..0000000
--- a/src/site/apt/httpcomponents-client-5.0.x/related-projects.apt
+++ /dev/null
@@ -1,54 +0,0 @@
-~~ ====================================================================
-~~ 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
-~~ regarding copyright ownership. The ASF licenses this file
-~~ 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
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ 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.
-~~ ====================================================================
-~~
-~~ This software consists of voluntary contributions made by many
-~~ individuals on behalf of the Apache Software Foundation. For more
-~~ information on the Apache Software Foundation, please see
-~~ <http://www.apache.org/>.
-
- ----------
- HttpComponents HttpCore Examples
- ----------
- ----------
- ----------
-
-Related projects
-
-* HttpClient 5.0 migration guide
-
- {{{https://ok2c.github.io/httpclient-migration-guide/}HttpClient 5.0 migration guide}}
- is a third party resource with recommendations about the upgrade process and
- possible upgrade paths from Apache HttpClient 4.x to Apache HttpClient 5.0.
-
-* Asynchronous JSON message processors
-
- {{{https://ok2c.github.io/httpcomponents-jackson/}Asynchronous JSON message processors}}
- library is a companion project for HttpClient 5.0 developed outside the Apache Software
- Foundation.
-
- The library provides a number of asynchronous message consumers and producers
- for efficient, reactive processing of HTTP messages with enclosed JSON content using
- {{{https://github.com/FasterXML/jackson}Jackson JSON processor}}.
-
-
-* Android extensions
-
- {{{https://ok2c.github.io/httpclient-android-ext/}Android extensions for
- Apache HttpClient 5.0}} is a third party library that provides extra functionality
- simplifying application of Apache HttpClient on Google Android platform.
diff --git a/src/site/apt/httpcomponents-client-5.1.x/android.apt b/src/site/apt/httpcomponents-client-5.1.x/android.apt
deleted file mode 100644
index ff348c7..0000000
--- a/src/site/apt/httpcomponents-client-5.1.x/android.apt
+++ /dev/null
@@ -1,39 +0,0 @@
-~~ ====================================================================
-~~ 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
-~~ regarding copyright ownership. The ASF licenses this file
-~~ 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
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ 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.
-~~ ====================================================================
-~~
-~~ This software consists of voluntary contributions made by many
-~~ individuals on behalf of the Apache Software Foundation. For more
-~~ information on the Apache Software Foundation, please see
-~~ <http://www.apache.org/>.
-
- ----------
- HttpClient for Android
- ----------
- ----------
- ----------
-
-HttpClient for Android
-
- Apache HttpCLient 5.x is expected to work well with Android API 19 and newer
-
-----
-dependencies {
- compile group: 'org.apache.httpcomponents.client5' , name: 'httpclient5' , version: '5.1-beta1'
-}
-----
diff --git a/src/site/apt/httpcomponents-client-5.1.x/logging.apt b/src/site/apt/httpcomponents-client-5.1.x/logging.apt
deleted file mode 100644
index f693e85..0000000
--- a/src/site/apt/httpcomponents-client-5.1.x/logging.apt
+++ /dev/null
@@ -1,200 +0,0 @@
-~~ ====================================================================
-~~ 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
-~~ regarding copyright ownership. The ASF licenses this file
-~~ 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
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ 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.
-~~ ====================================================================
-~~
-~~ This software consists of voluntary contributions made by many
-~~ individuals on behalf of the Apache Software Foundation. For more
-~~ information on the Apache Software Foundation, please see
-~~ <http://www.apache.org/>.
-
- ----------
- HttpClient Logging Practices
- ----------
- ----------
- ----------
-
-Logging Practices
-
- Being a library HttpClient is not to dictate which logging framework the user has to use.
- Therefore HttpClient utilizes the logging facade provided by the
- {{{https://logging.apache.org/log4j/2.x/manual/api.html}Apache Log4j 2}} package.
- <<<Log4j 2>>> provides a simple and generalized
- {{{https://logging.apache.org/log4j/2.x/log4j-api/apidocs/index.html?org/apache/logging/log4j/package-summary.html}log interface}} to
- various logging packages. By using <<<Log4j>>>, HttpClient can be configured for a
- variety of different logging behaviours. That means the user will have to make a choice which
- logging implementation to use. By default <<<Log4j 2>>> supports the following logging
- implementation:
-
- * {{{https://logging.apache.org/log4j/2.x/}Log4J 2}}
-
- * {{{https://logging.apache.org/log4j/2.x/log4j-to-slf4j/index.html}SLF4J}}
-
- * {{{https://logging.apache.org/log4j/2.x/log4j-api/apidocs/org/apache/logging/log4j/simple/SimpleLogger.html}
- SimpleLog}} (internal to <<<Log4J 2>>>)
-
- * {{{https://logging.apache.org/log4j/2.x/log4j-jul/index.html}
- java.util.logging}}
-
- By implementing some simple interfaces <<<Log4J 2>>> can be extended to support
- basically any other custom logging framework. <<<Log4J 2>>> tries to automatically
- discover the logging framework to use. If it fails to select the expected one, you must
- configure <<<Log4J 2>>> by hand. Please refer to the <<<Log4J 2>>>
- documentation for more information.
-
- HttpClient performs three different kinds of logging: the standard context logging used within
- each class, HTTP header logging and full wire logging.
-
-* {Understanding Logger Names}
-
- Most logging implementations use a hierarchical scheme for matching logger names with logging
- configuration. In this scheme, the logger name hierarchy is represented by <<<'.'>>> characters
- in the logger name, in a fashion very similar to the hierarchy used for Java package names. For example,
- <<<org.apache.logging.appender>>> and <<<org.apache.logging.filter>>> both have
- <<<org.apache.logging>>> as their parent. In most cases, applications name their loggers by
- passing the current class's name to <<<LogManager.getLogger(...)>>>.
-
-* {Context Logging}
-
- Context logging contains information about the internal operation of HttpClient as it performs
- HTTP requests. Each class has its own logger named according to the class's fully qualified name.
- For example the class <<<DefaultHttpClient>>> has a logger named
- <<<org.apache.http.impl.client.DefaultHttpClient>>>. Since all classes follow this convention
- it is possible to configure context logging for all classes using the single logger named
- <<<org.apache.hc.client5.http>>>.
-
-* {Wire Logging}
-
- The wire logger is used to log all data transmitted to and from servers when executing HTTP
- requests. The wire logger uses the <<<org.apache.hc.client5.http.wire>>> logger name. This logger should
- only be enabled to debug problems, as it will produce an extremely large amount of log data.
-
-* {HTTP header Logging}
-
- Because the content of HTTP requests is usually less important for debugging than the HTTP
- headers, use the <<<org.apache.hc.client5.http.headers>>> logger for capturing HTTP headers only.
-
-* {Configuration Examples}
-
- <<<Log4j 2>>> can delegate to a variety of logging implementations for processing the actual output.
- Below are configuration examples for <<<Log4j 2>>>, <<<Commons Logging>>>, and
- <<<java.util.logging>>>.
-
-** {Log4j 2 Examples}
-
- The simplest way to {{{https://logging.apache.org/log4j/2.x/manual/configuration.html}configure}} <<<Log4j 2>>>
- is via a <<<log4j2.xml>>> file. <<<Log4j 2>>> will
- {{{https://logging.apache.org/log4j/2.x/manual/configuration.html#AutomaticConfiguration}automatically}}
- configure itself using a file named <<<log4j2.xml>>> when it's present at the root of the application
- classpath. Below are some <<<Log4j>>> configuration examples.
-
- <<Note:>> The <<<Log4j 2>>> implementation a.k.a "core" is not included in the <<<HttpClient>>> distribution.
- You can include it in your project using
- {{{https://logging.apache.org/log4j/2.x/maven-artifacts.html}Maven, Ivy, Gradle, or SBT}}.
-
- * Enable header wire + context logging - <<Best for Debugging>>
-
---------------------------------------
-<Configuration>
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="org.apache.hc.client5.http" level="DEBUG">
- <AppenderRef ref="Console"/>
- </Logger>
- <Logger name="org.apache.hc.client5.http.wire" level="DEBUG">
- <AppenderRef ref="Console"/>
- </Logger>
- <Root level="INFO">
- <AppenderRef ref="STDOUT" />
- </Root>
- </Loggers>
-</Configuration>
---------------------------------------
-
- * Enable full wire + context logging
-
---------------------------------------
-<Configuration>
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="org.apache.hc.client5.http" level="DEBUG">
- <AppenderRef ref="Console"/>
- </Logger>
- <Root level="INFO">
- <AppenderRef ref="STDOUT" />
- </Root>
- </Loggers>
-</Configuration>
---------------------------------------
-
- * Enable context logging for connection management
-
---------------------------------------
-<Configuration>
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="org.apache.hc.client5.http.impl.io" level="DEBUG">
- <AppenderRef ref="Console"/>
- </Logger>
- <Logger name="org.apache.hc.client5.http.impl.nio" level="DEBUG">
- <AppenderRef ref="Console"/>
- </Logger>
- <Root level="INFO">
- <AppenderRef ref="STDOUT" />
- </Root>
- </Loggers>
-</Configuration>
---------------------------------------
-
- * Enable context logging for connection management / request execution
-
---------------------------------------
-<Configuration>
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="org.apache.hc.client5.http.impl" level="DEBUG">
- <AppenderRef ref="Console"/>
- </Logger>
- <Root level="INFO">
- <AppenderRef ref="STDOUT" />
- </Root>
- </Loggers>
-</Configuration>
---------------------------------------
-
- []
-
- The <<<Log4J 2>>> manual is the best reference for how to configure <<<Log4J 2>>>. It is available at
- {{{https://logging.apache.org/log4j/2.x/manual/}
- https://logging.apache.org/log4j/2.x/manual/}}.
-
diff --git a/src/site/apt/httpcomponents-client-5.1.x/related-projects.apt b/src/site/apt/httpcomponents-client-5.1.x/related-projects.apt
deleted file mode 100644
index 9f8efa5..0000000
--- a/src/site/apt/httpcomponents-client-5.1.x/related-projects.apt
+++ /dev/null
@@ -1,54 +0,0 @@
-~~ ====================================================================
-~~ 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
-~~ regarding copyright ownership. The ASF licenses this file
-~~ 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
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ 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.
-~~ ====================================================================
-~~
-~~ This software consists of voluntary contributions made by many
-~~ individuals on behalf of the Apache Software Foundation. For more
-~~ information on the Apache Software Foundation, please see
-~~ <http://www.apache.org/>.
-
- ----------
- HttpComponents HttpCore Examples
- ----------
- ----------
- ----------
-
-Related projects
-
-* HttpClient 5.0 migration guide
-
- {{{https://ok2c.github.io/httpclient-migration-guide/}HttpClient 5.0 migration guide}}
- is a third party resource with recommendations about the upgrade process and
- possible upgrade paths from Apache HttpClient 4.x to Apache HttpClient 5.0.
-
-* Asynchronous JSON message processors
-
- {{{https://ok2c.github.io/httpcomponents-jackson/}Asynchronous JSON message processors}}
- library is a companion project for HttpClient 5.0 developed outside the Apache Software
- Foundation.
-
- The library provides a number of asynchronous message consumers and producers
- for efficient, reactive processing of HTTP messages with enclosed JSON content using
- {{{https://github.com/FasterXML/jackson}Jackson JSON processor}}.
-
-
-* Android extensions
-
- {{{https://ok2c.github.io/httpclient-android-ext/}Android extensions for
- Apache HttpClient 5.0}} is a third party library that provides extra functionality
- simplifying application of Apache HttpClient on Google Android platform.
diff --git a/src/site/apt/httpcomponents-core-5.0.x/related-projects.apt b/src/site/apt/httpcomponents-core-5.0.x/related-projects.apt
deleted file mode 100644
index 2a69703..0000000
--- a/src/site/apt/httpcomponents-core-5.0.x/related-projects.apt
+++ /dev/null
@@ -1,43 +0,0 @@
-~~ ====================================================================
-~~ 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
-~~ regarding copyright ownership. The ASF licenses this file
-~~ 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
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ 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.
-~~ ====================================================================
-~~
-~~ This software consists of voluntary contributions made by many
-~~ individuals on behalf of the Apache Software Foundation. For more
-~~ information on the Apache Software Foundation, please see
-~~ <http://www.apache.org/>.
-
- ----------
- HttpComponents HttpCore Examples
- ----------
- ----------
- ----------
-
-Related projects
-
-* Asynchronous JSON message processors
-
- {{{https://ok2c.github.io/httpcomponents-jackson/}Asynchronous JSON message processors}}
- library is a companion project for HttpCore 5.0 developed outside the Apache Software Foundation.
-
- The library provides a number of asynchronous message consumers and producers
- for efficient, reactive processing of HTTP messages with enclosed JSON content using
- {{{https://github.com/FasterXML/jackson}Jackson JSON processor}}.
-
-
-
diff --git a/src/site/apt/httpcomponents-core-5.1.x/related-projects.apt b/src/site/apt/httpcomponents-core-5.1.x/related-projects.apt
deleted file mode 100644
index 2a69703..0000000
--- a/src/site/apt/httpcomponents-core-5.1.x/related-projects.apt
+++ /dev/null
@@ -1,43 +0,0 @@
-~~ ====================================================================
-~~ 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
-~~ regarding copyright ownership. The ASF licenses this file
-~~ 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
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ 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.
-~~ ====================================================================
-~~
-~~ This software consists of voluntary contributions made by many
-~~ individuals on behalf of the Apache Software Foundation. For more
-~~ information on the Apache Software Foundation, please see
-~~ <http://www.apache.org/>.
-
- ----------
- HttpComponents HttpCore Examples
- ----------
- ----------
- ----------
-
-Related projects
-
-* Asynchronous JSON message processors
-
- {{{https://ok2c.github.io/httpcomponents-jackson/}Asynchronous JSON message processors}}
- library is a companion project for HttpCore 5.0 developed outside the Apache Software Foundation.
-
- The library provides a number of asynchronous message consumers and producers
- for efficient, reactive processing of HTTP messages with enclosed JSON content using
- {{{https://github.com/FasterXML/jackson}Jackson JSON processor}}.
-
-
-
diff --git a/src/site/markdown/httpcomponents-client-4.x/android.md b/src/site/markdown/httpcomponents-client-4.x/android.md
new file mode 100644
index 0000000..9052a0c
--- /dev/null
+++ b/src/site/markdown/httpcomponents-client-4.x/android.md
@@ -0,0 +1,64 @@
+<!--
+ 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
+ regarding copyright ownership. The ASF licenses this file
+ 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
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ 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.
+-->
+
+HttpClient for Android
+======================
+
+Google Android 1.0 was released with a pre-BETA snapshot of Apache HttpClient. To coincide with the first Android
+release Apache HttpClient 4.0 APIs had to be frozen prematurely, while many of interfaces and internal structures were
+still not fully worked out. As Apache HttpClient 4.0 was maturing the project was expecting Google to incorporate the
+latest code improvements into their code tree. Unfortunately it did not happen. Version of Apache HttpClient shipped
+with Android has effectively become a fork.
+
+Eventually Google decided to discontinue further development of their fork while refusing to upgrade to the stock
+version of Apache HttpClient citing compatibility concerns as a reason for such decision. Google completely removed
+their fork of Apache HttpClient from Android in version 8.0 (API 26) only.
+
+Those users who want to continue using Apache HttpClient on Android are advised to consider
+
+* [Apache HttpCLient 5.0](../httpcomponents-client-ga) stock version, which works well with Android API 19 and newer
+
+ ```
+ dependencies {
+ compile group: 'org.apache.httpcomponents.client5' , name: 'httpclient5' , version: '5.0.3'
+ }
+ ```
+
+* Apache HttpClient packages for
+ Android [maintained by Marek Sebera](https://github.com/smarek/httpclient-android/wiki/Project-Introduction) when
+ targeting Android API 23 and newer
+
+ ```
+ dependencies {
+ compile group: 'cz.msebera.android' , name: 'httpclient', version: '4.5.3'
+ }
+ ```
+
+* [Android extensions](https://ok2c.github.io/httpclient-android-ext/) for Apache HttpClient 4.5 when targeting Android
+ API 26 or newer.
+
+ Android extensions for Apache HttpClient provide a replacement for the default `HostnameVerifier`
+ implementation incompatible with Android and provide a builder for `PoolingHttpClientConnectionManager`
+ instances optimized for Android called `AndroidHttpClientConnectionManagerBuilder`.
+
+ ```
+ dependencies {
+ api 'com.github.ok2c.hc4.android:httpclient-android:0.1.0'
+ }
+ ```
diff --git a/src/site/markdown/httpcomponents-client-4.x/logging.md b/src/site/markdown/httpcomponents-client-4.x/logging.md
new file mode 100644
index 0000000..3d238d4
--- /dev/null
+++ b/src/site/markdown/httpcomponents-client-4.x/logging.md
@@ -0,0 +1,259 @@
+<!--
+ 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
+ regarding copyright ownership. The ASF licenses this file
+ 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
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ 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.
+-->
+
+Logging Practices
+=================
+
+Being a library HttpClient is not to dictate which logging framework the user has to use. Therefore HttpClient utilizes
+the logging interface provided by the
+[Commons Logging](http://commons.apache.org/logging/) package. `Commons Logging` provides a simple and generalized
+[log interface](http://commons.apache.org/logging/commons-logging-1.0.4/docs/apidocs/) to various logging packages. By
+using `Commons Logging`, HttpClient can be configured for a variety of different logging behaviours. That means the user
+will have to make a choice which logging framework to use. By default `Commons Logging` supports the following logging
+frameworks:
+
+* [Log4J](http://logging.apache.org/log4j/docs/index.html)
+
+* [java.util.logging](http://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html)
+
+* [SimpleLog](http://commons.apache.org/logging/commons-logging-1.0.4/docs/apidocs/org/apache/commons/logging/impl/SimpleLog.html) (
+ internal to `Commons Logging`)
+
+By implementing some simple interfaces `Commons Logging` can be extended to support basically any other custom logging
+framework. `Commons Logging` tries to automatically discover the logging framework to use. If it fails to select the
+expected one, you must configure `Commons Logging` by hand. Please refer to the `Commons Logging`
+documentation for more information.
+
+HttpClient performs three different kinds of logging: the standard context logging used within each class, HTTP header
+logging and full wire logging.
+
+### Context Logging
+
+Context logging contains information about the internal operation of HttpClient as it performs HTTP requests. Each class
+has its own log named according to the class's fully qualified name. For example the class `DefaultHttpClient` has a log
+named
+`org.apache.http.impl.client.DefaultHttpClient`. Since all classes follow this convention it is possible to configure
+context logging for all classes using the single log named
+`org.apache.http.impl.client`.
+
+### Wire Logging
+
+The wire log is used to log all data transmitted to and from servers when executing HTTP requests. The wire log uses
+the `org.apache.http.wire` logging category. This log should only be enabled to debug problems, as it will produce an
+extremely large amount of log data.
+
+### HTTP header Logging
+
+Because the content of HTTP requests is usually less important for debugging than the HTTP headers,
+the `org.apache.http.headers` logging category for capturing HTTP headers only.
+
+### Configuration Examples
+
+`Commons Logging` can delegate to a variety of loggers for processing the actual output. Below are configuration
+examples for `Commons Logging`, `Log4j` and
+`java.util.logging`.
+
+## Commons Logging Examples
+
+`Commons Logging` comes with a basic logger called `SimpleLog`. This logger writes all logged messages to `System.err`.
+The following examples show how to configure
+`Commons Logging` via system properties to use `SimpleLog`. It is strongly recommended configuring `Commons Logging`
+system properties through JVM process arguments at the start up.
+
+* Enable header wire + context logging - <<Best for Debugging>>
+
+ ```
+ -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
+ -Dorg.apache.commons.logging.simplelog.showdatetime=true
+ -Dorg.apache.commons.logging.simplelog.log.org.apache.http=DEBUG
+ -Dorg.apache.commons.logging.simplelog.log.org.apache.http.wire=ERROR
+ ```
+
+* Enable full wire + context logging
+
+ ```
+ -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
+ -Dorg.apache.commons.logging.simplelog.showdatetime=true
+ -Dorg.apache.commons.logging.simplelog.log.org.apache.http=DEBUG
+ ```
+
+* Enable context logging for connection management
+
+ ```
+ -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
+ -Dorg.apache.commons.logging.simplelog.showdatetime=true
+ -Dorg.apache.commons.logging.simplelog.log.org.apache.http.impl.conn=DEBUG
+ ```
+
+* Enable context logging for connection management / request execution
+
+ ```
+ -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
+ -Dorg.apache.commons.logging.simplelog.showdatetime=true
+ -Dorg.apache.commons.logging.simplelog.log.org.apache.http.impl.conn=DEBUG
+ -Dorg.apache.commons.logging.simplelog.log.org.apache.http.impl.client=DEBUG
+ -Dorg.apache.commons.logging.simplelog.log.org.apache.http.client=DEBUG
+ ```
+
+## Log4j Examples
+
+The simplest way to configure `Log4j` is via a `log4j.properties` file. `Log4j` will automatically read and configure
+itself using a file named `log4j.properties` when it's present at the root of the application classpath. Below are
+some `Log4j` configuration examples.
+
+**Note:** `Log4j` is not included in the `HttpClient` distribution.
+
+* Enable header wire + context logging - **Best for Debugging**
+
+ ```
+ log4j.rootLogger=INFO, stdout
+
+ log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+ log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+ log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n
+
+ log4j.logger.org.apache.http=DEBUG
+ log4j.logger.org.apache.http.wire=ERROR
+ ```
+
+* Enable full wire + context logging
+
+ ```
+ log4j.rootLogger=INFO, stdout
+
+ log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+ log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+ log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n
+
+ log4j.logger.org.apache.http=DEBUG
+ ```
+
+* Enable context logging for connection management
+
+ ```
+ log4j.rootLogger=INFO, stdout
+
+ log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+ log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+ log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n
+
+ log4j.logger.org.apache.http.impl.conn=DEBUG
+ ```
+
+* Enable context logging for connection management / request execution
+
+ ```
+ log4j.rootLogger=INFO, stdout
+
+ log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+ log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+ log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n
+
+ log4j.logger.org.apache.http.impl.conn=DEBUG
+ log4j.logger.org.apache.http.impl.client=DEBUG
+ log4j.logger.org.apache.http.client=DEBUG
+ ```
+
+Note that the default configuration for Log4J is very inefficient as it causes all the logging information to be
+generated but not actually sent anywhere. The `Log4J` manual is the best reference for how to configure `Log4J`. It is
+available at http://logging.apache.org/log4j/docs/manual.html .
+
+### java.util.logging Examples
+
+Since JDK 1.4 there has been a package
+[java.util.logging](http://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html) that provides a
+logging framework similar to `Log4J`. By default it reads a config file from `$JAVA_HOME/jre/lib/logging.properties`
+which looks like this (comments stripped):
+
+```
+handlers=java.util.logging.ConsoleHandler
+.level=INFO
+java.util.logging.FileHandler.pattern = %h/java%u.log
+java.util.logging.FileHandler.limit = 50000
+java.util.logging.FileHandler.count = 1
+java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
+java.util.logging.ConsoleHandler.level = INFO
+java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
+com.xyz.foo.level = SEVERE
+```
+
+To customize logging a custom `logging.properties` file should be created in the project directory. The location of this
+file must be passed to the JVM as a system property. This can be done on the command line like so:
+
+```
+$JAVA_HOME/java -Djava.util.logging.config.file=$HOME/myapp/logging.properties
+-classpath $HOME/myapp/target/classes com.myapp.Main
+```
+
+Alternatively [LogManager#readConfiguration(InputStream)](http://docs.oracle.com/javase/7/docs/api/java/util/logging/LogManager.html#readConfiguration(java.io.InputStream))
+can be used to pass it the desired configuration.
+
+* Enable header wire + context logging - **Best for Debugging**
+
+ ```
+ .level = INFO
+
+ handlers=java.util.logging.ConsoleHandler
+ java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
+ java.util.logging.ConsoleHandler.level = ALL
+
+ org.apache.http.level = FINEST
+ org.apache.http.wire.level = SEVERE
+ ```
+
+* Enable full wire + context logging
+
+ ```
+ .level = INFO
+
+ handlers=java.util.logging.ConsoleHandler
+ java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
+ java.util.logging.ConsoleHandler.level = ALL
+
+ org.apache.http.level = FINEST
+ ```
+
+* Enable context logging for connection management
+
+ ```
+ .level = INFO
+
+ handlers=java.util.logging.ConsoleHandler
+ java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
+ java.util.logging.ConsoleHandler.level = ALL
+
+ org.apache.http.impl.conn.level = FINEST
+ ```
+
+* Enable context logging for connection management / request execution
+
+ ```
+ .level = INFO
+
+ handlers=java.util.logging.ConsoleHandler
+ java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
+ java.util.logging.ConsoleHandler.level = ALL
+
+ org.apache.http.impl.conn.level = FINEST
+ org.apache.http.impl.client.level = FINEST
+ org.apache.http.client.level = FINEST
+ ```
+
+More detailed information is available from the
+[Java Logging documentation](http://docs.oracle.com/javase/7/docs/technotes/guides/logging/overview.html).
\ No newline at end of file
diff --git a/src/site/markdown/httpcomponents-client-4.x/ntlm.md b/src/site/markdown/httpcomponents-client-4.x/ntlm.md
new file mode 100644
index 0000000..1707acd
--- /dev/null
+++ b/src/site/markdown/httpcomponents-client-4.x/ntlm.md
@@ -0,0 +1,145 @@
+<!--
+ 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
+ regarding copyright ownership. The ASF licenses this file
+ 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
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ 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.
+-->
+
+NTLM support in HttpClient
+==========================
+
+Background
+----------
+
+NTLM is a proprietary authentication scheme developed by Microsoft and optimized for Windows operating system.
+
+Until year 2008 there was no official, publicly available, complete documentation of the
+protocol. [Unofficial](http://davenport.sourceforge.net/ntlm.html) 3rd party protocol descriptions existed as a result
+of reverse-engineering efforts. It was not really known whether the protocol based on the reverse-engineering were
+complete or even correct.
+
+Microsoft
+published [MS-NLMP](http://download.microsoft.com/download/a/e/6/ae6e4142-aa58-45c6-8dcf-a657e5900cd3/%5BMS-NLMP%5D.pdf)
+and [MS-NTHT](http://download.microsoft.com/download/a/e/6/ae6e4142-aa58-45c6-8dcf-a657e5900cd3/%5BMS-NTHT%5D.pdf)
+specifications in February 2008 as a part of its
+[Interoperability Principles initiative](http://www.microsoft.com/interop/principles/default.mspx).
+
+HttpClient as of version 4.1 initially supported NTLMv1, NTLMv2, and NTLM2SessionResponse authentication protocols,
+based on the reverse engineering approach. As of version 4.2.3, HttpClient now supports a more correct implementation,
+based in large part on Microsoft's own specifications. This is expected to correct a number of problems, especially
+since Microsoft (as of Windows Server 2008 R2) began using a new implementation of its protocols. This new Microsoft
+implementation has led to authentication failures in some cases from some of the older reverse-engineered client
+implementations of NTLM.
+
+The new HttpClient NTLM implementation is known to have been tried successfully against at least the following systems:
+
+* Windows Server 2000 and Server 2003 systems, configured to use LM and NTLMv1 authentication
+
+* Windows Server 2003 systems, configured to use NTLMv2 authentication
+
+* Windows Server 2008 R2 systems, configured to use NTLM2SessionResponse authentication
+
+If the current HttpClient NTLM implementation should prove problematic in your environment, we'd definitely like to hear
+about it. You are also welcome to try an alternative NTLM implementation, should it seem necessary. One can also
+use [JCIFS](http://jcifs.samba.org/), which includes an NTLM engine developed by members of the Samba project.
+
+Using Samba JCIFS as an alternative NTLM engine
+-----------------------------------------------
+
+Follow these instructions to build an NTLMEngine implementation using JCIFS library
+
+***Disclaimer: Use code at your own discretion. Do NOT report any issues related to the use of JCIFS library to Apache
+HttpComponents project***.
+
+* Download version 1.3.14 or newer of the JCIFS library from the [Samba](http://jcifs.samba.org/) web site
+
+* Implement NTLMEngine interface
+
+ ```
+ import java.io.IOException;
+
+ import jcifs.ntlmssp.NtlmFlags;
+ import jcifs.ntlmssp.Type1Message;
+ import jcifs.ntlmssp.Type2Message;
+ import jcifs.ntlmssp.Type3Message;
+ import jcifs.util.Base64;
+
+ import org.apache.http.impl.auth.NTLMEngine;
+ import org.apache.http.impl.auth.NTLMEngineException;
+
+ public final class JCIFSEngine implements NTLMEngine {
+
+ private static final int TYPE_1_FLAGS =
+ NtlmFlags.NTLMSSP_NEGOTIATE_56 |
+ NtlmFlags.NTLMSSP_NEGOTIATE_128 |
+ NtlmFlags.NTLMSSP_NEGOTIATE_NTLM2 |
+ NtlmFlags.NTLMSSP_NEGOTIATE_ALWAYS_SIGN |
+ NtlmFlags.NTLMSSP_REQUEST_TARGET;
+
+ public String generateType1Msg(final String domain, final String workstation)
+ throws NTLMEngineException {
+ final Type1Message type1Message = new Type1Message(TYPE_1_FLAGS, domain, workstation);
+ return Base64.encode(type1Message.toByteArray());
+ }
+
+ public String generateType3Msg(final String username, final String password,
+ final String domain, final String workstation, final String challenge)
+ throws NTLMEngineException {
+ Type2Message type2Message;
+ try {
+ type2Message = new Type2Message(Base64.decode(challenge));
+ } catch (final IOException exception) {
+ throw new NTLMEngineException("Invalid NTLM type 2 message", exception);
+ }
+ final int type2Flags = type2Message.getFlags();
+ final int type3Flags = type2Flags
+ & (0xffffffff ^ (NtlmFlags.NTLMSSP_TARGET_TYPE_DOMAIN | NtlmFlags.NTLMSSP_TARGET_TYPE_SERVER));
+ final Type3Message type3Message = new Type3Message(type2Message, password, domain,
+ username, workstation, type3Flags);
+ return Base64.encode(type3Message.toByteArray());
+ }
+
+ }
+ ```
+
+* Implement AuthSchemeProvider interface
+
+ ```
+ public class JCIFSNTLMSchemeFactory implements AuthSchemeProvider {
+
+ public AuthScheme create(final HttpContext context) {
+ return new NTLMScheme(new JCIFSEngine());
+ }
+ }
+ ```
+
+* Register NTLMSchemeFactory with the HttpClient instance you want to NTLM enable.
+
+ ```
+ Registry<AuthSchemeProvider> authSchemeRegistry = RegistryBuilder.<AuthSchemeProvider>create()
+ .register(AuthSchemes.NTLM, new JCIFSNTLMSchemeFactory())
+ .register(AuthSchemes.BASIC, new BasicSchemeFactory())
+ .register(AuthSchemes.DIGEST, new DigestSchemeFactory())
+ .register(AuthSchemes.SPNEGO, new SPNegoSchemeFactory())
+ .register(AuthSchemes.KERBEROS, new KerberosSchemeFactory())
+ .build();
+ CloseableHttpClient httpClient = HttpClients.custom()
+ .setDefaultAuthSchemeRegistry(authSchemeRegistry)
+ .build();
+ ```
+
+* Set NTCredentials for the web server you are going to access.
+
+
diff --git a/src/site/markdown/httpcomponents-client-4.x/primer.md b/src/site/markdown/httpcomponents-client-4.x/primer.md
new file mode 100644
index 0000000..93833ad
--- /dev/null
+++ b/src/site/markdown/httpcomponents-client-4.x/primer.md
@@ -0,0 +1,487 @@
+<!--
+ 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
+ regarding copyright ownership. The ASF licenses this file
+ 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
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ 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.
+-->
+
+Client HTTP Programming Primer
+==============================
+
+About
+-----
+
+This document is intended for people who suddenly have to or want to implement an application that automates something
+usually done with a browser, but are missing the background to understand what they actually need to do. It provides
+guidance on the steps required to implement a program that interacts with a web site which is designed to be used with a
+browser. It does not save you from eventually learning the background of what you are doing, but it should help you to
+get started quickly and learn the details later.
+
+This document has evolved from discussions on the HttpClient mailing lists. Although it refers to HttpClient, the
+concepts described here apply equally to HttpComponents or
+Java's [HttpURLConnection](http://docs.oracle.com/javase/7/docs/api/java/net/HttpURLConnection.html)
+or any other HTTP communication library for any programming language. So you might find it useful even if you're not
+using Java and HttpClient.
+
+The existence of this document does not imply that the HttpClient community feels responsible for teaching you how to
+program a client HTTP application. It is merely a way for us to reduce the noise on the mailing list without just
+leaving the newbies out in the cold.
+
+Scenario
+--------
+
+Let's assume that you have some kind of repetitive, web-based task that you want to automate. Something like:
+
+* goto page http://xxx.yyy.zzz/login.html
+
+* enter username and password in a web form and hit the "login" button
+
+* navigate to a specific page
+
+* check the number/headline/whatever shown on that page
+
+At this time, we don't have a specific example which could be developed into a sample application. So this document is
+all bla-bla, and you will have to work out the details - all the details - yourself. Such is life.
+
+Caveat
+------
+
+This scenario describes a hobbyist usage of HTTP, in other words:
+***a bad practice***. Web sites are designed for user interaction, not as an application programming interface (API).
+The interface of a web site is the user interface displayed by a browser. The HTTP communication between the browser and
+the server is an internal API, subject to change without notice.
+
+A web site can be redesigned at any point in time. The server then sends different documents and a browser will display
+the new content. The user easily adjusts to click the appropriate links, and the browser communicates via HTTP as
+specified by the new documents from the server. Your application that only mimicks a browser will simply break.
+
+Nevertheless, implementing this scenario will help you to get familiar with HTTP communication. It is also "good enough"
+for hobbyists applications, for example if you want to download the latest installment of your favorite daily webcomic
+to install it as the screen background. There is no big damage if such an application breaks.
+
+If you want to implement a solid application, you should use only published APIs. For example, to check for new mail on
+your webmail account, you should ask the webmail provider for POP or IMAP access. These are standardized protocols
+supported my most EMail client applications. If you want to have a newsticker, look for RSS feeds from the provider and
+applications that display them.
+
+As another example, if you want to perform a web search, there are search companies that provide an API for using their
+search engines. Unlike the examples before, such APIs are proprietary. You will still have to implement an application,
+but then you are using a published API that the provider will not change without notice.
+
+Not a Browser
+-------------
+
+HttpClient is not a browser. It is an HTTP communication library and as such it provides only a subset of functions
+expected from a common browser application. The most fundamental difference is absence of user interface in HttpClient.
+The browser needs a rendering engine to display pages, and to interpret user input such as mouse clicks somewhere on the
+displayed page. There is a layout engine which computes how an HTML page should be displayed, including cascading style
+sheets and images. A JavaScript interpreter runs JavaScript code embedded in or referenced from HTML pages. Events from
+the user interface are passed to the JavaScript interpreter for processing. On top of that, there are interfaces for
+plugins that can handle Applets, embedded media objects like PDF files, Quicktime movies and Flash animations, or
+ActiveX controls that can do anything. HttpClient can only be used programmatically through its APIs to transmit and
+receive HTTP messages. HttpClient is also completely content agnostic. It can transfer message content but it is unable
+to render or process it in any fashion.
+
+Another major difference is tolerance for bad input or HTTP standard violations. There needs to be tolerance for invalid
+user input to make the browser user friendly. There also needs to be tolerance for malformed documents retrieved from
+servers, and for flaws in server behavior when executing protocols, to make as many websites as possible accessible to
+the user. HttpClient is however strives to adhere to the HTTP standard specification and related standards as close and
+as possible by default. It also provides means to relaxing some of the restrictions imposed by the specification where
+permissible or required for compatibility with non-compliant HTTP origin or proxy servers.
+
+Terminology
+-----------
+
+This section introduces some important terms you have to know to understand the rest of this document.
+
+### HTTP Message
+
+consists of a header section and an optional entity. There are two kinds of messages, requests and responses. They
+differ in the format of the first line, but both can have header fields and an optional entity.
+
+### HTTP Request
+
+is sent from a client to a server. The first line includes the URI for which the request is sent, and a method that the
+server should execute for the client.
+
+### HTTP Response
+
+is sent from a server to a client in response to a request. The first line includes a status code that tells about
+success or failure of the request. HTTP defines a set of status codes, like 200 for success and 404 for not found. Other
+protocols based on HTTP can define additional status codes.
+
+### Method
+
+is an operation requested from the server. HTTP defines a set of operations, the most frequent being GET and POST. Other
+protocols based on HTTP can define additional methods.
+
+### Header Fields
+
+are name-value pairs, where both name and value are text. The name of a header field is not case sensitive. Multiple
+values can be assigned to the same name. RFC 2616 defines a wide range of header fields for handling various aspects of
+the HTTP protocol. Other specifications, like RFC 2617 and RFC 2965, define additional headers. Some of the defined
+headers are for general use, others are meant for exclusive use with either requests or responses, still others are
+meant for use only with an entity.
+
+### Entity
+
+is data sent with an HTTP message. For example, a response can contain the page or image you are downloading as an
+entity, or a request can include the parameters that you entered into a web form. The entity of an HTTP message can have
+an arbitrary data format, which is usually specified as a MIME type in a header field.
+
+### Session
+
+is a series of requests from a single source to a server. The server can keep session data, and needs to recognize the
+session to which each incoming request belongs. For example, if you execute a web search, the server will only return
+one page of search results. But it keeps track of the other results and makes them available when you click on the link
+to the "next" page. The server needs to know from the request that it is you and your session for which more results are
+requested, and not me and my session. That's because I searched for something else.
+
+### Cookies
+
+are the preferred way for servers to track sessions. The server supplies a piece of data, called a cookie, in response
+to a request. The server expects the client to send that piece of data in a header field with each following request of
+the same session. The cookie is different for each session, so the server can identify to which session a request
+belongs by looking at the cookie. If the cookie is missing from a request, the server will not respond as expected.
+
+Step by Step
+------------
+
+### GET the Login Page
+
+Create and execute a GET request for the login page. Just use the link you would type into the browser as the URL. This
+is what a browser does when you enter a URL in the address bar or when you click on a link that points to another web
+page.
+
+Inspect the response from the server:
+
+* do you get the page you expected?
+
+It should be sent as the entity of the response to your request. The entity is also referred to as the response body.
+
+* do you get a session cookie?
+
+Cookies are sent in a header field named Set-Cookie or Set-Cookie2. It is possible that you don't get a session cookie
+until you log in. If there is no session cookie in the response, you'll have to do perform step 2 later, after you reach
+the point where the cookie is set.
+
+If you do not get the page you expect, check the URL you are requesting. If it is correct, the server may use a browser
+detection. You will have to set the header field User-Agent to a value used by a popular browser to pretend that the
+request is coming from that browser.
+
+If you can't get the login page, get the home page instead now. Get the login page in the next step, when you establish
+the session.
+
+### Establish the Session
+
+Create and execute another GET request for a page. You can simply request the login page again, or some other page of
+which you know the URL. Do NOT try to get a page which would be returned in response to submitting a web form. Use
+something you can reach simply by clicking on a link in the browser. Something where you can see the URL in the browser
+status line while the mouse pointer is hovering over the link.
+
+This step is important when developing the application. Once you know that your application does establish the session
+correctly, you may be able to remove it. Only if you couldn't get the login page directly and had to get the home page
+first, you know you have to leave it in.
+
+Inspect the request being sent to the server.
+
+* is the session cookie sent with the request?
+
+You can see what is sent to the server by enabling the wire log for HttpClient. You only need to see the request
+headers, not the body. The session cookie should be sent in a header field called Cookie. There may be several of those,
+and other cookies might be sent as well.
+
+Inspect the response from the server:
+
+* do you get another session cookie?
+
+You should not get another session cookie. If you get the same session cookie as before, the server behaves a little
+strange but that should not be a problem. If you get a new session cookie, then the server did not recognize the session
+for the request. Usually, this happens if the request did not contain the session cookie. But servers might use other
+means to track sessions, or to detect session hijacking.
+
+If the session cookie is not sent in the request, one of two things has gone wrong. Either the cookie was not detected
+in the previous response, or the cookie was not selected for being sent with the new request.
+
+HttpClient automatically parses cookies sent in responses and puts them into a cookie store. HttpClient uses a
+configurable cookie policy to decide whether a cookie being sent from a server is correct. The default policy complies
+strictly with RFC 2109, but many servers do not. Play around with the cookie policies until the cookie is accepted and
+put into the cookie store.
+
+If the cookie is accepted from the previous response but still not sent with the new request, make sure that HttpClient
+uses the same cookie store object. Unless you explicitly manage cookie store objects (not recommended for newbies!),
+this will be the case if you use the same HttpClient object to execute both requests.
+
+If the cookie is still not sent with the request, make sure that the URL you are requesting is in the scope for the
+cookie. Cookies are only sent to the domain and path specified in the cookie scope. A cookie for host "
+jakarta.apache.org" will not be sent to host
+"tomcat.apache.org". A cookie for domain ".apache.org" will be sent to both. A cookie for host "apache.org", without the
+leading dot, will not be sent to "jakarta.apache.org". The latter case can be resolved by using a different cookie spec
+that adds the leading dot. In the other cases, use a URL that in the cookie scope to establish the session.
+
+If the session cookie is sent with the request, but a new session cookie is set in the response anyway, check whether
+there are cookies other than the session cookie in the request. Some servers are incapable of detecting multiple cookies
+sent in individual header fields. HttpClient can be advised to put all cookies into a single header field.
+
+If that doesn't help, you are in trouble. The server may use additional means to track the session, for example the
+header field named Referer. Set that field to the URL of the previous request.
+([see this mail](http://mail-archives.apache.org/mod_mbox/jakarta-httpclient-user/200602.mbox/%3c19b.44e04b45.31166eaa@aol.com%3e))
+
+If that doesn't help either, you will have to compare the request from your application to a corresponding one generated
+by a browser. The instructions in step 5 for POST requests apply for GET requests as well. It's even simpler with GET,
+since you don't have an entity.
+
+### Analyze the Form
+
+Now it is time to analyze the form defined in the HTML markup of the page. A form in HTML is a set of name-value-pairs
+called parameters, where some of the values can be entered in the browser. By analyzing the HTML markup, you can learn
+which parameters you have to define and how to send them to the server.
+
+Look for the `<form>` tag in the page source. There may be several forms in the page, but they can not be nested. Locate
+the form you want to submit. Locate the matching `</form>` tag. Everything in between the two may be relevant. Let's
+start with the {attributes of the `<form>` tag}:
+
+##### method
+
+specifies the method used for submitting the form. If it is GET or not specified at all, then you need to create a GET
+request. The parameters will be added as a query string to the URL. If the method is POST, you need to create a POST
+request. The parameters will be put in the entity of the request, also referred to as the request body. How to do that
+is discussed in step 5.
+
+##### action
+
+specifies the URL to which the request has to be sent. Do not try to get this URL from the address bar of your browser!
+A browser will automatically follow redirects and only displays the final URL, which can be different from the URL in
+this attribute. It is possible that the URL includes a query string that specifies some parameters. If so, keep that in
+mind.
+
+##### enctype
+
+specifies the MIME type for the entity of the request generated by the form. The two common cases are url-encoded (
+default) and multipart-mime. Note that these terms are just informally used here, the exact values that need to be
+written in an HTML document are specified elsewhere. This attribute is only used for the POST method. If the method is
+GET, the parameters will always be url-encoded, but not in an entity.
+
+##### accept-charset
+
+specifies the character set that the browser should allow for user input. It will not be discussed here, but you will
+have to consider this value if you experience charset related problems.
+
+Except for optional query parameters in the action attribute, the parameters of a form are specified by HTML tags
+between <form> and </form>. The following is a list of tags that can be used to define parameters. Except where stated
+otherwise, they have a name attribute which specifies the name of the parameter. The value of the parameter usually
+depends on user input.
+
+```
+<input type="text" name="...">
+<input type="password" name="...">
+```
+
+specify single-line input fields. Using the return key in one of these fields will submit the form, so the value really
+is a single line of input from the user.
+
+```
+<input type="text" readonly name="..." value="...">
+<input type="hidden" name="..." value="...">
+```
+
+specify a parameter that can not be changed by the user. The value of the parameter is given by the value attribute.
+
+```
+<input type="radio" name="..." value="...">
+<input type="checkbox" name="..." value="...">
+```
+
+specify a parameter that can be included or omitted. There usually is more than one tag with the same name. For radio
+buttons, only one can be selected and the value of the parameter is the value of the selected radio button. For
+checkboxes, more than one can be selected. There will be one name-value-pair for each selected checkbox, with the same
+name for all of them.
+
+```
+<input type="submit" name="..." value="...">
+<button type="submit" name="..." value="...">
+```
+
+specify a button to submit the form. The parameter will only be added to the form if that button is used to submit. If
+another button is used, or the form is submitted by pressing the return key in a text input field, the parameter is not
+part of the submitted form data. If the name attribute is missing, no parameter is added to the form data for that
+button.
+
+```
+<textarea name="...">
+<textarea value="..." readonly>
+```
+
+specify a multi-line input field. In the readonly case, the value of the parameter is the text between the `<textarea>`
+and `</textarea>` tags.
+
+```
+<select name="..." multiple>}}}
+ <option value="...">...</option>}}}
+ <option value="...">...</option>}}}
+ ...
+</select>
+```
+
+specify a selection list or drop-down menu. If the multiple attribute is not present, only one option can be selected.
+There will be one name-value-pair for each selected option, with the same name for all of them. If there is no value
+attribute, the value for that option is the text between <option> and </option>.
+
+```
+<input type="image" name="...">
+```
+
+specifies an image that can be clicked to submit the form. If that image is clicked to submit the form, two parameters
+are added to the form data. The name attribute is suffixed with ".x" and ".y", the values for the parameters are the
+relative coordinates of the mouse pointer within the image at the time of the click, in pixel. If the name attribute is
+missing, no parameters will be added to the form data.
+
+```
+<input type="file" name="...">
+```
+
+specifies a file selection box. The user can select a file that should be sent as part of the form data. This is only
+possible if the encoding is multipart-mime. Unlike other parameters, the file is not mapped to a simple name-value-pair.
+File upload is not a topic for beginners.
+
+These tags are used to define parameters in static HTML. With dynamic HTML, in particular JavaScript, the parameter
+values can be changed before the form is submitted. If that is the case, you are in trouble. Learn JavaScript, analyze
+the code that is executed, and modify your application to match that behavior.
+
+### Analyze the Form, Again
+
+After you have determined the action URL and name-value-pairs of a form, you should exit the program you used to get the
+HTML source, start it again and repeat the analysis with the new page.
+
+Most parameters will be the same for both pages. But some parameters, in particular those from hidden input fields, may
+change from session to session, or even with every request. The same can be the case with the action URL.
+
+Parameters that remain the same can be hard-coded in your program. If parameters change (except for user input), then
+your application has to request the page with the form and extract the dynamic parameters at runtime. If you're lucky
+you can locate them by simple string searches. If you're unlucky, you need an HTML parser to make sense of the page.
+HTML parsing is out of scope for HttpClient, but you'll find some HTML parsers mentioned in the mailing list archives.
+
+Note that a redesign of the form on the server can break your application at any time. Whenever that happens, you have
+to repeat the analysis with the new form returned by the server after the redesign, and adjust your application
+accordingly.
+
+### POST the Form
+
+After analyzing the form, it is time to create a request that matches what a browser would generate. If the method is
+GET, just add the name-value-pairs for all parameters to the query string. If the method is POST, things are a little
+more complicated.
+
+It depends on the server how closely you have to match browser behavior. For example, a servlet will not distinguish
+between parameters in the query string and url-encoded parameters of the entity. But other server side code might make
+that distinction. The safe way is always to match browser behavior exactly.
+
+HttpClient supports both encoding types, url-encoded and multipart-mime. To send parameters url-encoded, use the POST
+request and add the parameters directly there. To send parameters in multipart-mime, collect the parameters in a
+multipart-encoded request entity and add set the entity for the POST request. You will also find support for file upload
+in the multipart package. Note that these techniques are mutually exclusive, they can not be combined. Parameters
+defined in the query string of the URL can remain there.
+
+Send the request. Inspect the response from the server:
+
+* do you get a status code 303 or 307?
+
+That is called a redirect. Follow redirects to the ultimate page and inspect that response. See step 6 on following
+redirects.
+
+* do you get the page you expected?
+
+If the server response to your POST request indicates a problem, try to enable or disable the expect-continue handshake,
+or switch the protocol version to HTTP/1.0. If that doesn't help...
+
+Inspect the request you are sending:
+
+* are there significant differences to the request of a browser?
+
+There is a variety of sniffer programs you can use to grep the browser request. Some of them are mentioned in the
+responses
+to [on the mailing list](http://mail-archives.apache.org/mod_mbox/jakarta-httpclient-user/200603.mbox/%3c981224FF5B88B349B7C1FED584D2620E02A2CBB2@CORPUSMX50B.corp.emc.com%3e
+this question).
+
+Candidates for problems are missing or wrong parameters, and differences in the header fields. The parameters are all up
+to you. As a general rule for the header fields, you should send the same as the browser does. The order of the fields
+does not matter.
+
+But there's a caveat: some header fields are controlled by HttpClient and can not be set explicitly. Other header fields
+are used to indicate capabilities which a browser has, but your application probably has not. For these, the request
+from your application has to and should differ. Here is a possibly incomplete list of headers that need special
+consideration:
+
+* `Host`
+
+ controlled by HttpClient. The value is usually obtained from the URL you are posting to. It is possible to set a
+ different value, called a "virtual host".
+
+* `Content-Type`
+
+* `Content-Length`
+
+* `Transfer-Encoding`
+
+ controlled by HttpClient. The values are obtained from the request entity.
+
+* `Connection`
+
+ usually controlled by HttpClient to handle connection keep-alive. Leave it alone or set the value to "close".
+
+* `Content-Encoding`
+
+ used to indicate the capability to process compressed responses. Do not set this, unless you are prepared to implement
+ decompression.
+
+### Follow Redirects
+
+It is quite common for servers to respond with a 303 or 307 status code to a POST request. These redirects indicate that
+your application has to send another request to retrieve the actual result of the operation you have triggered with the
+POST request.
+
+HttpClient can be configured to follow some redirects automatically. Others it is not allowed to follow automatically,
+since RFC 2616 specifies that a user interaction should take place. We will make sure that HttpClient is compliant with
+this requirement, but we can't stop you from implementing a different behavior in your application. The Location header
+field in the redirect response indicates the URL from which to fetch the actual page. It is common practice that servers
+return a relative URL as the location, although the specification requires an absolute URL.
+
+Note that there may be more than one redirect in succession. Your application then has to follow the redirect for a
+redirect, but make sure that you do not enter an infinite loop. If you find that there are more than two redirects in
+succession, something probably is fishy.
+
+### Logout
+
+Your application can send as many GET and POST requests and follow as many redirects as is required. But you should
+remember that there is a session tracked by the server. Once your application is done, and if the web site does provide
+a logout link, you should send a final request to log out. This will tell the server that the session data can be
+discarded. If the server prevents multiple logins with the same user ID and your application has to run repeatedly,
+logout may even be required.
+
+Further Reading
+---------------
+
+ReferenceMaterials: a list of technical specifications for HTTP and related stuff.
+
+* [ HTML 4.01 Specification, Section on Forms](http://www.w3.org/TR/html4/interact/forms.html): Includes how browsers
+ have to generate the data to submit to the server.
+
+* [Giving Form to Forms](https://digital.com/tools/html-cheatsheet/):
+ Explains how to define HTML forms and what is submitted to the server. Probably easier to digest than the HTML 4.01
+ Specification.
+
+* [Commons File Upload](http://jakarta.apache.org/commons/fileupload/): Server-side library for parsing multipart
+ requests.
+
+* [Tutorial on File Upload in HTML](http://www.cs.tut.fi/~jkorpela/forms/file.html)
diff --git a/src/site/markdown/httpcomponents-client-5.x/android.md b/src/site/markdown/httpcomponents-client-5.x/android.md
new file mode 100644
index 0000000..0388d3f
--- /dev/null
+++ b/src/site/markdown/httpcomponents-client-5.x/android.md
@@ -0,0 +1,26 @@
+<!--
+ 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
+ regarding copyright ownership. The ASF licenses this file
+ 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
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ 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.
+-->
+
+HttpClient for Android
+======================
+
+Apache HttpCLient 5.x is expected to work well with Android API 19 and newer.
+
+There is a companion project [Android extensions](https://ok2c.github.io/httpclient-android-ext/) which is a third party
+library that provides extra functionality simplifying application of Apache HttpClient on Google Android platform.
diff --git a/src/site/markdown/httpcomponents-client-5.x/logging.md b/src/site/markdown/httpcomponents-client-5.x/logging.md
new file mode 100644
index 0000000..423332b
--- /dev/null
+++ b/src/site/markdown/httpcomponents-client-5.x/logging.md
@@ -0,0 +1,178 @@
+<!--
+ 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
+ regarding copyright ownership. The ASF licenses this file
+ 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
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ 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.
+-->
+
+Logging Practices
+=================
+
+Being a library HttpClient is not to dictate which logging framework the user has to use. Therefore HttpClient utilizes
+the logging facade provided by the [Simple Logging Facade for Java (SLF4J)](http://slf4j.org/) package. `SLF4J` provides
+a simple and generalized [log interface](http://slf4j.org/manual.html) to various logging packages. By using `SLF4J`,
+HttpClient can be configured for a variety of different logging behaviours. That means the user will have to make a
+choice which logging implementation to use. There are several popular logging backends that can be used through
+the `SLF4J` facade APIs:
+
+- [Logback](http://logback.qos.ch/)
+
+- [Log4j 2](http://logging.apache.org/log4j/2.x/index.html)
+
+- [SimpleLogger](http://slf4j.org/api/org/slf4j/impl/SimpleLogger.html) (internal to `SLF4J`)
+
+- [java.util.logging](http://slf4j.org/api/org/slf4j/impl/JDK14LoggerAdapter.html) (internal to `SLF4J`)
+
+HttpComponents project however mostly works with [Log4j 2](http://logging.apache.org/log4j/2.x/index.html) backend and
+recommends it to our users.
+
+HttpClient performs three different kinds of logging: the standard context logging used within each class, HTTP header
+logging and full wire logging.
+
+Understanding Logger Names
+--------------------------
+
+Most logging implementations use a hierarchical scheme for matching logger names with logging configuration. In this
+scheme, the logger name hierarchy is represented by '`.`' characters in the logger name, in a fashion very similar to
+the hierarchy used for Java package names. For example, `org.apache.logging.appender` and `org.apache.logging.filter`
+both have `org.apache.logging` as their parent. In most cases, applications name their loggers by passing the current
+class's name to `LogManager.getLogger(...)`.
+
+### Context Logging
+
+Context logging contains information about the internal operation of HttpClient as it performs HTTP requests. Each class
+has its own logger named according to the class's fully qualified name. For example the class `DefaultHttpClient` has a
+logger named `org.apache.http.impl.client.DefaultHttpClient`. Since all classes follow this convention it is possible to
+configure context logging for all classes using the single logger named
+`org.apache.hc.client5.http`.
+
+### Wire Logging
+
+The wire logger is used to log all data transmitted to and from servers when executing HTTP requests. The wire logger
+uses the `org.apache.hc.client5.http.wire` logger name. This logger should only be enabled to debug problems, as it will
+produce an extremely large amount of log data.
+
+### HTTP header Logging
+
+Because the content of HTTP requests is usually less important for debugging than the HTTP headers, use the `
+org.apache.hc.client5.http.headers` logger for capturing HTTP headers only.
+
+Configuration Examples
+----------------------
+
+`SLF4J` can delegate to a variety of logging implementations for processing the actual output. Below are configuration
+examples for `Log4j 2`, `Commons Logging`, and `java.util.logging`.
+
+### Log4j 2 Examples
+
+The simplest way to [configure](https://logging.apache.org/log4j/2.x/manual/configuration.html) `Log4j 2` is via
+a `log4j2.xml` file. `Log4j 2`
+will [automatically](https://logging.apache.org/log4j/2.x/manual/configuration.html#AutomaticConfiguration) configure
+itself using a file named `log4j2.xml` when it's present at the root of the application classpath.
+
+Below are some `Log4j` configuration examples.
+
+**Note:** The `Log4j 2` implementation a.k.a "core" is not included in the `HttpClient` distribution. You can include it
+in your project using [Maven, Ivy, Gradle, or SBT](https://logging.apache.org/log4j/2.x/maven-artifacts.html).
+
+- Enable header wire + context logging - **Best for Debugging**
+
+ ```
+ <Configuration>
+ <Appenders>
+ <Console name="STDOUT">
+ <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Logger name="org.apache.hc.client5.http" level="DEBUG">
+ <AppenderRef ref="Console"/>
+ </Logger>
+ <Logger name="org.apache.hc.client5.http.wire" level="DEBUG">
+ <AppenderRef ref="Console"/>
+ </Logger>
+ <Root level="INFO">
+ <AppenderRef ref="STDOUT" />
+ </Root>
+ </Loggers>
+ </Configuration>
+ ```
+
+- Enable full wire + context logging
+
+ ```
+ <Configuration>
+ <Appenders>
+ <Console name="STDOUT">
+ <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Logger name="org.apache.hc.client5.http" level="DEBUG">
+ <AppenderRef ref="Console"/>
+ </Logger>
+ <Root level="INFO">
+ <AppenderRef ref="STDOUT" />
+ </Root>
+ </Loggers>
+ </Configuration>
+ ```
+
+- Enable context logging for connection management
+
+ ```
+ <Configuration>
+ <Appenders>
+ <Console name="STDOUT">
+ <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Logger name="org.apache.hc.client5.http.impl.io" level="DEBUG">
+ <AppenderRef ref="Console"/>
+ </Logger>
+ <Logger name="org.apache.hc.client5.http.impl.nio" level="DEBUG">
+ <AppenderRef ref="Console"/>
+ </Logger>
+ <Root level="INFO">
+ <AppenderRef ref="STDOUT" />
+ </Root>
+ </Loggers>
+ </Configuration>
+ ```
+
+- Enable context logging for connection management / request execution
+
+ ```
+ <Configuration>
+ <Appenders>
+ <Console name="STDOUT">
+ <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Logger name="org.apache.hc.client5.http.impl" level="DEBUG">
+ <AppenderRef ref="Console"/>
+ </Logger>
+ <Root level="INFO">
+ <AppenderRef ref="STDOUT" />
+ </Root>
+ </Loggers>
+ </Configuration>
+ ```
+
+The `Log4J 2` manual is the best reference for how to configure `Log4J 2`. It is available at
+[https://logging.apache.org/log4j/2.x/manual/](https://logging.apache.org/log4j/2.x/manual/).
+
diff --git a/src/site/markdown/httpcomponents-client-5.x/related-projects.md b/src/site/markdown/httpcomponents-client-5.x/related-projects.md
new file mode 100644
index 0000000..c6b12ca
--- /dev/null
+++ b/src/site/markdown/httpcomponents-client-5.x/related-projects.md
@@ -0,0 +1,43 @@
+<!--
+ 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
+ regarding copyright ownership. The ASF licenses this file
+ 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
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ 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.
+-->
+
+Related projects
+================
+
+HttpClient 5.0 migration guide
+------------------------------
+
+[HttpClient 5.0 migration guide](https://ok2c.github.io/httpclient-migration-guide/) is a third party resource with
+recommendations about the upgrade process and possible upgrade paths from Apache HttpClient 4.x to Apache HttpClient
+5.x.
+
+Asynchronous JSON message processors
+------------------------------
+
+[Asynchronous JSON message processors](https://ok2c.github.io/httpcomponents-jackson/) library is a companion project
+for HttpClient 5.0 developed outside the Apache Software Foundation.
+
+The library provides a number of asynchronous message consumers and producers for efficient, reactive processing of HTTP
+messages with enclosed JSON content using [Jackson JSON processor](https://github.com/FasterXML/jackson).
+
+Android extensions
+------------------
+
+[Android extensions for Apache HttpClient 5.x](https://ok2c.github.io/httpclient-android-ext/) is a third party library
+that provides extra functionality simplifying application of Apache HttpClient on Google Android platform.
diff --git a/src/site/markdown/httpcomponents-core-5.x/related-projects.md b/src/site/markdown/httpcomponents-core-5.x/related-projects.md
new file mode 100644
index 0000000..f46acd3
--- /dev/null
+++ b/src/site/markdown/httpcomponents-core-5.x/related-projects.md
@@ -0,0 +1,33 @@
+<!--
+ 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
+ regarding copyright ownership. The ASF licenses this file
+ 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
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ 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.
+-->
+
+Related projects
+================
+
+Asynchronous JSON message processors
+------------------------------------
+
+[Asynchronous JSON message processors](https://ok2c.github.io/httpcomponents-jackson/) library is a companion project
+for HttpCore 5.x developed outside the Apache Software Foundation.
+
+The library provides a number of asynchronous message consumers and producers for efficient, reactive processing of HTTP
+messages with enclosed JSON content using [Jackson JSON processor](https://github.com/FasterXML/jackson).
+
+
+
diff --git a/src/site/resources/httpcomponents-client-4.5.x/documentation.links b/src/site/resources/httpcomponents-client-4.5.x/documentation.links
index 5c1084a..fb5d11e 100644
--- a/src/site/resources/httpcomponents-client-4.5.x/documentation.links
+++ b/src/site/resources/httpcomponents-client-4.5.x/documentation.links
@@ -3,3 +3,8 @@
current ../components/httpcomponents-client-4.5.x/4.5.13
4.5.13 ../components/httpcomponents-client-4.5.x/4.5.13
+
+android.html ../components/httpcomponents-client-4.x/android.html
+logging.html ../components/httpcomponents-client-4.x/logging.html
+ntlm.html ../components/httpcomponents-client-4.x/ntml.html
+primer.html ../components/httpcomponents-client-4.x/primer.html
diff --git a/src/site/resources/httpcomponents-client-5.0.x/documentation.links b/src/site/resources/httpcomponents-client-5.0.x/documentation.links
index 39cabcd..3732d1b 100644
--- a/src/site/resources/httpcomponents-client-5.0.x/documentation.links
+++ b/src/site/resources/httpcomponents-client-5.0.x/documentation.links
@@ -3,3 +3,7 @@
5.0.3 ../components/httpcomponents-client-5.0.x/5.0.3
current ../components/httpcomponents-client-5.0.x/5.0.3
+
+android.html ../components/httpcomponents-client-5.x/android.html
+logging.html ../components/httpcomponents-client-5.x/logging.html
+related-projects.html ../components/httpcomponents-client-5.x/related-projects.html
diff --git a/src/site/resources/httpcomponents-client-5.1.x/documentation.links b/src/site/resources/httpcomponents-client-5.1.x/documentation.links
index b562b21..51b23ec 100644
--- a/src/site/resources/httpcomponents-client-5.1.x/documentation.links
+++ b/src/site/resources/httpcomponents-client-5.1.x/documentation.links
@@ -3,3 +3,7 @@
5.1-beta1 ../components/httpcomponents-client-5.1.x/5.1-beta1
current ../components/httpcomponents-client-5.1.x/5.1-beta1
+
+android.html ../components/httpcomponents-client-5.x/android.html
+logging.html ../components/httpcomponents-client-5.x/logging.html
+related-projects.html ../components/httpcomponents-client-5.x/related-projects.html
diff --git a/src/site/resources/httpcomponents-core-5.0.x/documentation.links b/src/site/resources/httpcomponents-core-5.0.x/documentation.links
index b770af3..f88e462 100644
--- a/src/site/resources/httpcomponents-core-5.0.x/documentation.links
+++ b/src/site/resources/httpcomponents-core-5.0.x/documentation.links
@@ -3,3 +3,5 @@
5.0.3 ../components/httpcomponents-core-5.0.x/5.0.3
current ../components/httpcomponents-core-5.0.x/5.0.3
+
+related-projects.html ../components/httpcomponents-core-5.x/related-projects.html
diff --git a/src/site/resources/httpcomponents-core-5.1.x/documentation.links b/src/site/resources/httpcomponents-core-5.1.x/documentation.links
index 17f959a..577e635 100644
--- a/src/site/resources/httpcomponents-core-5.1.x/documentation.links
+++ b/src/site/resources/httpcomponents-core-5.1.x/documentation.links
@@ -3,3 +3,5 @@
5.1-beta3 ../components/httpcomponents-core-5.1.x/5.1-beta3
current ../components/httpcomponents-core-5.1.x/5.1-beta3
+
+related-projects.html ../components/httpcomponents-core-5.x/related-projects.html