0
# Repository Operations
1

2
Maven's repository operations provide abstractions for working with artifact repositories, including local and remote repositories, authentication, proxy configuration, and metadata management. Note that many of these interfaces are deprecated in favor of the Maven Resolver API, but remain functional for legacy compatibility.
3

4
## Core Repository Interfaces
5

6
### ArtifactRepository (Deprecated)
7

8
Primary abstraction for artifact repositories with path resolution, policy management, and artifact operations.
9

10
```java { .api }
11
@Deprecated
12
public interface ArtifactRepository {
13
    // Path operations
14
    String pathOf(Artifact artifact);
15
    String pathOfRemoteRepositoryMetadata(ArtifactMetadata artifactMetadata);
16
    String pathOfLocalRepositoryMetadata(ArtifactMetadata metadata, ArtifactRepository repository);
17
    
18
    // Repository identification
19
    String getUrl();
20
    void setUrl(String url);
21
    String getId();
22
    void setId(String id);
23
    String getBasedir();
24
    String getProtocol();
25
    String getKey();
26
    
27
    // Repository policies
28
    ArtifactRepositoryPolicy getSnapshots();
29
    ArtifactRepositoryPolicy getReleases();
30
    void setSnapshotUpdatePolicy(ArtifactRepositoryPolicy policy);
31
    void setReleaseUpdatePolicy(ArtifactRepositoryPolicy policy);
32
    
33
    // Layout management
34
    ArtifactRepositoryLayout getLayout();
35
    void setLayout(ArtifactRepositoryLayout layout);
36
    
37
    // Authentication and proxy
38
    Authentication getAuthentication();
39
    void setAuthentication(Authentication authentication);
40
    Proxy getProxy();
41
    void setProxy(Proxy proxy);
42
    
43
    // Artifact operations
44
    Artifact find(Artifact artifact);
45
    List<String> findVersions(Artifact artifact);
46
    boolean isProjectAware();
47
    
48
    // Repository mirroring (since 3.0-alpha-1)
49
    List<ArtifactRepository> getMirroredRepositories();
50
    void setMirroredRepositories(List<ArtifactRepository> mirroredRepositories);
51
    
52
    // Repository blocking (since 3.8.1)
53
    boolean isBlocked();
54
    void setBlocked(boolean blocked);
55
}
56
```
57

58
**Usage Examples**:
59

60
```java
61
// Basic repository setup (deprecated approach)
62
ArtifactRepository repository = // obtained from configuration
63
repository.setId("central");
64
repository.setUrl("https://repo1.maven.org/maven2");
65

66
// Get artifact path in repository
67
String path = repository.pathOf(artifact); // e.g., "org/example/my-lib/1.0/my-lib-1.0.jar"
68

69
// Configure authentication
70
Authentication auth = new Authentication("username", "password");
71
repository.setAuthentication(auth);
72

73
// Set up proxy
74
Proxy proxy = new Proxy();
75
proxy.setHost("proxy.company.com");
76
proxy.setPort(8080);
77
repository.setProxy(proxy);
78
```
79

80
### ArtifactRepositoryPolicy (Deprecated)
81

82
Defines update and checksum policies for repository operations.
83

84
```java { .api }
85
@Deprecated
86
public class ArtifactRepositoryPolicy {
87
    // Update policy constants
88
    public static final String UPDATE_POLICY_NEVER = "never";
89
    public static final String UPDATE_POLICY_ALWAYS = "always"; 
90
    public static final String UPDATE_POLICY_DAILY = "daily";
91
    public static final String UPDATE_POLICY_INTERVAL = "interval";
92
    
93
    // Checksum policy constants
94
    public static final String CHECKSUM_POLICY_FAIL = "fail";
95
    public static final String CHECKSUM_POLICY_WARN = "warn";
96
    public static final String CHECKSUM_POLICY_IGNORE = "ignore";
97
    
98
    // Policy methods
99
    public boolean isEnabled();
100
    public void setEnabled(boolean enabled);
101
    public String getUpdatePolicy();
102
    public void setUpdatePolicy(String updatePolicy);
103
    public String getChecksumPolicy();
104
    public void setChecksumPolicy(String checksumPolicy);
105
    public boolean checkOutOfDate(Date lastModified);
106
    public void merge(ArtifactRepositoryPolicy policy);
107
}
108
```
109

110
**Usage Examples**:
111

