js.io

Class FilesInputStream

java.lang.Object

java.io.InputStream

js.io.FilesInputStream

All Implemented Interfaces:

Closeable, AutoCloseable, Iterable<File>

public class FilesInputStream
extends InputStream
implements Iterable<File>, Closeable

Files archive input stream. This class works together with FilesOutputStream 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 a stream for files archive, created by files output stream, and extract meta data and files hierarchy. It provides an iterator for files from archive and an utility method to copy file to target system, see copy(File).

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 FilesOutputStream.putMeta(String, Object). On receive side, this files archive input stream can retrieve application meta data uing getMeta(String) and related methods.

Version:

final

Author:

Iulian Rotaru

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	FilesInputStream.FilesIterator Iterator over files archive.

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 ZipInputStream	filesArchive Files archive ZIP extractor.
private FilesInputStream.FilesIterator	filesIterator Files archive iterator.
private Manifest	manifest Archive manifest contains a single predefined attribute, namely implementation version.
private static boolean	UNIX_PATH Flag true if file separator is Unix like, that is, forward slash.
private static String	VERSION Implementation version.

Constructor Summary

Constructors

Constructor and Description
FilesInputStream(InputStream filesArchive) Create files input reader for given files archive and extract manifest.
FilesInputStream(ZipInputStream filesArchive) Create files input reader for given files archive and extract manifest.

Method Summary

Modifier and Type	Method and Description
void	close() Close input stream on files archive.
void	copy(File targetFile) Utility method that copy current ZIP entry to output file.
String	getMeta(String key) Get string value from files archive meta data.
<T> T	getMeta(String key, Class<T> type) Get files archive meta data converted to requested type.
<T> T	getMeta(String key, Class<T> type, T defaultValue) Get files archive meta data converted to requested type or default value if meta data key is missing.
String	getMeta(String key, String defaultValue) Get string value from files archive meta data or default value if requested key does not exist.
Iterator<File>	iterator() Get files archive iterator.
int	read() Read next byte from files archive.

Methods inherited from class java.io.InputStream

available, mark, markSupported, read, read, reset, skip

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

VERSION

private static final String VERSION

Implementation version.

See Also:

Constant Field Values

UNIX_PATH

private static final boolean UNIX_PATH

Flag true if file separator is Unix like, that is, forward slash.

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 ZipInputStream filesArchive

Files archive ZIP extractor.

manifest

private Manifest manifest

Archive manifest contains a single predefined attribute, namely implementation version. Application meta data can be retrieved using getMeta(String) and related methods.

filesIterator

private FilesInputStream.FilesIterator filesIterator

Files archive iterator.

Constructor Detail

FilesInputStream

public FilesInputStream(InputStream filesArchive)
                 throws IOException

Create files input reader for given files archive and extract manifest. Files archive data should be generated by FilesOutputStream.

Parameters:

filesArchive - input stream for a files archive.

Throws:

IOException - if files archive read fails.

InvalidFilesArchiveException - if manifest processing fails.

FilesInputStream

public FilesInputStream(ZipInputStream filesArchive)
                 throws IOException

Create files input reader for given files archive and extract manifest. Files archive data should be generated by FilesOutputStream.

Parameters:

filesArchive - input stream for a files archive.

Throws:

IOException - if files archive read fails.

InvalidFilesArchiveException - if manifest processing fails.

Method Detail

read

public int read()
         throws IOException

Read next byte from files archive.

Specified by:

read in class InputStream

Returns:

next byte or -1 if end of archive detected.

Throws:

IOException

iterator

public Iterator<File> iterator()

Get files archive iterator.

Specified by:

iterator in interface Iterable<File>

Returns:

files archive iterator.

close

public void close()
           throws IOException

Close input stream on files archive.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class InputStream

Throws:

IOException

getMeta

public String getMeta(String key)

Get string value from files archive meta data. Meta data was added into archive by FilesOutputStream.putMeta(String, Object).

Parameters:

key - meta data key.

Returns:

meta data value.

Throws:

InvalidFilesArchiveException - if requested meta data key does not exists.

getMeta

public String getMeta(String key,
                      String defaultValue)

Get string value from files archive meta data or default value if requested key does not exist.

Parameters:

key - meta data key,

defaultValue - default value returned if meta data key not found.

Returns:

meta data value or default value.

getMeta

public <T> T getMeta(String key,
                     Class<T> type)

Get files archive meta data converted to requested type.

Type Parameters:

T - meta data type.

Parameters:

key - meta data key,

type - type to convert meta data value to.

Returns:

meta data value converted to type.

Throws:

InvalidFilesArchiveException - if requested meta data key does not exists.

getMeta

public <T> T getMeta(String key,
                     Class<T> type,
                     T defaultValue)

Get files archive meta data converted to requested type or default value if meta data key is missing.

Type Parameters:

T - meta data type.

Parameters:

key - meta data key,

type - type to convert meta data value to,

defaultValue - default value returned if key not found.

Returns:

meta data value converted to type or default value.

copy

public void copy(File targetFile)
          throws IOException

Utility method that copy current ZIP entry to output file. This method is designed to work in conjunction with FilesInputStream.FilesIterator that takes care to update current ZIP entry. Usage pattern is in sample code; trying to use it in different contexts has not predictable results.

 for (File file : files) {
        File targetFile = new File(targetDir, file.getPath());
        files.copy(targetFile);
 }
 

Files input stream - files is iterated using for each loop. For every source file create related targetFile and enact files input stream to self copy its current entry to target file. Note that this method ensure target file parent directories are created. Also this method works in overwrite mode, that is, if target file already exist it will be overwritten and old content lost.

Warning: do not use Files.copy(InputStream, OutputStream); it closes both input and output streams and trying to get ZIP next entry after that will fail with stream closed exception.

Parameters:

targetFile - target file.

Throws:

IOException - if read/write operation fails.