0
# Maven Artifact API
1

2
Maven Artifact API provides core interfaces and classes for representing, manipulating, and managing software artifacts within the Maven ecosystem. It includes comprehensive version handling capabilities, repository interaction APIs, and metadata management functionality.
3

4
## Package Information
5

6
- **Package Name**: maven-artifact
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Group ID**: org.apache.maven
10
- **Artifact ID**: maven-artifact
11
- **Version**: 3.9.11
12
- **Installation**: Include as dependency in your Maven project
13

14
```xml
15
<dependency>
16
    <groupId>org.apache.maven</groupId>
17
    <artifactId>maven-artifact</artifactId>
18
    <version>3.9.11</version>
19
</dependency>
20
```
21

22
## Core Imports
23

24
```java
25
import org.apache.maven.artifact.Artifact;
26
import org.apache.maven.artifact.DefaultArtifact;
27
import org.apache.maven.artifact.ArtifactUtils;
28
import org.apache.maven.artifact.handler.ArtifactHandler;
29
import org.apache.maven.artifact.versioning.ComparableVersion;
30
import org.apache.maven.artifact.versioning.VersionRange;
31
```
32

33
## Basic Usage
34

35
```java
36
import org.apache.maven.artifact.*;
37
import org.apache.maven.artifact.handler.ArtifactHandler;
38
import org.apache.maven.artifact.versioning.*;
39

40
// Create a new artifact (Note: Use your ArtifactHandler implementation)
41
// ArtifactHandler handler = new YourArtifactHandler("jar");
42
Artifact artifact = new DefaultArtifact(
43
    "org.example",           // groupId
44
    "my-library",           // artifactId  
45
    "1.0.0",               // version
46
    Artifact.SCOPE_COMPILE, // scope
47
    "jar",                 // type
48
    null,                  // classifier
49
    handler                // artifact handler
50
);
51

52
// Work with versions
53
ComparableVersion version1 = new ComparableVersion("1.2.3");
54
ComparableVersion version2 = new ComparableVersion("1.2.4");
55
int comparison = version1.compareTo(version2); // Returns -1
56

57
// Create version ranges
58
VersionRange range = VersionRange.createFromVersionSpec("[1.0,2.0)");
59
boolean matches = range.containsVersion(new DefaultArtifactVersion("1.5"));
60

61
// Use utilities
62
String key = ArtifactUtils.key(artifact);
63
boolean isSnapshot = ArtifactUtils.isSnapshot("1.0-SNAPSHOT");
64
```
65

66
## Architecture
67

68
The Maven Artifact API is organized around several key concepts:
69

70
- **Artifact Identity**: Unique identification using coordinates (groupId:artifactId:version:classifier)
71
- **Version Management**: Sophisticated version parsing, comparison, and range handling
72
- **Repository Operations**: Abstraction over various repository types and access patterns
73
- **Resolution Framework**: Exception handling and filtering for dependency resolution workflows
74

75
## Capabilities
76

77
### Artifact Creation and Management
78

79
Core artifact representation and utility operations for Maven artifact identity and manipulation.
80

