Author: svn-site-role
Date: Sun Sep 24 11:53:38 2023
New Revision: 1912521
Log:
Site checkin for project Apache Maven Site
Modified:
maven/website/content/guides/mini/guide-http-settings.html
maven/website/content/maven-site-1.0-site.jar
Modified: maven/website/content/guides/mini/guide-http-settings.html
==============================================================================
--- maven/website/content/guides/mini/guide-http-settings.html (original)
+++ maven/website/content/guides/mini/guide-http-settings.html Sun Sep 24
11:53:38 2023
@@ -161,20 +161,19 @@
<main id="bodyColumn" class="span10" >
<section>
<h1>Advanced configuration to HttpClient HTTP Wagon</h1>
-<p><b>This page contains Wagon specific information, but the default transport
in Maven 3.9.0+ is NOT Wagon anymore. Make sure to check <a
href="./guide-resolver-transport.html">Resolver Transport guide</a> first, as
things have changed.</b></p>
+<p><b>This page contains Wagon specific information, but the default transport
in Maven 3.9.0+ is NOT Wagon anymore. Make sure to check the <a
href="./guide-resolver-transport.html">Resolver Transport guide</a> first, as
things have changed.</b></p>
<ul>
<li><a href="#Advanced_configuration_to_HttpClient_HTTP_Wagon">Advanced
configuration to HttpClient HTTP Wagon</a>
<ul>
-<li><a href="#Advanced_Configuration_of_the_HttpClient_HTTP_Wagon">Advanced
Configuration of the HttpClient HTTP Wagon</a>
-<ul>
<li><a href="#Introduction">Introduction</a></li>
<li><a href="#The_Basics">The Basics</a></li>
<li><a
href="#Configuring_GET.2C_HEAD.2C_PUT.2C_or_All_of_the_Above">Configuring GET,
HEAD, PUT, or All of the Above</a></li>
<li><a href="#Taking_Control_of_Your_HTTP_Headers">Taking Control of Your HTTP
Headers</a></li>
<li><a href="#Fine-Tuning_HttpClient_Parameters">Fine-Tuning HttpClient
Parameters</a>
<ul>
-<li><a href="#Non-String_Parameter_Values">Non-String Parameter Values</a></li>
-<li><a href="#Example.3A_Using_Preemptive_Authentication">Example: Using
Preemptive Authentication</a></li>
+<li><a href="#Non-String_Parameter_Values">Non-String Parameter Values</a>
+<ul>
+<li><a href="#Example.3A_Using_Preemptive_Authentication">Example: Using
Preemptive Authentication</a></li></ul></li>
<li><a
href="#Example.3A_Lifting_auth_scope_restriction_for_external_authentication_systems">Example:
Lifting auth scope restriction for external authentication systems</a></li>
<li><a href="#Ignoring_Cookies">Ignoring Cookies</a></li></ul></li>
<li><a href="#Support_for_General-Wagon_Configuration_Standards">Support for
General-Wagon Configuration Standards</a>
@@ -182,16 +181,15 @@
<li><a href="#HTTP_Headers">HTTP Headers</a></li>
<li><a href="#Connection_Timeouts">Connection Timeouts</a></li>
<li><a href="#Read_time_out">Read time out</a></li></ul></li>
-<li><a href="#Resources">Resources</a></li></ul></li></ul></li></ul><section>
-<h2>Advanced Configuration of the HttpClient HTTP Wagon</h2>
+<li><a href="#Resources">Resources</a></li></ul></li></ul>
<p>You can use the default wagon implementation for a given protocol, or you
can select an alternative wagon <code>provider</code> on a per-protocol basis.
For more information, see the <a href="./guide-wagon-providers.html">Guide to
Wagon Providers</a> [3]. The default wagon http(s) is the HttpClient based on
<a class="externalLink"
href="https://hc.apache.org/httpcomponents-client-4.5.x/";>Apache Http Client
4.5</a>. HTTP connection pooling prevents reopening new connections to the same
server for each request. This pool feature is configurable with some parameters
[4]. The default wagon comes with some default configuration:</p>
<ul>
<li>http(s) connection pool: default to 20.</li>
-<li>readTimeout: default to 1,800,000ms (~30 minutes) (see section <code>Read
time out</code> below)</li>
+<li>readTimeout: default to 1800000 (~30 minutes) (see section <code>Read time
out</code> below)</li>
<li>default Preemptive Authentication only with PUT (GET doesn't use anymore
default Preemptive Authentication)</li></ul><section>
-<h3>Introduction</h3>
+<h2>Introduction</h2>
<p>The HttpClient-based HTTP wagon offers more control over the configuration
used to access HTTP-based Maven repositories. For starters, you have
fine-grained control over what HTTP headers are used when resolving artifacts.
In addition, you can also configure a wide range of parameters to control the
behavior of HttpClient itself. Best of all, you have the ability to control
these headers and parameters for all requests, or individual request types
(GET, HEAD, and PUT).</p></section><section>
-<h3>The Basics</h3>
+<h2>The Basics</h2>
<p>Without any special configuration, Maven's HTTP wagon uses some default
HTTP headers and client parameters when managing artifacts. The default headers
are:</p>
<div class="verbatim">
<pre>Cache-control: no-cache
@@ -219,8 +217,8 @@ problems with HTTP servers and proxies t
<p>Without this setting, PUT requests that require authentication transfer
their entire payload to the server before that server issues an authentication
challenge. In order to complete the PUT request, the client must then re-send
the payload with the proper credentials specified in the HTTP headers. This
results in twice the bandwidth usage, and twice the time to transfer each
artifact.</p>
<p>Another option to avoid this double transfer is what's known as preemptive
authentication, which involves sending the authentication headers along with
the original PUT request. However, there are a few potential issues with this
approach. For one thing, in the event you have an unused
<code><server></code> entry that specifies an invalid username/password
combination, some servers may respond with a <code>401 Unauthorized</code> even
if the server doesn't actually require any authentication for the request. In
addition, blindly sending authentication credentials with every request
regardless of whether the server has made a challenge can result in a security
hole, since the server may not make provisions to secure credentials for paths
that don't require authentication.</p>
<p>We'll discuss preemptive authentication in another example,
below.</p></section><section>
-<h3>Configuring GET, HEAD, PUT, or All of the Above</h3>
-<p><b>Starting with Maven 3.9.0 native HTTP transport will pick up the
"all" settings only (get, head, put are neglected!)" but it will
WARN about it's deprecation. For users sticking with Wagon nothing
changes.</b></p>
+<h2>Configuring GET, HEAD, PUT, or All of the Above</h2>
+<p><b>Starting with Maven 3.9.0 native HTTP transport will pick up the
"all" settings only (get, head, put are neglected!)" but it will
WARN about its deprecation. For users sticking with Wagon nothing
changes.</b></p>
<p>In all of the examples below, it's important to understand that you can
configure the HTTP settings for all requests made to a given server, or for
only one method. To configure all methods for a server, use the following
section of the <code>settings.xml</code> file:</p>
<div class="verbatim source"><pre class="prettyprint linenums"><settings>
[...]
@@ -237,7 +235,7 @@ problems with HTTP servers and proxies t
</server>
</servers>
</settings></pre></div>
-<p>On the other hand, if you can live with the default configuration for most
requests - say, HEAD and GET requests, which are used to check for the
existence of a file and retrieve a file respectively - maybe you only need to
configure the PUT method:</p>
+<p>On the other hand, if you can live with the default configuration for most
requests — say, HEAD and GET requests, which are used to check for the
existence of a file and retrieve a file respectively — maybe you only
need to configure the PUT method:</p>
<div class="verbatim source"><pre class="prettyprint linenums"><settings>
[...]
<servers>
@@ -254,7 +252,7 @@ problems with HTTP servers and proxies t
</servers>
</settings></pre></div>
<p>For clarity, the other two sections are <code><get></code> for GET
requests, and <code><head></code> for HEAD requests. I know that's going
to be hard to remember...</p></section><section>
-<h3>Taking Control of Your HTTP Headers</h3>
+<h2>Taking Control of Your HTTP Headers</h2>
<p>As you may have noticed above, the default HTTP headers do have the
potential to cause problems. For instance, some websites set the encoding for
downloading GZipped files as <code>gzip</code>, in spite of the fact that the
HTTP request itself isn't being sent using GZip compression. If the client is
using the <code>Accept-Encoding: gzip</code> header, this can result in the
client itself decompressing the GZipped file <i>during the transfer</i> and
writing the decompressed file to the local disk with the original filename.
This can be misleading to say the least, and can use up an inordinate amount of
disk space on the local computer.</p>
<p>To turn off this default behavior, simply disable the default headers.
Then, respecify the other headers that you are still interested in, like
this:</p>
<div class="verbatim source"><pre class="prettyprint linenums"><settings>
@@ -296,9 +294,9 @@ problems with HTTP servers and proxies t
</servers>
[...]
</settings></pre></div></section><section>
-<h3>Fine-Tuning HttpClient Parameters</h3>
+<h2>Fine-Tuning HttpClient Parameters</h2>
<p>Going beyond the power of HTTP request parameters, HttpClient provides a
host of other configuration options. In most cases, you won't need to customize
these. But in case you do, Maven provides access to specify your own
fine-grained configuration for HttpClient. Again, you can specify these
parameter customizations per-method (HEAD, GET, or PUT), or for all methods of
interacting with a given server. For a complete list of supported parameters,
see the link[2] in Resources section below.</p><section>
-<h4>Non-String Parameter Values</h4>
+<h3>Non-String Parameter Values</h3>
<p>Many of the configuration parameters for HttpClient have simple string
values; however, there are important exceptions to this. In some cases, you may
need to specify boolean, integer, or long values. In others, you may even need
to specify a collection of string values. You can specify these using a simple
formatting syntax, as follows:</p>
<ol style="list-style-type: decimal">
<li><b>booleans:</b> <code>%b,<value></code></li>
@@ -312,7 +310,7 @@ problems with HTTP servers and proxies t
<value2>,
<value3>,
...</pre></div></li></ol>
-<p>As you may have noticed, this syntax is similar to the format-and-data
strategy used by functions like <code>sprintf()</code> in many languages. The
syntax has been chosen with this similarity in mind, to make it a little more
intuitive to use.</p></section><section>
+<p>As you may have noticed, this syntax is similar to the format-and-data
strategy used by functions like <code>sprintf()</code> in many languages. The
syntax has been chosen with this similarity in mind, to make it a little more
intuitive to use.</p><section>
<h4>Example: Using Preemptive Authentication</h4>
<p>Using the above syntax, you can configure preemptive authentication for PUT
requests using the boolean HttpClient parameter
<code>http.authentication.preemptive</code>, like this:</p>
<div class="verbatim source"><pre class="prettyprint linenums"><settings>
@@ -348,10 +346,10 @@ problems with HTTP servers and proxies t
</configuration>
</server>
</servers>
-</settings></pre></div></section><section>
-<h4>Example: Lifting auth scope restriction for external authentication
systems</h4>
+</settings></pre></div></section></section><section>
+<h3>Example: Lifting auth scope restriction for external authentication
systems</h3>
<p>Maven Wagon by default limits supplied credentials to the host:port
combination scope, ignoring any other target servers. When the target server
delegates authentication to an external system, you need to deliberately lift
that scope limitation. Configure your server element to pass authentication to
all target servers which challenge the client. +---+ <i>settings</i>
<i>servers</i> <i>server</i> <i>id</i>my-server<i>/id</i> <i>configuration</i>
<i>basicAuthScope</i> <i>host</i>ANY<i>/host</i> <i>port</i>ANY<i>/port</i>
<i>!-- or even 443 to force the use of TLS --</i> <i>/basicAuthScope</i>
<i>httpConfiguration</i> <i>all</i> <i>params</i> <i>property</i>
<i>name</i>http.protocol.cookie-policy<i>/name</i>
<i>value</i>standard<i>/value</i> <i>/property</i> <i>/params</i> <i>/all</i>
<i>/httpConfiguration</i> <i>/configuration</i> <i>/server</i> <i>/servers</i>
<i>/settings</i> +---+</p></section><section>
-<h4>Ignoring Cookies</h4>
+<h3>Ignoring Cookies</h3>
<p>Like the example above, telling the HttpClient to ignore cookies for all
methods of request is a simple matter of configuring the
<code>http.protocol.cookie-policy</code> parameter (it uses a regular string
value, so no special syntax is required):</p>
<div class="verbatim source"><pre class="prettyprint linenums"><settings>
<servers>
@@ -373,9 +371,9 @@ problems with HTTP servers and proxies t
</servers>
</settings></pre></div>
<p>The configuration above can be useful in cases where the repository is
using cookies - like the session cookies that are often mistakenly turned on or
left on in appservers - alongside HTTP redirection. In these cases, it becomes
far more likely that the cookie issued by the appserver uses a
<code>Path</code> that is inconsistent with the one used by the client to
access the server. If you have this problem, and know that you don't need to
use this session cookie, you can ignore cookies from this server with the above
configuration.</p></section></section><section>
-<h3>Support for General-Wagon Configuration Standards</h3>
+<h2>Support for General-Wagon Configuration Standards</h2>
<p>It should be noted that configuration options previously available in the
HttpClient-driven HTTP wagon are still supported in addition to this new,
fine-grained approach. These include the configuration of HTTP headers and
connection timeouts. Let's examine each of these briefly:</p><section>
-<h4>HTTP Headers</h4>
+<h3>HTTP Headers</h3>
<p>In all HTTP Wagon implementations, you can add your own HTTP headers like
this:</p>
<div class="verbatim source"><pre class="prettyprint linenums"><settings>
<servers>
@@ -393,7 +391,7 @@ problems with HTTP servers and proxies t
</servers>
</settings></pre></div>
<p>It's important to understand that the above approach doesn't allow you to
turn off all of the default HTTP headers; nor does it allow you to specify
headers on a per-method basis. However, this configuration remains available in
both the lightweight and httpclient-based Wagon
implementations.</p></section><section>
-<h4>Connection Timeouts</h4>
+<h3>Connection Timeouts</h3>
<p>All wagon implementations that extend the <code>AbstractWagon</code> class,
including those for SCP, HTTP, FTP, and more, allow the configuration of a
connection timeout, to allow the user to tell Maven how long to wait before
giving up on a connection that has not responded. This option is preserved in
the HttpClient-based wagon, but this wagon also provides a fine-grained
alternative configuration that can allow you to specify timeouts per-method for
a given server. The old configuration option - which is still supported - looks
like this:</p>
<div class="verbatim source"><pre class="prettyprint linenums"><settings>
<servers>
@@ -421,8 +419,8 @@ problems with HTTP servers and proxies t
</servers>
</settings></pre></div>
<p>If all you need is a per-server timeout configuration, you still have the
option to use the old <code><timeout></code> parameter. If you need to
separate timeout preferences according to HTTP method, you can use one more
like that specified directly above.</p></section><section>
-<h4>Read time out</h4>
-<p>With Wagon 2.0 and Apache Maven 3.0.4, a default timeout of 30 minutes
comes by default. If you want to change this value, you can add the following
setup in your settings:</p>
+<h3>Read time out</h3>
+<p>The default timeout is 30 minutes. If you want to change this value, you
can add the following setup in your settings:</p>
<div class="verbatim source"><pre class="prettyprint linenums"><settings>
<servers>
<server>
@@ -437,12 +435,12 @@ problems with HTTP servers and proxies t
</server>
</servers>
</settings></pre></div></section></section><section>
-<h3>Resources</h3>
+<h2>Resources</h2>
<ol style="list-style-type: decimal">
<li><a class="externalLink"
href="https://hc.apache.org/httpcomponents-client-4.5.x/";>HttpClient
website</a></li>
<li><a class="externalLink"
href="https://hc.apache.org/httpclient-3.x/preference-api.html";>HttpClient
preference architecture and configuration guide</a></li>
<li><a href="./guide-wagon-providers.html">Guide to Wagon Providers</a></li>
-<li><a href="/wagon/wagon-providers/wagon-http/">Wagon
Http</a></li></ol></section></section></section>
+<li><a href="/wagon/wagon-providers/wagon-http/">Wagon
Http</a></li></ol></section></section>
</main>
</div>
</div>
Modified: maven/website/content/maven-site-1.0-site.jar
==============================================================================
Binary files - no diff available.
