org.argeo.slc.repo/src/org/eclipse/aether/artifact/Artifact.java

   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 }