112
```java
113
// Create and configure repository policies
114
ArtifactRepositoryPolicy snapshotPolicy = new ArtifactRepositoryPolicy();
115
snapshotPolicy.setEnabled(true);
116
snapshotPolicy.setUpdatePolicy(ArtifactRepositoryPolicy.UPDATE_POLICY_DAILY);
117
snapshotPolicy.setChecksumPolicy(ArtifactRepositoryPolicy.CHECKSUM_POLICY_WARN);
118

119
ArtifactRepositoryPolicy releasePolicy = new ArtifactRepositoryPolicy();
120
releasePolicy.setEnabled(true);
121
releasePolicy.setUpdatePolicy(ArtifactRepositoryPolicy.UPDATE_POLICY_NEVER);
122
releasePolicy.setChecksumPolicy(ArtifactRepositoryPolicy.CHECKSUM_POLICY_FAIL);
123

124
// Apply to repository
125
repository.setSnapshotUpdatePolicy(snapshotPolicy);
126
repository.setReleaseUpdatePolicy(releasePolicy);
127

128
// Check if update is needed
129
boolean needsUpdate = snapshotPolicy.checkOutOfDate(lastDownloadTime);
130
```
131

132
## Authentication and Proxy
133

134
### Authentication
135

136
Repository authentication configuration for secure repository access.
137

138
```java { .api }
139
public class Authentication {
140
    public Authentication(String userName, String password);
141
    
142
    // Basic authentication
143
    public String getUsername();
144
    public void setUsername(String username);
145
    public String getPassword();
146
    public void setPassword(String password);
147
    
148
    // Private key authentication
149
    public String getPrivateKey();
150
    public void setPrivateKey(String privateKey);
151
    public String getPassphrase();
152
    public void setPassphrase(String passphrase);
153
}
154
```
155

156
**Usage Examples**:
157

158
```java
159
// Basic username/password authentication
160
Authentication basicAuth = new Authentication("myuser", "mypassword");
161

162
// Private key authentication
163
Authentication keyAuth = new Authentication("keyuser", null);
164
keyAuth.setPrivateKey("/path/to/private/key");
165
keyAuth.setPassphrase("keypassphrase");
166

167
// Apply to repository
168
repository.setAuthentication(basicAuth);
169
```
170

171
### Proxy
172

173
Proxy server configuration for repository access through corporate proxies.
174

175
```java { .api }
176
public class Proxy {
177
    // Proxy type constants
178
    public static final String PROXY_SOCKS5 = "SOCKS_5";
179
    public static final String PROXY_SOCKS4 = "SOCKS4"; 
180
    public static final String PROXY_HTTP = "HTTP";
181
    
182
    // Basic proxy configuration
183
    public String getHost();
184
    public void setHost(String host);
185
    public int getPort();
186
    public void setPort(int port);
187
    public String getProtocol();
188
    public void setProtocol(String protocol);
189
    
190
    // Proxy authentication
191
    public String getUserName();
192
    public void setUserName(String userName);
193
    public String getPassword();
194
    public void setPassword(String password);
195
    
196
    // Proxy bypass configuration
197
    public String getNonProxyHosts();
198
    public void setNonProxyHosts(String nonProxyHosts);
199
    
200
    // NTLM authentication
201
    public String getNtlmHost();
202
    public void setNtlmHost(String ntlmHost);
203
    public String getNtlmDomain();
204
    public void setNtlmDomain(String ntlmDomain);
205
}
206
```
207

208
**Usage Examples**:
209

210
```java
211
// HTTP proxy configuration
212
Proxy httpProxy = new Proxy();
213
httpProxy.setProtocol(Proxy.PROXY_HTTP);
214
httpProxy.setHost("proxy.company.com");
215
httpProxy.setPort(8080);
216
httpProxy.setUserName("proxyuser");
217
httpProxy.setPassword("proxypass");
218
httpProxy.setNonProxyHosts("localhost|127.0.0.1|*.internal.com");
219

220
// SOCKS proxy configuration
221
Proxy socksProxy = new Proxy();
222
socksProxy.setProtocol(Proxy.PROXY_SOCKS5);
223
socksProxy.setHost("socks.company.com");
224
socksProxy.setPort(1080);
225

226
// NTLM proxy authentication
227
httpProxy.setNtlmHost("workstation");
228
httpProxy.setNtlmDomain("CORPORATE");
229

230
// Apply to repository
231
repository.setProxy(httpProxy);
232
```
233

234
## Repository Layout
235

236
### ArtifactRepositoryLayout (Deprecated)
237

238
Defines how artifacts are organized within repositories.
239