81
```java { .api }
82
public interface Artifact extends Comparable<Artifact> {
83
    // Identity methods
84
    String getGroupId();
85
    void setGroupId(String groupId);
86
    String getArtifactId();
87
    void setArtifactId(String artifactId);
88
    String getVersion();
89
    void setVersion(String version);
90
    String getType();
91
    String getClassifier();
92
    boolean hasClassifier();
93
    String getScope();
94
    void setScope(String scope);
95
    
96
    // File operations
97
    File getFile();
98
    void setFile(File destination);
99
    
100
    // Version management
101
    String getBaseVersion();
102
    void setBaseVersion(String baseVersion);
103
    VersionRange getVersionRange();
104
    void setVersionRange(VersionRange newRange);
105
    void selectVersion(String version);
106
    ArtifactVersion getSelectedVersion() throws OverConstrainedVersionException;
107
    boolean isSelectedVersionKnown() throws OverConstrainedVersionException;
108
    List<ArtifactVersion> getAvailableVersions();
109
    void setAvailableVersions(List<ArtifactVersion> versions);
110
    
111
    // Repository operations
112
    ArtifactRepository getRepository();
113
    void setRepository(ArtifactRepository remoteRepository);
114
    void updateVersion(String version, ArtifactRepository localRepository);
115
    String getDownloadUrl();
116
    void setDownloadUrl(String downloadUrl);
117
    
118
    // Metadata management
119
    void addMetadata(ArtifactMetadata metadata);
120
    Collection<ArtifactMetadata> getMetadataList();
121
    
122
    // Dependency management
123
    List<String> getDependencyTrail();
124
    void setDependencyTrail(List<String> dependencyTrail);
125
    ArtifactFilter getDependencyFilter();
126
    void setDependencyFilter(ArtifactFilter artifactFilter);
127
    
128
    // Artifact handling
129
    ArtifactHandler getArtifactHandler();
130
    void setArtifactHandler(ArtifactHandler handler);
131
    
132
    // Status management
133
    String getId();
134
    String getDependencyConflictId();
135
    boolean isSnapshot();
136
    void setResolved(boolean resolved);
137
    boolean isResolved();
138
    void setResolvedVersion(String version);
139
    boolean isRelease();
140
    void setRelease(boolean release);
141
    boolean isOptional();
142
    void setOptional(boolean optional);
143
}
144
```
145

146
```java { .api }
147
public class DefaultArtifact implements Artifact {
148
    public DefaultArtifact(String groupId, String artifactId, String version, 
149
                          String scope, String type, String classifier, 
150
                          ArtifactHandler artifactHandler);
151
    
152
    public DefaultArtifact(String groupId, String artifactId, VersionRange versionRange, 
153
                          String scope, String type, String classifier, 
154
                          ArtifactHandler artifactHandler);
155
    
156
    public DefaultArtifact(String groupId, String artifactId, VersionRange versionRange, 
157
                          String scope, String type, String classifier, 
158
                          ArtifactHandler artifactHandler, boolean optional);
159
}
160
```
161

162
```java { .api }
163
public final class ArtifactUtils {
164
    public static boolean isSnapshot(String version);
165
    public static String toSnapshotVersion(String version);
166
    public static String versionlessKey(Artifact artifact);
167
    public static String versionlessKey(String groupId, String artifactId);
168
    public static String key(Artifact artifact);
169
    public static String key(String groupId, String artifactId, String version);
170
    public static Map<String, Artifact> artifactMapByVersionlessId(Collection<Artifact> artifacts);
171
    public static Artifact copyArtifactSafe(Artifact artifact);
172
    public static Artifact copyArtifact(Artifact artifact);
173
    public static <T extends Collection<Artifact>> T copyArtifacts(Collection<Artifact> from, T to);
174
    public static <K, T extends Map<K, Artifact>> T copyArtifacts(Map<K, ? extends Artifact> from, T to);
175
}
176
```
177

178
### Artifact Type Handling
179

180
Configuration for different artifact types and their handling characteristics.
181

182
```java { .api }
183
public interface ArtifactHandler {
184
    String getExtension();
185
    String getClassifier();
186
    String getDirectory();
187
    String getPackaging();
188
    String getLanguage();
189
    boolean isIncludesDependencies();
190
    boolean isAddedToClasspath();
191
}
192
```
193

194
### Exception Handling
195

196
```java { .api }
197
public class InvalidArtifactRTException extends RuntimeException {
198
    public InvalidArtifactRTException(String groupId, String artifactId, String version, String type, String message);
199
    public InvalidArtifactRTException(String groupId, String artifactId, String version, String type, String message, Throwable cause);
200
    
201
    public String getGroupId();
202
    public String getArtifactId();
203
    public String getVersion();
204
    public String getType();
205
    public String getBaseMessage();
206
    public String getArtifactKey();
207
    public String getMessage();
208
}
209
```
210

211
### Version Management
212

213
Advanced version parsing, comparison, and range operations for Maven version semantics.
214

