You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-commits@maven.apache.org by sv...@apache.org on 2025/02/04 22:30:13 UTC

svn commit: r1923577 - /maven/website/content/repositories/artifacts.html

Author: svn-site-role
Date: Tue Feb  4 22:30:13 2025
New Revision: 1923577

Log:
Site checkin for project Apache Maven Site

Modified:
    maven/website/content/repositories/artifacts.html

Modified: maven/website/content/repositories/artifacts.html
==============================================================================
--- maven/website/content/repositories/artifacts.html (original)
+++ maven/website/content/repositories/artifacts.html Tue Feb  4 22:30:13 2025
@@ -153,24 +153,21 @@ specific language governing permissions
 under the License.
 -->
 
-<p>An Artifact is &#x201c;anything&#x201d; (any file) that can be addressed using its coordinates, and Maven downloads, installs or
-deploys for you. Most of them are POMs and JARs but
-an artifact can be really anything. A very important thing about artifacts is that they have coordinates,
+<p>An artifact is a file (more precisely, a sequence of bytes) that can be addressed using its coordinates
+and which Maven downloads, installs, or deploys for you. Most artifacts are POMs and JARs, but
+an artifact can be really any file. A very important thing about artifacts is that they have coordinates,
 so they are not &#x201c;just files&#x201d;, but they are files that are in some way addressable by Maven.</p>
-<p>Artifact coordinates, are most often represented as <code>groupId:artifactId:version</code>, or GAV in short or when
-informally used (please note that Artifact coordinates has more fields, but for brevity we still call the
-coordinates &#x201c;GAV&#x201d;, not &#x201c;GAVCE&#x201d;). The artifact coordinates uniquely describe the artifact you are referring to,
-but does not tell anything about its source (or origin). It is up to Maven to figure out (or you to tell Maven
-how to figure it out).</p>
-<p>A word about uniqueness: as stated above, GAV coordinates uniquely identifies artifact, but only <strong>within one repository</strong>.
-It is clearly possible (but discouraged) to have multiple repositories with overlapping content (so R1 and R2 both
-contain artifact with same GAV). If those files are not-identical (truly, ie. hash wise), it may cause severe
-issues without you noticing it. In short, these cases should be avoided.</p>
-<p>While Maven internally uses the notion of &#x201c;artifact&#x201d; thoroughly (just look at sources!), end users may never hit this term.
-That's due the fact, that while for Maven, &#x201c;everything is artifact&#x201d; (internally), Maven end users actually speak about
-&#x201c;projects&#x201d;, &#x201c;parent projects&#x201d;, &#x201c;dependencies&#x201d;, &#x201c;build plugins&#x201d;, &#x201c;reporting plugins&#x201d;, &#x201c;build extensions&#x201d; and so on.</p><section><a id="Artifact_Properties"></a>
+<p>Artifact coordinates are most often represented as <code>groupId:artifactId:version</code>, or GAV in short.
+(Please note that artifact coordinates have more fields, but for brevity we still call the
+coordinates &#x201c;GAV&#x201d;, not &#x201c;GAVCE&#x201d;). The artifact coordinates uniquely identify an artifact,
+but do not specify anything about its source. It is up to Maven to figure out (or you to tell Maven
+how to figure out) how and from where to retrieve the artifact.</p>
+<p>A word about uniqueness: as stated above, GAV coordinates uniquely identify an artifact, but only <strong>within one repository</strong>.
+Different repositories can contain artifacts with the same GAV. (This is normal with
+mirror repositories.) If those files are not identical, it can cause severe
+issues without you noticing it. In short, these cases should be avoided.</p><section><a id="Artifact_Properties"></a>
 <h2>Artifact Properties</h2>
-<p>The artifacts that Maven (internally) uses has following (for our topic related) properties:</p>
+<p>The artifacts that Maven uses internally have the following properties:</p>
 <table class="table table-striped">
 <thead>
 <tr class="a">
@@ -178,36 +175,34 @@ That's due the fact, that while for Mave
 <th>Description</th></tr></thead><tbody>
 <tr class="b">
 <td>groupId</td>
-<td>The artifact group</td></tr>
+<td>The project group</td></tr>
 <tr class="a">
 <td>artifactId</td>
-<td>The artifact id</td></tr>
+<td>The artifact ID</td></tr>
 <tr class="b">
 <td>version</td>
-<td>The artifact version (linked w/ baseVersion)</td></tr>
+<td>The artifact version (linked with baseVersion)</td></tr>
 <tr class="a">
 <td>baseVersion</td>
-<td>The artifact base version (linked w/ version)</td></tr>
+<td>The artifact base version (linked with version)</td></tr>
 <tr class="b">
 <td>classifier</td>
-<td>The artifact distinguishing classifier (optional)</td></tr>
+<td>The artifact classifier (optional)</td></tr>
 <tr class="a">
 <td>extension</td>
 <td>The artifact extension (default: &#x201c;jar&#x201d;)</td></tr></tbody>
 </table>
 
-<p>One property worth explaining is a bit of special one: <code>baseVersion</code> that is actually derived/linked to
-<code>version</code> (or the other way around, depending on the context): for release artifacts, it holds the same value as
-<code>version</code>, whereas for snapshot artifacts, it holds the &#x201c;non-timestamped snapshot version&#x201d;. For example,
-for snapshot version &#x201c;1.0-20220119.164608-1&#x201d;, the <code>baseVersion</code> would have the value &#x201c;1.0-SNAPSHOT&#x201d;.
-So, <code>version</code> and <code>baseVersion</code> are linked, derived from each other, but <strong>they have different values only in
-case of snapshots</strong>.</p>
-<p>Important note about Artifacts: the fact is an artifact a snapshot or not, should be queried with method
-<code>Artifact#isSnapshot()</code>.</p></section><section><a id="But_where_do_I_set_Artifact_extension.3F"></a>
-<h2>But where do I set Artifact extension?</h2>
-<p>In short, nowhere. Or maybe &#x201c;you rarely have to&#x201d;. Maven POM (where you declare your project, parent project,
-dependencies, plugins and other), maps those elements onto artifact coordinates with some extra logic.</p>
-<p>In case of &#x201c;project&#x201d; and &#x201c;parent project&#x201d; aka POMs (after POM made into effective POM, ie. parent values inherited):</p>
+<p>One property worth explaining is a bit of special one: <code>baseVersion</code> is derived from/linked to
+<code>version</code> (or the other way around, depending on the context). For release artifacts, it has the same value as
+<code>version</code>, whereas for snapshot artifacts, it has the &#x201c;non-timestamped snapshot version&#x201d;. For example,
+snapshot version &#x201c;1.0-20220119.164608-1&#x201d; has the <code>baseVersion</code> &#x201c;1.0-SNAPSHOT&#x201d;.
+So, <code>version</code> and <code>baseVersion</code> are linked, derived from each other, but <strong>they have different values only in the
+case of snapshots</strong>.</p></section><section><a id="But_where_do_I_set_the_Artifact_extension.3F"></a>
+<h2>But where do I set the Artifact extension?</h2>
+<p>In short, nowhere. Or maybe &#x201c;you rarely have to&#x201d;. The Maven POM (where you declare your project, parent project,
+dependencies, plugins and other items), maps those elements onto artifact extensions with some extra logic.</p>
+<p>In case of &#x201c;project&#x201d; and &#x201c;parent project&#x201d; POMs (after the POM is made into an effective POM, that is, parent values have been inherited):</p>
 <table class="table table-striped">
 <thead>
 <tr class="a">
@@ -236,7 +231,7 @@ dependencies, plugins and other), maps t
 <td><code>pom</code> (always)</td></tr></tbody>
 </table>
 
