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