0
# Import and Export
1

2
The import and export system provides comprehensive support for converting archives to and from various formats including ZIP, TAR (with compression options), and exploded directory structures.
3

4
## Export Implementations
5

6
### Abstract Base Classes
7

8
#### AbstractStreamExporterImpl
9

10
Base implementation for all stream-based exporters.
11

12
```java { .api }
13
public abstract class AbstractStreamExporterImpl implements StreamExporter
14
```
15

16
**Key Methods:**
17
```java { .api }
18
public InputStream exportAsInputStream()
19
public void exportTo(OutputStream outputStream)
20
public void exportTo(File file)
21
```
22

23
#### AbstractExporterDelegate<T>
24

25
Delegation pattern base for custom exporters.
26

27
```java { .api }
28
public abstract class AbstractExporterDelegate<T> implements Exporter<T>
29
```
30

31
### ZIP Format Exporters
32

33
#### ZipExporterImpl
34

35
Standard ZIP format exporter with compression.
36

37
```java { .api }
38
public class ZipExporterImpl extends AbstractStreamExporterImpl implements ZipExporter
39
```
40

41
**Key Features:**
42
- DEFLATE compression algorithm
43
- Preserves directory structure
44
- Handles file permissions and timestamps
45
- Supports ZIP64 format for large archives
46

47
**Usage:**
48
```java
49
Archive<?> archive = // ... create archive
50
InputStream zipStream = archive.as(ZipExporter.class).exportAsInputStream();
51

52
// Export to file
53
File zipFile = new File("archive.zip");
54
archive.as(ZipExporter.class).exportTo(zipFile);
55
```
56

57
#### ZipStoredExporterImpl
58

59
Uncompressed ZIP format exporter for faster processing.
60

61
```java { .api }
62
public class ZipStoredExporterImpl extends AbstractStreamExporterImpl implements ZipExporter
63
```
64

65
**Key Features:**
66
- No compression (STORED method)
67
- Faster processing for large files
68
- Same structure as compressed ZIP
69
- Larger file sizes
70

71
**Usage:**
72
```java
73
// Export without compression for speed
74
archive.as(ZipStoredExporter.class).exportTo(outputStream);
75
```
76

77
### TAR Format Exporters
78

79
#### TarExporterImpl
80

81
Standard TAR format exporter.
82

83
```java { .api }
84
public class TarExporterImpl extends AbstractStreamExporterImpl implements TarExporter
85
```
86

87
**Key Features:**
88
- POSIX TAR format
89
- Preserves Unix file permissions
90
- Handles long filenames
91
- Supports symbolic links
92

93
#### TarGzExporterImpl
94

95
GZIP-compressed TAR format exporter.
96

97
```java { .api }
98
public class TarGzExporterImpl extends AbstractStreamExporterImpl implements TarGzExporter
99
```
100

101
**Key Features:**
102
- GZIP compression
103
- Standard .tar.gz format
104
- Good compression ratio
105
- Cross-platform compatibility
106

107
#### TarBz2ExporterImpl
108

109
BZIP2-compressed TAR format exporter.
110

111
```java { .api }
112
public class TarBz2ExporterImpl extends AbstractStreamExporterImpl implements TarBz2Exporter
113
```
114

115
**Key Features:**
116
- BZIP2 compression
117
- Better compression ratio than GZIP
118
- Slower compression speed
119
- .tar.bz2 format
120

121
**Usage Examples:**
122
```java
123
// Standard TAR
124
archive.as(TarExporter.class).exportTo("archive.tar");
125

126
// GZIP compressed
127
archive.as(TarGzExporter.class).exportTo("archive.tar.gz");
128

129
// BZIP2 compressed  
130
archive.as(TarBz2Exporter.class).exportTo("archive.tar.bz2");
131
```
132

133
### Directory Export
134

135
#### ExplodedExporterImpl
136

137
Exports archives to exploded directory structure.
138

139
```java { .api }
140
public class ExplodedExporterImpl implements ExplodedExporter
141
```
142

143
**Key Methods:**
144
```java { .api }
145
public File exportExploded(File directory)
146
public void exportExploded(File directory, Filter<ArchivePath> filter)
147
```
148

149
**Usage:**
150
```java
151
// Export to directory
152
File explodedDir = new File("exploded-archive");
153
archive.as(ExplodedExporter.class).exportExploded(explodedDir);
154

155
// Export with filtering
156
archive.as(ExplodedExporter.class)
157
       .exportExploded(explodedDir, Filters.exclude(".*\\.tmp"));
158
```
159

160
## Import Implementations
161

162
### ZIP Format Importers
163

164
#### ZipImporterImpl
165

166
Imports archives from ZIP format streams and files.
167

168
```java { .api }
169
public class ZipImporterImpl implements ZipImporter
170
```
171

172
**Key Methods:**
173
```java { .api }
174
public Archive<?> importFrom(File file)
175
public Archive<?> importFrom(InputStream inputStream)
176
public Archive<?> importFrom(InputStream inputStream, String archiveName)
177
```
178

