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 f766c48c [MNG-7739] Clear up documentation (#399)
f766c48c is described below
commit f766c48c426c9d7a5fd0a22211638bf917bb461b
Author: Tamas Cservenak <ta...@cservenak.net>
AuthorDate: Tue Mar 14 15:21:44 2023 +0100
[MNG-7739] Clear up documentation (#399)
As some changes creeped in that are actually 3.9+ ONLY. Also, explain what
is and what is not picked up from legacy configs.
This PR moves content added in commit
2647fb00efea98d0f9b21c2632e373bdf45742ad from Wagon page to Resolver Transport
page.
---
https://issues.apache.org/jira/browse/MNG-7739
---
content/apt/guides/mini/guide-http-settings.apt | 70 ++--------------------
.../guides/mini/guide-resolver-transport.md | 25 +++++++-
2 files changed, 27 insertions(+), 68 deletions(-)
diff --git a/content/apt/guides/mini/guide-http-settings.apt
b/content/apt/guides/mini/guide-http-settings.apt
index db36a07a..4b425e4b 100644
--- a/content/apt/guides/mini/guide-http-settings.apt
+++ b/content/apt/guides/mini/guide-http-settings.apt
@@ -26,78 +26,13 @@
~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html
-Advanced Configuration of the Maven Wagon Transport
+Advanced configuration to HttpClient HTTP Wagon
<<This page contains Wagon specific information, but the default transport
in Maven 3.9.0+ is NOT Wagon anymore.
Make sure to check {{{./guide-resolver-transport.html}Resolver Transport
guide}} first, as things have changed.>>
- 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 the 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 3.9.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} configuration}}
page. While one can easily define simple typed
- values on command line using <<<-D...>>> switch, some more complex values,
like HTTP headers, cannot.
-
%{toc}
-*Advanced configuration to Wagon
-
- 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
configuring 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
@@ -173,6 +108,9 @@ problems with HTTP servers and proxies that do not support
HTTP/1.1 protocol.
**Configuring GET, HEAD, PUT, or All of the Above
+ <<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.>>
+
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:
diff --git a/content/markdown/guides/mini/guide-resolver-transport.md
b/content/markdown/guides/mini/guide-resolver-transport.md
index fa49c31c..32883ed7 100644
--- a/content/markdown/guides/mini/guide-resolver-transport.md
+++ b/content/markdown/guides/mini/guide-resolver-transport.md
@@ -33,6 +33,8 @@ The Resolver contains configuration for many aspects,
including transport (see t
prefixed with `aether.connector.`). They can be found on
[resolver configuration
page](https://maven.apache.org/resolver/configuration.html).
+**This page applies only to Maven 3.9.0 and newer.**
+
## Switching Between Transports
The transport used by resolver can be controlled using the
`-Dmaven.resolver.transport` user property, for which accepted
@@ -75,10 +77,29 @@ In all HTTP transports, you can add your custom HTTP
headers like this:
</settings>
```
-It is important to understand that the above approach does not allow you to
turn off all the default HTTP headers;
-nor does it allow you to specify headers on a per-method basis. However, this
configuration remains available in all
+It is important to understand that the above approach does not allow you to
turn off all 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 (and works for
"native" but also Wagon transport).
+## Timeouts
+
+All transport implementations that perform some network access allow
configuring 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.
+
+```xml
+<settings>
+ <servers>
+ <server>
+ <id>my-server</id>
+ <configuration>
+ <connectTimeout>10000</connectTimeout> <!-- milliseconds -->
+ <requestTimeout>1800000</requestTimeout> <!-- milliseconds -->
+ </configuration>
+ </server>
+ </servers>
+</settings>
+```
+
## How To Upgrade from Wagon? (or "native transport does not work")
If your build environment uses Wagon specific configuration (in `settings.xml`
or alike), you should migrate your
