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.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 }