View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.maven.api;
20  
21  import org.apache.maven.api.annotations.Experimental;
22  import org.apache.maven.api.annotations.Immutable;
23  import org.apache.maven.api.annotations.Nonnull;
24  
25  /**
26   * A Maven artifact is a file, typically a JAR, that is produced and used by Maven projects.
27   * It is identified by a unique combination of a group ID, artifact ID, version, classifier,
28   * and extension, and it is stored in a repository for dependency management and build purposes.
29   *
30   * <p>Each {@code Artifact} instance is basically an exact pointer to a file in a Maven repository.
31   * {@code Artifact} instances are created when <dfn>resolving</dfn> {@link ArtifactCoordinates} instances.
32   * Resolving is the process that selects a {@linkplain #getVersion() particular version}
33   * and downloads the artifact in the local repository.  This operation returns a {@link DownloadedArtifact}.
34   * </p>
35   *
36   * @since 4.0.0
37   */
38  @Experimental
39  @Immutable
40  public interface Artifact {
41      /**
42       * {@return a unique identifier for this artifact}
43       * The identifier is composed of groupId, artifactId, extension, classifier, and version.
44       *
45       * @see ArtifactCoordinates#getId()
46       */
47      @Nonnull
48      default String key() {
49          String c = getClassifier();
50          return getGroupId()
51                  + ':'
52                  + getArtifactId()
53                  + ':'
54                  + getExtension()
55                  + (c.isEmpty() ? "" : ":" + c)
56                  + ':'
57                  + getVersion();
58      }
59  
60      /**
61       * {@return the group identifier of the artifact}
62       *
63       * @see ArtifactCoordinates#getGroupId()
64       */
65      @Nonnull
66      String getGroupId();
67  
68      /**
69       * {@return the identifier of the artifact}
70       *
71       * @see ArtifactCoordinates#getArtifactId()
72       */
73      @Nonnull
74      String getArtifactId();
75  
76      /**
77       * {@return the version of the artifact}
78       * Contrarily to {@link ArtifactCoordinates},
79       * each {@code Artifact} is associated to a specific version instead of a range of versions.
80       * If the {@linkplain #getBaseVersion() base version} contains a meta-version such as {@code SNAPSHOT},
81       * those keywords are replaced by, for example, the actual timestamp.
82       *
83       * @see ArtifactCoordinates#getVersionConstraint()
84       */
85      @Nonnull
86      Version getVersion();
87  
88      /**
89       * {@return the version or meta-version of the artifact}
90       * A meta-version is a version suffixed with the {@code SNAPSHOT} keyword.
91       * Meta-versions are represented in a base version by their symbols (e.g., {@code SNAPSHOT}),
92       * while they are replaced by, for example, the actual timestamp in the {@linkplain #getVersion() version}.
93       */
94      @Nonnull
95      Version getBaseVersion();
96  
97      /**
98       * Returns the classifier of the artifact.
99       *
100      * @return the classifier or an empty string if none, never {@code null}
101      * @see ArtifactCoordinates#getClassifier()
102      */
103     @Nonnull
104     String getClassifier();
105 
106     /**
107      * Returns the file extension of the artifact.
108      * The dot separator is <em>not</em> included in the returned string.
109      *
110      * @return the file extension or an empty string if none, never {@code null}
111      * @see ArtifactCoordinates#getExtension()
112      */
113     @Nonnull
114     String getExtension();
115 
116     /**
117      * Determines whether this artifact uses a snapshot version.
118      *
119      * @return {@code true} if the artifact is a snapshot, {@code false} otherwise
120      * @see org.apache.maven.api.Session#isVersionSnapshot(String)
121      */
122     boolean isSnapshot();
123 
124     /**
125      * {@return coordinates with the same identifiers as this artifact}
126      * This is a shortcut for {@code session.createArtifactCoordinates(artifact)}.
127      *
128      * @see org.apache.maven.api.Session#createArtifactCoordinates(Artifact)
129      */
130     @Nonnull
131     ArtifactCoordinates toCoordinates();
132 }