0
# Maven Repository Metadata Model
1

2
Maven Repository Metadata Model provides Java classes for working with Maven repository metadata. It uses Modello MDO (Model Definition Object) files to generate Java classes that represent metadata structures for Maven artifacts, including versioning information, plugin mappings, and snapshot data.
3

4
## Package Information
5

6
- **Package Name**: maven-repository-metadata
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: org.apache.maven  
10
- **Artifact ID**: maven-repository-metadata
11
- **Version**: 2.2.1
12
- **Installation**: Add to your Maven POM:
13

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

22
## Core Imports
23

24
```java
25
// Model classes
26
import org.apache.maven.artifact.repository.metadata.Metadata;
27
import org.apache.maven.artifact.repository.metadata.Versioning;
28
import org.apache.maven.artifact.repository.metadata.Snapshot;
29
import org.apache.maven.artifact.repository.metadata.Plugin;
30
import org.apache.maven.plugin.mapping.PluginMap;
31
import org.apache.maven.plugin.mapping.MappedPlugin;
32

33
// XML I/O classes (generated at build time)
34
import org.apache.maven.artifact.repository.metadata.io.xpp3.MetadataXpp3Reader;
35
import org.apache.maven.artifact.repository.metadata.io.xpp3.MetadataXpp3Writer;
36
import org.apache.maven.plugin.mapping.io.xpp3.PluginMapXpp3Reader;
37
import org.apache.maven.plugin.mapping.io.xpp3.PluginMapXpp3Writer;
38
```
39

40
## Basic Usage
41

42
```java
43
import org.apache.maven.artifact.repository.metadata.Metadata;
44
import org.apache.maven.artifact.repository.metadata.Versioning;
45
import org.apache.maven.artifact.repository.metadata.Snapshot;
46

47
// Create metadata for an artifact
48
Metadata metadata = new Metadata();
49
metadata.setGroupId("com.example");
50
metadata.setArtifactId("my-library");
51
metadata.setVersion("1.0.0");
52

53
// Set up versioning information
54
Versioning versioning = new Versioning();
55
versioning.setLatest("1.2.0");
56
versioning.setRelease("1.1.0");
57
versioning.updateTimestamp(); // Sets lastUpdated to current time
58

59
// Add available versions
60
versioning.addVersion("1.0.0");
61
versioning.addVersion("1.1.0");
62
versioning.addVersion("1.2.0");
63

64
metadata.setVersioning(versioning);
65

66
// Work with snapshots
67
Snapshot snapshot = new Snapshot();
68
snapshot.setTimestamp("20091027.121200");
69
snapshot.setBuildNumber(4);
70
versioning.setSnapshot(snapshot);
71
```
72

73
## Architecture
74

75
Maven Repository Metadata Model is built around a code generation architecture that creates type-safe Java classes from declarative model definitions:
76

77
- **Modello-based Generation**: Uses two MDO (Model Definition Object) files to generate all model classes at build time
78
  - `metadata.mdo` - Defines repository metadata model (`Metadata`, `Versioning`, `Snapshot`, `Plugin`)  
79
  - `plugins.mdo` - Defines plugin mapping model (`PluginMap`, `MappedPlugin`)
80
- **Package Organization**: Generated classes are organized into two distinct packages
81
  - `org.apache.maven.artifact.repository.metadata` - Core repository metadata classes
82
  - `org.apache.maven.plugin.mapping` - Plugin mapping classes
83
- **XML Serialization**: All model classes include automatic XML serialization support through generated I/O classes
84
- **Schema Validation**: Support for XSD schema validation of metadata XML documents
85
- **Merge Capabilities**: Built-in metadata merging for combining information from multiple sources
86

87
## Capabilities
88

89
### Repository Metadata Management
90

91
Core metadata container for Maven repository directory information.
92

93
```java { .api }
94
public class Metadata {
95
    public String getGroupId();
96
    public void setGroupId(String groupId);
97
    public String getArtifactId(); 
98
    public void setArtifactId(String artifactId);
99
    public String getVersion();
100
    public void setVersion(String version);
101
    public Versioning getVersioning();
102
    public void setVersioning(Versioning versioning);
103
    public java.util.List<Plugin> getPlugins();
104
    public void setPlugins(java.util.List<Plugin> plugins);
105
    public void addPlugin(Plugin plugin);
106
    public boolean merge(Metadata sourceMetadata);
107
}
108
```
109

110
The `merge` method combines metadata from another source, merging plugins and versioning information. Returns `true` if any changes were made.
111

112
### Version Information Management
113

114
Manages versioning information for artifacts including latest versions, releases, and available versions.
115

