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 88c2bf79 Add new resolver transport dedicated page (#391)
88c2bf79 is described below
commit 88c2bf79b799bf963f89f820598c702b23588ee4
Author: Tamas Cservenak <[email protected]>
AuthorDate: Tue Mar 7 10:26:54 2023 +0100
Add new resolver transport dedicated page (#391)
And existing page rename to "advanced Wagon configuration" as that's what
it is.
---
content/apt/guides/mini/guide-http-settings.apt | 19 +++--
content/markdown/docs/3.9.0/release-notes.md | 1 +
.../guides/mini/guide-resolver-transport.md | 95 ++++++++++++++++++++++
content/site.xml | 3 +-
4 files changed, 109 insertions(+), 9 deletions(-)
diff --git a/content/apt/guides/mini/guide-http-settings.apt
b/content/apt/guides/mini/guide-http-settings.apt
index 64634ba2..db36a07a 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 Transport Configuration
+ Guide to Advanced Wagon Transport Configuration
------
John Casey
------
@@ -26,22 +26,25 @@
~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html
-Advanced Configuration of the Maven Resolver Transport
+Advanced Configuration of the Maven Wagon Transport
-%{toc}
+ <<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 existing Resolver transports see the
{{{https://maven.apache.org/resolver/} Resolver}}
+ 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 4.x changed to the more modern
+ 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} this page}}. While
one can easily define simple typed
+ {{{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.
-*Advanced configuration to Transports
+%{toc}
+
+*Advanced configuration to Wagon
Using your <<<settings.xml>>> you can customize the transport configurations
in several ways.
@@ -73,7 +76,7 @@ Advanced Configuration of the Maven Resolver Transport
**Connection Timeouts
- All transport implementations that perform some network access allow the
configuration of a several 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.
+---+
diff --git a/content/markdown/docs/3.9.0/release-notes.md
b/content/markdown/docs/3.9.0/release-notes.md
index e9fbfe32..4f6b5053 100644
--- a/content/markdown/docs/3.9.0/release-notes.md
+++ b/content/markdown/docs/3.9.0/release-notes.md
@@ -47,6 +47,7 @@ If you have any questions, please consult:
### Potentially Breaking Core Changes
+* The Maven Resolver transport has changed from Wagon to "native HTTP", see
[Resolver Transport guide](/guides/mini/guide-resolver-transport.html).
* Maven 2.x was auto-injecting an ancient version of `plexus-utils` dependency
into the plugin classpath, and Maven 3.x continued doing this to preserve
backward compatibility. Starting with Maven 3.9, it does not happen anymore.
This change may lead to plugin breakage. The fix for affected plugin
maintainers is to explicitly declare a dependency on `plexus-utils`. The
workaround for affected plugin users is to add this dependency to plugin
dependencies until issue is fixed by the affect [...]
* Mojos are prevented to boostrap new instance of `RepositorySystem` (for
example by using deprecated `ServiceLocator`), they should reuse
`RepositorySystem` instance provided by Maven instead. See
[MNG-7471](https://issues.apache.org/jira/browse/MNG-7471).
* Each line in `.mvn/maven.config` is now interpreted as a single argument.
That is, if the file contains multiple arguments, these must now be placed on
separate lines, see [MNG-7684](https://issues.apache.org/jira/browse/MNG-7684).
diff --git a/content/markdown/guides/mini/guide-resolver-transport.md
b/content/markdown/guides/mini/guide-resolver-transport.md
new file mode 100644
index 00000000..2381cb15
--- /dev/null
+++ b/content/markdown/guides/mini/guide-resolver-transport.md
@@ -0,0 +1,95 @@
+## Guide for Resolver Transport
+<!--
+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.
+-->
+
+Historically, since Maven 2.x, the only transport used by Maven was Maven
Wagon. Since the introduction of the Resolver in
+Maven 3.x, it did "wrap" it in the `maven-resolver-transport-wagon` module,
and continued to use it. Still, Wagon is
+deeply integrated with the old Plexus DI container and many, if not all, of
its configuration are bound to be set in
+Plexus XML, which is not type safe, nor validated, nor future-proof.
+
+**Starting with Maven 3.9.0 release, the _default transport_ (the default
transport used by Maven Resolver)
+changed from ancient Wagon to modern `maven-resolver-transport-http` aka
_native HTTP_ transport.**
+
+Take a peek at the Resolver [architecture
diagram](https://maven.apache.org/resolver/) and the _transport_ box
+contains several implementations, and this number will probably increase.
+
+The Resolver contains configuration for many aspects, including transport (see
the keys
+prefixed with `aether.connector.`). They can be found on
+[resolver configuration
page](https://maven.apache.org/resolver/configuration.html).
+
+## Switching Between Transports
+
+The transport used by resolver can be controlled using the
`-Dmaven.resolver.transport` user property, for which accepted
+values are `native` (the default), `wagon` (uses legacy Wagon) and `auto`
(delegates to resolver to sort
+out defaults).
+
+The accepted values of `maven.resolver.transport` user property:
+* `default` (implied if not present), does `auto` by default
+* `native` forces use of transport-http
+* `wagon` forces use of transport-wagon
+* `auto` delegates to the resolver the transport choice (using
`aether.priority.<class>` and related properties, or just relying on component
priorities).
+
+Note: _forces_ means that the resolver will use the given transport even if
another higher prioritized component is present
+on classpath.
+
+Given the priority of `native` is higher than `wagon`, and that starting with
Maven 3.9.0 both are present on resolver
+classpath, `native` is chosen by default. This behaviour preserves existing
(pre 3.9.0) behaviour of Maven Resolver,
+that allowed third party transports to be added (by copying them to `lib/ext`)
that have higher priorities. Still,
+fallback is possible with explicit use of `native` or `wagon` values.
+
+## Custom HTTP Headers
+
+In all HTTP transports, you can add your custom HTTP headers like this:
+
+```xml
+<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 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).
+
+## 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
+configuration first. You can still upgrade and use latest Maven, with use
`-Dmaven.resolver.transport=wagon` user property
+to stick with Wagon, but migration to new transport is warmly recommended.
+
+## The Devil Is In Details
+
+Depending on which transport you use (`native`, `wagon` or something else),
you will want to refer to the corresponding
+page(s) for detailed configuration options:
+
+* For Native HTTP transport detailed configuration user properties are
[collected on this page](https://maven.apache.org/resolver/configuration.html).
+* For Wagon you want to use `-Dmaven.resolver.transport=wagon` user property
and [configuration from this
page](https://maven.apache.org/guides/mini/guide-http-settings.html).
+* For any third party transport, please refer to its own documentation.
diff --git a/content/site.xml b/content/site.xml
index b2e33af2..9ec5efa5 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -106,7 +106,8 @@ under the License.
<item name="Encrypting Passwords"
href="/guides/mini/guide-encryption.html" />
<item name="Using Proxies" href="/guides/mini/guide-proxies.html" />
<item name="Authenticated HTTPS"
href="/guides/mini/guide-repository-ssl.html" />
- <item name="HTTP Connection Settings"
href="/guides/mini/guide-http-settings.html" />
+ <item name="Resolver Transport"
href="/guides/mini/guide-resolver-transport.html" />
+ <item name="Advanced Wagon HTTP Configuration"
href="/guides/mini/guide-http-settings.html" />
<item name="Alternative Wagon Providers"
href="/guides/mini/guide-wagon-providers.html" />
<item name="Relocation" href="/guides/mini/guide-relocation.html" />
</item>
