svn commit: r1561741 - /httpcomponents/httpclient-android/trunk/README.txt

[ol...@apache.org]

Author: olegk
Date: Mon Jan 27 16:50:26 2014
New Revision: 1561741

URL: http://svn.apache.org/r1561741
Log:
Added background and compatibility notes to project README.txt

Modified:
    httpcomponents/httpclient-android/trunk/README.txt

Modified: httpcomponents/httpclient-android/trunk/README.txt
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient-android/trunk/README.txt?rev=1561741&r1=1561740&r2=1561741&view=diff
==============================================================================
--- httpcomponents/httpclient-android/trunk/README.txt (original)
+++ httpcomponents/httpclient-android/trunk/README.txt Mon Jan 27 16:50:26 2014
@@ -1,3 +1,154 @@
-This project represents an effort to provide an implementation of Apache HttpClient, 
-which can be deployed on Google Android in parallel to the outdated version shipped with platform  
-while remaining (almost fully) API compatible with Apache HttpClient 4.3.  
+This project represents an effort to provide an implementation of Apache HttpClient, which can be 
+deployed on Google Android in parallel to the outdated version shipped with platform  while 
+remaining partially API compatible with Apache HttpClient 4.3.  
+
+Background
+----------
+
+Google Android 1.0 was released with a pre-BETA spapshot 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 became a fork. Eventually Google decided to discontinue further development of their 
+fork while refusing to upgrade to the stock version of Apache HttpClient siting compatibility 
+concerns as a reason for such decision. As a result those Android developers who would like to 
+continue using Apache HttpClient APIs on Android cannot advantage of newer features, performance 
+improvements and bug fixes. 
+
+Apache HttpClient 4.3 re-spin for Android is intended to remedy the situation by providing 
+official releases compatible with Google Android.  
+
+Compatibility notes 
+----------
+
+(1) HttpClient re-spin for Android is compiled against the official Android SDK and is expected
+to be fully compatible with any code consuming HttpClient services through its interface 
+(HttpClient) rather than the default implementation (DefaultHttpClient).
+
+(2) Code compiled against stock versions of Apache HttpClient 4.3 is not fully compatible with
+HttpClient re-spin for Android. 
+
+(3) Code compile against HttpClient re-spin for Android should can be fully compatible with the
+stock version of Apache HttpClient 4.3 as long as 'shaded' implementation classes are not directly
+references by the consuming code.
+
+'Shaded' implementation classes 
+----------
+
+Classes with 'org.apache.http.**.*HC4' name pattern had to be created in order to avoid conflicts 
+with earlier version of the same classes shipped with Android.   
+
+It is generally recommended to avoid using these classes in applications if full compatibility with
+the stock version of Apache HttpClient is desired.
+
+---
+org.apache.http.entity.StringEntityHC4
+org.apache.http.entity.FileEntityHC4
+org.apache.http.entity.InputStreamEntityHC4
+org.apache.http.entity.AbstractHttpEntityHC4
+org.apache.http.entity.HttpEntityWrapperHC4
+org.apache.http.entity.BasicHttpEntityHC4
+org.apache.http.entity.SerializableEntityHC4
+org.apache.http.entity.ByteArrayEntityHC4
+org.apache.http.entity.BufferedHttpEntityHC4
+org.apache.http.impl.NoConnectionReuseStrategyHC4
+org.apache.http.impl.entity.LaxContentLengthStrategyHC4
+org.apache.http.impl.entity.StrictContentLengthStrategyHC4
+org.apache.http.impl.DefaultHttpRequestFactoryHC4
+org.apache.http.impl.DefaultConnectionReuseStrategyHC4
+org.apache.http.impl.EnglishReasonPhraseCatalogHC4
+org.apache.http.impl.cookie.BestMatchSpecHC4
+org.apache.http.impl.cookie.RFC2109DomainHandlerHC4
+org.apache.http.impl.cookie.RFC2109VersionHandlerHC4
+org.apache.http.impl.cookie.RFC2109SpecHC4
+org.apache.http.impl.cookie.RFC2965DomainAttributeHandlerHC4
+org.apache.http.impl.cookie.NetscapeDraftHeaderParserHC4
+org.apache.http.impl.cookie.NetscapeDraftSpecHC4
+org.apache.http.impl.cookie.PublicSuffixListParserHC4
+org.apache.http.impl.cookie.BrowserCompatSpecHC4
+org.apache.http.impl.cookie.RFC2965PortAttributeHandlerHC4
+org.apache.http.impl.cookie.PublicSuffixFilterHC4
+org.apache.http.impl.cookie.BasicDomainHandlerHC4
+org.apache.http.impl.cookie.CookieSpecBaseHC4
+org.apache.http.impl.cookie.AbstractCookieSpecHC4
+org.apache.http.impl.cookie.RFC2965DiscardAttributeHandlerHC4
+org.apache.http.impl.cookie.BestMatchSpecFactoryHC4
+org.apache.http.impl.cookie.BrowserCompatSpecFactoryHC4
+org.apache.http.impl.cookie.AbstractCookieAttributeHandlerHC4
+org.apache.http.impl.cookie.BasicCommentHandlerHC4
+org.apache.http.impl.cookie.BasicMaxAgeHandlerHC4
+org.apache.http.impl.cookie.RFC2109SpecFactoryHC4
+org.apache.http.impl.cookie.BasicClientCookie2HC4
+org.apache.http.impl.cookie.BasicExpiresHandlerHC4
+org.apache.http.impl.cookie.BasicClientCookieHC4
+org.apache.http.impl.cookie.RFC2965VersionAttributeHandlerHC4
+org.apache.http.impl.cookie.NetscapeDomainHandlerHC4
+org.apache.http.impl.cookie.NetscapeDraftSpecFactoryHC4
+org.apache.http.impl.cookie.RFC2965SpecHC4
+org.apache.http.impl.cookie.RFC2965SpecFactoryHC4
+org.apache.http.impl.cookie.BasicSecureHandlerHC4
+org.apache.http.impl.cookie.BasicPathHandlerHC4
+org.apache.http.impl.cookie.RFC2965CommentUrlAttributeHandlerHC4
+org.apache.http.impl.conn.WireHC4
+org.apache.http.impl.io.ContentLengthOutputStreamHC4
+org.apache.http.impl.io.ChunkedOutputStreamHC4
+org.apache.http.impl.io.ContentLengthInputStreamHC4
+org.apache.http.impl.io.IdentityInputStreamHC4
+org.apache.http.impl.io.IdentityOutputStreamHC4
+org.apache.http.impl.io.AbstractMessageParserHC4
+org.apache.http.impl.io.ChunkedInputStreamHC4
+org.apache.http.impl.io.AbstractMessageWriterHC4
+org.apache.http.impl.DefaultHttpResponseFactoryHC4
+org.apache.http.impl.auth.DigestSchemeFactoryHC4
+org.apache.http.impl.auth.BasicSchemeHC4
+org.apache.http.impl.auth.RFC2617SchemeHC4
+org.apache.http.impl.auth.NTLMSchemeHC4
+org.apache.http.impl.auth.DigestSchemeHC4
+org.apache.http.impl.auth.BasicSchemeFactoryHC4
+org.apache.http.impl.auth.AuthSchemeBaseHC4
+org.apache.http.impl.client.BasicCredentialsProviderHC4
+org.apache.http.impl.client.DefaultConnectionKeepAliveStrategyHC4
+org.apache.http.impl.client.DefaultUserTokenHandlerHC4
+org.apache.http.impl.client.DefaultHttpRequestRetryHandlerHC4
+org.apache.http.impl.client.RedirectLocationsHC4
+org.apache.http.impl.client.BasicCookieStoreHC4
+org.apache.http.impl.client.EntityEnclosingRequestWrapperHC4
+org.apache.http.impl.client.BasicResponseHandlerHC4
+org.apache.http.protocol.ResponseConnControlHC4
+org.apache.http.protocol.RequestTargetHostHC4
+org.apache.http.protocol.RequestConnControlHC4
+org.apache.http.protocol.RequestUserAgentHC4
+org.apache.http.protocol.RequestDateHC4
+org.apache.http.protocol.BasicHttpContextHC4
+org.apache.http.protocol.RequestContentHC4
+org.apache.http.util.VersionInfoHC4
+org.apache.http.util.EntityUtilsHC4
+org.apache.http.conn.ssl.StrictHostnameVerifierHC4
+org.apache.http.conn.ssl.AllowAllHostnameVerifierHC4
+org.apache.http.conn.ssl.AbstractVerifierHC4
+org.apache.http.conn.ssl.BrowserCompatHostnameVerifierHC4
+org.apache.http.conn.util.InetAddressUtilsHC4
+org.apache.http.conn.EofSensorInputStreamHC4
+org.apache.http.auth.AuthStateHC4
+org.apache.http.message.BasicLineFormatterHC4
+org.apache.http.message.BasicHeaderValueParserHC4
+org.apache.http.message.BasicHeaderValueFormatterHC4
+org.apache.http.message.BasicLineParserHC4
+org.apache.http.client.entity.UrlEncodedFormEntityHC4
+org.apache.http.client.methods.HttpGetHC4
+org.apache.http.client.methods.HttpDeleteHC4
+org.apache.http.client.methods.HttpPutHC4
+org.apache.http.client.methods.HttpOptionsHC4
+org.apache.http.client.methods.HttpPostHC4
+org.apache.http.client.methods.HttpEntityEnclosingRequestBaseHC4
+org.apache.http.client.methods.HttpHeadHC4
+org.apache.http.client.methods.HttpTraceHC4
+org.apache.http.client.methods.HttpRequestBaseHC4
+org.apache.http.client.utils.URIUtilsHC4
+org.apache.http.client.utils.CloneUtilsHC4
+org.apache.http.client.utils.URLEncodedUtilsHC4
+org.apache.http.client.protocol.RequestAddCookiesHC4
+org.apache.http.client.protocol.RequestDefaultHeadersHC4
+org.apache.http.client.protocol.ResponseProcessCookiesHC4
+