From 2ff8cb8a105fe6fd4f675acf08061eab5c102496 Mon Sep 17 00:00:00 2001 From: Tamas Cservenak Date: Fri, 4 Aug 2023 14:17:34 +0200 Subject: [PATCH] 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(-) delete mode 100644 maven-resolver-supplier/README.md create mode 100644 src/site/markdown/third-party-integrations.md diff --git a/maven-resolver-supplier/README.md b/maven-resolver-supplier/README.md deleted file mode 100644 index 6b2a023b9..000000000 --- a/maven-resolver-supplier/README.md +++ /dev/null @@ -1,56 +0,0 @@ - - -# 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` -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 000000000..9a96771c9 --- /dev/null +++ b/src/site/markdown/third-party-integrations.md @@ -0,0 +1,72 @@ +# Third-party integrations + + +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` +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 3dbe96ff5..fdb5af531 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -32,6 +32,7 @@ under the License. +