116
```java { .api }
117
public class Versioning {
118
    public String getLatest();
119
    public void setLatest(String latest);
120
    public String getRelease();
121
    public void setRelease(String release);
122
    public Snapshot getSnapshot();
123
    public void setSnapshot(Snapshot snapshot);
124
    public java.util.List<String> getVersions();
125
    public void setVersions(java.util.List<String> versions);
126
    public void addVersion(String version);
127
    public String getLastUpdated();
128
    public void setLastUpdated(String lastUpdated);
129
    public void updateTimestamp();
130
    public void setLastUpdatedTimestamp(java.util.Date date);
131
}
132
```
133

134
The `updateTimestamp()` method sets the `lastUpdated` field to the current time in UTC using the format "yyyyMMddHHmmss".
135

136
### Snapshot Information
137

138
Handles snapshot-specific information including timestamps and build numbers.
139

140
```java { .api }
141
public class Snapshot {
142
    public String getTimestamp();
143
    public void setTimestamp(String timestamp);
144
    public int getBuildNumber();
145
    public void setBuildNumber(int buildNumber);
146
    public boolean isLocalCopy();
147
    public void setLocalCopy(boolean localCopy);
148
}
149
```
150

151
### Plugin Mapping
152

153
Manages mapping information for Maven plugins within a group.
154

155
```java { .api }
156
public class Plugin {
157
    public String getName();
158
    public void setName(String name);
159
    public String getPrefix();
160
    public void setPrefix(String prefix);
161
    public String getArtifactId();
162
    public void setArtifactId(String artifactId);
163
}
164
```
165

166
### Plugin Group Mappings
167

168
Root container for plugin mappings within a specific group.
169

170
```java { .api }
171
public class PluginMap {
172
    public String getGroupId();
173
    public void setGroupId(String groupId);
174
    public java.util.List<MappedPlugin> getPlugins();
175
    public void setPlugins(java.util.List<MappedPlugin> plugins);
176
    public void addPlugin(MappedPlugin plugin);
177
}
178
```
179

180
### Individual Plugin Mappings
181

182
Mapping information for individual plugins within a group.
183

184
```java { .api }
185
public class MappedPlugin {
186
    public String getPrefix();
187
    public void setPrefix(String prefix);
188
    public String getArtifactId();
189
    public void setArtifactId(String artifactId);
190
}
191
```
192

193
## XML Serialization
194

195
All classes support XML serialization through Modello-generated I/O classes:
196

197
### Generated Reader/Writer Classes
198

199
```java { .api }
200
// Generated XML I/O for repository metadata
201
public class MetadataXpp3Reader {
202
    public Metadata read(Reader reader) throws IOException, XmlPullParserException;
203
    public Metadata read(InputStream in) throws IOException, XmlPullParserException;
204
}
205

206
public class MetadataXpp3Writer {
207
    public void write(Writer writer, Metadata metadata) throws IOException;
208
    public void write(OutputStream out, Metadata metadata) throws IOException;
209
}
210

211
// Generated XML I/O for plugin mappings
212
public class PluginMapXpp3Reader {
213
    public PluginMap read(Reader reader) throws IOException, XmlPullParserException;
214
    public PluginMap read(InputStream in) throws IOException, XmlPullParserException;
215
}
216

217
public class PluginMapXpp3Writer {
218
    public void write(Writer writer, PluginMap pluginMap) throws IOException;
219
    public void write(OutputStream out, PluginMap pluginMap) throws IOException;
220
}
221
```
222

223
### XML Features
224

225
- **Metadata XML**: Serializes to/from Maven metadata XML format used in repositories
226
- **Plugin Map XML**: Serializes to/from plugin mapping XML format
227
- **Schema Validation**: Supports XSD schema validation for XML documents
228
- **Namespace Handling**: Proper XML namespace support for Maven metadata schemas
229
- **Streaming Support**: Both Reader/InputStream and Writer/OutputStream interfaces
230

231
## Advanced Usage Examples
232

233
### Merging Metadata from Multiple Sources
234

235
```java
236
// Create base metadata
237
Metadata baseMetadata = new Metadata();
238
baseMetadata.setGroupId("com.example");
239
baseMetadata.setArtifactId("my-library");
240

241
Versioning baseVersioning = new Versioning();
242
baseVersioning.addVersion("1.0.0");
243
baseVersioning.addVersion("1.1.0"); 
244
baseVersioning.setLatest("1.1.0");
245
baseVersioning.setRelease("1.1.0");
246
baseMetadata.setVersioning(baseVersioning);
247

248
// Create source metadata with new information
249
Metadata sourceMetadata = new Metadata();
250
sourceMetadata.setGroupId("com.example");
251
sourceMetadata.setArtifactId("my-library");
252

253
Versioning sourceVersioning = new Versioning();
254
sourceVersioning.addVersion("1.2.0");
255
sourceVersioning.setLatest("1.2.0");
256
sourceVersioning.setRelease("1.2.0");
257
sourceVersioning.updateTimestamp();
258
sourceMetadata.setVersioning(sourceVersioning);
259

260
// Merge the metadata
261
boolean changed = baseMetadata.merge(sourceMetadata);
262
if (changed) {
263
    // Metadata was updated with new information
264
    System.out.println("Metadata updated with new versions");
265
}
266
```
267

268
### Working with Plugin Mappings
269

270
```java
271
// Create plugin map for a group
272
PluginMap pluginMap = new PluginMap();
273
pluginMap.setGroupId("org.apache.maven.plugins");
274

275
// Add plugin mappings
276
MappedPlugin compilerPlugin = new MappedPlugin();
277
compilerPlugin.setPrefix("compiler");
278
compilerPlugin.setArtifactId("maven-compiler-plugin");
279
pluginMap.addPlugin(compilerPlugin);
280

281
MappedPlugin surefirePlugin = new MappedPlugin();
282
surefirePlugin.setPrefix("surefire");
283
surefirePlugin.setArtifactId("maven-surefire-plugin");
284
pluginMap.addPlugin(surefirePlugin);
285
```
286

287
### Managing Snapshot Versions
288

289
```java
290
Metadata metadata = new Metadata();
291
metadata.setGroupId("com.example");
292
metadata.setArtifactId("my-library");
293
metadata.setVersion("1.0-SNAPSHOT");
294

295
Versioning versioning = new Versioning();
296
versioning.setLatest("1.0-SNAPSHOT");
297

298
// Create snapshot information
299
Snapshot snapshot = new Snapshot();
300
snapshot.setTimestamp("20091027.121200");
301
snapshot.setBuildNumber(4);
302
snapshot.setLocalCopy(false);
303

304
versioning.setSnapshot(snapshot);
305
versioning.updateTimestamp();
306

307
metadata.setVersioning(versioning);
308
```
309

310
### XML Serialization Example
311

312
```java
313
import org.apache.maven.artifact.repository.metadata.io.xpp3.MetadataXpp3Reader;
314
import org.apache.maven.artifact.repository.metadata.io.xpp3.MetadataXpp3Writer;
315
import java.io.*;
316

317
// Read metadata from XML file
318
MetadataXpp3Reader reader = new MetadataXpp3Reader();
319
Metadata metadata;
320
try (FileReader fileReader = new FileReader("maven-metadata.xml")) {
321
    metadata = reader.read(fileReader);
322
    System.out.println("Loaded metadata for: " + metadata.getGroupId() + ":" + metadata.getArtifactId());
323
}
324

325
// Write metadata to XML file
326
MetadataXpp3Writer writer = new MetadataXpp3Writer();
327
try (FileWriter fileWriter = new FileWriter("updated-metadata.xml")) {
328
    writer.write(fileWriter, metadata);
329
    System.out.println("Metadata written to file");
330
}
331

332
// Work with streams
333
try (InputStream inputStream = new FileInputStream("metadata.xml");
334
     OutputStream outputStream = new FileOutputStream("copy-metadata.xml")) {
335
    Metadata streamMetadata = reader.read(inputStream);
336
    writer.write(outputStream, streamMetadata);
337
}
338
```
339

340
## Dependencies
341

342
- **org.codehaus.plexus:plexus-utils** - Utility functions for Plexus IoC container
343
- **Standard Java Libraries** - java.util.*, java.text.* for collections and date formatting
344

345
## Error Handling
346

347
### Standard Exceptions
348

349
The model classes primarily use standard Java exceptions:
350
- **IllegalArgumentException** - For invalid parameter values
351
- **NullPointerException** - When accessing properties of null objects
352

353
### XML Processing Exceptions
354

355
XML serialization operations may throw:
356
- **IOException** - File system or stream errors during read/write operations
357
- **XmlPullParserException** - XML parsing errors for malformed metadata files
358

359
### Repository Metadata Exceptions
360

361
Maven's repository metadata handling defines specific exceptions for different metadata operations:
362
- **RepositoryMetadataResolutionException** - Failure to resolve metadata from repositories
363
- **RepositoryMetadataInstallationException** - Errors during metadata installation to local repository
364
- **RepositoryMetadataDeploymentException** - Problems deploying metadata to remote repositories
365
- **RepositoryMetadataStoreException** - General metadata storage failures
366
- **RepositoryMetadataReadException** - Errors reading existing metadata files
367

368
These exceptions extend from Maven's core artifact management exception hierarchy and provide detailed error information for troubleshooting metadata operations.