215
```java { .api }
216
public class ComparableVersion implements Comparable<ComparableVersion> {
217
    public ComparableVersion(String version);
218
    public int compareTo(ComparableVersion other);
219
    public String getCanonical();
220
    public static void main(String... args); // CLI utility
221
}
222
```
223

224
```java { .api }
225
public class VersionRange {
226
    public static VersionRange createFromVersionSpec(String spec) 
227
        throws InvalidVersionSpecificationException;
228
    public static VersionRange createFromVersion(String version);
229
    public boolean containsVersion(ArtifactVersion version);
230
    public ArtifactVersion matchVersion(List<ArtifactVersion> versions);
231
    public VersionRange restrict(VersionRange restriction) 
232
        throws OverConstrainedVersionException;
233
}
234
```
235

236
[Version Management](./versioning.md)
237

238
### Repository Operations
239

240
Repository configuration, authentication, and metadata management for artifact storage and retrieval.
241

242
```java { .api }
243
@Deprecated
244
public interface ArtifactRepository {
245
    String pathOf(Artifact artifact);
246
    String getUrl();
247
    void setUrl(String url);
248
    String getId();
249
    void setId(String id);
250
    Authentication getAuthentication();
251
    void setAuthentication(Authentication authentication);
252
    Proxy getProxy();
253
    void setProxy(Proxy proxy);
254
}
255
```
256

257
```java { .api }
258
public class Authentication {
259
    public Authentication(String userName, String password);
260
    public String getUsername();
261
    public void setUsername(String username);
262
    public String getPassword();
263
    public void setPassword(String password);
264
    public String getPrivateKey();
265
    public void setPrivateKey(String privateKey);
266
}
267
```
268

269
[Repository Operations](./repository.md)
270

271
### Artifact Resolution
272

273
Exception handling and filtering mechanisms for dependency resolution workflows.
274

275
```java { .api }
276
public abstract class AbstractArtifactResolutionException extends Exception {
277
    public Artifact getArtifact();
278
    public String getGroupId();
279
    public String getArtifactId();
280
    public String getVersion();
281
    public List<ArtifactRepository> getRemoteRepositories();
282
}
283
```
284

285
```java { .api }
286
public interface ArtifactFilter {
287
    boolean include(Artifact artifact);
288
}
289
```
290

291
[Resolution and Filtering](./resolution.md)
292

293
## Constants
294

295
### Artifact Scopes
296
```java { .api }
297
public interface Artifact {
298
    String SCOPE_COMPILE = "compile";
299
    String SCOPE_TEST = "test";
300
    String SCOPE_RUNTIME = "runtime";
301
    String SCOPE_PROVIDED = "provided";
302
    String SCOPE_SYSTEM = "system";
303
    String SCOPE_IMPORT = "import";
304
}
305
```
306

307
### Version Constants
308
```java { .api }
309
public interface Artifact {
310
    String RELEASE_VERSION = "RELEASE";
311
    String LATEST_VERSION = "LATEST";
312
    String SNAPSHOT_VERSION = "SNAPSHOT";
313
    Pattern VERSION_FILE_PATTERN = Pattern.compile("^(.*)-(\\d{8}\\.\\d{6})-(\\d+)$");
314
}
315
```
316

317
### Scope Constants
318
```java { .api }
319
public interface Artifact {
320
    String SCOPE_COMPILE_PLUS_RUNTIME = "compile+runtime";
321
    String SCOPE_RUNTIME_PLUS_SYSTEM = "runtime+system";
322
}
323
```
324

325
## Migration Notes
326

327
Several components in this API are marked as deprecated:
328

329
- **ArtifactRepository**, **ArtifactRepositoryPolicy**, **ArtifactRepositoryLayout** interfaces are deprecated but still functional
330
- **org.apache.maven.artifact.metadata.ArtifactMetadata** is deprecated in favor of the legacy metadata interface
331
- New projects should use the Maven Resolver API for repository operations when possible
332

333
The core artifact and versioning APIs remain stable and are not deprecated.