public class TarBuilder extends AbstractStreamAddCapableArchiveBuilder<TarBuilder,TarEntrySettings>
ArchiveBuilder
for
building Tar files. Files and directories are written to the archive as they
are added using any of this object's add
methods.
The Tar file format is fairly simple, but it has evolved a bit since it was
introduced. By default, this object creates Tar file compatible with the Gnu
Tar implementation. By setting another TarEntryStrategy
, the archive
can be made to have a different format. The following strategy
implementations exist:
V7TarEntryStrategy
– creates a Tar file using the old Unix
v7 Tar format. File names (including their paths) are limited to a maximum
length of 99 characters.UstarEntryStrategy
– creates a Tar file using the POSIX
1003.1-1988 (ustar) format. File names (including their paths) are limited to
a theoretical maximum length of 255 characters. Depending on where there is a
slash in the file name, the actual maximum length is often shorter. The
shortest maximum length is 99 characters. Ustar entries have the entity owner
user and group names in text as well as their numerical values.GnuTarEntryStrategy
– (the default) creates a Tar file
using the same file format as the Gnu Tar (1.20) implementation. This
implementation extends the ustar format with support for file names of an
unlimited length. This implementation does not support all Gnu Tar features,
such as sparse files and archive labels.PaxTarEntryStrategy
&nsash; creates a Tar file using the POSIX
1003.1-2001 (pax) format. This extends the ustar format with support for file
names of an unlimited length and with support for metadata variables.
This object uses the strategy described in
ArchiveBuilder
to determine the effective
TarEntrySettings
for an entry added to the archive.
This implementation does not support adding symbolic links to the archive.
If it is in a locking FileSystem
, the target file is
locked for writing until the Tar builder is close()
:d.
This object is not safe to use concurrently from several threads without external synchronization.
TarStreamBuilder
,
TarFile
Constructor and Description |
---|
TarBuilder(org.entityfs.RandomAccess target,
TarBuilderSettings settings)
Create a new Tar archive builder on an already open
RandomAccess object. |
TarBuilder(org.entityfs.RandomlyAccessibleFile target)
Create a Tar builder using the default settings.
|
TarBuilder(org.entityfs.RandomlyAccessibleFile target,
TarBuilderSettings settings)
Create a Tar builder using the supplied settings.
|
Modifier and Type | Method and Description |
---|---|
protected void |
addDirectoryCallback(org.entityfs.el.AbsoluteLocation location,
Object d,
TarEntrySettings effectiveSettings,
Date lastModified)
This callback method is implemented by subclasses to add a directory
entry to the archive.
|
protected void |
addFileCallback(org.entityfs.el.AbsoluteLocation location,
org.entityfs.ReadableFile f,
TarEntrySettings effectiveSettings,
Date lastModified)
This callback method is implemented by subclasses to add a file entry to
the archive.
|
protected void |
addStreamCallback(org.entityfs.el.AbsoluteLocation location,
InputStream is,
TarEntrySettings effectiveSettings,
Date lastModified)
This callback method is implemented by subclasses to add a file entry
containing data read from a stream to the archive.
|
protected void |
assertNotClosed()
Subclasses implement this method to throw an
IllegalStateException if it is called after the archive builder
has been closed. |
void |
close()
This method finishes writing the Tar file and closes it.
|
protected void |
finalize() |
protected TarEntrySettings |
getDefaultDefaultDirectoryEntrySettings()
Subclasses implement this method to return a default settings object for
directory entries if the client does not specify one when creating the
archive builder object.
|
protected TarEntrySettings |
getDefaultDefaultFileEntrySettings()
Subclasses implement this method to return a default settings object for
file entries if the client does not specify one when creating the archive
builder object.
|
boolean |
isClosed()
Is this archive builder closed?
|
add, add
add, add, add, add, add, add, add, add, add, addRecursively, addRecursively, addRecursively, addRecursively, addRecursively, addRule, addRules, getDefaultDirectoryEntrySettings, getDefaultFileEntrySettings, getEffectiveSettingsForDirectory, getEffectiveSettingsForDirectory, getEffectiveSettingsForFile, getEffectiveSettingsForFile, getRules, getThis, removeRule, setDefaultDirectoryEntrySettings, setDefaultFileEntrySettings
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
add, add, add, add, add, add, add, add, add, addRecursively, addRecursively, addRecursively, addRecursively, addRecursively, addRule, addRules, getDefaultDirectoryEntrySettings, getDefaultFileEntrySettings, getRules, removeRule, setDefaultDirectoryEntrySettings, setDefaultFileEntrySettings
public TarBuilder(org.entityfs.RandomlyAccessibleFile target) throws org.entityfs.support.exception.WrappedIOException
TarBuilderSettings
.)target
- The file to write the archive to. The previous contents of
this file is discarded. If this method completes successfully, the target
file is locked for writing until close()
is called.org.entityfs.support.exception.WrappedIOException
- On I/O errors.TarBuilder(RandomlyAccessibleFile, TarBuilderSettings)
,
TarBuilder(RandomAccess, TarBuilderSettings)
public TarBuilder(org.entityfs.RandomlyAccessibleFile target, TarBuilderSettings settings) throws org.entityfs.support.exception.WrappedIOException
target
- The file to write the archive to. The previous contents of
this file is discarded. If this method completes successfully, the target
file is locked for writing until close()
is called.settings
- The settings for the builder. Set this to null
to
use the default settings.org.entityfs.support.exception.WrappedIOException
- On I/O errors.TarBuilder(RandomlyAccessibleFile)
,
TarBuilder(RandomAccess, TarBuilderSettings)
public TarBuilder(org.entityfs.RandomAccess target, TarBuilderSettings settings) throws org.entityfs.support.exception.WrappedIOException
RandomAccess
object. It will use the supplied
settings object.target
- The RandomAccess
to write data to. This object is
not closed when close()
is called. The Tar builder
assumes that it has exclusive access to this RandomAccess
.settings
- The settings for the builder. Set this to null
to
use the default settings.org.entityfs.support.exception.WrappedIOException
- On I/O errors.TarBuilder(RandomlyAccessibleFile, TarBuilderSettings)
protected TarEntrySettings getDefaultDefaultDirectoryEntrySettings()
AbstractArchiveBuilder
getDefaultDefaultDirectoryEntrySettings
in class AbstractArchiveBuilder<TarBuilder,TarEntrySettings>
protected TarEntrySettings getDefaultDefaultFileEntrySettings()
AbstractArchiveBuilder
getDefaultDefaultFileEntrySettings
in class AbstractArchiveBuilder<TarBuilder,TarEntrySettings>
protected void assertNotClosed() throws IllegalStateException
AbstractArchiveBuilder
IllegalStateException
if it is called after the archive builder
has been closed.assertNotClosed
in class AbstractArchiveBuilder<TarBuilder,TarEntrySettings>
IllegalStateException
- If the archive builder has been closed.protected void addDirectoryCallback(org.entityfs.el.AbsoluteLocation location, Object d, TarEntrySettings effectiveSettings, Date lastModified) throws org.entityfs.support.exception.WrappedIOException, ArchiveEntryAddException
AbstractArchiveBuilder
Note: If this method throws an exception, it is the method's responsibility to make sure that the archive file is left in a consistent state. This should probably always mean that the failed entry is truncated from the archive file and that the current archive file pointer is restored to where it was before the method was called.
addDirectoryCallback
in class AbstractArchiveBuilder<TarBuilder,TarEntrySettings>
location
- The location of the entry in the archive.d
- The directory. This may be a DirectoryView
or a File
.effectiveSettings
- The effective settings for the entry.lastModified
- The time when the directory was last modified.org.entityfs.support.exception.WrappedIOException
- On I/O errors.ArchiveEntryAddException
- If the entry could not be added to the
archive for some other reason than an I/O error.protected void addFileCallback(org.entityfs.el.AbsoluteLocation location, org.entityfs.ReadableFile f, TarEntrySettings effectiveSettings, Date lastModified) throws org.entityfs.support.exception.WrappedIOException, ArchiveEntryAddException
AbstractArchiveBuilder
Note: If this method throws an exception, it is the method's responsibility to make sure that the archive file is left in a consistent state. This should probably always mean that the failed entry is truncated from the archive file and that the current archive file pointer is restored to where it was before the method was called.
addFileCallback
in class AbstractArchiveBuilder<TarBuilder,TarEntrySettings>
location
- The location of the entry in the archive.f
- The file.effectiveSettings
- The effective settings for the entry.lastModified
- The time when the file was last modified.org.entityfs.support.exception.WrappedIOException
- On I/O errors.ArchiveEntryAddException
- If the entry could not be added to the
archive for some other reason than an I/O error.protected void addStreamCallback(org.entityfs.el.AbsoluteLocation location, InputStream is, TarEntrySettings effectiveSettings, Date lastModified) throws org.entityfs.support.exception.WrappedIOException, ArchiveEntryAddException
AbstractStreamAddCapableArchiveBuilder
Note: If this method throws an exception, it is the method's responsibility to make sure that the archive file is left in a consistent state. This should probably always mean that the failed entry is truncated from the archive file and that the current archive file pointer is restored to where it was before the method was called.
addStreamCallback
in class AbstractStreamAddCapableArchiveBuilder<TarBuilder,TarEntrySettings>
location
- The location of the entry in the archive.is
- The stream to read file data from. The method should read up to
the end of the stream, but not close the stream.effectiveSettings
- The effective settings for the entry.lastModified
- The time when the file was last modified.org.entityfs.support.exception.WrappedIOException
- On I/O errors.ArchiveEntryAddException
- If the entry could not be added to the
archive for some other reason than an I/O error.public boolean isClosed()
ArchiveBuilder
true
if this archive builder is closed.public void close() throws org.entityfs.support.exception.WrappedIOException
FileSystem
.org.entityfs.support.exception.WrappedIOException
- On I/O errors.