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}. Contrarily to {@link ArtifactCoordinates},
78       * each {@code Artifact} is associated to a specific version instead of a range of versions.
79       * If the {@linkplain #getBaseVersion() base version} contains a meta-version such as {@code SNAPSHOT},
80       * those keywords are replaced by, for example, the actual timestamp.
81       *
82       * @see ArtifactCoordinates#getVersionConstraint()
83       */
84      @Nonnull
85      Version getVersion();
86  
87      /**
88       * {@return the version or meta-version of the artifact}.
89       * A meta-version is a version suffixed with the {@code SNAPSHOT} keyword.
90       * Meta-versions are represented in a base version by their symbols (e.g., {@code SNAPSHOT}),
91       * while they are replaced by, for example, the actual timestamp in the {@linkplain #getVersion() version}.
92       */
93      @Nonnull
94      Version getBaseVersion();
95  
96      /**
97       * Returns the classifier of the artifact.
98       *
99       * @return the classifier or an empty string if none, never {@code null}
100      * @see ArtifactCoordinates#getClassifier()
101      */
102     @Nonnull
103     String getClassifier();
104 
105     /**
106      * Returns the file extension of the artifact.
107      * The dot separator is <em>not</em> included in the returned string.
108      *
109      * @return the file extension or an empty string if none, never {@code null}
110      * @see ArtifactCoordinates#getExtension()
111      */
112     @Nonnull
113     String getExtension();
114 
115     /**
116      * Determines whether this artifact uses a snapshot version.
117      *
118      * @return {@code true} if the artifact is a snapshot, {@code false} otherwise
119      * @see org.apache.maven.api.Session#isVersionSnapshot(String)
120      */
121     boolean isSnapshot();
122 
123     /**
124      * {@return coordinates with the same identifiers as this artifact}.
125      * This is a shortcut for {@code session.createArtifactCoordinates(artifact)}.
126      *
127      * @see org.apache.maven.api.Session#createArtifactCoordinates(Artifact)
128      */
129     @Nonnull
130     ArtifactCoordinates toCoordinates();
131 }