de.esprit.appsuite.io.archive.javatar

## Class TarArchive

- java.lang.Object
- - de.esprit.appsuite.io.archive.javatar.TarArchive

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable

      public class TarArchive
      extends java.lang.Object
      implements java.io.Closeable

  The TarArchive class implements the concept of a tar archive. A tar archive is a series of entries, each of which represents a file system object. Each entry in the archive consists of a header record. Directory entries consist only of the header record, and are followed by entries for the directory's contents. File entries consist of a header record followed by the number of records needed to contain the file's contents. All entries are written on record boundaries. Records are 512 bytes long. TarArchives are instantiated in either read or write mode, based upon whether they are instantiated with an InputStream or an OutputStream. Once instantiated TarArchives read/write mode can not be changed. There is currently no support for random access to tar archives. However, it seems that subclassing TarArchive, and using the TarBuffer.getCurrentRecordNum() and TarBuffer.getCurrentBlockNum() methods, this would be rather trvial.
  Version:
    $Revision: 1.4 $
  Author:
    Timothy Gerard Endres,
  See Also:
    `TarBuffer`, `TarHeader`, `TarEntry`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `asciiTranslate`
    `protected boolean` | `debug`
    `protected int` | `groupId`
    `protected java.lang.String` | `groupName`
    `protected boolean` | `keepOldFiles`
    `protected java.lang.String` | `pathPrefix`
    `protected TarProgressDisplay` | `progressDisplay`
    `protected byte[]` | `recordBuf`
    `protected int` | `recordSize`
    `protected java.lang.String` | `rootPath`
    `protected TarInputStream` | `tarIn`
    `protected TarOutputStream` | `tarOut`
    `protected java.lang.String` | `tempPath`
    `protected TarTransFileTyper` | `transTyper`
    `protected int` | `userId`
    `protected java.lang.String` | `userName`
    `protected boolean` | `verbose`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TarArchive(java.io.InputStream inStream)` The InputStream based constructors create a TarArchive for the purposes of e'x'tracting or lis't'ing a tar archive.
    `TarArchive(java.io.InputStream inStream, int blockSize)`
    `TarArchive(java.io.InputStream inStream, int blockSize, int recordSize)`
    `TarArchive(java.io.OutputStream outStream)` The OutputStream based constructors create a TarArchive for the purposes of 'c'reating a tar archive.
    `TarArchive(java.io.OutputStream outStream, int blockSize)`
    `TarArchive(java.io.OutputStream outStream, int blockSize, int recordSize)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close the archive.
    `void` | `extractContents(java.io.File destDir)` Perform the "extract" command and extract the contents of the archive.
    `int` | `getGroupId()` Get the group id being used for archive entry headers.
    `java.lang.String` | `getGroupName()` Get the group name being used for archive entry headers.
    `int` | `getRecordSize()` Get the archive's record size.
    `java.lang.String` | `getTempDirectory()` Get the current temporary directory path.
    `int` | `getUserId()` Get the user id being used for archive entry headers.
    `java.lang.String` | `getUserName()` Get the user name being used for archive entry headers.
    `boolean` | `isVerbose()` Returns the verbosity setting.
    `void` | `listContents()` Perform the "list" command and list the contents of the archive.
    `void` | `setAsciiTranslation(boolean asciiTranslate)` Set the ascii file translation flag.
    `void` | `setDebug(boolean debugF)` Set the debugging flag.
    `void` | `setKeepOldFiles(boolean keepOldFiles)` Set the flag that determines whether existing files are kept, or overwritten during extraction.
    `void` | `setTarProgressDisplay(TarProgressDisplay display)` Set the current progress display interface.
    `void` | `setTempDirectory(java.lang.String path)` Set the current temporary directory path.
    `void` | `setTransFileTyper(TarTransFileTyper transTyper)` Set the object that will determine if a file is of type ascii text for translation purposes.
    `void` | `setUserInfo(int userId, java.lang.String userName, int groupId, java.lang.String groupName)` Set user and group information that will be used to fill in the tar archive's entry headers.
    `void` | `setVerbose(boolean verbose)` Set the verbosity flag.
    `void` | `writeEntry(TarEntry oldEntry, boolean recurse)` Write an entry to the archive.
    `void` | `writeEntry(TarEntry oldEntry, boolean recurse, AccumulatingProgressInputStream accStream)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### verbose

          protected boolean verbose

    - #### debug

          protected boolean debug

    - #### keepOldFiles

          protected boolean keepOldFiles

    - #### asciiTranslate

          protected boolean asciiTranslate

    - #### userId

          protected int userId

    - #### userName

          protected java.lang.String userName

    - #### groupId

          protected int groupId

    - #### groupName

          protected java.lang.String groupName

    - #### rootPath

          protected java.lang.String rootPath

    - #### tempPath

          protected java.lang.String tempPath

    - #### pathPrefix

          protected java.lang.String pathPrefix

    - #### recordSize

          protected int recordSize

    - #### recordBuf

          protected byte[] recordBuf

    - #### tarIn

          protected TarInputStream tarIn

    - #### tarOut

          protected TarOutputStream tarOut

    - #### transTyper

          protected TarTransFileTyper transTyper

    - #### progressDisplay

          protected TarProgressDisplay progressDisplay

  - ### Constructor Detail

    - #### TarArchive

          public TarArchive(java.io.InputStream inStream)

      The InputStream based constructors create a TarArchive for the purposes of e'x'tracting or lis't'ing a tar archive. Thus, use these constructors when you wish to extract files from or list the contents of an existing tar archive.

    - #### TarArchive

          public TarArchive(java.io.InputStream inStream,
                    int blockSize)

    - #### TarArchive

          public TarArchive(java.io.InputStream inStream,
                    int blockSize,
                    int recordSize)

    - #### TarArchive

          public TarArchive(java.io.OutputStream outStream)

      The OutputStream based constructors create a TarArchive for the purposes of 'c'reating a tar archive. Thus, use these constructors when you wish to create a new tar archive and write files into it.

    - #### TarArchive

          public TarArchive(java.io.OutputStream outStream,
                    int blockSize)

    - #### TarArchive

          public TarArchive(java.io.OutputStream outStream,
                    int blockSize,
                    int recordSize)

  - ### Method Detail

    - #### setDebug

          public void setDebug(boolean debugF)

      Set the debugging flag.
      Parameters:
        `debugF` - The new debug setting.

    - #### isVerbose

          public boolean isVerbose()

      Returns the verbosity setting.
      Returns:
        The current verbosity setting.

    - #### setVerbose

          public void setVerbose(boolean verbose)

      Set the verbosity flag.
      Parameters:
        `verbose` - The new verbosity setting.

    - #### setTarProgressDisplay

          public void setTarProgressDisplay(TarProgressDisplay display)

      Set the current progress display interface. This allows the programmer to use a custom class to display the progress of the archive's processing.
      Parameters:
        `display` - The new progress display interface.
      See Also:
        `TarProgressDisplay`

    - #### setKeepOldFiles

          public void setKeepOldFiles(boolean keepOldFiles)

      Set the flag that determines whether existing files are kept, or overwritten during extraction.
      Parameters:
        `keepOldFiles` - If true, do not overwrite existing files.

    - #### setAsciiTranslation

          public void setAsciiTranslation(boolean asciiTranslate)

      Set the ascii file translation flag. If ascii file translatio is true, then the MIME file type will be consulted to determine if the file is of type 'text/*'. If the MIME type is not found, then the TransFileTyper is consulted if it is not null. If either of these two checks indicates the file is an ascii text file, it will be translated. The translation converts the local operating system's concept of line ends into the UNIX line end, '\n', which is the defacto standard for a TAR archive. This makes text files compatible with UNIX, and since most tar implementations for other platforms, compatible with most other platforms.
      Parameters:
        `asciiTranslate` - If true, translate ascii text files.

    - #### setTransFileTyper

          public void setTransFileTyper(TarTransFileTyper transTyper)

      Set the object that will determine if a file is of type ascii text for translation purposes.
      Parameters:
        `transTyper` - The new TransFileTyper object.

    - #### setUserInfo

          public void setUserInfo(int userId,
                         java.lang.String userName,
                         int groupId,
                         java.lang.String groupName)

      Set user and group information that will be used to fill in the tar archive's entry headers. Since Java currently provides no means of determining a user name, user id, group name, or group id for a given File, TarArchive allows the programmer to specify values to be used in their place.
      Parameters:
        `userId` - The user Id to use in the headers.
        `userName` - The user name to use in the headers.
        `groupId` - The group id to use in the headers.
        `groupName` - The group name to use in the headers.

    - #### getUserId

          public int getUserId()

      Get the user id being used for archive entry headers.
      Returns:
        The current user id.

    - #### getUserName

          public java.lang.String getUserName()

      Get the user name being used for archive entry headers.
      Returns:
        The current user name.

    - #### getGroupId

          public int getGroupId()

      Get the group id being used for archive entry headers.
      Returns:
        The current group id.

    - #### getGroupName

          public java.lang.String getGroupName()

      Get the group name being used for archive entry headers.
      Returns:
        The current group name.

    - #### getTempDirectory

          public java.lang.String getTempDirectory()

      Get the current temporary directory path. Because Java's File did not support temporary files until version 1.2, TarArchive manages its own concept of the temporary directory. The temporary directory defaults to the 'user.dir' System property.
      Returns:
        The current temporary directory path.

    - #### setTempDirectory

          public void setTempDirectory(java.lang.String path)

      Set the current temporary directory path.
      Parameters:
        `path` - The new temporary directory path.

    - #### getRecordSize

          public int getRecordSize()

      Get the archive's record size. Because of its history, tar supports the concept of buffered IO consisting of BLOCKS of RECORDS. This allowed tar to match the IO characteristics of the physical device being used. Of course, in the Java world, this makes no sense, WITH ONE EXCEPTION - archives are expected to be propertly "blocked". Thus, all of the horrible TarBuffer support boils down to simply getting the "boundaries" correct.
      Returns:
        The record size this archive is using.

    - #### close

          public void close()
                     throws java.io.IOException

      Close the archive. This simply calls the underlying tar stream's close() method.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Throws:
        `java.io.IOException`

    - #### listContents

          public void listContents()
                            throws java.io.IOException,
                                   InvalidHeaderException

      Perform the "list" command and list the contents of the archive. Note that this method uses the progress display to actually list the contents. If the progress display is not set, nothing will be listed!
      Throws:
        `java.io.IOException`
        `InvalidHeaderException`

    - #### extractContents

          public void extractContents(java.io.File destDir)
                               throws java.io.IOException,
                                      InvalidHeaderException

      Perform the "extract" command and extract the contents of the archive.
      Parameters:
        `destDir` - The destination directory into which to extract.
      Throws:
        `java.io.IOException`
        `InvalidHeaderException`

    - #### writeEntry

          public void writeEntry(TarEntry oldEntry,
                        boolean recurse)
                          throws java.io.IOException

      Write an entry to the archive. This method will call the putNextEntry() and then write the contents of the entry, and finally call closeEntry() for entries that are files. For directories, it will call putNextEntry(), and then, if the recurse flag is true, process each entry that is a child of the directory.
      Parameters:
        `oldEntry` - The TarEntry representing the entry to write to the archive.
        `recurse` - If true, process the children of directory entries.
      Throws:
        `java.io.IOException`

    - #### writeEntry

          public void writeEntry(TarEntry oldEntry,
                        boolean recurse,
                        AccumulatingProgressInputStream accStream)
                          throws java.io.IOException

      Throws:
        `java.io.IOException`

Copyright © 2014 EsprIT-Systems. All Rights Reserved.