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.eclipse.aether.artifact;
20
21 import java.io.File;
22 import java.nio.file.Path;
23 import java.util.Map;
24
25 /**
26 * A specific artifact. In a nutshell, an artifact has identifying coordinates and optionally a file that denotes its
27 * data. <em>Note:</em> Artifact instances are supposed to be immutable, e.g. any exposed mutator method returns a new
28 * artifact instance and leaves the original instance unchanged. <em>Note:</em> Implementors are strongly advised to
29 * inherit from {@link AbstractArtifact} instead of directly implementing this interface.
30 *
31 * @noimplement This interface is not intended to be implemented by clients.
32 * @noextend This interface is not intended to be extended by clients.
33 */
34 public interface Artifact {
35
36 /**
37 * Gets the group identifier of this artifact, for example "org.apache.maven".
38 *
39 * @return The group identifier, never {@code null}.
40 */
41 String getGroupId();
42
43 /**
44 * Gets the artifact identifier of this artifact, for example "maven-model".
45 *
46 * @return The artifact identifier, never {@code null}.
47 */
48 String getArtifactId();
49
50 /**
51 * Gets the version of this artifact, for example "1.0-20100529-1213". Note that in case of meta versions like
52 * "1.0-SNAPSHOT", the artifact's version depends on the state of the artifact. Artifacts that have been resolved or
53 * deployed will usually have the meta version expanded.
54 * This may also return version ranges like "[1.0,2.0)". The exact syntax for (meta) versions and version ranges
55 * depends on the underlying provider (encapsulated in {@link org.eclipse.aether.RepositorySystem}).
56 *
57 * @return The version, never {@code null}.
58 */
59 String getVersion();
60
61 /**
62 * Sets the version of the artifact.
63 *
64 * @param version The version of this artifact, may be {@code null} or empty.
65 * @return The new artifact, never {@code null}.
66 */
67 Artifact setVersion(String version);
68
69 /**
70 * Gets the base version of this artifact, for example "1.0-SNAPSHOT". In contrast to the {@link #getVersion()}, the
71 * base version will always refer to the unresolved meta version.
72 *
73 * @return The base version, never {@code null}.
74 */
75 String getBaseVersion();
76
77 /**
78 * Determines whether this artifact uses a snapshot version.
79 *
80 * @return {@code true} if the artifact is a snapshot, {@code false} otherwise.
81 */
82 boolean isSnapshot();
83
84 /**
85 * Gets the classifier of this artifact, for example "sources".
86 *
87 * @return The classifier or an empty string if none, never {@code null}.
88 */
89 String getClassifier();
90
91 /**
92 * Gets the (file) extension of this artifact, for example "jar" or "tar.gz".
93 *
94 * @return The file extension (without leading period), never {@code null}.
95 */
96 String getExtension();
97
98 /**
99 * Gets the file of this artifact. Note that only resolved artifacts have a file associated with them. In general,
100 * callers must not assume any relationship between an artifact's filename and its coordinates.
101 *
102 * @return The file or {@code null} if the artifact isn't resolved.
103 * @deprecated Use {@link #getPath()} instead.
104 */
105 @Deprecated
106 File getFile();
107
108 /**
109 * Gets the file of this artifact. Note that only resolved artifacts have a file associated with them. In general,
110 * callers must not assume any relationship between an artifact's filename and its coordinates.
111 *
112 * @return The file or {@code null} if the artifact isn't resolved.
113 * @since 2.0.0
114 */
115 Path getPath();
116
117 /**
118 * Sets the file of the artifact.
119 *
120 * @param file The file of the artifact, may be {@code null}
121 * @return The new artifact, never {@code null}.
122 * @deprecated Use {@link #setPath(Path)} instead.
123 */
124 @Deprecated
125 Artifact setFile(File file);
126
127 /**
128 * Sets the file of the artifact.
129 *
130 * @param path The file of the artifact, may be {@code null}
131 * @return The new artifact, never {@code null}.
132 * @since 2.0.0
133 */
134 Artifact setPath(Path path);
135
136 /**
137 * Gets the specified property.
138 *
139 * @param key The name of the property, must not be {@code null}.
140 * @param defaultValue The default value to return in case the property is not set, may be {@code null}.
141 * @return The requested property value or {@code null} if the property is not set and no default value was
142 * provided.
143 * @see ArtifactProperties
144 */
145 String getProperty(String key, String defaultValue);
146
147 /**
148 * Gets the properties of this artifact. Clients may use these properties to associate non-persistent values with an
149 * artifact that help later processing when the artifact gets passed around within the application.
150 *
151 * @return The (read-only) properties, never {@code null}.
152 * @see ArtifactProperties
153 */
154 Map<String, String> getProperties();
155
156 /**
157 * Sets the properties for the artifact. Note that these properties exist merely in memory and are not persisted
158 * when the artifact gets installed/deployed to a repository.
159 *
160 * @param properties The properties for the artifact, may be {@code null}.
161 * @return The new artifact, never {@code null}.
162 * @see ArtifactProperties
163 */
164 Artifact setProperties(Map<String, String> properties);
165 }