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 void addArchivedFileSet(@Nonnull File archiveFile) throws ArchiverException;
132
133 /**
134 * Obsolete, use {@link #addArchivedFileSet(ArchivedFileSet)}.
135 *
136 * @deprecated Will go away in next major version
137 */
138 @Deprecated
139 void addArchivedFileSet(@Nonnull File archiveFile, String prefix) throws ArchiverException;
140
141 /**
142 * Obsolete, use {@link #addArchivedFileSet(ArchivedFileSet)}.
143 *
144 * @deprecated Will go away in next major version
145 */
146 @Deprecated
147 void addArchivedFileSet(File archiveFile, String[] includes, String[] excludes) throws ArchiverException;
148
149 /**
150 * Obsolete, use {@link #addArchivedFileSet(ArchivedFileSet)}.
151 *
152 * @deprecated Will go away in next major version
153 */
154 @Deprecated
155 void addArchivedFileSet(@Nonnull File archiveFile, String prefix, String[] includes, String[] excludes)
156 throws ArchiverException;
157
158 /**
159 * Adds the given archive file set to the archive. This method is basically obsoleting
160 * {@link #addArchivedFileSet(File)}, {@link #addArchivedFileSet(File, String[], String[])}, and
161 * {@link #addArchivedFileSet(File, String, String[], String[])}. However, as these methods are in widespread use,
162 * they cannot easily be deprecated.
163 *
164 * Stream transformers are supported on this method
165 *
166 * @since 1.0-alpha-9
167 */
168 void addArchivedFileSet(ArchivedFileSet fileSet) throws ArchiverException;
169
170 /**
171 * Adds the given archive file set to the archive. This method is basically obsoleting
172 * {@link #addArchivedFileSet(File)}, {@link #addArchivedFileSet(File, String[], String[])}, and
173 * {@link #addArchivedFileSet(File, String, String[], String[])}. However, as these methods are in widespread use,
174 * they cannot easily be deprecated.
175 *
176 * @param charset the encoding to use, particularly useful to specific non-standard filename encodings
177 * for some kinds of archives (for instance zip files)
178 *
179 * Stream transformers are supported on this method
180 *
181 * @param fileSet the fileSet to add
182 * @param charset
183 *
184 * @since 1.0-alpha-9
185 */
186 void addArchivedFileSet(ArchivedFileSet fileSet, Charset charset) throws ArchiverException;
187
188 /**
189 * Adds the given resource collection to the archive.
190 *
191 * Stream transformers are *not* supported on this method
192 *
193 * @since 1.0-alpha-10
194 */
195 void addResource(PlexusIoResource resource, String destFileName, int permissions) throws ArchiverException;
196
197 /**
198 * Adds the given resource collection to the archive.
199 *
200 * Stream transformers are supported on this method
201 *
202 * @since 1.0-alpha-10
203 */
204 void addResources(PlexusIoResourceCollection resources) throws ArchiverException;
205
206 File getDestFile();
207
208 void setDestFile(File destFile);
209
210 void setFileMode(int mode);
211
212 int getFileMode();
213
214 int getOverrideFileMode();
215
216 void setDefaultFileMode(int mode);
217
218 int getDefaultFileMode();
219
220 /**
221 * This is the forced mode that should be used regardless if set, otherwise falls back to default.
222 *
223 * @param mode
224 */
225 void setDirectoryMode(int mode);
226
227 /**
228 * Gets the forced mode for directories, falling back to default if none is forced.
229 *
230 * @return
231 */
232 int getDirectoryMode();
233
234 int getOverrideDirectoryMode();
235
236 /**
237 * This is the "default" value we should use if no other value is specified
238 *
239 * @param mode
240 */
241 void setDefaultDirectoryMode(int mode);
242
243 int getDefaultDirectoryMode();
244
245 boolean getIncludeEmptyDirs();
246
247 void setIncludeEmptyDirs(boolean includeEmptyDirs);
248
249 void setDotFileDirectory(File dotFileDirectory);
250
251 /**
252 * Returns an iterator over instances of {@link ArchiveEntry}, which have previously been added by calls to
253 * {@link #addResources(PlexusIoResourceCollection)}, {@link #addResource(PlexusIoResource, String, int)},
254 * {@link #addFileSet(FileSet)}, etc.
255 *
256 * @since 1.0-alpha-10
257 */
258 @Nonnull
259 ResourceIterator getResources() throws ArchiverException;
260
261 /**
262 * @deprecated Use {@link #getResources()}
263 */
264 Map<String, ArchiveEntry> getFiles();
265
266 /**
267 * <p>
268 * Returns, whether recreating the archive is forced (default). Setting this option to false means, that the
269 * archiver should compare the timestamps of included files with the timestamp of the target archive and rebuild the
270 * archive only, if the latter timestamp precedes the former timestamps. Checking for timestamps will typically
271 * offer a performance gain (in particular, if the following steps in a build can be suppressed, if an archive isn't
272 * recreated) on the cost that you get inaccurate results from time to time. In particular, removal of source files
273 * won't be detected.
274 * </p>
275 * <p>
276 * An archiver doesn't necessarily support checks for uptodate. If so, setting this option to true will simply be
277 * ignored. The method {@link #isSupportingForced()} may be called to check whether an archiver does support
278 * uptodate checks.
279 * </p>
280 *
281 * @return true if the target archive should always be created; false otherwise
282 *
283 * @see #setForced(boolean)
284 * @see #isSupportingForced()
285 */
286 boolean isForced();
287
288 /**
289 * <p>
290 * Sets, whether recreating the archive is forced (default). Setting this option to false means, that the archiver
291 * should compare the timestamps of included files with the timestamp of the target archive and rebuild the archive
292 * only, if the latter timestamp precedes the former timestamps. Checking for timestamps will typically offer a
293 * performance gain (in particular, if the following steps in a build can be suppressed, if an archive isn't
294 * recreated) on the cost that you get inaccurate results from time to time. In particular, removal of source files
295 * won't be detected.
296 * </p>
297 * <p>
298 * An archiver doesn't necessarily support checks for uptodate. If so, setting this option to true will simply be
299 * ignored. The method {@link #isSupportingForced()} may be called to check whether an archiver does support
300 * uptodate checks.
301 * </p>
302 *
303 * @param forced
304 * true, if the target archive should always be created; false otherwise
305 *
306 * @see #isForced()
307 * @see #isSupportingForced()
308 */
309 void setForced(boolean forced);
310
311 /**
312 * Returns, whether the archive supports uptodate checks. If so, you may set {@link #setForced(boolean)} to true.
313 *
314 * @return true, if the archiver does support uptodate checks, false otherwise
315 *
316 * @see #setForced(boolean)
317 * @see #isForced()
318 */
319 boolean isSupportingForced();
320
321 /**
322 * Returns the behavior of this archiver when duplicate files are detected.
323 */
324 String getDuplicateBehavior();
325
326 /**
327 * Set the behavior of this archiver when duplicate files are detected. One of: <br>
328 * <ul>
329 * <li>add - Add the duplicates to the archive as duplicate entries</li>
330 * <li>skip/preserve - Leave the first entry encountered in the archive, skip the new one</li>
331 * <li>fail - throw an {@link ArchiverException}</li>
332 * </ul>
333 * <br>
334 * See {@link Archiver#DUPLICATES_ADD}, {@link Archiver#DUPLICATES_SKIP}, {@link Archiver#DUPLICATES_PRESERVE},
335 * {@link Archiver#DUPLICATES_FAIL}.
336 */
337 void setDuplicateBehavior(String duplicate);
338
339 /**
340 * to use or not the jvm method for file permissions: user all <b>not active for group permissions</b>
341 *
342 * @since 1.1
343 * @param useJvmChmod
344 * @deprecated this setting is now ignored. The jvm is always used.
345 */
346 @Deprecated
347 void setUseJvmChmod(boolean useJvmChmod);
348
349 /**
350 *
351 * @since 1.1
352 * @return
353 * @deprecated this setting is now ignored. The jvm is always used.
354 */
355 @Deprecated
356 boolean isUseJvmChmod();
357
358 /**
359 * @since 1.1
360 */
361 boolean isIgnorePermissions();
362
363 /**
364 * @since 1.1
365 */
366 void setIgnorePermissions(final boolean ignorePermissions);
367
368 /**
369 * Define forced last modification date for entries (if non null).
370 *
371 * @param lastModifiedDate
372 * @since 4.2.0
373 * @deprecated Use {@link #setLastModifiedTime(FileTime)} instead
374 */
375 @Deprecated
376 void setLastModifiedDate(final Date lastModifiedDate);
377
378 /**
379 * @since 4.2.0
380 * @deprecated Use {@link #getLastModifiedTime()} instead
381 */
382 @Deprecated
383 Date getLastModifiedDate();
384
385 /**
386 * Sets the last modification time of the entries (if non null).
387 *
388 * @param lastModifiedTime to set in the archive entries
389 *
390 * @see #getLastModifiedTime()
391 * @since 4.3.0
392 */
393 void setLastModifiedTime(final FileTime lastModifiedTime);
394
395 /**
396 * Returns the last modification time of the archiver.
397 *
398 * @return The last modification time of the archiver, null if not specified
399 *
400 * @see #setLastModifiedTime(FileTime)
401 * @since 4.3.0
402 */
403 FileTime getLastModifiedTime();
404
405 /**
406 * Set filename comparator, used to sort file entries when scanning directories since File.list() does not
407 * guarantee any order.
408 *
409 * @since 4.2.0
410 */
411 void setFilenameComparator(Comparator<String> filenameComparator);
412
413 /**
414 * @since 4.2.0
415 */
416 void setOverrideUid(int uid);
417
418 /**
419 * @since 4.2.0
420 */
421 void setOverrideUserName(String userName);
422
423 /**
424 * @since 4.2.0
425 */
426 int getOverrideUid();
427
428 /**
429 * @since 4.2.0
430 */
431 String getOverrideUserName();
432
433 /**
434 * @since 4.2.0
435 */
436 void setOverrideGid(int gid);
437
438 /**
439 * @since 4.2.0
440 */
441 void setOverrideGroupName(String groupName);
442
443 /**
444 * @since 4.2.0
445 */
446 int getOverrideGid();
447
448 /**
449 * @since 4.2.0
450 */
451 String getOverrideGroupName();
452
453 /**
454 * @since 4.7.0
455 */
456 void setUmask(int umask);
457
458 /**
459 * @since 4.7.0
460 */
461 int getUmask();
462
463 /**
464 * This method is obsolete and will just call {@link #configureReproducibleBuild(FileTime)}
465 * with the Date transformed into FileTime.
466 *
467 * @param lastModifiedDate the date to use for archive entries last modified time
468 * @since 4.2.0
469 * @deprecated Use {@link #configureReproducibleBuild(FileTime)} instead.
470 */
471 @Deprecated
472 void configureReproducible(Date lastModifiedDate);
473
474 /**
475 * Configure the archiver to create archives in a reproducible way (see
476 * <a href="https://reproducible-builds.org/">Reproducible Builds</a>).
477 * <p>This will configure:
478 * <ul>
479 * <li>reproducible archive entries order,</li>
480 * <li>defined entries timestamp</li>
481 * </ul>
482 *
483 * @param lastModifiedTime The last modification time of the entries
484 *
485 * @see <a href="https://reproducible-builds.org/">Reproducible Builds</a>
486 * @since 4.3.0
487 */
488 void configureReproducibleBuild(FileTime lastModifiedTime);
489 }