View Javadoc
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 }