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 }