0
# Snapshot Management
1

2
Comprehensive snapshot artifact handling for SNAPSHOT versions, including build numbers, timestamps, and sub-artifact tracking with support for both legacy and modern snapshot formats.
3

4
## Capabilities
5

6
### Snapshot Class
7

8
Snapshot data for the last artifact corresponding to the SNAPSHOT base version, containing timestamp and build information.
9

10
```java { .api }
11
/**
12
 * Snapshot data for SNAPSHOT artifacts
13
 * Contains timestamp, build number, and local copy flag
14
 */
15
public class Snapshot implements Serializable, Cloneable {
16
  // Constructors
17
  public Snapshot();
18
  
19
  // Timestamp management
20
  public String getTimestamp();
21
  public void setTimestamp(String timestamp);
22
  
23
  // Build tracking
24
  public int getBuildNumber();
25
  public void setBuildNumber(int buildNumber);
26
  
27
  // Local copy handling
28
  public boolean isLocalCopy();
29
  public void setLocalCopy(boolean localCopy);
30
  
31
  // Object operations
32
  public Snapshot clone();
33
}
34
```
35

36
**Usage Examples:**
37

38
```java
39
import org.apache.maven.artifact.repository.metadata.Snapshot;
40

41
// Create snapshot for deployment
42
Snapshot snapshot = new Snapshot();
43
snapshot.setTimestamp("20231201.143022"); // Format: yyyyMMdd.HHmmss
44
snapshot.setBuildNumber(1);
45
snapshot.setLocalCopy(false);
46

47
// Update for next deployment
48
snapshot.setBuildNumber(snapshot.getBuildNumber() + 1);
49
snapshot.setTimestamp("20231201.145030");
50

51
// Check if using local copy
52
if (snapshot.isLocalCopy()) {
53
    // Use base version filename instead of timestamped
54
    System.out.println("Using local copy with base version filename");
55
}
56
```
57

58
### SnapshotVersion Class
59

60
Versioning information for sub-artifacts of snapshot artifacts, tracking different classifier/extension combinations.
61

62
```java { .api }
63
/**
64
 * Versioning information for sub-artifacts of snapshot artifacts
65
 * Each classifier/extension pair represents a unique sub-artifact
66
 */
67
public class SnapshotVersion implements Serializable, Cloneable {
68
  // Constructors
69
  public SnapshotVersion();
70
  
71
  // Artifact identification
72
  public String getClassifier();
73
  public void setClassifier(String classifier);
74
  public String getExtension();
75
  public void setExtension(String extension);
76
  
77
  // Version tracking
78
  public String getVersion();
79
  public void setVersion(String version);
80
  public String getUpdated();
81
  public void setUpdated(String updated);
82
  
83
  // Object operations
84
  public SnapshotVersion clone();
85
  public boolean equals(Object other);
86
  public int hashCode();
87
  public String toString();
88
}
89
```
90

91
**Usage Examples:**
92

93
```java
94
import org.apache.maven.artifact.repository.metadata.SnapshotVersion;
95

96
// Main JAR snapshot version
97
SnapshotVersion mainJar = new SnapshotVersion();
98
mainJar.setClassifier("");
99
mainJar.setExtension("jar");
100
mainJar.setVersion("1.2.0-20231201.143022-1");
101
mainJar.setUpdated("20231201143022");
102

103
// Sources JAR snapshot version
104
SnapshotVersion sourcesJar = new SnapshotVersion();
105
sourcesJar.setClassifier("sources");
106
sourcesJar.setExtension("jar");
107
sourcesJar.setVersion("1.2.0-20231201.143022-1");
108
sourcesJar.setUpdated("20231201143022");
109

110
// Javadoc JAR snapshot version
111
SnapshotVersion javadocJar = new SnapshotVersion();
112
javadocJar.setClassifier("javadoc");
113
javadocJar.setExtension("jar");
114
javadocJar.setVersion("1.2.0-20231201.143022-1");
115
javadocJar.setUpdated("20231201143022");
116

117
// Check equality (based on classifier, extension, version, updated)
118
boolean same = mainJar.equals(sourcesJar); // false - different classifiers
119
```
120

121
### Snapshot Version Management
122