-<p>In case of &#x201c;build plugins&#x201d; and &#x201c;build extensions&#x201d;, as they are JARs, this is how corresponding elements are mapped
+<p>In the case of &#x201c;build plugins&#x201d; and &#x201c;build extensions&#x201d;, as they are JARs, this is how corresponding elements are mapped
 (for build extension change the XML path prefix to <code>project/build/extensions/extension[x]</code>):</p>
 <table class="table table-striped">
 <thead>
@@ -266,7 +261,7 @@ dependencies, plugins and other), maps t
 <td>-&gt; <code>jar</code> (always)</td></tr></tbody>
 </table>
 
-<p>And finally, in case of &#x201c;dependencies&#x201d;, this is the mapping (no, scope is NOT part of artifact coordinates):</p>
+<p>And finally, in the case of &#x201c;dependencies&#x201d;, this is the mapping (no, scope is NOT part of artifact coordinates):</p>
 <table class="table table-striped">
 <thead>
 <tr class="a">
@@ -295,11 +290,12 @@ dependencies, plugins and other), maps t
 <td>-&gt; type handler provided, or same as type</td></tr></tbody>
 </table>
 
-<p>Here, we need to make a short detour to explain &#x201c;type&#x201d; (of a dependency) and how it becomes artifact extension.</p>
-<p>Maven for dependencies defines &#x201c;type&#x201d;, that describes what that dependency is (should it be added to classpath and
-many other things). Plugins and extensions may define new types, that is usually a must for plugins introducing
-a &#x201c;packaging&#x201d; (lifecycle mapping) by providing <code>ArtifactHandler</code> components with name corresponding to type name.</p>
-<p>Maven Core out of the box <a href="/ref/current/maven-core/artifact-handlers.html">defines following &#x201c;types&#x201d; (handled by same named <code>ArtifactHandler</code> components)</a>:</p>
+<p>Here, we need to make a short detour to explain &#x201c;dependency type&#x201d; and how it becomes an artifact extension.</p>
+<p>A dependency type determines how the artifact referenced by the dependency is used.
+For example, should it be added to comple-time classpath, the test classpath, or both?
+Plugins and extensions may define new types. This is usually required for plugins introducing
+a &#x201c;packaging&#x201d; (lifecycle mapping) by providing <code>ArtifactHandler</code> components with a name corresponding to type name.</p>
+<p>Out of the box, Maven Core defines the <a href="/ref/current/maven-core/artifact-handlers.html">following &#x201c;types&#x201d; (handled by the same named <code>ArtifactHandler</code> components)</a>:</p>
 <table class="table table-striped">
 <thead>
 <tr class="a">
