js.io

Class FilesOutputStream

java.lang.Object

java.io.OutputStream

js.io.FilesOutputStream

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

public class FilesOutputStream
extends OutputStream
implements Closeable

Files archive output stream. This class works together with FilesInputStream to transfer files archives. A files archive is a hierarchical files collections bundled with meta data. Archive is compressed using ZIP lossless data compression and meta is carried by a standard Java JAR Manifest. This class gets and output stream and inject meta data and files, on the fly, see putMeta(String, Object) and addFiles(File) and related.

Common use case is with URL connection and Servlet HTTP request but is not limited to this scenario. Input stream for this class could be a file archive stored on disk, but file content should be generated by files output stream. Both output and input streams are processed on the fly.

 FilesOutputStream outputFiles = new FilesOutputStream(connection.getOutputStream());
 outputFiles.putMeta("Base-Directory", baseDir);
 outputFiles.addFiles(new File("source-directory"));
 outputFiles.close();
 

 FilesInputStream inputFiles = new FilesInputStream(httpRequest.getInputStream());
 File baseDir = inputFiles.getMeta("Base-Directory", File.class);
 for (File file : inputFiles) {
        File targetFile = new File(targetDir, file.getPath());
        files.copy(targetFile);
 }
 inputFiles.close();
 

Manifest is mandatory even if no meta data is present and is always the first entry in archive. There is a single predefined attribute, the implementation version but application level meta data is supported. Files output stream can put arbitrary meta data using putMeta(String, Object). On receive side, this files archive input stream can retrieve application meta data uing FilesInputStream.getMeta(String) and related methods.

Version:

final

Author:

Iulian Rotaru

Field Summary

Fields

Modifier and Type	Field and Description
private static int	BUFFER_SIZE The size of the buffer used for internal bytes processing.
private ZipOutputStream	filesArchive Output stream where meta data and files are to be injected.
private Manifest	manifest This archive manifest.
private static String	VERSION Files archive implementation version.

Constructor Summary

Constructors

Constructor and Description
FilesOutputStream(OutputStream filesArchive) Construct files archive wrapping an output stream where archive bytes are injected.

Method Summary

Modifier and Type	Method and Description
void	addFile(File file) Inject file content into archive using file relative path as archive entry name.
private void	addFileEntry(String entryName, InputStream inputStream) Add file entry to this files archive.
void	addFiles(File baseDir) Add files hierarchy to this archive.
void	addFiles(File baseDir, List<String> fileNames) Add files list to this archive.
private void	addManifestEntry() Add manifest entry to this files output stream.
void	close() Close this files output stream and takes care to write manifest if no files was added.
void	putMeta(String key, Object value) Put meta data to this archive manifest.
void	write(int b) Write byte to files archive.

Methods inherited from class java.io.OutputStream

flush, write, write

Methods inherited from class java.lang.Object

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

Field Detail

VERSION

private static final String VERSION

Files archive implementation version.

See Also:

Constant Field Values

BUFFER_SIZE

private static final int BUFFER_SIZE

The size of the buffer used for internal bytes processing.

See Also:

Constant Field Values

filesArchive

private ZipOutputStream filesArchive

Output stream where meta data and files are to be injected.

manifest

private Manifest manifest

This archive manifest. It has at least archive version attribute and is updated by putMeta(String, Object). Is lazily written to this archive just before injecting first file content.

Constructor Detail

FilesOutputStream

public FilesOutputStream(OutputStream filesArchive)

Construct files archive wrapping an output stream where archive bytes are injected.

Parameters:

filesArchive - output stream to files archive to write to.

Method Detail

write

public void write(int b)
           throws IOException

Write byte to files archive.

Specified by:

write in class OutputStream

Throws:

IOException

putMeta

public void putMeta(String key,
                    Object value)

Put meta data to this archive manifest. If key already exists is overridden. Meta value is converted to string and can be any type for which there is a Converter registered.

Parameters:

key - meta data key,

value - meta data value.

addFiles

public void addFiles(File baseDir)
              throws IOException

Add files hierarchy to this archive. Traverse all baseDir directory files, no matter how deep hierarchy is and delegate addFile(File).

Parameters:

baseDir - files hierarchy base directory.

Throws:

IOException - if archive writing operation fails.

addFiles

public void addFiles(File baseDir,
                     List<String> fileNames)
              throws FileNotFoundException,
                     IOException

Add files list to this archive. Files from list are relative to given base directory. For every file create a new entry into this ZIP archive with file name as entry name. As mentioned file/entry name is relative to base directory and does not start with it. For example, bee it /var/www/ a base directory and an item from files list site/index.htm; resulting entry name is site/index.htm and file content is read from /var/www/site/index.htm.

Parameters:

baseDir - files base directory,

fileNames - file names list.

Throws:

FileNotFoundException - if file not found on baseDir descendants.

IOException - if writing to archive fails.

addFile

public void addFile(File file)
             throws IOException

Inject file content into archive using file relative path as archive entry name. File to add is relative to a common base directory. All files from this archive should be part of that base directory hierarchy; it is user code responsibility to enforce this constrain.

Parameters:

file - file to add to this archive.

Throws:

IllegalArgumentException - if file does not exist or is a directory.

IOException - if archive writing operation fails.

close

public void close()
           throws IOException

Close this files output stream and takes care to write manifest if no files was added. Manifest is written lazily just before first file entry. For empty files stream we still need to send manifest and this method ensure that.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class OutputStream

Throws:

IOException

addManifestEntry

private void addManifestEntry()
                       throws IOException

Add manifest entry to this files output stream. This method reset manifest to null signaling manifest was processed.

Throws:

IOException - if manifest entry write fails.

addFileEntry

private void addFileEntry(String entryName,
                          InputStream inputStream)
                   throws IOException

Add file entry to this files archive. This method takes care to lazily write manifest just before first file entry.

Parameters:

entryName - entry name,

inputStream - file content.

Throws:

IOException - if file entry write fails.