1 /**
2 *
3 * Copyright 2004 The Apache Software Foundation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.codehaus.plexus.archiver;
18
19 import javax.annotation.Nonnull;
20
21 import java.io.File;
22 import java.io.IOException;
23 import java.nio.charset.Charset;
24 import java.nio.file.attribute.FileTime;
25 import java.util.Comparator;
26 import java.util.Date;
27 import java.util.HashSet;
28 import java.util.Map;
29 import java.util.Set;
30
31 import org.codehaus.plexus.components.io.resources.PlexusIoResource;
32 import org.codehaus.plexus.components.io.resources.PlexusIoResourceCollection;
33
34 public interface Archiver {
35
36 /**
37 * Default value for the dirmode attribute.
38 */
39 int DEFAULT_DIR_MODE = UnixStat.DIR_FLAG | UnixStat.DEFAULT_DIR_PERM;
40
41 /**
42 * Default value for the filemode attribute.
43 */
44 int DEFAULT_FILE_MODE = UnixStat.FILE_FLAG | UnixStat.DEFAULT_FILE_PERM;
45
46 /**
47 * Default value for the symlinkmode attribute.
48 */
49 int DEFAULT_SYMLILNK_MODE = UnixStat.LINK_FLAG | UnixStat.DEFAULT_LINK_PERM;
50
51 String DUPLICATES_ADD = "add";
52
53 String DUPLICATES_PRESERVE = "preserve";
54
55 String DUPLICATES_SKIP = "skip";
56
57 String DUPLICATES_FAIL = "fail";
58
59 Set<String> DUPLICATES_VALID_BEHAVIORS = new HashSet<String>() {
60
61 private static final long serialVersionUID = 1L;
62
63 {
64 add(DUPLICATES_ADD);
65 add(DUPLICATES_PRESERVE);
66 add(DUPLICATES_SKIP);
67 add(DUPLICATES_FAIL);
68 }
69 };
70
71 void createArchive() throws ArchiverException, IOException;
72
73 /**
74 * Obsolete, use {@link #addFileSet(FileSet)}.
75 *
76 * @deprecated Will go away in next major version
77 */
78 @Deprecated
79 void addDirectory(@Nonnull File directory) throws ArchiverException;
80
81 /**
82 * Obsolete, use {@link #addFileSet(FileSet)}.
83 *
84 * @deprecated Will go away in next major version
85 */
86 @Deprecated
87 void addDirectory(@Nonnull File directory, String prefix) throws ArchiverException;
88
89 /**
90 * Obsolete, use {@link #addFileSet(FileSet)}.
91 *
92 * @deprecated Will go away in next major version
93 */
94 @Deprecated
95 void addDirectory(@Nonnull File directory, String[] includes, String[] excludes) throws ArchiverException;
96
97 /**
98 * Obsolete, use {@link #addFileSet(FileSet)}.
99 *
100 * @deprecated Will go away in next major version
101 */
102 @Deprecated
103 void addDirectory(@Nonnull File directory, String prefix, String[] includes, String[] excludes)
104 throws ArchiverException;
105
106 /**
107 * Adds the given file set to the archive. This method is basically obsoleting {@link #addDirectory(File)},
108 * {@link #addDirectory(File, String)}, {@link #addDirectory(File, String[], String[])}, and
109 * {@link #addDirectory(File, String, String[], String[])}. However, as these methods are in widespread use, they
110 * cannot easily be deprecated.
111 *
112 * @throws ArchiverException
113 * Adding the file set failed.
114 * @since 1.0-alpha-9
115 */
116 void addFileSet(@Nonnull FileSet fileSet) throws ArchiverException;
117
118 void addSymlink(String symlinkName, String symlinkDestination) throws ArchiverException;
119
120 void addSymlink(String symlinkName, int permissions, String symlinkDestination) throws ArchiverException;
121
122 void addFile(@Nonnull File inputFile, @Nonnull String destFileName) throws ArchiverException;
123
124 void addFile(@Nonnull File inputFile, @Nonnull String destFileName, int permissions) throws ArchiverException;
125
126 /**
127 * Obsolete, use {@link #addArchivedFileSet(ArchivedFileSet)}.
128 *
129 * @deprecated Will go away in next major version
130 */
131 @Deprecated
132 void addArchivedFileSet(@Nonnull File archiveFile) throws ArchiverException;
133
134 /**
135 * Obsolete, use {@link #addArchivedFileSet(ArchivedFileSet)}.
136 *
137 * @deprecated Will go away in next major version
138 */
139 @Deprecated
140 void addArchivedFileSet(@Nonnull File archiveFile, String prefix) throws ArchiverException;
141
142 /**
143 * Obsolete, use {@link #addArchivedFileSet(ArchivedFileSet)}.
144 *
145 * @deprecated Will go away in next major version
146 */
147 @Deprecated
148 void addArchivedFileSet(File archiveFile, String[] includes, String[] excludes) throws ArchiverException;
149
150 /**
151 * Obsolete, use {@link #addArchivedFileSet(ArchivedFileSet)}.
152 *
153 * @deprecated Will go away in next major version
154 */
155 @Deprecated
156 void addArchivedFileSet(@Nonnull File archiveFile, String prefix, String[] includes, String[] excludes)
157 throws ArchiverException;
158
159 /**
160 * Adds the given archive file set to the archive. This method is basically obsoleting
161 * {@link #addArchivedFileSet(File)}, {@link #addArchivedFileSet(File, String[], String[])}, and
162 * {@link #addArchivedFileSet(File, String, String[], String[])}. However, as these methods are in widespread use,
163 * they cannot easily be deprecated.
164 *
165 * Stream transformers are supported on this method
166 *
167 * @since 1.0-alpha-9
168 */
169 void addArchivedFileSet(ArchivedFileSet fileSet) throws ArchiverException;
170
171 /**
172 * Adds the given archive file set to the archive. This method is basically obsoleting
173 * {@link #addArchivedFileSet(File)}, {@link #addArchivedFileSet(File, String[], String[])}, and
174 * {@link #addArchivedFileSet(File, String, String[], String[])}. However, as these methods are in widespread use,
175 * they cannot easily be deprecated.
176 *
177 * @param charset the encoding to use, particularly useful to specific non-standard filename encodings
178 * for some kinds of archives (for instance zip files)
179 *
180 * Stream transformers are supported on this method
181 *
182 * @param fileSet the fileSet to add
183 * @param charset
184 *
185 * @since 1.0-alpha-9
186 */
187 void addArchivedFileSet(ArchivedFileSet fileSet, Charset charset) throws ArchiverException;
188
189 /**
190 * Adds the given resource collection to the archive.
191 *
192 * Stream transformers are *not* supported on this method
193 *
194 * @since 1.0-alpha-10
195 */
196 void addResource(PlexusIoResource resource, String destFileName, int permissions) throws ArchiverException;
197
198 /**
199 * Adds the given resource collection to the archive.
200 *
201 * Stream transformers are supported on this method
202 *
203 * @since 1.0-alpha-10
204 */
205 void addResources(PlexusIoResourceCollection resources) throws ArchiverException;
206
207 File getDestFile();
208
209 void setDestFile(File destFile);
210
211 void setFileMode(int mode);
212
213 int getFileMode();
214
215 int getOverrideFileMode();
216
217 void setDefaultFileMode(int mode);
218
219 int getDefaultFileMode();
220
221 /**
222 * This is the forced mode that should be used regardless if set, otherwise falls back to default.
223 *
224 * @param mode
225 */
226 void setDirectoryMode(int mode);
227
228 /**
229 * Gets the forced mode for directories, falling back to default if none is forced.
230 *
231 * @return
232 */
233 int getDirectoryMode();
234
235 int getOverrideDirectoryMode();
236
237 /**
238 * This is the "default" value we should use if no other value is specified
239 *
240 * @param mode
241 */
242 void setDefaultDirectoryMode(int mode);
243
244 int getDefaultDirectoryMode();
245
246 boolean getIncludeEmptyDirs();
247
248 void setIncludeEmptyDirs(boolean includeEmptyDirs);
249
250 void setDotFileDirectory(File dotFileDirectory);
251
252 /**
253 * Returns an iterator over instances of {@link ArchiveEntry}, which have previously been added by calls to
254 * {@link #addResources(PlexusIoResourceCollection)}, {@link #addResource(PlexusIoResource, String, int)},
255 * {@link #addFileSet(FileSet)}, etc.
256 *
257 * @since 1.0-alpha-10
258 */
259 @Nonnull
260 ResourceIterator getResources() throws ArchiverException;
261
262 /**
263 * Returns a map of the files that have been added to the archive.
264 * <p>
265 * Note: The entry names in the map may use platform-specific path separators
266 * in the base implementation. However, archive format-specific implementations
267 * (such as ZIP-based archivers) should normalize paths according to their format
268 * requirements. For example, ZIP archivers normalize to forward slashes as required
269 * by the ZIP file specification.
270 * </p>
271 *
272 * @return A map where keys are entry names and values are the corresponding ArchiveEntry objects.
273 * @deprecated Use {@link #getResources()}
274 */
275 @Deprecated
276 Map<String, ArchiveEntry> getFiles();
277
278 /**
279 * <p>
280 * Returns, whether recreating the archive is forced (default). Setting this option to false means, that the
281 * archiver should compare the timestamps of included files with the timestamp of the target archive and rebuild the
282 * archive only, if the latter timestamp precedes the former timestamps. Checking for timestamps will typically
283 * offer a performance gain (in particular, if the following steps in a build can be suppressed, if an archive isn't
284 * recreated) on the cost that you get inaccurate results from time to time. In particular, removal of source files
285 * won't be detected.
286 * </p>
287 * <p>
288 * An archiver doesn't necessarily support checks for uptodate. If so, setting this option to true will simply be
289 * ignored. The method {@link #isSupportingForced()} may be called to check whether an archiver does support
290 * uptodate checks.
291 * </p>
292 *
293 * @return true if the target archive should always be created; false otherwise
294 *
295 * @see #setForced(boolean)
296 * @see #isSupportingForced()
297 */
298 boolean isForced();
299
300 /**
301 * <p>
302 * Sets, whether recreating the archive is forced (default). Setting this option to false means, that the archiver
303 * should compare the timestamps of included files with the timestamp of the target archive and rebuild the archive
304 * only, if the latter timestamp precedes the former timestamps. Checking for timestamps will typically offer a
305 * performance gain (in particular, if the following steps in a build can be suppressed, if an archive isn't
306 * recreated) on the cost that you get inaccurate results from time to time. In particular, removal of source files
307 * won't be detected.
308 * </p>
309 * <p>
310 * An archiver doesn't necessarily support checks for uptodate. If so, setting this option to true will simply be
311 * ignored. The method {@link #isSupportingForced()} may be called to check whether an archiver does support
312 * uptodate checks.
313 * </p>
314 *
315 * @param forced
316 * true, if the target archive should always be created; false otherwise
317 *
318 * @see #isForced()
319 * @see #isSupportingForced()
320 */
321 void setForced(boolean forced);
322
323 /**
324 * Returns, whether the archive supports uptodate checks. If so, you may set {@link #setForced(boolean)} to true.
325 *
326 * @return true, if the archiver does support uptodate checks, false otherwise
327 *
328 * @see #setForced(boolean)
329 * @see #isForced()
330 */
331 boolean isSupportingForced();
332
333 /**
334 * Returns the behavior of this archiver when duplicate files are detected.
335 */
336 String getDuplicateBehavior();
337
338 /**
339 * Set the behavior of this archiver when duplicate files are detected. One of: <br>
340 * <ul>
341 * <li>add - Add the duplicates to the archive as duplicate entries</li>
342 * <li>skip/preserve - Leave the first entry encountered in the archive, skip the new one</li>
343 * <li>fail - throw an {@link ArchiverException}</li>
344 * </ul>
345 * <br>
346 * See {@link Archiver#DUPLICATES_ADD}, {@link Archiver#DUPLICATES_SKIP}, {@link Archiver#DUPLICATES_PRESERVE},
347 * {@link Archiver#DUPLICATES_FAIL}.
348 */
349 void setDuplicateBehavior(String duplicate);
350
351 /**
352 * to use or not the jvm method for file permissions: user all <b>not active for group permissions</b>
353 *
354 * @since 1.1
355 * @param useJvmChmod
356 * @deprecated this setting is now ignored. The jvm is always used.
357 */
358 @Deprecated
359 void setUseJvmChmod(boolean useJvmChmod);
360
361 /**
362 *
363 * @since 1.1
364 * @return
365 * @deprecated this setting is now ignored. The jvm is always used.
366 */
367 @Deprecated
368 boolean isUseJvmChmod();
369
370 /**
371 * @since 1.1
372 */
373 boolean isIgnorePermissions();
374
375 /**
376 * @since 1.1
377 */
378 void setIgnorePermissions(final boolean ignorePermissions);
379
380 /**
381 * Define forced last modification date for entries (if non null).
382 *
383 * @param lastModifiedDate
384 * @since 4.2.0
385 * @deprecated Use {@link #setLastModifiedTime(FileTime)} instead
386 */
387 @Deprecated
388 void setLastModifiedDate(final Date lastModifiedDate);
389
390 /**
391 * @since 4.2.0
392 * @deprecated Use {@link #getLastModifiedTime()} instead
393 */
394 @Deprecated
395 Date getLastModifiedDate();
396
397 /**
398 * Sets the last modification time of the entries (if non null).
399 *
400 * @param lastModifiedTime to set in the archive entries
401 *
402 * @see #getLastModifiedTime()
403 * @since 4.3.0
404 */
405 void setLastModifiedTime(final FileTime lastModifiedTime);
406
407 /**
408 * Returns the last modification time of the archiver.
409 *
410 * @return The last modification time of the archiver, null if not specified
411 *
412 * @see #setLastModifiedTime(FileTime)
413 * @since 4.3.0
414 */
415 FileTime getLastModifiedTime();
416
417 /**
418 * Set filename comparator, used to sort file entries when scanning directories since File.list() does not
419 * guarantee any order.
420 *
421 * @since 4.2.0
422 */
423 void setFilenameComparator(Comparator<String> filenameComparator);
424
425 /**
426 * @since 4.2.0
427 */
428 void setOverrideUid(int uid);
429
430 /**
431 * @since 4.2.0
432 */
433 void setOverrideUserName(String userName);
434
435 /**
436 * @since 4.2.0
437 */
438 int getOverrideUid();
439
440 /**
441 * @since 4.2.0
442 */
443 String getOverrideUserName();
444
445 /**
446 * @since 4.2.0
447 */
448 void setOverrideGid(int gid);
449
450 /**
451 * @since 4.2.0
452 */
453 void setOverrideGroupName(String groupName);
454
455 /**
456 * @since 4.2.0
457 */
458 int getOverrideGid();
459
460 /**
461 * @since 4.2.0
462 */
463 String getOverrideGroupName();
464
465 /**
466 * @since 4.7.0
467 */
468 void setUmask(int umask);
469
470 /**
471 * @since 4.7.0
472 */
473 int getUmask();
474
475 /**
476 * This method is obsolete and will just call {@link #configureReproducibleBuild(FileTime)}
477 * with the Date transformed into FileTime.
478 *
479 * @param lastModifiedDate the date to use for archive entries last modified time
480 * @since 4.2.0
481 * @deprecated Use {@link #configureReproducibleBuild(FileTime)} instead.
482 */
483 @Deprecated
484 void configureReproducible(Date lastModifiedDate);
485
486 /**
487 * Configure the archiver to create archives in a reproducible way (see
488 * <a href="https://reproducible-builds.org/">Reproducible Builds</a>).
489 * <p>This will configure:
490 * <ul>
491 * <li>reproducible archive entries order,</li>
492 * <li>defined entries timestamp</li>
493 * </ul>
494 *
495 * @param lastModifiedTime The last modification time of the entries
496 *
497 * @see <a href="https://reproducible-builds.org/">Reproducible Builds</a>
498 * @since 4.3.0
499 */
500 void configureReproducibleBuild(FileTime lastModifiedTime);
501 }