240
```java { .api }
241
@Deprecated
242
public interface ArtifactRepositoryLayout {
243
    String getId();
244
    String pathOf(Artifact artifact);
245
    String pathOfLocalRepositoryMetadata(ArtifactMetadata metadata, 
246
                                       ArtifactRepository repository);
247
    String pathOfRemoteRepositoryMetadata(ArtifactMetadata artifactMetadata);
248
}
249
```
250

251
### ArtifactRepositoryLayout2
252

253
Extended repository layout interface with repository factory capabilities.
254

255
```java { .api }
256
public interface ArtifactRepositoryLayout2 extends ArtifactRepositoryLayout {
257
    ArtifactRepository newMavenArtifactRepository(String id, String url, 
258
                                                ArtifactRepositoryPolicy snapshots,
259
                                                ArtifactRepositoryPolicy releases);
260
}
261
```
262

263
## Metadata Management
264

265
### ArtifactMetadata (Deprecated)
266

267
Contains artifact metadata with merge capabilities.
268

269
```java { .api }
270
@Deprecated
271
public interface ArtifactMetadata 
272
    extends org.apache.maven.repository.legacy.metadata.ArtifactMetadata {
273
    void merge(ArtifactMetadata metadata);
274
}
275
```
276

277
### ArtifactMetadata (Legacy)
278

279
Legacy artifact metadata operations for storage and retrieval.
280

281
```java { .api }
282
public interface ArtifactMetadata {
283
    // Storage location queries
284
    boolean storedInArtifactVersionDirectory();
285
    boolean storedInGroupDirectory();
286
    
287
    // Artifact identification
288
    String getGroupId();
289
    String getArtifactId();
290
    String getBaseVersion();
291
    Object getKey();
292
    
293
    // File name resolution
294
    String getLocalFilename(ArtifactRepository repository);
295
    String getRemoteFilename();
296
    
297
    // Operations
298
    void merge(ArtifactMetadata metadata);
299
    void storeInLocalRepository(ArtifactRepository localRepository, 
300
                              ArtifactRepository remoteRepository)
301
        throws RepositoryMetadataStoreException;
302
    String extendedToString();
303
}
304
```
305

306
## Exception Handling
307

308
### RepositoryMetadataStoreException
309

310
Exception thrown when repository metadata storage operations fail.
311

312
```java { .api }
313
public class RepositoryMetadataStoreException extends Exception {
314
    public RepositoryMetadataStoreException(String message);
315
    public RepositoryMetadataStoreException(String message, Exception cause);
316
}
317
```
318

319
**Common Scenarios**:
320
- Insufficient permissions to write metadata files
321
- Network connectivity issues during remote metadata updates
322
- Corrupted local repository metadata
323
- Disk space exhaustion
324

325
## Migration Guidance
326

327
**Important**: Most repository-related interfaces in this package are deprecated. For new projects, consider using:
328

329
- **Maven Resolver API** (org.eclipse.aether) for repository operations
330
- **Maven Model** (org.apache.maven.model) for POM processing
331
- **Maven Settings** (org.apache.maven.settings) for configuration
332

333
However, these deprecated interfaces remain functional and are still used internally by Maven for backward compatibility.
334

335
## Common Usage Patterns
336

337
### Repository Configuration
338

339
```java
340
// Basic repository setup (legacy approach)
341
ArtifactRepository centralRepo = // from configuration
342
centralRepo.setId("central");
343
centralRepo.setUrl("https://repo1.maven.org/maven2");
344

345
// Configure policies
346
ArtifactRepositoryPolicy releases = new ArtifactRepositoryPolicy();
347
releases.setEnabled(true);
348
releases.setUpdatePolicy(ArtifactRepositoryPolicy.UPDATE_POLICY_DAILY);
349

350
centralRepo.setReleaseUpdatePolicy(releases);
351
```
352

353
### Secure Repository Access
354

355
```java
356
// Set up authenticated repository with proxy
357
Authentication auth = new Authentication("username", "password");
358
Proxy proxy = new Proxy();
359
proxy.setHost("proxy.company.com");
360
proxy.setPort(8080);
361
proxy.setProtocol(Proxy.PROXY_HTTP);
362

363
ArtifactRepository secureRepo = // from configuration
364
secureRepo.setAuthentication(auth);
365
secureRepo.setProxy(proxy);
366
```
367

368
### Repository Mirroring
369

370
```java
371
// Configure repository mirrors
372
List<ArtifactRepository> mirrors = Arrays.asList(mirror1, mirror2);
373
repository.setMirroredRepositories(mirrors);
374

375
// Block problematic repositories (Maven 3.8.1+)
376
repository.setBlocked(true);
377
```