Coverage Report - org.codehaus.plexus.archiver.Archiver
 
Classes in this File Line Coverage Branch Coverage Complexity
Archiver
N/A
N/A
1
Archiver$1
75 %
6/8
N/A
1
 
 1  0
 /**
 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  0
     public static final Set<String> DUPLICATES_VALID_BEHAVIORS = new HashSet<String>()
 58  1
     {
 59  
 
 60  
         private static final long serialVersionUID = 1L;
 61  
 
 62  
 
 63  
         {
 64  1
             add( DUPLICATES_ADD );
 65  1
             add( DUPLICATES_PRESERVE );
 66  1
             add( DUPLICATES_SKIP );
 67  1
             add( DUPLICATES_FAIL );
 68  1
         }
 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  
 }