123
Integration of snapshot and snapshot version information in the versioning system.
124

125
```java { .api }
126
// Snapshot management methods in Versioning class
127
public Snapshot getSnapshot();
128
public void setSnapshot(Snapshot snapshot);
129
public List<SnapshotVersion> getSnapshotVersions();
130
public void setSnapshotVersions(List<SnapshotVersion> snapshotVersions);
131
public void addSnapshotVersion(SnapshotVersion snapshotVersion);
132
public void removeSnapshotVersion(SnapshotVersion snapshotVersion);
133
```
134

135
**Usage Examples:**
136

137
```java
138
import org.apache.maven.artifact.repository.metadata.Versioning;
139
import org.apache.maven.artifact.repository.metadata.Snapshot;
140
import org.apache.maven.artifact.repository.metadata.SnapshotVersion;
141

142
// Set up versioning for snapshot
143
Versioning versioning = new Versioning();
144
versioning.setLatest("1.2.0-SNAPSHOT");
145

146
// Create snapshot info
147
Snapshot snapshot = new Snapshot();
148
snapshot.setTimestamp("20231201.143022");
149
snapshot.setBuildNumber(1);
150
versioning.setSnapshot(snapshot);
151

152
// Add snapshot versions for different artifacts
153
SnapshotVersion jarVersion = new SnapshotVersion();
154
jarVersion.setExtension("jar");
155
jarVersion.setVersion("1.2.0-20231201.143022-1");
156
jarVersion.setUpdated("20231201143022");
157
versioning.addSnapshotVersion(jarVersion);
158

159
SnapshotVersion pomVersion = new SnapshotVersion();
160
pomVersion.setExtension("pom");
161
pomVersion.setVersion("1.2.0-20231201.143022-1");
162
pomVersion.setUpdated("20231201143022");
163
versioning.addSnapshotVersion(pomVersion);
164

165
// Access snapshot versions
166
List<SnapshotVersion> versions = versioning.getSnapshotVersions();
167
for (SnapshotVersion version : versions) {
168
    System.out.printf("Extension: %s, Version: %s%n", 
169
                      version.getExtension(), version.getVersion());
170
}
171
```
172

173
### Legacy vs Modern Snapshot Formats
174

175
The library supports both Maven 2 legacy format and modern snapshot formats with intelligent merging.
176

177
**Legacy Format (Maven 2):**
178
- Only contains basic snapshot information (timestamp, build number)
179
- No snapshot versions list
180
- Used by older Maven versions
181

182
**Modern Format (Maven 3+):**
183
- Contains detailed snapshot versions for each sub-artifact
184
- Tracks classifier/extension combinations separately
185
- Provides more granular control
186

187
**Merging Behavior:**
188

189
```java
190
// Legacy format detection and handling
191
Metadata legacyMetadata = new Metadata();
192
Versioning legacyVersioning = new Versioning();
193
Snapshot legacySnapshot = new Snapshot();
194
legacySnapshot.setTimestamp("20231201.120000");
195
legacySnapshot.setBuildNumber(1);
196
legacyVersioning.setSnapshot(legacySnapshot);
197
// Note: No snapshot versions list in legacy format
198

199
Metadata modernMetadata = new Metadata();
200
Versioning modernVersioning = new Versioning();
201
// ... add snapshot versions list
202

203
// Merging preserves format compatibility
204
// Never converts from legacy to modern format
205
// Never converts from modern to legacy format
206
boolean changed = legacyMetadata.merge(modernMetadata);
207
// Result maintains legacy format
208
```
209

210
## Timestamp Formats
211

212
The library uses specific timestamp formats for different contexts:
213

214
- **Snapshot timestamps**: `yyyyMMdd.HHmmss` (e.g., "20231201.143022")
215
- **Updated timestamps**: `yyyyMMddHHmmss` (e.g., "20231201143022")
216
- **All timestamps use UTC timezone**
217

218
## Error Handling
219

220
Snapshot management includes robust error handling:
221

222
- **Format validation**: Timestamp formats are validated during parsing
223
- **Null safety**: Default values prevent null pointer exceptions
224
- **Clone safety**: Deep cloning preserves all snapshot data
225
- **Equality checking**: Proper equals/hashCode implementation for collections