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}. Contrarily to {@link ArtifactCoordinates}, 78 * each {@code Artifact} is associated to a specific version instead of a range of versions. 79 * If the {@linkplain #getBaseVersion() base version} contains a meta-version such as {@code SNAPSHOT}, 80 * those keywords are replaced by, for example, the actual timestamp. 81 * 82 * @see ArtifactCoordinates#getVersionConstraint() 83 */ 84 @Nonnull 85 Version getVersion(); 86 87 /** 88 * {@return the version or meta-version of the artifact}. 89 * A meta-version is a version suffixed with the {@code SNAPSHOT} keyword. 90 * Meta-versions are represented in a base version by their symbols (e.g., {@code SNAPSHOT}), 91 * while they are replaced by, for example, the actual timestamp in the {@linkplain #getVersion() version}. 92 */ 93 @Nonnull 94 Version getBaseVersion(); 95 96 /** 97 * Returns the classifier of the artifact. 98 * 99 * @return the classifier or an empty string if none, never {@code null} 100 * @see ArtifactCoordinates#getClassifier() 101 */ 102 @Nonnull 103 String getClassifier(); 104 105 /** 106 * Returns the file extension of the artifact. 107 * The dot separator is <em>not</em> included in the returned string. 108 * 109 * @return the file extension or an empty string if none, never {@code null} 110 * @see ArtifactCoordinates#getExtension() 111 */ 112 @Nonnull 113 String getExtension(); 114 115 /** 116 * Determines whether this artifact uses a snapshot version. 117 * 118 * @return {@code true} if the artifact is a snapshot, {@code false} otherwise 119 * @see org.apache.maven.api.Session#isVersionSnapshot(String) 120 */ 121 boolean isSnapshot(); 122 123 /** 124 * {@return coordinates with the same identifiers as this artifact}. 125 * This is a shortcut for {@code session.createArtifactCoordinates(artifact)}. 126 * 127 * @see org.apache.maven.api.Session#createArtifactCoordinates(Artifact) 128 */ 129 @Nonnull 130 ArtifactCoordinates toCoordinates(); 131 }