1 package org.eclipse.aether.artifact;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.io.File;
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 /**
38 * Gets the group identifier of this artifact, for example "org.apache.maven".
39 *
40 * @return The group identifier, never {@code null}.
41 */
42 String getGroupId();
43
44 /**
45 * Gets the artifact identifier of this artifact, for example "maven-model".
46 *
47 * @return The artifact identifier, never {@code null}.
48 */
49 String getArtifactId();
50
51 /**
52 * Gets the version of this artifact, for example "1.0-20100529-1213". Note that in case of meta versions like
53 * "1.0-SNAPSHOT", the artifact's version depends on the state of the artifact. Artifacts that have been resolved or
54 * deployed will usually have the meta version expanded.
55 *
56 * @return The version, never {@code null}.
57 */
58 String getVersion();
59
60 /**
61 * Sets the version of the artifact.
62 *
63 * @param version The version of this artifact, may be {@code null} or empty.
64 * @return The new artifact, never {@code null}.
65 */
66 Artifact setVersion( String version );
67
68 /**
69 * Gets the base version of this artifact, for example "1.0-SNAPSHOT". In contrast to the {@link #getVersion()}, the
70 * base version will always refer to the unresolved meta version.
71 *
72 * @return The base version, never {@code null}.
73 */
74 String getBaseVersion();
75
76 /**
77 * Determines whether this artifact uses a snapshot version.
78 *
79 * @return {@code true} if the artifact is a snapshot, {@code false} otherwise.
80 */
81 boolean isSnapshot();
82
83 /**
84 * Gets the classifier of this artifact, for example "sources".
85 *
86 * @return The classifier or an empty string if none, never {@code null}.
87 */
88 String getClassifier();
89
90 /**
91 * Gets the (file) extension of this artifact, for example "jar" or "tar.gz".
92 *
93 * @return The file extension (without leading period), never {@code null}.
94 */
95 String getExtension();
96
97 /**
98 * Gets the file of this artifact. Note that only resolved artifacts have a file associated with them. In general,
99 * callers must not assume any relationship between an artifact's filename and its coordinates.
100 *
101 * @return The file or {@code null} if the artifact isn't resolved.
102 */
103 File getFile();
104
105 /**
106 * Sets the file of the artifact.
107 *
108 * @param file The file of the artifact, may be {@code null}
109 * @return The new artifact, never {@code null}.
110 */
111 Artifact setFile( File file );
112
113 /**
114 * Gets the specified property.
115 *
116 * @param key The name of the property, must not be {@code null}.
117 * @param defaultValue The default value to return in case the property is not set, may be {@code null}.
118 * @return The requested property value or {@code null} if the property is not set and no default value was
119 * provided.
120 * @see ArtifactProperties
121 */
122 String getProperty( String key, String defaultValue );
123
124 /**
125 * Gets the properties of this artifact. Clients may use these properties to associate non-persistent values with an
126 * artifact that help later processing when the artifact gets passed around within the application.
127 *
128 * @return The (read-only) properties, never {@code null}.
129 * @see ArtifactProperties
130 */
131 Map<String, String> getProperties();
132
133 /**
134 * Sets the properties for the artifact. Note that these properties exist merely in memory and are not persisted
135 * when the artifact gets installed/deployed to a repository.
136 *
137 * @param properties The properties for the artifact, may be {@code null}.
138 * @return The new artifact, never {@code null}.
139 * @see ArtifactProperties
140 */
141 Artifact setProperties( Map<String, String> properties );
142
143 }