179
**Usage:**
180
```java
181
// Import from file
182
Archive<?> archive = ShrinkWrap.create(ZipImporter.class)
183
    .importFrom(new File("source.zip"))
184
    .as(GenericArchive.class);
185

186
// Import from stream
187
InputStream zipStream = // ... get stream
188
Archive<?> archive = ShrinkWrap.create(ZipImporter.class)
189
    .importFrom(zipStream, "imported.zip")
190
    .as(JavaArchive.class);
191
```
192

193
### TAR Format Importers
194

195
#### TarImporterImpl
196

197
Standard TAR format importer.
198

199
```java { .api }
200
public class TarImporterImpl implements TarImporter
201
```
202

203
#### TarGzImporterImpl
204

205
GZIP-compressed TAR format importer.
206

207
```java { .api }
208
public class TarGzImporterImpl implements TarGzImporter
209
```
210

211
#### TarBz2ImporterImpl
212

213
BZIP2-compressed TAR format importer.
214

215
```java { .api }
216
public class TarBz2ImporterImpl implements TarBz2Importer
217
```
218

219
**Usage Examples:**
220
```java
221
// Standard TAR
222
Archive<?> archive = ShrinkWrap.create(TarImporter.class)
223
    .importFrom(new File("archive.tar"))
224
    .as(GenericArchive.class);
225

226
// GZIP compressed
227
Archive<?> archive = ShrinkWrap.create(TarGzImporter.class)
228
    .importFrom(new File("archive.tar.gz"))
229
    .as(JavaArchive.class);
230

231
// BZIP2 compressed
232
Archive<?> archive = ShrinkWrap.create(TarBz2Importer.class)
233
    .importFrom(new File("archive.tar.bz2"))
234
    .as(WebArchive.class);
235
```
236

237
### Directory Import
238

239
#### ExplodedImporterImpl
240

241
Imports archives from exploded directory structures.
242

243
```java { .api }
244
public class ExplodedImporterImpl implements ExplodedImporter
245
```
246

247
**Key Methods:**
248
```java { .api }
249
public Archive<?> importDirectory(File directory)
250
public Archive<?> importDirectory(File directory, Filter<ArchivePath> filter)
251
```
252

253
**Usage:**
254
```java
255
// Import entire directory
256
Archive<?> archive = ShrinkWrap.create(ExplodedImporter.class)
257
    .importDirectory(new File("exploded-webapp"))
258
    .as(WebArchive.class);
259

260
// Import with filtering
261
Archive<?> archive = ShrinkWrap.create(ExplodedImporter.class)
262
    .importDirectory(sourceDir, Filters.exclude(".*\\.bak"))
263
    .as(JavaArchive.class);
264
```
265

266
## Advanced Import/Export Features
267

268
### Streaming Operations
269

270
All importers and exporters support streaming for memory efficiency:
271

272
```java
273
// Stream-based export
274
try (OutputStream out = new FileOutputStream("archive.zip")) {
275
    archive.as(ZipExporter.class).exportTo(out);
276
}
277

278
// Stream-based import
279
try (InputStream in = new FileInputStream("source.zip")) {
280
    Archive<?> archive = ShrinkWrap.create(ZipImporter.class)
281
        .importFrom(in, "imported")
282
        .as(GenericArchive.class);
283
}
284
```
285

286
### Filtering Support
287

288
Import and export operations support content filtering:
289

290
```java
291
// Export with filtering
292
Filter<ArchivePath> filter = Filters.exclude(".*\\.tmp", ".*\\.log");
293
archive.as(ExplodedExporter.class).exportExploded(targetDir, filter);
294

295
// Import with filtering  
296
Archive<?> filtered = ShrinkWrap.create(ExplodedImporter.class)
297
    .importDirectory(sourceDir, Filters.include(".*\\.class", ".*\\.xml"))
298
    .as(JavaArchive.class);
299
```
300

301
### Format Detection
302

303
Automatic format detection based on file extensions and content:
304

305
```java
306
// Automatic format detection
307
File unknownFile = new File("archive.unknown");
308
Archive<?> archive = ArchiveFactory.importFrom(unknownFile);
309
```
310

311
### Compression Options
312

313
TAR exporters support compression level configuration:
314

315
```java
316
// Configure compression level
317
TarGzExporter exporter = archive.as(TarGzExporter.class);
318
exporter.setCompressionLevel(9); // Maximum compression
319
exporter.exportTo("highly-compressed.tar.gz");
320
```
321

322
### Metadata Preservation
323

324
Import/export operations preserve important metadata:
325

326
- File timestamps
327
- File permissions (on Unix systems)
328
- Directory structure
329
- Archive entry comments
330
- Extended attributes (where supported)
331

332
### Error handling
333

334
Common error scenarios and handling:
335

336
```java
337
try {
338
    archive.as(ZipExporter.class).exportTo(file);
339
} catch (ArchiveExportException e) {
340
    // Handle export errors
341
    logger.error("Export failed: " + e.getMessage(), e);
342
} catch (IOException e) {
343
    // Handle I/O errors
344
    logger.error("I/O error during export: " + e.getMessage(), e);
345
}
346
```
347

348
### Performance Considerations
349

350
- **Memory Usage**: Streaming operations minimize memory footprint
351
- **Compression Speed**: Choose appropriate compression algorithms based on needs
352
- **I/O Optimization**: Buffered streams used internally for optimal performance
353
- **Parallel Processing**: Large archives can be processed with parallel streams where appropriate