@@ -356,15 +352,14 @@ a &#x201c;packaging&#x201d; (lifecycle m
 <td> </td></tr></tbody>
 </table>
 
-<p>From table above, we can see that if we define the dependency type as &#x201c;war&#x201d;, we will hit the &#x201c;war&#x201d; handler, that will
+<p>From the table above, we can see that if we define the dependency type as &#x201c;war&#x201d;, we will hit the &#x201c;war&#x201d; handler. That will
 result in using the <code>war</code> extension (which may not be obvious, as the type and extension we end up with are the same, but internally this
-indirection does happen). The &#x201c;test-jar&#x201d; is more obvious, as it translates to <code>jar</code> extension. Finally, the <strong>any</strong>
-last row will be used if none above matches, hence in that case your &#x201c;type&#x201d; is used just as &#x201c;extension&#x201d;, for example
-you can write <code>&lt;type&gt;tar.gz&lt;/type&gt;</code> for dependency, and you will end up with extension <code>tar.gz</code> (all this happens
-because as there is no artifact handler named &#x201c;tar.gz&#x201d; in table above). Still, you should be aware that this table
-above may be extended by various plugins and extensions you use in your build!</p>
-<p>Also, this has &#x201c;interesting&#x201d; consequences, consider for example following Artifact:
-<code>org.project:reusable-test-support:1.0:tests:jar</code>. With type handlers above, maybe surprisingly, the dependency to
+indirection does happen). The &#x201c;test-jar&#x201d; is more obvious, as it translates to the <code>jar</code> extension. Finally, the <strong>any</strong>
+last row will be used if none of the above match. Hence in that case the &#x201c;type&#x201d; is used as the &#x201c;extension&#x201d;. For example.
+if the dependency type is <code>&lt;type&gt;tar.gz&lt;/type&gt;</code>, the extension will also be <code>tar.gz</code>.
+This table may be extended by plugins and extensions used in the build.</p>
+<p>Also, this has &#x201c;interesting&#x201d; consequences. Consider the artifact
+<code>org.project:reusable-test-support:1.0:tests:jar</code>. With the type handlers above, maybe surprisingly, the dependency to
 this very same artifact can be described in two ways:</p>
 
 <pre class="prettyprint linenums"><code class="language-xml">&lt;dependency&gt;
@@ -383,12 +378,11 @@ this very same artifact can be described
   &lt;type&gt;test-jar&lt;/type&gt;
 &lt;/dependency&gt;
 </code></pre>
-<p>Obvious difference is presence of <code>classifier</code> in first case, while in second lack of it but presence of <code>type</code> &#x201c;test-jar&#x201d;,
-that in the other hand, implies classifier of &#x201c;tests&#x201d;. In both cases, extension is &#x201c;jar&#x201d; (in first it uses the default
-value for this property, while in second type defines it).</p>
-<p>Note: In this very case, using the first way is somewhat &#x201c;explicit&#x201d;, and is recommended way. Not so for the
+<p>The obvious difference is presence of <code>classifier</code> in first case, while in second lack of it but presence of <code>type</code> &#x201c;test-jar&#x201d;,
+that in the other hand, implies a classifier of &#x201c;tests&#x201d;. In both cases, the extension is &#x201c;jar&#x201d;. The first it uses the default value for this property, while the second type defines it.</p>
+<p>Note: In this very case, the first way is somewhat &#x201c;explicit&#x201d;, and is recommended. Not so for the
 cases when type handler carries some important extra information (like some custom packaging), where using <code>type</code>
-is more appropriate. Simply put, in this case the type &#x201c;test-jar&#x201d; is like an alias for ordinary JARs with &#x201c;tests&#x201d;
+is more appropriate. Simply put, in this case the type &#x201c;test-jar&#x201d; is like an alias for ordinary JARs with the &#x201c;tests&#x201d;
 classifier.</p></section><section><a id="Summary"></a>
 <h2>Summary</h2>
 <p>In short, this is how various Maven bits like &#x201c;project&#x201d;, &#x201c;parent project&#x201d;, &#x201c;plugin&#x201d;, &#x201c;extension&#x201d; and &#x201c;dependency&#x201d;