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 *
55 * @return The version, never {@code null}.
56 */
57 String getVersion();
58
59 /**
60 * Sets the version of the artifact.
61 *
62 * @param version The version of this artifact, may be {@code null} or empty.
63 * @return The new artifact, never {@code null}.
64 */
65 Artifact setVersion(String version);
66
67 /**
68 * Gets the base version of this artifact, for example "1.0-SNAPSHOT". In contrast to the {@link #getVersion()}, the
69 * base version will always refer to the unresolved meta version.
70 *
71 * @return The base version, never {@code null}.
72 */
73 String getBaseVersion();
74
75 /**
76 * Determines whether this artifact uses a snapshot version.
77 *
78 * @return {@code true} if the artifact is a snapshot, {@code false} otherwise.
79 */
80 boolean isSnapshot();
81
82 /**
83 * Gets the classifier of this artifact, for example "sources".
84 *
85 * @return The classifier or an empty string if none, never {@code null}.
86 */
87 String getClassifier();
88
89 /**
90 * Gets the (file) extension of this artifact, for example "jar" or "tar.gz".
91 *
92 * @return The file extension (without leading period), never {@code null}.
93 */
94 String getExtension();
95
96 /**
97 * Gets the file of this artifact. Note that only resolved artifacts have a file associated with them. In general,
98 * callers must not assume any relationship between an artifact's filename and its coordinates.
99 *
100 * @return The file or {@code null} if the artifact isn't resolved.
101 * @deprecated Use {@link #getPath()} instead.
102 */
103 @Deprecated
104 File getFile();
105
106 /**
107 * Gets the file of this artifact. Note that only resolved artifacts have a file associated with them. In general,
108 * callers must not assume any relationship between an artifact's filename and its coordinates.
109 *
110 * @return The file or {@code null} if the artifact isn't resolved.
111 * @since 2.0.0
112 */
113 Path getPath();
114
115 /**
116 * Sets the file of the artifact.
117 *
118 * @param file The file of the artifact, may be {@code null}
119 * @return The new artifact, never {@code null}.
120 * @deprecated Use {@link #setPath(Path)} instead.
121 */
122 @Deprecated
123 Artifact setFile(File file);
124
125 /**
126 * Sets the file of the artifact.
127 *
128 * @param path The file of the artifact, may be {@code null}
129 * @return The new artifact, never {@code null}.
130 * @since 2.0.0
131 */
132 Artifact setPath(Path path);
133
134 /**
135 * Gets the specified property.
136 *
137 * @param key The name of the property, must not be {@code null}.
138 * @param defaultValue The default value to return in case the property is not set, may be {@code null}.
139 * @return The requested property value or {@code null} if the property is not set and no default value was
140 * provided.
141 * @see ArtifactProperties
142 */
143 String getProperty(String key, String defaultValue);
144
145 /**
146 * Gets the properties of this artifact. Clients may use these properties to associate non-persistent values with an
147 * artifact that help later processing when the artifact gets passed around within the application.
148 *
149 * @return The (read-only) properties, never {@code null}.
150 * @see ArtifactProperties
151 */
152 Map<String, String> getProperties();
153
154 /**
155 * Sets the properties for the artifact. Note that these properties exist merely in memory and are not persisted
156 * when the artifact gets installed/deployed to a repository.
157 *
158 * @param properties The properties for the artifact, may be {@code null}.
159 * @return The new artifact, never {@code null}.
160 * @see ArtifactProperties
161 */
162 Artifact setProperties(Map<String, String> properties);
163 }