org.at4j.zip.builder
Class ZipBuilder

java.lang.Object
  extended by org.at4j.archive.builder.AbstractArchiveBuilder<U,V>
      extended by org.at4j.archive.builder.AbstractStreamAddCapableArchiveBuilder<ZipBuilder,ZipEntrySettings>
          extended by org.at4j.zip.builder.ZipBuilder
All Implemented Interfaces:
ArchiveBuilder<ZipBuilder,ZipEntrySettings>, StreamAddCapableArchiveBuilder<ZipBuilder,ZipEntrySettings>, ZipBuilderConfiguration

public class ZipBuilder
extends AbstractStreamAddCapableArchiveBuilder<ZipBuilder,ZipEntrySettings>
implements ZipBuilderConfiguration

The Zip builder is an ArchiveBuilder for building Zip files. Files and directories are written to the archive as they are added using any of this object's add methods.

The Zip file format gives great flexibility in the kind of metadata that is stored along with the Zip entries. All Zip entries have a set of metadata properties in common, such as the last modification time of the file system entity (file or directory) that was used to create the entry or the internal file attributes ( ZipInternalFileAttributes). In addition to the generic metadata, External file attributes (used for both files and directories) store metadata that is specific for the platform where the Zip archive was created (Windows, Unix, etc). Extra fields can be used to store additional metadata. Files added to the Zip archive may be compressed using one of several compression methods.

The Zip builder uses a ZipExternalFileAttributesFactory to create external file attributes for added files and directories. It uses zero or more ZipEntryExtraFieldFactory:s to create extra fields for entries, and it uses a ZipEntryCompressionMethodFactory to compress file entries. To know which implementation of each factory to use for a given entry, which means to know the effective ZipEntrySettings for an entry, it uses default settings, global rules and entry-specific rules in the way described in the ArchiveBuilder documentation.

The Zip builder uses a InternalFileAttributesStrategy to determine the internal file attributes for each entry. The default strategy, DefaultInternalFileAttributesStrategy, can be exchanged for a custom strategy if necessary.

Global Zip file settings, such as the Zip file comment, are set directly on this object.

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 Zip 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:
ZipFile

Constructor Summary
ZipBuilder(RandomAccess target, ZipBuilderSettings settings)
          Create a Zip builder on an already open RandomAccess object.
ZipBuilder(RandomlyAccessibleFile target)
          Create a new Zip builder that uses the default default entry settings when adding entries, and the platform's default charset to encode entry names and other text data.
ZipBuilder(RandomlyAccessibleFile target, ZipBuilderSettings settings)
          Create a new Zip builder that uses the supplied default file and directory entry settings when adding entries, and the supplied charsets to encode entry names and other text metadata.
 
