This is an automated email from the ASF dual-hosted git repository.
cstamas pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new 2647fb00 Add generic documentation how to configure transports (#347)
2647fb00 is described below
commit 2647fb00efea98d0f9b21c2632e373bdf45742ad
Author: Tamas Cservenak <ta...@cservenak.net>
AuthorDate: Fri Dec 2 16:11:40 2022 +0100
Add generic documentation how to configure transports (#347)
As HTTP settings are not "wagon-only" anymore.
---
.../guides/development/guide-maven-development.apt | 5 +-
content/apt/guides/mini/guide-http-settings.apt | 99 ++++++++++++++++++----
2 files changed, 86 insertions(+), 18 deletions(-)
diff --git a/content/apt/guides/development/guide-maven-development.apt
b/content/apt/guides/development/guide-maven-development.apt
index a39eee14..1b919b67 100644
--- a/content/apt/guides/development/guide-maven-development.apt
+++ b/content/apt/guides/development/guide-maven-development.apt
@@ -182,8 +182,9 @@ Developing Maven
** <<Maven Wagon>>
- Maven Wagon is a standalone API that deals with transporting files and
directories. Maven Core uses the Wagon
- API to download and upload artifacts and artifact metadata. The site plug-in
uses it to publish the site.
+ Maven Wagon is a standalone API that dealt with transporting files and
directories in Maven 2.x. Maven Core today
+ uses the Resolver Transport API, that among other implementations, contains a
wrapper for Wagon as well.
+ Also, the site plug-in uses it to publish the site.
You can {{{/wagon/}read more about Wagon}}.
diff --git a/content/apt/guides/mini/guide-http-settings.apt
b/content/apt/guides/mini/guide-http-settings.apt
index 1a7e2f65..c8302db7 100644
--- a/content/apt/guides/mini/guide-http-settings.apt
+++ b/content/apt/guides/mini/guide-http-settings.apt
@@ -1,5 +1,5 @@
------
- Guide to Advanced HTTP Wagon Configuration
+ Guide to Advanced HTTP Transport Configuration
------
John Casey
------
@@ -26,10 +26,77 @@
~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html
-Advanced Configuration of the HttpClient HTTP Wagon
+Advanced Configuration of the Maven Resolver Transport
%{toc}
+ You can use the default transport for a given protocol, or you can select
the transport you want by using the configuration.
+ For more information about existing Resolver transports see the
{{{https://maven.apache.org/resolver/} Resolver}}
+ site. The default transport in Maven 3.x is Transport-Wagon, the Wagon layer
having been introduced in Maven 2.x.
+ Since then, more modern transports were introduced as well, even supporting
overlapping protocols. The default
+ transport in Maven 4.x changed to the more modern
+
{{{https://maven.apache.org/resolver/maven-resolver-transport-http/index.html}"native";
HTTP}} transport.
+
+ Ultimate reference for resolver transport configuration can be found on
+ {{{https://maven.apache.org/resolver/configuration.html} this page}}. While
one can easily define simple typed
+ values on command line using <<<-D...>>> switch, some more complex values,
like HTTP headers, cannot.
+
+*Advanced configuration to Transports
+
+ Using your <<<settings.xml>>> you can customize the transport configurations
in several ways.
+
+**HTTP Headers
+
+ In all HTTP transports, you can add your custom HTTP headers like this:
+
++---+
+<settings>
+ <servers>
+ <server>
+ <id>my-server</id>
+ <configuration>
+ <httpHeaders>
+ <property>
+ <name>Foo</name>
+ <value>Bar</value>
+ </property>
+ </httpHeaders>
+ </configuration>
+ </server>
+ </servers>
+</settings>
++---+
+
+ It is important to understand that the above approach does not 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 all
+ transports that support headers, like HTTP transports are.
+
+**Connection Timeouts
+
+ All transport implementations that perform some network access allow the
configuration of a several timeouts,
+ for example to allow the user to tell Maven how long to wait before giving
up on a connection that has not responded.
+
++---+
+<settings>
+ <servers>
+ <server>
+ <id>my-server</id>
+ <configuration>
+ <connectTimeout>10000</connectTimeout> <!-- milliseconds -->
+ <requestTimeout>1800000</requestTimeout> <!-- milliseconds -->
+ </configuration>
+ </server>
+ </servers>
+</settings>
++---+
+
+ These above define per-server timeout configuration, and show default values.
+
+ These are the standard ways to configure transport, regarding custom
headers, and various timeouts. Each transport
+ MAY introduce it's own specific configuration, like we can see below for
Wagon.
+
+*Advanced Configuration of the HttpClient HTTP Wagon
+
You can use the default wagon implementation for a given
protocol, or you can select an alternative wagon <<<provider>>> on a
per-protocol basis.
For more information, see the {{{./guide-wagon-providers.html}Guide to Wagon
Providers}} \[3\].
@@ -44,7 +111,7 @@ Advanced Configuration of the HttpClient HTTP Wagon
* default Preemptive Authentication only with PUT (GET doesn't use anymore
default Preemptive Authentication)
-*Introduction
+**Introduction
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
@@ -52,7 +119,7 @@ Advanced Configuration of the HttpClient HTTP Wagon
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).
-*The Basics
+**The Basics
Without any special configuration, Maven's HTTP wagon uses some default HTTP
headers and client parameters when managing
artifacts. The default headers are:
@@ -101,7 +168,7 @@ problems with HTTP servers and proxies that do not support
HTTP/1.1 protocol.
We'll discuss preemptive authentication in another example, below.
-*Configuring GET, HEAD, PUT, or All of the Above
+**Configuring GET, HEAD, PUT, or All of the Above
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 <<<settings.xml>>> file:
@@ -148,7 +215,7 @@ problems with HTTP servers and proxies that do not support
HTTP/1.1 protocol.
For clarity, the other two sections are <<<\<get\>>>> for GET requests, and
<<<\<head\>>>> for HEAD requests. I know that's going to
be hard to remember...
-*Taking Control of Your HTTP Headers
+**Taking Control of Your HTTP Headers
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 <<<gzip>>>, in spite of
the fact that the HTTP request itself isn't being
@@ -201,14 +268,14 @@ problems with HTTP servers and proxies that do not
support HTTP/1.1 protocol.
</settings>
+---+
-*Fine-Tuning HttpClient Parameters
+**Fine-Tuning HttpClient Parameters
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.
-**Non-String Parameter Values
+***Non-String Parameter Values
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
@@ -237,7 +304,7 @@ problems with HTTP servers and proxies that do not support
HTTP/1.1 protocol.
As you may have noticed, this syntax is similar to the format-and-data
strategy used by functions like <<<sprintf()>>>
in many languages. The syntax has been chosen with this similarity in mind,
to make it a little more intuitive to use.
-**Example: Using Preemptive Authentication
+***Example: Using Preemptive Authentication
Using the above syntax, you can configure preemptive authentication for PUT
requests using the boolean HttpClient parameter
<<<http.authentication.preemptive>>>, like this:
@@ -283,7 +350,7 @@ problems with HTTP servers and proxies that do not support
HTTP/1.1 protocol.
</settings>
+---+
-**Example: Lifting auth scope restriction for external authentication systems
+***Example: Lifting auth scope restriction for external authentication systems
Maven Wagon by default limits supplied credentials to the host:port
combination
scope, ignoring any other target servers. When the target server delegates
@@ -316,7 +383,7 @@ problems with HTTP servers and proxies that do not support
HTTP/1.1 protocol.
</settings>
+---+
-**Ignoring Cookies
+***Ignoring Cookies
Like the example above, telling the HttpClient to ignore cookies for all
methods of request is a simple matter of
configuring the <<<http.protocol.cookie-policy>>> parameter (it uses a
regular string value, so no special syntax
@@ -350,13 +417,13 @@ problems with HTTP servers and proxies that do not
support HTTP/1.1 protocol.
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.
-*Support for General-Wagon Configuration Standards
+**Support for General-Wagon Configuration Standards
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:
-**HTTP Headers
+***HTTP Headers
In all HTTP Wagon implementations, you can add your own HTTP headers like
this:
@@ -382,7 +449,7 @@ problems with HTTP servers and proxies that do not support
HTTP/1.1 protocol.
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.
-**Connection Timeouts
+***Connection Timeouts
All wagon implementations that extend the <<<AbstractWagon>>> 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
@@ -426,7 +493,7 @@ problems with HTTP servers and proxies that do not support
HTTP/1.1 protocol.
parameter. If you need to separate timeout preferences according to HTTP
method, you can use one more like that
specified directly above.
-** Read time out
+*** Read time out
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:
@@ -448,7 +515,7 @@ problems with HTTP servers and proxies that do not support
HTTP/1.1 protocol.
</settings>
+---+
-*Resources
+**Resources
[[1]] {{{https://hc.apache.org/httpcomponents-client-4.5.x/}HttpClient
website}}
