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-resolver.git
The following commit(s) were added to refs/heads/master by this push:
new 2ff8cb8a Add new site page "Third-party Integrations"
2ff8cb8a is described below
commit 2ff8cb8a105fe6fd4f675acf08061eab5c102496
Author: Tamas Cservenak <ta...@cservenak.net>
AuthorDate: Fri Aug 4 14:17:34 2023 +0200
Add new site page "Third-party Integrations"
Where new supplier is described.
---
maven-resolver-supplier/README.md | 56 ---------------------
src/site/markdown/third-party-integrations.md | 72 +++++++++++++++++++++++++++
src/site/site.xml | 1 +
3 files changed, 73 insertions(+), 56 deletions(-)
diff --git a/maven-resolver-supplier/README.md
b/maven-resolver-supplier/README.md
deleted file mode 100644
index 6b2a023b..00000000
--- a/maven-resolver-supplier/README.md
+++ /dev/null
@@ -1,56 +0,0 @@
-<!---
- 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.
--->
-
-# Maven Resolver Supplier
-
-This simple module serves the purpose to "bootstrap" resolver when there is no
desire to use
-[Eclipse Sisu](https://eclipse.dev/sisu/). It provides one simple class
-`org.eclipse.aether.supplier.RepositorySystemSupplier` that implements
`Supplier<RepositorySystem>`
-and supplies ready-to-use `RepositorySystem` instances.
-
-The supplier class is written in such way, to allow easy customization if
needed: just extend the class and override
-method one need (all methods are protected).
-
-Consumer/users of this module **must provide SLF4J backend**. Resolver uses
`slf4j-api` for logging purposes, but this
-module does NOT provide any backend for it. It is the consumer/user obligation
to provide one at runtime.
-
-Version of `maven-resolver-supplier` artifact used **must be strictly
aligned** with other Resolver artifacts
-on classpath.
-
-By default, "full resolver experience" is provided:
-* for connector, the connector-basic is provided
-* for transport the two transport-file and transport-http implementations are
provided. If Wagon is needed, add
- transport-wagon as dependency, and customize `RepositorySystemSupplier` to
include it. This makes it available, but
- NOT used yet! To use it, you still need to configure resolver to favor Wagon
over native HTTP.
-
-# Resolver configuration
-
-The supplier will provide only a "vanilla" instance. To configure resolver,
use session user (or
-configuration) properties, when constructing session. All the configuration
options are available as
-[listed here](https://maven.apache.org/resolver/configuration.html).
-
-# Extending Resolver
-
-Extending supplied resolver is simple, and basically requires same three steps
for whatever extra you want to include
-(like Wagon transport, distributed locking, etc).
-
-First, you need to include needed module (with transitive deps) to your
dependencies.
-
-Second, you need to customize `RepositorySystemSupplier` to make new
components (`WagonTransporterFactory`, or
-distributed lock factories) available.
-
-Third, you need to configure session (via user of config properties) to make
Resolver use newly added components.
\ No newline at end of file
diff --git a/src/site/markdown/third-party-integrations.md
b/src/site/markdown/third-party-integrations.md
new file mode 100644
index 00000000..9a96771c
--- /dev/null
+++ b/src/site/markdown/third-party-integrations.md
@@ -0,0 +1,72 @@
+# Third-party integrations
+<!---
+ 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.
+-->
+
+Maven Resolver provided option for third-party integration using
`ServiceLocator` (SL)
+from the beginning. Back when SL was implemented, the DI container in use with
Resolver and
+Maven was the Plexus DI container, that had its own limitations: no
constructor injection
+among others. Hence, the two was somewhat aligned with each other. Today, with
Sisu DI,
+this is not true anymore: we want to use constructor injection for components,
but
+SL is always getting into our way forcing us to always add default constructor
to components.
+Hence, decision was made, and SL was deprecated while ago, and is about to be
+dropped in Resolver 2.0.0 release.
+
+Resolver does provide alternative solution for those third-party integrations,
where the
+(recommended) Sisu DI is not available or cannot be used for some reason. All
the
+resolver integrations starting with release 1.9.15 can start migrating off the
SL
+to current solution described below.
+
+## Maven Resolver Supplier
+
+A new simple module `maven-resolver-supplier` serves the purpose to
"bootstrap" resolver instance
+when there is no desire to use [Eclipse Sisu](https://eclipse.dev/sisu/) DI.
It provides one simple class
+`org.eclipse.aether.supplier.RepositorySystemSupplier` that implements
`Supplier<RepositorySystem>`
+and supplies ready-to-use `RepositorySystem` instances. The
`RepositorySystemSession` should be
+created using the
`org.apache.maven.repository.internal.MavenRepositorySystemUtils#newSession()`
method
+and local repository added to it in usual way (there is no change in this
area).
+
+The supplier class is written in a way, to allow easy customization if needed:
just extend the class and override
+method as needed (all methods are protected).
+
+Consumer/users of this module **must provide SLF4J implementation** in
classpath. Resolver uses `slf4j-api` for
+logging purposes, but this module does NOT provide any implementation for it
as a dependency.
+It is the consumer/user obligation to provide one at runtime.
+
+Version of `maven-resolver-supplier` artifact in use **must be strictly
aligned** with other Resolver artifacts
+on classpath.
+
+## Resolver configuration
+
+By default, "full resolver experience" is provided:
+* for connector, the connector-basic is provided
+* for transport the two transport-file and transport-http implementations are
provided. If Wagon is needed, add
+ transport-wagon as dependency (see Extending Resolver below).
+
+The supplier will provide fully usable instance. To configure resolver, use
session user (or
+configuration) properties, when constructing session. All the configuration
options are available as
+[listed here](https://maven.apache.org/resolver/configuration.html).
+
+## Extending Resolver
+
+Extending supplied resolver is simple, and basically requires same three steps
for whatever extra you want to include
+(like Wagon transport, distributed locking, etc).
+
+* First, you need to include needed module (with transitive deps) to your
dependencies.
+* Second, you need to customize `RepositorySystemSupplier` by extending it,
and to make new components
+ available (by adding `WagonTransporterFactory` to transport factories, or
distributed lock factories to lock factories).
+* Third, you need to configure session (via user or configuration properties)
to make Resolver use newly added components.
+
diff --git a/src/site/site.xml b/src/site/site.xml
index 3dbe96ff..fdb5af53 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -32,6 +32,7 @@ under the License.
<item name="Expected Checksums" href="expected-checksums.html"/>
<item name="About Local Repository" href="local-repository.html"/>
<item name="Remote Repository Filtering"
href="remote-repository-filtering.html"/>
+ <item name="Third-party Integrations"
href="third-party-integrations.html"/>
<item name="Maven 3.8.x" href="maven-3.8.x.html"/>
<item name="JavaDocs" href="apidocs/index.html"/>
<item name="Source Xref" href="xref/index.html"/>