Method Summary
protected  void addDirectoryCallback(AbsoluteLocation location, Object d, ZipEntrySettings 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, ZipEntrySettings 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, ZipEntrySettings 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()
          This method throws an IllegalStateException if the Zip builder is closed.
protected  void assertReadLocked(ReadLockable o)
          This method throws a ReadLockRequiredException if the supplied object is not locked for reading.
 void close()
          Finish the Zip file and close the Zip builder.
protected  void finalize()
           
protected  ZipEntrySettings getDefaultDefaultDirectoryEntrySettings()
          This method returns the default directory entry settings.
protected  ZipEntrySettings getDefaultDefaultFileEntrySettings()
          This method returns the default file entry settings.
 String getFileComment()
          Get the Zip file comment.
 Charset getFileNameEncodingCharset()
          Get the charset used for encoding file names in the Zip file.
 InternalFileAttributesStrategy getInternalFileAttributesStrategy()
          Get the strategy used for determining a Zip entry's internal file attributes property.
 Charset getTextEncodingCharset()
          Get the charset used for encoding text such as comments in the Zip file.
 boolean isClosed()
          Is this archive builder closed?
 ZipBuilder setInternalFileAttributesStrategy(InternalFileAttributesStrategy strat)
          Set the strategy to use for determining a Zip entry's internal file attributes property.
 
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

ZipBuilder

public ZipBuilder(RandomlyAccessibleFile target)
           throws WrappedIOException
Create a new Zip builder that uses the default default entry settings when adding entries, and the platform's default charset to encode entry names and other text data.

Parameters:
target - The target file. The previous contents of this file is discarded. If it is in a locking FileSystem, the file will be locked for writing by the calling thread until this object is close():d.
Throws:
WrappedIOException - On I/O errors
See Also:
ZipBuilder(RandomlyAccessibleFile, ZipBuilderSettings), ZipBuilder(RandomAccess, ZipBuilderSettings)

ZipBuilder

public ZipBuilder(RandomlyAccessibleFile target,
                  ZipBuilderSettings settings)
           throws WrappedIOException
Create a new Zip builder that uses the supplied default file and directory entry settings when adding entries, and the supplied charsets to encode entry names and other text metadata.

Parameters:
target - The target file. The previous contents of this file is discarded. If it is in a locking FileSystem, the file will be locked for writing by the calling thread until this object is close():d.
settings - The configuration of the Zip builder. Set this to null to use the default configuration.
Throws:
WrappedIOException - On I/O errors
See Also:
ZipBuilder(RandomlyAccessibleFile), ZipBuilder(RandomAccess, ZipBuilderSettings)

ZipBuilder

public ZipBuilder(RandomAccess target,
                  ZipBuilderSettings settings)
           throws WrappedIOException
Create a Zip builder on an already open RandomAccess object. The builder will use the supplied charsets for encoding text and the supplied default entry settings.

Parameters:
target - The target RandomAccess. It is not closed by this object when close() is called. This object assumes that it has exclusive access to the RandomAccess.
settings - The configuration of the Zip builder. Set this to null to use the default configuration.
Throws:
WrappedIOException - On I/O errors
See Also:
ZipBuilder(RandomlyAccessibleFile), ZipBuilder(RandomlyAccessibleFile, ZipBuilderSettings)
Method Detail

setInternalFileAttributesStrategy

public ZipBuilder setInternalFileAttributesStrategy(InternalFileAttributesStrategy strat)
Set the strategy to use for determining a Zip entry's internal file attributes property.

By default, the Zip builder uses an instance of the DefaultInternalFileAttributesStrategy.

Parameters:
strat - The new internal file attributes strategy.
Returns:
this
See Also:
getInternalFileAttributesStrategy()

getInternalFileAttributesStrategy

public InternalFileAttributesStrategy getInternalFileAttributesStrategy()
Get the strategy used for determining a Zip entry's internal file attributes property.

Returns:
The strategy.
See Also:
setInternalFileAttributesStrategy(InternalFileAttributesStrategy)

getDefaultDefaultDirectoryEntrySettings

protected ZipEntrySettings getDefaultDefaultDirectoryEntrySettings()
This method returns the default directory entry settings.

The returned object should not be modified in any way by the caller.

Specified by:
getDefaultDefaultDirectoryEntrySettings in class AbstractArchiveBuilder<ZipBuilder,ZipEntrySettings>
Returns:
The default directory entry settings.

getDefaultDefaultFileEntrySettings

protected ZipEntrySettings getDefaultDefaultFileEntrySettings()
This method returns the default file entry settings.

The returned object should not be modified in any way by the caller.

Specified by:
getDefaultDefaultFileEntrySettings in class AbstractArchiveBuilder<ZipBuilder,ZipEntrySettings>
Returns:
The default file entry settings.

getFileComment

public String getFileComment()
Get the Zip file comment.

Returns:
The Zip file comment. This may be null.

getFileNameEncodingCharset

public Charset getFileNameEncodingCharset()
Get the charset used for encoding file names in the Zip file.

Specified by:
getFileNameEncodingCharset in interface ZipBuilderConfiguration
Returns:
The charset used for encoding file names in the Zip file.
See Also:
getTextEncodingCharset()

getTextEncodingCharset

public Charset getTextEncodingCharset()
Get the charset used for encoding text such as comments in the Zip file.

Specified by:
getTextEncodingCharset in interface ZipBuilderConfiguration
Returns:
The charset used for encoding text in the Zip file.
See Also:
getFileNameEncodingCharset()

assertNotClosed

protected void assertNotClosed()
                        throws IllegalStateException
This method throws an IllegalStateException if the Zip builder is closed.

Specified by:
assertNotClosed in class AbstractArchiveBuilder<ZipBuilder,ZipEntrySettings>
Throws:
IllegalStateException - If the Zip builder is closed.

assertReadLocked

protected void assertReadLocked(ReadLockable o)
                         throws ReadLockRequiredException
This method throws a ReadLockRequiredException if the supplied object is not locked for reading.

Parameters:
o - The object to check for locking.
Throws:
ReadLockRequiredException - If the supplied object is not locked for reading by the calling thread.

addDirectoryCallback

protected void addDirectoryCallback(AbsoluteLocation location,
                                    Object d,
                                    ZipEntrySettings 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<ZipBuilder,ZipEntrySettings>
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,
                               ZipEntrySettings 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<ZipBuilder,ZipEntrySettings>
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,
                                 ZipEntrySettings 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<ZipBuilder,ZipEntrySettings>
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?

Specified by:
isClosed in interface ArchiveBuilder<ZipBuilder,ZipEntrySettings>
Returns:
true if this archive builder is closed.

close

public void close()
           throws WrappedIOException
Finish the Zip file and close the Zip builder.

Specified by:
close in interface ArchiveBuilder<ZipBuilder,ZipEntrySettings>
Throws:
WrappedIOException - On I/O errors.

finalize

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