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 * @deprecated Use {@link #getResources()}
264 */
265 @Deprecated
266 Map<String, ArchiveEntry> getFiles();
267
268 /**
269 * <p>
270 * Returns, whether recreating the archive is forced (default). Setting this option to false means, that the
271 * archiver should compare the timestamps of included files with the timestamp of the target archive and rebuild the
272 * archive only, if the latter timestamp precedes the former timestamps. Checking for timestamps will typically
273 * offer a performance gain (in particular, if the following steps in a build can be suppressed, if an archive isn't
274 * recreated) on the cost that you get inaccurate results from time to time. In particular, removal of source files
275 * won't be detected.
276 * </p>
277 * <p>
278 * An archiver doesn't necessarily support checks for uptodate. If so, setting this option to true will simply be
279 * ignored. The method {@link #isSupportingForced()} may be called to check whether an archiver does support
280 * uptodate checks.
281 * </p>
282 *
283 * @return true if the target archive should always be created; false otherwise
284 *
285 * @see #setForced(boolean)
286 * @see #isSupportingForced()
287 */
288 boolean isForced();
289
290 /**
291 * <p>
292 * Sets, whether recreating the archive is forced (default). Setting this option to false means, that the archiver
293 * should compare the timestamps of included files with the timestamp of the target archive and rebuild the archive
294 * only, if the latter timestamp precedes the former timestamps. Checking for timestamps will typically offer a
295 * performance gain (in particular, if the following steps in a build can be suppressed, if an archive isn't
296 * recreated) on the cost that you get inaccurate results from time to time. In particular, removal of source files
297 * won't be detected.
298 * </p>
299 * <p>
300 * An archiver doesn't necessarily support checks for uptodate. If so, setting this option to true will simply be
301 * ignored. The method {@link #isSupportingForced()} may be called to check whether an archiver does support
302 * uptodate checks.
303 * </p>
304 *
305 * @param forced
306 * true, if the target archive should always be created; false otherwise
307 *
308 * @see #isForced()
309 * @see #isSupportingForced()
310 */
311 void setForced(boolean forced);
312
313 /**
314 * Returns, whether the archive supports uptodate checks. If so, you may set {@link #setForced(boolean)} to true.
315 *
316 * @return true, if the archiver does support uptodate checks, false otherwise
317 *
318 * @see #setForced(boolean)
319 * @see #isForced()
320 */
321 boolean isSupportingForced();
322
323 /**
324 * Returns the behavior of this archiver when duplicate files are detected.
325 */
326 String getDuplicateBehavior();
327
328 /**
329 * Set the behavior of this archiver when duplicate files are detected. One of: <br>
330 * <ul>
331 * <li>add - Add the duplicates to the archive as duplicate entries</li>
332 * <li>skip/preserve - Leave the first entry encountered in the archive, skip the new one</li>
333 * <li>fail - throw an {@link ArchiverException}</li>
334 * </ul>
335 * <br>
336 * See {@link Archiver#DUPLICATES_ADD}, {@link Archiver#DUPLICATES_SKIP}, {@link Archiver#DUPLICATES_PRESERVE},
337 * {@link Archiver#DUPLICATES_FAIL}.
338 */
339 void setDuplicateBehavior(String duplicate);
340
341 /**
342 * to use or not the jvm method for file permissions: user all <b>not active for group permissions</b>
343 *
344 * @since 1.1
345 * @param useJvmChmod
346 * @deprecated this setting is now ignored. The jvm is always used.
347 */
348 @Deprecated
349 void setUseJvmChmod(boolean useJvmChmod);
350
351 /**
352 *
353 * @since 1.1
354 * @return
355 * @deprecated this setting is now ignored. The jvm is always used.
356 */
357 @Deprecated
358 boolean isUseJvmChmod();
359
360 /**
361 * @since 1.1
362 */
363 boolean isIgnorePermissions();
364
365 /**
366 * @since 1.1
367 */
368 void setIgnorePermissions(final boolean ignorePermissions);
369
370 /**
371 * Define forced last modification date for entries (if non null).
372 *
373 * @param lastModifiedDate
374 * @since 4.2.0
375 * @deprecated Use {@link #setLastModifiedTime(FileTime)} instead
376 */
377 @Deprecated
378 void setLastModifiedDate(final Date lastModifiedDate);
379
380 /**
381 * @since 4.2.0
382 * @deprecated Use {@link #getLastModifiedTime()} instead
383 */
384 @Deprecated
385 Date getLastModifiedDate();
386
387 /**
388 * Sets the last modification time of the entries (if non null).
389 *
390 * @param lastModifiedTime to set in the archive entries
391 *
392 * @see #getLastModifiedTime()
393 * @since 4.3.0
394 */
395 void setLastModifiedTime(final FileTime lastModifiedTime);
396
397 /**
398 * Returns the last modification time of the archiver.
399 *
400 * @return The last modification time of the archiver, null if not specified
401 *
402 * @see #setLastModifiedTime(FileTime)
403 * @since 4.3.0
404 */
405 FileTime getLastModifiedTime();
406
407 /**
408 * Set filename comparator, used to sort file entries when scanning directories since File.list() does not
409 * guarantee any order.
410 *
411 * @since 4.2.0
412 */
413 void setFilenameComparator(Comparator<String> filenameComparator);
414
415 /**
416 * @since 4.2.0
417 */
418 void setOverrideUid(int uid);
419
420 /**
421 * @since 4.2.0
422 */
423 void setOverrideUserName(String userName);
424
425 /**
426 * @since 4.2.0
427 */
428 int getOverrideUid();
429
430 /**
431 * @since 4.2.0
432 */
433 String getOverrideUserName();
434
435 /**
436 * @since 4.2.0
437 */
438 void setOverrideGid(int gid);
439
440 /**
441 * @since 4.2.0
442 */
443 void setOverrideGroupName(String groupName);
444
445 /**
446 * @since 4.2.0
447 */
448 int getOverrideGid();
449
450 /**
451 * @since 4.2.0
452 */
453 String getOverrideGroupName();
454
455 /**
456 * @since 4.7.0
457 */
458 void setUmask(int umask);
459
460 /**
461 * @since 4.7.0
462 */
463 int getUmask();
464
465 /**
466 * This method is obsolete and will just call {@link #configureReproducibleBuild(FileTime)}
467 * with the Date transformed into FileTime.
468 *
469 * @param lastModifiedDate the date to use for archive entries last modified time
470 * @since 4.2.0
471 * @deprecated Use {@link #configureReproducibleBuild(FileTime)} instead.
472 */
473 @Deprecated
474 void configureReproducible(Date lastModifiedDate);
475
476 /**
477 * Configure the archiver to create archives in a reproducible way (see
478 * <a href="https://reproducible-builds.org/">Reproducible Builds</a>).
479 * <p>This will configure:
480 * <ul>
481 * <li>reproducible archive entries order,</li>
482 * <li>defined entries timestamp</li>
483 * </ul>
484 *
485 * @param lastModifiedTime The last modification time of the entries
486 *
487 * @see <a href="https://reproducible-builds.org/">Reproducible Builds</a>
488 * @since 4.3.0
489 */
490 void configureReproducibleBuild(FileTime lastModifiedTime);
491 }