View Javadoc
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 java.io.File;
20  import java.io.IOException;
21  import java.nio.charset.Charset;
22  import java.util.HashSet;
23  import java.util.Map;
24  import java.util.Set;
25  import javax.annotation.Nonnull;
26  import org.codehaus.plexus.components.io.resources.PlexusIoResource;
27  import org.codehaus.plexus.components.io.resources.PlexusIoResourceCollection;
28  
29  public interface Archiver
30  {
31  
32      /**
33       * Default value for the dirmode attribute.
34       */
35      int DEFAULT_DIR_MODE = UnixStat.DIR_FLAG | UnixStat.DEFAULT_DIR_PERM;
36  
37      /**
38       * Default value for the filemode attribute.
39       */
40      int DEFAULT_FILE_MODE = UnixStat.FILE_FLAG | UnixStat.DEFAULT_FILE_PERM;
41  
42      /**
43       * Default value for the symlinkmode attribute.
44       */
45      int DEFAULT_SYMLILNK_MODE = UnixStat.LINK_FLAG | UnixStat.DEFAULT_LINK_PERM;
46  
47      String ROLE = Archiver.class.getName();
48  
49      public static final String DUPLICATES_ADD = "add";
50  
51      public static final String DUPLICATES_PRESERVE = "preserve";
52  
53      public static final String DUPLICATES_SKIP = "skip";
54  
55      public static final String DUPLICATES_FAIL = "fail";
56  
57      public static final Set<String> DUPLICATES_VALID_BEHAVIORS = new HashSet<String>()
58      {
59  
60          private static final long serialVersionUID = 1L;
61  
62  
63          {
64              add( DUPLICATES_ADD );
65              add( DUPLICATES_PRESERVE );
66              add( DUPLICATES_SKIP );
67              add( DUPLICATES_FAIL );
68          }
69  
70      };
71  
72      void createArchive()
73          throws ArchiverException, IOException;
74  
75      /**
76       * Obsolete, use {@link #addFileSet(FileSet)}.
77       * You can use "inline" of this method in your
78       * IDE to get the proper implementation for this release.
79       *
80       * @deprecated Will go away in next major version
81       */
82      @Deprecated
83      void addDirectory( @Nonnull File directory )
84          throws ArchiverException;
85  
86      /**
87       * Obsolete, use {@link #addFileSet(FileSet)}.
88       * You can use "inline" of this method in your
89       * IDE to get the proper implementation for this release.
90       *
91       * @deprecated Will go away in next major version
92       */
93      @Deprecated
94      void addDirectory( @Nonnull File directory, String prefix )
95          throws ArchiverException;
96  
97      /**
98       * Obsolete, use {@link #addFileSet(FileSet)}.You can use "inline" of this method in your
99       * IDE to get the proper implementation for this release.
100      *
101      * @deprecated Will go away in next major version
102      */
103     @Deprecated
104     void addDirectory( @Nonnull File directory, String[] includes, String[] excludes )
105         throws ArchiverException;
106 
107     /**
108      * Obsolete, use {@link #addFileSet(FileSet)}.
109      * You can use "inline" of this method in your
110      * IDE to get the proper implementation for this release.
111      *
112      * @deprecated Will go away in next major version
113      */
114     @Deprecated
115     void addDirectory( @Nonnull File directory, String prefix, String[] includes, String[] excludes )
116         throws ArchiverException;
117 
118     /**
119      * Adds the given file set to the archive. This method is basically obsoleting {@link #addDirectory(File)},
120      * {@link #addDirectory(File, String)}, {@link #addDirectory(File, String[], String[])}, and
121      * {@link #addDirectory(File, String, String[], String[])}. However, as these methods are in widespread use, they
122      * cannot easily be made deprecated.
123      *
124      * @throws ArchiverException
125      * Adding the file set failed.
126      * @since 1.0-alpha-9
127      */
128     void addFileSet( @Nonnull FileSet fileSet )
129         throws ArchiverException;
130 
131     void addSymlink( String symlinkName, String symlinkDestination )
132         throws ArchiverException;
133 
134     void addSymlink( String symlinkName, int permissions, String symlinkDestination )
135         throws ArchiverException;
136 
137     void addFile( @Nonnull File inputFile, @Nonnull String destFileName )
138         throws ArchiverException;
139 
140     void addFile( @Nonnull File inputFile, @Nonnull String destFileName, int permissions )
141         throws ArchiverException;
142 
143     /**
144      * Obsolete, use {@link #addArchivedFileSet(ArchivedFileSet)}. You can use "inline" of this method in your
145      * IDE to get the proper implementation for this release.
146      *
147      * @deprecated Will go away in next major version
148      */
149     void addArchivedFileSet( @Nonnull File archiveFile )
150         throws ArchiverException;
151 
152     /**
153      * Obsolete, use {@link #addArchivedFileSet(ArchivedFileSet)}. You can use "inline" of this method in your
154      * IDE to get the proper implementation for this release.
155      *
156      * @deprecated Will go away in next major version
157      */
158     @Deprecated
159     void addArchivedFileSet( @Nonnull File archiveFile, String prefix )
160         throws ArchiverException;
161 
162     /**
163      * Obsolete, use {@link #addArchivedFileSet(ArchivedFileSet)}. You can use "inline" of this method in your
164      * IDE to get the proper implementation for this release.
165      *
166      * @deprecated Will go away in next major version
167      */
168     @Deprecated
169     void addArchivedFileSet( File archiveFile, String[] includes, String[] excludes )
170         throws ArchiverException;
171 
172     /**
173      * Obsolete, use {@link #addArchivedFileSet(ArchivedFileSet)}. You can use "inline" of this method in your
174      * IDE to get the proper implementation for this release.
175      *
176      * @deprecated Will go away in next major version
177      */
178     @Deprecated
179     void addArchivedFileSet( @Nonnull File archiveFile, String prefix, String[] includes, String[] excludes )
180         throws ArchiverException;
181 
182     /**
183      * Adds the given archive file set to the archive. This method is basically obsoleting
184      * {@link #addArchivedFileSet(File)}, {@link #addArchivedFileSet(File, String[], String[])}, and
185      * {@link #addArchivedFileSet(File, String, String[], String[])}. However, as these methods are in widespread use,
186      * they cannot easily be made deprecated.
187      *
188      * Stream transformers are supported on this method
189      *
190      * @since 1.0-alpha-9
191      */
192     void addArchivedFileSet( ArchivedFileSet fileSet )
193         throws ArchiverException;
194 
195     /**
196      * Adds the given archive file set to the archive. This method is basically obsoleting
197      * {@link #addArchivedFileSet(File)}, {@link #addArchivedFileSet(File, String[], String[])}, and
198      * {@link #addArchivedFileSet(File, String, String[], String[])}. However, as these methods are in widespread use,
199      * they cannot easily be made deprecated.
200      *
201      * @param charset the encoding to use, particularly useful to specific non-standard filename encodings
202      * for some kinds of archives (for instance zip files)
203      *
204      * Stream transformers are supported on this method
205      *
206      * @param fileSet the fileSet to add
207      * @param charset
208      *
209      * @since 1.0-alpha-9
210      */
211     void addArchivedFileSet( ArchivedFileSet fileSet, Charset charset )
212         throws ArchiverException;
213 
214     /**
215      * Adds the given resource collection to the archive.
216      *
217      * Stream transformers are *not* supported on this method
218      *
219      * @since 1.0-alpha-10
220      */
221     void addResource( PlexusIoResource resource, String destFileName, int permissions )
222         throws ArchiverException;
223 
224     /**
225      * Adds the given resource collection to the archive.
226      *
227      * Stream transformers are supported om this method
228      *
229      * @since 1.0-alpha-10
230      */
231     void addResources( PlexusIoResourceCollection resources )
232         throws ArchiverException;
233 
234     File getDestFile();
235 
236     void setDestFile( File destFile );
237 
238     void setFileMode( int mode );
239 
240     int getFileMode();
241 
242     int getOverrideFileMode();
243 
244     void setDefaultFileMode( int mode );
245 
246     int getDefaultFileMode();
247 
248     /**
249      * This is the forced mode that should be used regardless if set, otherwise falls back to default.
250      *
251      * @param mode
252      */
253     void setDirectoryMode( int mode );
254 
255     /**
256      * Gets the forced mode for directories, falling back to default if none is forced.
257      *
258      * @return
259      */
260     int getDirectoryMode();
261 
262     int getOverrideDirectoryMode();
263 
264     /**
265      * This is the "default" value we should use if no other value is specified
266      *
267      * @param mode
268      */
269     void setDefaultDirectoryMode( int mode );
270 
271     int getDefaultDirectoryMode();
272 
273     boolean getIncludeEmptyDirs();
274 
275     void setIncludeEmptyDirs( boolean includeEmptyDirs );
276 
277     void setDotFileDirectory( File dotFileDirectory );
278 
279     /**
280      * Returns an iterator over instances of {@link ArchiveEntry}, which have previously been added by calls to
281      * {@link #addResources(PlexusIoResourceCollection)}, {@link #addResource(PlexusIoResource, String, int)},
282      * {@link #addFileSet(FileSet)}, etc.
283      *
284      * @since 1.0-alpha-10
285      */
286     @Nonnull
287     ResourceIterator getResources()
288         throws ArchiverException;
289 
290     /**
291      * @deprecated Use {@link #getResources()}
292      */
293     Map<String, ArchiveEntry> getFiles();
294 
295     /**
296      * <p>
297      * Returns, whether recreating the archive is forced (default). Setting this option to false means, that the
298      * archiver should compare the timestamps of included files with the timestamp of the target archive and rebuild the
299      * archive only, if the latter timestamp precedes the former timestamps. Checking for timestamps will typically
300      * offer a performance gain (in particular, if the following steps in a build can be suppressed, if an archive isn't
301      * recrated) on the cost that you get inaccurate results from time to time. In particular, removal of source files
302      * won't be detected.
303      * </p>
304      * <p>
305      * An archiver doesn't necessarily support checks for uptodate. If so, setting this option to true will simply be
306      * ignored. The method {@link #isSupportingForced()} may be called to check whether an archiver does support
307      * uptodate checks.
308      * </p>
309      *
310      * @return True, if the target archive should always be created; false otherwise
311      *
312      * @see #setForced(boolean)
313      * @see #isSupportingForced()
314      */
315     boolean isForced();
316 
317     /**
318      * <p>
319      * Sets, whether recreating the archive is forced (default). Setting this option to false means, that the archiver
320      * should compare the timestamps of included files with the timestamp of the target archive and rebuild the archive
321      * only, if the latter timestamp precedes the former timestamps. Checking for timestamps will typically offer a
322      * performance gain (in particular, if the following steps in a build can be suppressed, if an archive isn't
323      * recrated) on the cost that you get inaccurate results from time to time. In particular, removal of source files
324      * won't be detected.
325      * </p>
326      * <p>
327      * An archiver doesn't necessarily support checks for uptodate. If so, setting this option to true will simply be
328      * ignored. The method {@link #isSupportingForced()} may be called to check whether an archiver does support
329      * uptodate checks.
330      * </p>
331      *
332      * @param forced
333      * True, if the target archive should always be created; false otherwise
334      *
335      * @see #isForced()
336      * @see #isSupportingForced()
337      */
338     void setForced( boolean forced );
339 
340     /**
341      * Returns, whether the archive supports uptodate checks. If so, you may set {@link #setForced(boolean)} to true.
342      *
343      * @return True, if the archiver does support uptodate checks, false otherwise
344      *
345      * @see #setForced(boolean)
346      * @see #isForced()
347      */
348     boolean isSupportingForced();
349 
350     /**
351      * Returns the behavior of this archiver when duplicate files are detected.
352      */
353     String getDuplicateBehavior();
354 
355     /**
356      * Set the behavior of this archiver when duplicate files are detected. One of: <br/>
357      * <ul>
358      * <li>add - Add the duplicates to the archive as duplicate entries</li>
359      * <li>skip/preserve - Leave the first entry encountered in the archive, skip the new one</li>
360      * <li>fail - throw an {@link ArchiverException}</li>
361      * </ul>
362      * <br/>
363      * See {@link Archiver#DUPLICATES_ADD}, {@link Archiver#DUPLICATES_SKIP}, {@link Archiver#DUPLICATES_PRESERVE},
364      * {@link Archiver#DUPLICATES_FAIL}.
365      */
366     void setDuplicateBehavior( String duplicate );
367 
368     /**
369      * to use or not the jvm method for file permissions: user all <b>not active for group permissions</b>
370      *
371      * @since 1.1
372      * @param useJvmChmod
373      * @deprecated this setting is now ignored. The jvm is always used.
374      */
375     @Deprecated
376     void setUseJvmChmod( boolean useJvmChmod );
377 
378     /**
379      *
380      * @since 1.1
381      * @return
382      * @deprecated this setting is now ignored. The jvm is always used.
383      */
384     @Deprecated
385     boolean isUseJvmChmod();
386 
387     /**
388      * @since 1.1
389      */
390     boolean isIgnorePermissions();
391 
392     /**
393      * @since 1.1
394      */
395     void setIgnorePermissions( final boolean ignorePermissions );
396 
397 }