Skip to content

Document deployment of artifacts #1588

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 19, 2025
Merged

Document deployment of artifacts #1588

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions src/site/markdown/deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Deployment
<!--
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.
-->

Deploying artifacts and related metadata to a (remote) repository can be achieved via Resolver API with method [`org.eclipse.aether.RepositorySystem.deploy(RepositorySystemSession session, DeployRequest request)`](https://github.com/apache/maven-resolver/blob/master/maven-resolver-api/src/main/java/org/eclipse/aether/RepositorySystem.java). This writes/uploads the given artifact(s) including metadata to the given repository leveraging a [`RepositoryConnector`](https://github.com/apache/maven-resolver/blob/master/maven-resolver-spi/src/main/java/org/eclipse/aether/spi/connector/RepositoryConnector.java).
Copy link
Member Author

@kwin kwin Sep 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about checksums? Are they treated as separate artifacts like signatures?

Copy link
Member

@cstamas cstamas Sep 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, checksums are feature of basic connector (check out M2 layout, that one contains the "configured" checksums), and they are opaquely (to client) being uploaded (on deploy) or being asked for (on consume) by basic connector. No client code should ever mangle with them (while deploying or resolving).

Though, as they are treated/cached in same was as artifacts and metadata, they are stored in local repository (on consume), and also, they can be explicitly resolved too by same calls as artifacts or metadata is resolved.

In short: checksums are NOT separate artifacts (even if they do behave like "separate artifacts" in some respect), but there are important differences. In general, you should NOT assume they are separate artifacts, you should leave their handling to basic connector: the role of basic connector among others, is that when it returns from a call with downloaded artifact, you KNOW the checksums are checked and are okay (according to session config like checksum policy and configured checksum algs), otherwise basic connector fails the call.

Copy link
Member

@cstamas cstamas Sep 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And one more important point: if you DO provide checksums, basic connector will let them pass (and deploy in opaque manner) unless configured to use same checksum algorithm. Think ASF source bundle deploys, we use a plugin to create SHA512 for them, (while Resolver is using 'standard' checksum config of MD5 and SHA1). IF Resolver would be configured to use SHA512 as well (mvn3: -Daether.checksums.algorithms=... and mvn4: aether.layout.maven2.checksumAlgorithms), it would recalculate and replace checksum with its own on deploy.

Copy link
Member

@cstamas cstamas Sep 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, important is the "kind" of checksum:

maven-resolver/maven-resolver-spi/src/main/java/org/eclipse/aether/spi/connector/checksum/ChecksumPolicy.java

Lines 65 to 93 in f737339

/**
* Enum denoting origin of checksum.
*
* @since 1.8.0
*/
enum ChecksumKind {
/**
* Remote external kind of checksum are retrieved from remote doing extra transport round-trip (usually by
* getting "file.jar.sha1" for corresponding "file.jar" file). This kind of checksum is part of layout, and
* was from beginning the "official" (and one and only) checksum used by resolver. If no external checksum
* present, {@link #onNoMoreChecksums()} method is invoked that (by default) fails retrieval.
*/
REMOTE_EXTERNAL,
/**
* Included checksums may be received from remote repository during the retrieval of the main file, for example
* from response headers in case of HTTP transport. They may be set with
* {@link org.eclipse.aether.spi.connector.transport.GetTask#setChecksum(String, String)}. If no included
* checksum present, {@link #REMOTE_EXTERNAL} is tried for.
*/
REMOTE_INCLUDED,
/**
* Provided checksums may be provided by {@link org.eclipse.aether.spi.checksums.ProvidedChecksumsSource}
* components, ahead of artifact retrieval. If no provided checksum present, {@link #REMOTE_INCLUDED} is
* tried for.
*/
PROVIDED
}


The most prominent consumer of this API is probably [maven-deploy-plugin](https://maven.apache.org/plugins/maven-deploy-plugin/).

# Repository Connector

The default repository connector implementation at [`BasicRepositoryConnectorFactory`](https://github.com/apache/maven-resolver/blob/master/maven-resolver-connector-basic/src/main/java/org/eclipse/aether/connector/basic/BasicRepositoryConnector.java) uses a `RepositoryLayout` to calculate the URL and a `Transporter` to achieve the actual upload/write of artifacts/metadata.

## Repository Layout

The repository layout determines the location to which the artifact is being written/uploaded with its `RepositoryLayout.getLocation(Artifact, true)` or `RepositoryLayout.getLocation(Metadata, true)` method. For [Maven 2 repositories](https://maven.apache.org/repositories/layout.html) the logic is implemented in [`Maven2RepositoryLayoutFactory`](https://github.com/apache/maven-resolver/blob/master/maven-resolver-impl/src/main/java/org/eclipse/aether/internal/impl/Maven2RepositoryLayoutFactory.java).

## Transporter

All transporter implementations have a [`put(...)`](https://github.com/apache/maven-resolver/blob/master/maven-resolver-spi/src/main/java/org/eclipse/aether/spi/connector/transport/Transporter.java) method which is called during deployment. The repository's URL protocol determines which method is used for the deployment. The standard transporters implement `put(...)` like follows:

URL Protocol | Implementation | Description
--- | --- | ---
`file`, `bundle` | `org.eclipse.aether.transport.file.FileTransporter` | Writes artifact/metadata to the file system.
`http`, `https` | multiple | Issues a HTTP PUT request for each given artifact/metadata.
`classpath` | `org.eclipse.aether.transport.classpath.ClasspathTransporter` | Unsupported
`minio+http`, `minio+https`, `s3+http`, `s3+https` | `org.eclipse.aether.transport.minio.MinioTransporter` | Uploads artifact/metadata as object to bucket. The location returned from the `RepositoryLayout` is being converted to an object and bucket name according to the configuration.
`*` | `org.eclipse.aether.transport.wagon.WagonTransporter` | Calls `StreamingWagon.putFromStream(...)` or `Wagon.put(...)`. See [Apache Wagon](https://maven.apache.org/wagon/) for further details.

1 change: 1 addition & 0 deletions src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ under the License.
<item name="Creating a RepositorySystemSession" href="creating-a-repository-system-session.html"/>
<item name="Resolving Dependencies" href="resolving-dependencies.html"/>
<item name="Common Misconceptions" href="common-misconceptions.html"/>
<item name="Artifact Deployment" href="deployment.html"/>
</menu>
<menu name="Reference">
<item name="Configuration" href="configuration.html"/>
Expand Down
Loading