org.clapper.util.io

Class Zipper

java.lang.Object

org.clapper.util.io.Zipper

public class Zipper
extends java.lang.Object

The Zipper class provides a convenient mechanism for writing zip and jar files; it's a simplifying layer that sits on top of the existing Zip and Jar classes provided by the JDK. A Zipper object behaves like a container into which a caller can drop File objects, InputStream objects, Writer objects, URLs and pathnames. The objects that are dropped into a Zipper container are written to the actual underlying zip or jar file at the moment they're added to the Zipper container.

A Zipper object will write directories as well as files, and it'll either preserve pathnames or flatten the paths down to single components. When preserving pathnames, a Zipper object converts absolute paths to relative paths by stripping any leading "file system mount points." On Unix, this means stripping the leading "/"; on Windows, it means stripping any leading drive letter and the leading "\". (See java.io.File.listRoots() for more information.)

A Zipper object will write a jar file if the associated file name ends in ".jar"; otherwise, it'll write a Zip file.

Note: The Zipper class currently provides no support for storing uncompressed (i.e., fully inflated) entries. All data stored in the underlying zip or jar file is compressed, even though the JDK-supplied zip and Jar classes support both compressed and uncompressed entries. If necessary, the Zipper class can be extended to support storing uncompressed data.

Example

The following code fragment adds three files and the contents of a URL to a zip file.

 try
 {
     URL    url = new URL ("http://www.fulltilt.com/index.htm");
     File   f1  = new File ("fred.java");
     String f2  = "c:\temp\foobar.exe";

     // create with "flatten" disabled, so we're preserving paths
     Zipper zipper = new Zipper ("c:\temp\myfile.zip", false);
     zipper.put (url, "msds.pdf");
     zipper.put (f1);
     zipper.put (f2);
     zipper.close();
 }

 catch (Exception ex)
 {
     ex.printStackTrace();
     System.exit (1);
 }
 

Assuming the above code fragment runs without I/O errors, it'll produce file C:\TEMP\MYFILE.ZIP containing the following entries, in order:

 index.htm
 fred.java
 temp/foobar.exe
 

Constructor Summary

Constructors

Constructor and Description
Zipper(java.io.File file, boolean flatten) Create a new Zipper object that will write the specified zip or jar file.
Zipper(java.io.File file, java.util.jar.Manifest manifest, boolean flatten) Create a new Zipper object that will write the specified zip or jar file.
Zipper(java.lang.String path, boolean flatten) Create a new Zipper object that will write the specified zip or jar file.
Zipper(java.lang.String path, java.util.jar.Manifest manifest, boolean flatten) Create a new Zipper object that will write the specified zip or jar file.

Method Summary

Modifier and Type	Method and Description
void	close() Close the Zipper object, flushing any changes to and closing the underlying zip or jar file.
boolean	containsEntry(java.lang.String name) Determine whether an entry with the specified name has been written to the zip file.
protected void	finalize() Destroys the object, closing the underlying zip or jar file, if it's open.
java.io.File	getFile() Get the File object that describes the underlying Jar or zip file to which this Zipper object is writing.
int	getTotalEntries() Get the total number of entries written to the zip or jar file so far.
void	put(byte[] bytes, java.lang.String name) Put an array of bytes to the zip or jar file.
void	put(java.io.File file) Put a File object to the zip or jar file.
void	put(java.io.File file, java.lang.String name) Put a File object to the zip or jar file, but using a specified Zip entry name, rather than the name of the file itself.
void	put(java.io.InputStream istream, java.lang.String name) Put an InputStream object to the zip or jar file.
void	put(java.lang.String path) Put a named file to the zip or jar file.
void	put(java.net.URL url, java.lang.String name) Open a URL, read its contents, and store the contents in the underlying zip or jar file.
void	writeDirectory(java.io.File file) Write a directory to the underlying Jar or zip file.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Zipper

public Zipper(java.lang.String path,
              boolean flatten)
       throws java.io.IOException

Create a new Zipper object that will write the specified zip or jar file.

Parameters:

path - The pathname of the zip or jar file to write. If the file already exists, it'll be overwritten.

flatten - If true, path names are flattened (i.e., all but the base file names are removed) in the Zip or jar file; otherwise, paths are left intact (after removal of any leading "/" character).

Throws:

java.io.IOException - The specified file is a directory or isn't writable

See Also:

Zipper(String,Manifest,boolean), Zipper(File,boolean), Zipper(File,Manifest,boolean)

Zipper

public Zipper(java.lang.String path,
              java.util.jar.Manifest manifest,
              boolean flatten)
       throws java.io.IOException

Create a new Zipper object that will write the specified zip or jar file.

Parameters:

path - The pathname of the zip or jar file to write. If the file already exists, it'll be overwritten.

manifest - Optional Manifest to associate with the Jar file. Ignored if file doesn't specify a Jar file. May be null.

flatten - If true, path names are flattened (i.e., all but the base file names are removed) in the Zip or jar file; otherwise, paths are left intact (after removal of any leading "/" character).

Throws:

java.io.IOException - The specified file is a directory or isn't writable

See Also:

Zipper(String,boolean), Zipper(File,boolean), Zipper(File,Manifest,boolean)

Zipper

public Zipper(java.io.File file,
              boolean flatten)
       throws java.io.IOException

