001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.eclipse.aether.artifact;
020
021import java.io.File;
022import java.util.Map;
023
024/**
025 * A specific artifact. In a nutshell, an artifact has identifying coordinates and optionally a file that denotes its
026 * data. <em>Note:</em> Artifact instances are supposed to be immutable, e.g. any exposed mutator method returns a new
027 * artifact instance and leaves the original instance unchanged. <em>Note:</em> Implementors are strongly advised to
028 * inherit from {@link AbstractArtifact} instead of directly implementing this interface.
029 *
030 * @noimplement This interface is not intended to be implemented by clients.
031 * @noextend This interface is not intended to be extended by clients.
032 */
033public interface Artifact {
034
035    /**
036     * Gets the group identifier of this artifact, for example "org.apache.maven".
037     *
038     * @return The group identifier, never {@code null}.
039     */
040    String getGroupId();
041
042    /**
043     * Gets the artifact identifier of this artifact, for example "maven-model".
044     *
045     * @return The artifact identifier, never {@code null}.
046     */
047    String getArtifactId();
048
049    /**
050     * Gets the version of this artifact, for example "1.0-20100529-1213". Note that in case of meta versions like
051     * "1.0-SNAPSHOT", the artifact's version depends on the state of the artifact. Artifacts that have been resolved or
052     * deployed will usually have the meta version expanded.
053     *
054     * @return The version, never {@code null}.
055     */
056    String getVersion();
057
058    /**
059     * Sets the version of the artifact.
060     *
061     * @param version The version of this artifact, may be {@code null} or empty.
062     * @return The new artifact, never {@code null}.
063     */
064    Artifact setVersion(String version);
065
066    /**
067     * Gets the base version of this artifact, for example "1.0-SNAPSHOT". In contrast to the {@link #getVersion()}, the
068     * base version will always refer to the unresolved meta version.
069     *
070     * @return The base version, never {@code null}.
071     */
072    String getBaseVersion();
073
074    /**
075     * Determines whether this artifact uses a snapshot version.
076     *
077     * @return {@code true} if the artifact is a snapshot, {@code false} otherwise.
078     */
079    boolean isSnapshot();
080
081    /**
082     * Gets the classifier of this artifact, for example "sources".
083     *
084     * @return The classifier or an empty string if none, never {@code null}.
085     */
086    String getClassifier();
087
088    /**
089     * Gets the (file) extension of this artifact, for example "jar" or "tar.gz".
090     *
091     * @return The file extension (without leading period), never {@code null}.
092     */
093    String getExtension();
094
095    /**
096     * Gets the file of this artifact. Note that only resolved artifacts have a file associated with them. In general,
097     * callers must not assume any relationship between an artifact's filename and its coordinates.
098     *
099     * @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}