org.at4j.tar.builder
Class TarBuilder

java.lang.Object
  extended by org.at4j.archive.builder.AbstractArchiveBuilder<U,V>
      extended by org.at4j.archive.builder.AbstractStreamAddCapableArchiveBuilder<TarBuilder,TarEntrySettings>
          extended by org.at4j.tar.builder.TarBuilder
All Implemented Interfaces:
ArchiveBuilder<TarBuilder,TarEntrySettings>, StreamAddCapableArchiveBuilder<TarBuilder,TarEntrySettings>

public class TarBuilder
extends AbstractStreamAddCapableArchiveBuilder<TarBuilder,TarEntrySettings>

The Tar builder is an 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:

All file formats are somewhat compatible with each other. If a tar implementation does not understand a specific feature, it treats it as a regular file. This may result in files with strange names appearing after unpacking an archive.

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.

Since:
1.0
Author:
Karl Gustafsson
See Also:
TarStreamBuilder, TarFile

Constructor Summary
TarBuilder(RandomAccess target, TarBuilderSettings settings)
          Create a new Tar archive builder on an already open RandomAccess object.
TarBuilder(RandomlyAccessibleFile target)
          Create a Tar builder using the default settings.
TarBuilder(RandomlyAccessibleFile target, TarBuilderSettings settings)
          Create a Tar builder using the supplied settings.
 
Method Summary
protected  void addDirectoryCallback(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(AbsoluteLocation location, ReadableFile f, TarEntrySettings effectiveSettings, Date lastModified)
          This callback method is implemented by subclasses to add a file entry to the archive.
protected  void addStreamCallback(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?
 
Methods inherited from class org.at4j.archive.builder.AbstractStreamAddCapableArchiveBuilder
add, add
 
Methods inherited from class org.at4j.archive.builder.AbstractArchiveBuilder
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
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.at4j.archive.builder.ArchiveBuilder
add, add, add, add, add, add, add, add, add, addRecursively, addRecursively, addRecursively, addRecursively, addRecursively, addRule, addRules, getDefaultDirectoryEntrySettings, getDefaultFileEntrySettings, getRules, removeRule, setDefaultDirectoryEntrySettings, setDefaultFileEntrySettings
 

Constructor Detail

TarBuilder

public TarBuilder(RandomlyAccessibleFile target)
           throws WrappedIOException
Create a Tar builder using the default settings. (See TarBuilderSettings.)

Parameters:
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.
Throws:
WrappedIOException - On I/O errors.
See Also:
TarBuilder(RandomlyAccessibleFile, TarBuilderSettings), TarBuilder(RandomAccess, TarBuilderSettings)

TarBuilder

public TarBuilder(RandomlyAccessibleFile target,
                  TarBuilderSettings settings)
           throws WrappedIOException
Create a Tar builder using the supplied settings.

Parameters:
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.
Throws:
WrappedIOException - On I/O errors.
See Also:
TarBuilder(RandomlyAccessibleFile), TarBuilder(RandomAccess, TarBuilderSettings)

TarBuilder

public TarBuilder(RandomAccess target,
                  TarBuilderSettings settings)
           throws WrappedIOException
Create a new Tar archive builder on an already open RandomAccess object. It will use the supplied settings object.

Parameters:
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.
Throws:
WrappedIOException - On I/O errors.
See Also:
TarBuilder(RandomlyAccessibleFile, TarBuilderSettings)
Method Detail

getDefaultDefaultDirectoryEntrySettings

protected TarEntrySettings getDefaultDefaultDirectoryEntrySettings()
Description copied from class: AbstractArchiveBuilder
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.

Specified by:
getDefaultDefaultDirectoryEntrySettings in class AbstractArchiveBuilder<TarBuilder,TarEntrySettings>
Returns:
The default settings object for directory entries if none is specified by the client.

getDefaultDefaultFileEntrySettings

protected TarEntrySettings getDefaultDefaultFileEntrySettings()
Description copied from class: AbstractArchiveBuilder
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.

Specified by:
getDefaultDefaultFileEntrySettings in class AbstractArchiveBuilder<TarBuilder,TarEntrySettings>
Returns:
The default settings object for file entries if none is specified by the client.

assertNotClosed

protected void assertNotClosed()
                        throws IllegalStateException
Description copied from class: AbstractArchiveBuilder
Subclasses implement this method to throw an IllegalStateException if it is called after the archive builder has been closed.

Specified by:
assertNotClosed in class AbstractArchiveBuilder<TarBuilder,TarEntrySettings>
Throws:
IllegalStateException - If the archive builder has been closed.

addDirectoryCallback

protected void addDirectoryCallback(AbsoluteLocation location,
                                    Object d,
                                    TarEntrySettings effectiveSettings,
                                    Date lastModified)
                             throws WrappedIOException,
                                    ArchiveEntryAddException
Description copied from class: AbstractArchiveBuilder
This callback method is implemented by subclasses to add a directory entry to the archive. The entry is added at the end of the archive file.

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.

Specified by:
addDirectoryCallback in class AbstractArchiveBuilder<TarBuilder,TarEntrySettings>
Parameters:
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.
Throws:
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.

addFileCallback

protected void addFileCallback(AbsoluteLocation location,
                               ReadableFile f,
                               TarEntrySettings effectiveSettings,
                               Date lastModified)
                        throws WrappedIOException,
                               ArchiveEntryAddException
Description copied from class: AbstractArchiveBuilder
This callback method is implemented by subclasses to add a file entry to the archive. The entry is added at the end of the archive file.

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.

Specified by:
addFileCallback in class AbstractArchiveBuilder<TarBuilder,TarEntrySettings>
Parameters:
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.
Throws:
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.

addStreamCallback

protected void addStreamCallback(AbsoluteLocation location,
                                 InputStream is,
                                 TarEntrySettings effectiveSettings,
                                 Date lastModified)
                          throws WrappedIOException,
                                 ArchiveEntryAddException
Description copied from class: AbstractStreamAddCapableArchiveBuilder
This callback method is implemented by subclasses to add a file entry containing data read from a stream to the archive. The entry is added at the end of the archive file.

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.

Specified by:
addStreamCallback in class AbstractStreamAddCapableArchiveBuilder<TarBuilder,TarEntrySettings>
Parameters:
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.
Throws:
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.

isClosed

public boolean isClosed()
Description copied from interface: ArchiveBuilder
Is this archive builder closed?

Returns:
true if this archive builder is closed.

close

public void close()
           throws WrappedIOException
This method finishes writing the Tar file and closes it. It also releases the write lock on the created Tar file, if it is in a locking FileSystem.

Throws:
WrappedIOException - On I/O errors.

finalize

protected void finalize()
                 throws Throwable
Overrides:
finalize in class Object
Throws:
Throwable