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