|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectbb.io.TarUtil
public final class TarUtil
Provides static utility methods for dealing with TAR Files.
This class is multithread safe: it is immutable (both its immediate state, as well as the deep state of its fields).
Nested Class Summary | |
---|---|
static class |
TarUtil.UnitTest
See the Overview page of the project's javadocs for a general description of this unit test class. |
Field Summary | |
---|---|
private static String |
appendAll_key
|
private static String |
appendBackup_key
|
private static String |
appendExtension_key
|
private static String |
appendTimeStamp_key
|
private static String |
directoryExtraction_key
|
private static String |
filter_key
|
private static boolean |
giveUserFeedback
|
private static List<String> |
keysLegal_archive
Specifies all the switch keys which can legally appear as command line arguments to main for an archive. |
private static List<String> |
keysLegal_extract
Specifies all the switch keys which can legally appear as command line arguments to main for an extract. |
private static String |
overwrite_key
|
private static String |
pathsToArchive_key
|
private static long |
tarableFileSizeLimit
Maximum size of a file that can be put into a TAR archive file by this class. |
private static String |
tarFile_key
|
Constructor Summary | |
---|---|
private |
TarUtil()
This sole private constructor suppresses the default (public) constructor, ensuring non-instantiability outside of this class. |
Method Summary | |
---|---|
static void |
archive(File tarFile,
FileFilter filter,
File... pathsToArchive)
Writes each element of pathsToArchive to a new TAR format archive file specified by tarFile. |
private static void |
archive(File path,
FileParent fileParent,
org.apache.commons.compress.archivers.tar.TarArchiveOutputStream tarArchiveOutputStream,
FileFilter filter)
Writes path as a new TarArchiveEntry to tarArchiveOutputStream. |
static void |
extract(File tarFile,
File directoryExtraction,
boolean overwrite)
Extracts the contents of tarFile to directoryExtraction. |
static org.apache.commons.compress.archivers.tar.TarArchiveEntry[] |
getEntries(File tarFile,
boolean sortResult)
Returns all the TarArchiveEntry s inside tarFile. |
static org.apache.commons.compress.archivers.tar.TarArchiveEntry[] |
getEntries(org.apache.commons.compress.archivers.tar.TarArchiveInputStream tarArchiveInputStream,
boolean sortResult)
Returns all the TarArchiveEntry s that can next be read by tarArchiveInputStream. |
private static InputStream |
getInputStream(File tarFile)
If tarFile's extension is simply tar, then returns a new FileInputStream. |
private static OutputStream |
getOutputStream(File tarFile)
If tarFile's extension is simply tar, then returns a new FileOutputStream. |
static boolean |
isTarable(File path)
If path is a directory, then returns true. |
static void |
main(String[] args)
May be used either to archive to or extract from a TAR file. |
private static void |
readInFile(File path,
OutputStream out)
Reads all the bytes from path and writes them to out. |
private static void |
writeOutFile(org.apache.commons.compress.archivers.tar.TarArchiveInputStream tarArchiveInputStream,
File path)
Writes all the bytes from tarArchiveInputStream's current TarArchiveEntry to path. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
private static final String tarFile_key
private static final String pathsToArchive_key
private static final String appendBackup_key
private static final String appendTimeStamp_key
private static final String appendExtension_key
private static final String appendAll_key
private static final String filter_key
private static final String directoryExtraction_key
private static final String overwrite_key
private static final List<String> keysLegal_archive
main
for an archive.
private static final List<String> keysLegal_extract
main
for an extract.
private static final long tarableFileSizeLimit
For historical reasons numerical values are encoded in octal with leading zeroes. The final character is either a null or a space. Thus although there are 12 bytes reserved for storing the file size, only 11 octal digits can be stored. This gives a maximum file size of 8 gigabytes on archived files. To overcome this limitation some versions of tar, including the GNU implementation, support an extension in which the file size is encoded in binary.
Tar (file format)
private static final boolean giveUserFeedback
Constructor Detail |
---|
private TarUtil()
Method Detail |
---|
public static void main(String[] args)
If archiving,
the source path(s) to be archived (which can be either normal files or directories)
are specified as the (key/value) command line switch -pathsToArchive commaSeparatedListOfPaths
.
The target TAR archive file is the (key/value) command line switch -tarFile insertPathHere
.
The following optional switches may also be supplied:
-appendBackup
appends _backup
to the TAR file's name-appendTimeStamp
appends _
followed by a timestamp to the TAR file's name-appendExtension
appends .tar
to the TAR file's name-appendAll
is equivalent to supplying all the above append options-filter fullyQualifiedClassName
specifies the name of a FileFilter which limits what gets archived.
Since this FileFilter class will be instantiated by a call to Class.forName,
it must have a no-arg constructor.
java bb.io.TarUtil -tarFile ../log/test.tar -pathsToArchive ../class1,../class2 -filter bb.io.filefilter.ClassFilter
If extracting,
the target directory to extract into is always specified as the command line switch -directoryExtraction insertPathHere
.
The source TAR archive file is the same -tarFile
command line switch mentioned before.
An optional switch -overwrite true/false
may also be supplied
to control if overwriting of existing normal files is allowed or not.
By default overwriting is not allowed (an Exception will be thrown if extraction needs to overwrite an existing file).
For example, here is a complete command line that extracts a TAR file to a specific directory, overwriting any existing files:
java bb.io.TarUtil -tarFile ../log/test.tar -directoryExtraction ../log/tarExtractOutput -overwrite true
Optional GZIP compression/decompression may also be done when archiving/extracting a TAR file.
Normally, the value for the -tarFile
switch must be a path
which ends in a ".tar" (case insensitive) extension.
However, this program will also accept either ".tar.gz" or ".tgz" extensions,
in which case it will automatically perform GZIP compression/decompression on the TAR file.
Note that the switches may appear in any order on the command line.
If this method is this Java process's entry point (i.e. first main
method),
then its final action is a call to System.exit
, which means that this method never returns;
its exit code is 0 if it executes normally, 1 if it throws a Throwable (which will be caught and logged).
Otherwise, this method returns and leaves the JVM running.
public static boolean isTarable(File path) throws IllegalArgumentException, SecurityException
tarableFileSizeLimit
, false otherwise.
Else returns false.
IllegalArgumentException
- if path == null or path does not exist
SecurityException
- if a security manager exists and its SecurityManager.checkRead method denies read access to pathpublic static void archive(File tarFile, FileFilter filter, File... pathsToArchive) throws Exception
Altho this method does not use DirUtil.getTree
,
it uses filter to control subdirectory exploration in a similar manner.
In general, the path stored in the archive
is the path relative to the parent of the relevant element of pathsToArchive.
For example, suppose that some element of pathsToArchive corresponds to D:/someDirectory
,
and suppose that that directory contains the subdirectory and child file D:/someDirectory/anotherDirectory/childFile
.
Then the paths stored in the archive are anotherDirectory
and anotherDirectory/childFile
respectively.
One complication with the above scheme is paths which are file system roots: they have no parents.
Examples include the windows path C:
or the unix path /
.
In cases like these, this method uses an imaginary parent name of the form rootXXX
(where XXX is an integer).
For example, on a windows machine, if pathsToArchive contains the paths C:
and D:
,
then the contents of C:
might be stored in the archive
with a path that starts with root1
, and the contents of D:
may have an archive path that starts with root2
.
This behavior ensures that the archive preserves the separate origins of the 2 sources,
which is necessary so that they do not get mixed when extracted.
The TAR archive witten by this method will use GNU TAR rules for the entry headers if long path names are encountered. This means that standard POSIX compliant programs that do not support the GNU TAR extension will be unable to extract the contents.
Optional GZIP compression may also be done. Normally, tarFile must be a path which ends in a ".tar" (case insensitive) extension. However, this method will also accept either ".tar.gz" or ".tgz" extensions, in which case it will perform GZIP compression on tarFile as part of archiving.
tarFile
- the TAR File that will write the archive data tofilter
- a FileFilter that can use to screen out paths from being written to the archive;
may be null, which means everything inside pathsToArchive gets archived;
if not null, see warnings in DirUtil.getTree
on directory acceptancepathsToArchive
- array of all the paths to archive
Exception
- if any Throwable is caught; the Throwable is stored as the cause, and the message stores the path of tarFile;
here are some of the possible causes:
isTarable
private static OutputStream getOutputStream(File tarFile) throws IllegalArgumentException, IOException
Note: the result is never buffered, since the TarArchiveOutputStream which will use the result always has an internal buffer.
IllegalArgumentException
- if tarFile has an unrecognized extension
IOException
- if an I/O problem occursprivate static void archive(File path, FileParent fileParent, org.apache.commons.compress.archivers.tar.TarArchiveOutputStream tarArchiveOutputStream, FileFilter filter) throws Exception
If path is a directory, then this method additionally calls itself on the contents (thus recursing thru the entire directory tree).
Warning: several popular programs (e.g. winzip) fail to display mere directory entries. Furthermore, if just a directory entry is present (i.e. it is empty), they also may fail to create a new empty directoy when extracting the TAR file's contents. These are bugs in their behavior.
An optional FileFilter can be supplied to screen out paths that would otherwise be archived.
This method does not close tarArchiveOutputStream: that is the responsibility of the caller.
The caller also must take on the responsibility to not do anything stupid, like write path more than once, or have the path be the same File that tarArchiveOutputStream is writing to.
path
- the File to archivefileParent
- the FileParent for pathtarArchiveOutputStream
- the TarArchiveOutputStream that will write the archive data tofilter
- a FileFilter that can use to screen out certain files from being written to the archive; may be null (so everything specified by path gets archived)
Exception
- if any Throwable is caught; the Throwable is stored as the cause, and the message stores path's information;
here are some of the possible causes:
isTarable
private static void readInFile(File path, OutputStream out) throws IOException
IOException
- if an I/O problem occurspublic static org.apache.commons.compress.archivers.tar.TarArchiveEntry[] getEntries(File tarFile, boolean sortResult) throws IllegalArgumentException, IOException
TarArchiveEntry
s inside tarFile.
tarFile
- the TAR format file to be readsortResult
- if true, then the result is first sorted by each entry's name before return;
otherwise the order is the sequence read from tarFile
IllegalArgumentException
- if tarFile fails Check.validFile
IOException
- if an I/O problem occurspublic static org.apache.commons.compress.archivers.tar.TarArchiveEntry[] getEntries(org.apache.commons.compress.archivers.tar.TarArchiveInputStream tarArchiveInputStream, boolean sortResult) throws IllegalArgumentException, IOException
TarArchiveEntry
s that can next be read by tarArchiveInputStream.
Nothing should have been previously read from tarArchiveInputStream if the full result is desired. Nothing more can be read from tarArchiveInputStream when this method returns, since the final action will be to close tarArchiveInputStream.
tarArchiveInputStream
- the TarArchiveInputStream to get the entries fromsortResult
- if true, then the result is first sorted by each entry's name before return;
otherwise the order is the sequence read from tarArchiveInputStream
IllegalArgumentException
- if tarArchiveInputStream == null
IOException
- if an I/O problem occurspublic static void extract(File tarFile, File directoryExtraction, boolean overwrite) throws IllegalArgumentException, SecurityException, IllegalStateException, IOException
It is an error if tarFile does not exist, is not a normal file, or is not in the proper TAR format. In contrast, directoryExtraction need not exist, since it (and any parent directories) will be created if necessary.
Optional GZIP decompression may also be done. Normally, tarFile must be a path which ends in a ".tar" (case insensitive) extension. However, this method will also accept either ".tar.gz" or ".tgz" extensions, in which case it will perform GZIP decompression on tarFile as part of extracting.
tarFile
- the TAR archive filedirectoryExtraction
- the directory that will extract the contents of tarFile intooverwrite
- specifies whether or not extraction is allowed to overwrite an existing normal file inside directoryExtraction
IllegalArgumentException
- if tarFile is not valid
;
if directoryExtraction fails DirUtil.ensureExists
;
tarFile has an invalid extension
SecurityException
- if a security manager exists and its SecurityManager.checkRead method
denies read access to tarFile or directoryExtraction
IllegalStateException
- if directoryExtraction failed to be created or is not an actual directory but is some other type of file
IOException
- if an I/O problem occursprivate static InputStream getInputStream(File tarFile) throws IllegalArgumentException, IOException
Note: the result is never buffered, since the TarArchiveInputStream which will use the result always has an internal buffer.
IllegalArgumentException
- if tarFile has an unrecognized extension
IOException
- if an I/O problem occursprivate static void writeOutFile(org.apache.commons.compress.archivers.tar.TarArchiveInputStream tarArchiveInputStream, File path) throws IOException
IOException
- if an I/O problem occurs
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |