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.

@author Timothy Gerard Endres,

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.

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.

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

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.

@param asciiTranslate If true, translate ascii text files.

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

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.
param  userId The user Id to use in the headers.
param  userName The user name to use in the headers.
param  groupId The group id to use in the headers.
param  groupName The group name to use in the headers.

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

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

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

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

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.

@return The current temporary directory path.

Set the current temporary directory path.
param  path The new temporary directory path.

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.

@return The record size this archive is using.

Close the archive. This simply calls the underlying tar stream's close()
method.

Perform the "list" command and list the contents of the archive. NOTE
That this method uses the progress display to actually list the conents.
If the progress display is not set, nothing will be listed!

Perform the "extract" command and extract the contents of the archive.

@param destDir The destination directory into which to extract.

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.
param  entry The TarEntry representing the entry to write to the archive.
param  recurse If true, process the children of directory entries.