Create a new Zipper object that will write the specified zip or jar file. The Zipper object is created in unbuffered mode.

Parameters:

file - The File object that specifies the zip or Jar file to write. If the file already exists, it'll be overwritten.

flatten - If true, path names are flattened (i.e., all but the base file names are removed) in the Zip or jar file; otherwise, paths are left intact (after removal of any leading "/" character).

Throws:

java.io.IOException - The specified file is a directory or isn't writable

See Also:

Zipper(String,boolean), Zipper(String,Manifest,boolean), Zipper(File,Manifest,boolean)

Zipper

public Zipper(java.io.File file,
              java.util.jar.Manifest manifest,
              boolean flatten)
       throws java.io.IOException

Create a new Zipper object that will write the specified zip or jar file.

Parameters:

file - The File object that specifies the zip or Jar file to write. If the file already exists, it'll be overwritten.

manifest - Optional Manifest to associate with the Jar file. Ignored if file doesn't specify a Jar file. May be null.

flatten - If true, path names are flattened (i.e., all but the base file names are removed) in the Zip or jar file; otherwise, paths are left intact (after removal of any leading "/" character).

Throws:

java.io.IOException - The specified file is a directory or isn't writable

See Also:

Zipper(String,boolean), Zipper(String,Manifest,boolean), Zipper(File,boolean)

Method Detail

finalize

protected void finalize()

Destroys the object, closing the underlying zip or jar file, if it's open.

Overrides:

finalize in class java.lang.Object

close

public void close()
           throws java.io.IOException

Close the Zipper object, flushing any changes to and closing the underlying zip or jar file.

Throws:

java.io.IOException - error closing Zip/jar file

containsEntry

public boolean containsEntry(java.lang.String name)

Determine whether an entry with the specified name has been written to the zip file. The name will be flattened if this object was created with flattening enabled.

Parameters:

name - The name to check

Returns:

true if that name was written to the zip file; false otherwise

getFile

public java.io.File getFile()

Get the File object that describes the underlying Jar or zip file to which this Zipper object is writing. It is legal to call this method even after the Zipper has been closed.

Returns:

the underlying zip or jar file

getTotalEntries

public int getTotalEntries()

Get the total number of entries written to the zip or jar file so far. It's legal to call this method even after the Zipper object has been closed.

Returns:

the total number of entries written to this object

See Also:

put(File), put(String), put(InputStream,String), close()

put

public void put(java.io.File file)
         throws java.io.IOException

Put a File object to the zip or jar file. The file's contents will be placed in the zip or jar file immediately following the last item that was written.

Parameters:

file - The File to be added to the zip or jar file. The specified file can be a file or a directory.

Throws:

java.io.IOException - The specified file doesn't exist or isn't readable.

See Also:

put(File,String), put(String), put(InputStream,String)

put

public void put(java.io.File file,
                java.lang.String name)
         throws java.io.IOException

Put a File object to the zip or jar file, but using a specified Zip entry name, rather than the name of the file itself. The file's contents will be placed in the zip or jar file immediately following the last item that was written.

Parameters:

file - The File to be added to the zip or jar file. The specified file can be a file or a directory.

name - The name to use for the Zip entry

Throws:

java.io.IOException - The specified file doesn't exist or isn't readable.

See Also:

put(File), put(String), put(InputStream,String)

put

public void put(java.lang.String path)
         throws java.io.IOException

Put a named file to the zip or jar file. The file's contents will be placed in the zip or jar file immediately following the last item that was written.

Parameters:

path - The path to the file to be added to the zip or jar file. The specified file can be a file or a directory.

Throws:

java.io.IOException - The specified file doesn't exist or isn't readable.

See Also:

put(File,String), put(File), put(InputStream,String)

put

public void put(java.io.InputStream istream,
                java.lang.String name)
         throws java.io.IOException

Put an InputStream object to the zip or jar file. The InputStream will be read until EOF, and the stream of bytes will be placed in the zip or jar file immediately following the last item that was written.

Parameters:

istream - The InputStream to be added to the zip or jar file.

name - The name to give the entry in the zip or jar file.

Throws:

java.io.IOException - The specified file doesn't exist or isn't readable.

See Also:

put(File,String), put(File), put(String)

put

public void put(byte[] bytes,
                java.lang.String name)
         throws java.io.IOException

Put an array of bytes to the zip or jar file. The stream of bytes will be placed in the zip or jar file immediately following the last item that was written.

Parameters:

bytes - The bytes to be added to the zip or jar file.

name - The name to give the entry in the zip or jar file.

Throws:

java.io.IOException - The specified file doesn't exist or isn't readable.

See Also:

put(File,String), put(File), put(String)

put

public void put(java.net.URL url,
                java.lang.String name)
         throws java.io.IOException

Open a URL, read its contents, and store the contents in the underlying zip or jar file. The URL's contents will be placed in the zip or jar file immediately following the last item that was written.

Parameters:

url - The URL to be downloaded and stored in the zip or jar file

name - The name to give the entry in the zip or jar file

Throws:

java.io.IOException - failed to open or read URL

writeDirectory

public void writeDirectory(java.io.File file)
                    throws java.io.IOException

Write a directory to the underlying Jar or zip file.

Parameters:

file - The File representing the directory to write

Throws:

java.io.IOException - on I/O error