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.apache.maven.api; 20 21 import org.apache.maven.api.annotations.Experimental; 22 import org.apache.maven.api.annotations.Immutable; 23 import org.apache.maven.api.annotations.Nonnull; 24 25 /** 26 * A Maven artifact is a file, typically a JAR, that is produced and used by Maven projects. 27 * It is identified by a unique combination of a group ID, artifact ID, version, classifier, 28 * and extension, and it is stored in a repository for dependency management and build purposes. 29 * 30 * <p>Each {@code Artifact} instance is basically an exact pointer to a file in a Maven repository. 31 * {@code Artifact} instances are created when <dfn>resolving</dfn> {@link ArtifactCoordinates} instances. 32 * Resolving is the process that selects a {@linkplain #getVersion() particular version} 33 * and downloads the artifact in the local repository. This operation returns a {@link DownloadedArtifact}. 34 * </p> 35 * 36 * @since 4.0.0 37 */ 38 @Experimental 39 @Immutable 40 public interface Artifact { 41 /** 42 * {@return a unique identifier for this artifact} 43 * The identifier is composed of groupId, artifactId, extension, classifier, and version. 44 * 45 * @see ArtifactCoordinates#getId() 46 */ 47 @Nonnull 48 default String key() { 49 String c = getClassifier(); 50 return getGroupId() 51 + ':' 52 + getArtifactId() 53 + ':' 54 + getExtension() 55 + (c.isEmpty() ? "" : ":" + c) 56 + ':' 57 + getVersion(); 58 } 59 60 /** 61 * {@return the group identifier of the artifact} 62 * 63 * @see ArtifactCoordinates#getGroupId() 64 */ 65 @Nonnull 66 String getGroupId(); 67 68 /** 69 * {@return the identifier of the artifact} 70 * 71 * @see ArtifactCoordinates#getArtifactId() 72 */ 73 @Nonnull 74 String getArtifactId(); 75 76 /** 77 * {@return the version of the artifact} 78 * Contrarily to {@link ArtifactCoordinates}, 79 * each {@code Artifact} is associated to a specific version instead of a range of versions. 80 * If the {@linkplain #getBaseVersion() base version} contains a meta-version such as {@code SNAPSHOT}, 81 * those keywords are replaced by, for example, the actual timestamp. 82 * 83 * @see ArtifactCoordinates#getVersionConstraint() 84 */ 85 @Nonnull 86 Version getVersion(); 87 88 /** 89 * {@return the version or meta-version of the artifact} 90 * A meta-version is a version suffixed with the {@code SNAPSHOT} keyword. 91 * Meta-versions are represented in a base version by their symbols (e.g., {@code SNAPSHOT}), 92 * while they are replaced by, for example, the actual timestamp in the {@linkplain #getVersion() version}. 93 */ 94 @Nonnull 95 Version getBaseVersion(); 96 97 /** 98 * Returns the classifier of the artifact. 99 * 100 * @return the classifier or an empty string if none, never {@code null} 101 * @see ArtifactCoordinates#getClassifier() 102 */ 103 @Nonnull 104 String getClassifier(); 105 106 /** 107 * Returns the file extension of the artifact. 108 * The dot separator is <em>not</em> included in the returned string. 109 * 110 * @return the file extension or an empty string if none, never {@code null} 111 * @see ArtifactCoordinates#getExtension() 112 */ 113 @Nonnull 114 String getExtension(); 115 116 /** 117 * Determines whether this artifact uses a snapshot version. 118 * 119 * @return {@code true} if the artifact is a snapshot, {@code false} otherwise 120 * @see org.apache.maven.api.Session#isVersionSnapshot(String) 121 */ 122 boolean isSnapshot(); 123 124 /** 125 * {@return coordinates with the same identifiers as this artifact} 126 * This is a shortcut for {@code session.createArtifactCoordinates(artifact)}. 127 * 128 * @see org.apache.maven.api.Session#createArtifactCoordinates(Artifact) 129 */ 130 @Nonnull 131 ArtifactCoordinates toCoordinates(); 132 }