/* Copyright (c) 2001-2010, The HSQL Development Group
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* Redistributions of source code must retain the above copyright notice, this
* list of conditions and the following disclaimer.
*
* Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* Neither the name of the HSQL Development Group nor the names of its
* contributors may be used to endorse or promote products derived from this
* software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG,
* OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
package org.hsqldb.lib.tar;
import java.io.EOFException;
import java.io.File;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.util.zip.GZIPInputStream;
/**
* Note that this class <b>is not</b> a java.io.FileInputStream,
* because our goal is to greatly restrict the public methods of
* FileInputStream, yet we must use public methods of the underlying
* FileInputStream internally. Can't accomplish these goals in Java if we
* subclass.
* <P>
* This class is ignorant about Tar header fields, attributes and such.
* It is concerned with reading and writing blocks of data in conformance with
* Tar formatting, in a way convenient to those who want to get the header and
* data blocks.
* </P> <P>
* Asymmetric to the Tar file writing side, the bufferBlocks setting here is
* used only for to adjust read buffer size (for file data reads), so the user
* can compromise between available memory and performance. Small buffer sizes
* will always work, but will incur more reads; on the other hand, buffer sizes
* larger than the largest component file is just a waste of memory.
* </P> <P>
* We assume the responsibility to manage the setting because the decision
* should be based on available RAM more than anything else (therefore, we can't
* set a good value automatically).
* </P> <P>
* As alluded to above, headers are read in separate reads, regardless of the
* readBufferBlocks setting. readBufferBlocks is used for reading
* <I>file data</I>.
* </P> <P>
* I have purposefully not implemented skip(), because, though I haven't tested
* it, I believe our readBlock() and readBlocks() methods are at least as fast,
* since we use the larges read buffer within limits the user has set.
* </P>
*/
public class TarFileInputStream {
/* Would love to use a RandomAccessFile, but RandomAccessFiles do not play
* nicely with InputStreams or filters, and it just would not work with
* compressed input. */
protected long bytesRead = 0;
// Pronounced as past tense of "to read", not the other forms of "read".
// I.e., the homonym of "red".
private InputStream readStream;
/* This is not a "Reader", but the byte "Stream" that we read() from. */
protected byte[] readBuffer;
protected int readBufferBlocks;
protected int compressionType;
/**
* Convenience wrapper to use default readBufferBlocks and compressionType.
*
* @see #TarFileInputStream(File, int, int)
*/
public TarFileInputStream(File sourceFile) throws IOException {
this(sourceFile, TarFileOutputStream.Compression.DEFAULT_COMPRESSION);
}
/**
* Convenience wrapper to use default readBufferBlocks.
*
* @see #TarFileInputStream(File, int, int)
*/
public TarFileInputStream(File sourceFile,
int compressionType) throws IOException {
this(sourceFile, compressionType,
TarFileOutputStream.Compression.DEFAULT_BLOCKS_PER_RECORD);
}
public int getReadBufferBlocks() {
return readBufferBlocks;
}
/**
* This class does no validation or enforcement of file naming conventions.
* If desired, the caller should enforce extensions like "tar" and
* "tar.gz" (and that they match the specified compression type).
* <P>
* This object will automatically release its I/O resources when you get
* false back from a readNextHeaderBlock() call.
* If you abort before then, you must call the close() method like for a
* normal InputStream.
* </P>
*
* @see #close()
* @see #readNextHeaderBlock()
*/
public TarFileInputStream(File sourceFile, int compressionType,
int readBufferBlocks) throws IOException {
if (!sourceFile.isFile()) {
throw new FileNotFoundException(sourceFile.getAbsolutePath());
}
if (!sourceFile.canRead()) {
throw new IOException(
RB.read_denied.getString(sourceFile.getAbsolutePath()));
}
this.readBufferBlocks = readBufferBlocks;
this.compressionType = compressionType;
readBuffer = new byte[readBufferBlocks * 512];
switch (compressionType) {
case TarFileOutputStream.Compression.NO_COMPRESSION :
readStream = new FileInputStream(sourceFile);
break;
case TarFileOutputStream.Compression.GZIP_COMPRESSION :
readStream =
new GZIPInputStream(new FileInputStream(sourceFile),
readBuffer.length);
break;
default :
throw new IllegalArgumentException(
RB.compression_unknown.getString(compressionType));
}
}
/**
* readBlocks(int) is the method that USERS of this class should use to
* read file data from the tar file.
* This method reads from the tar file and writes to the readBuffer array.
* <P>
* This class and subclasses should read from the underlying readStream
* <b>ONLY WITH THIS METHOD</b>.
* That way we can be confident that bytesRead will always be accurate.
* </P> <P>
* This method is different from a typical Java byte array read command
* in that when reading tar files <OL>
* <LI>we always know ahead-of-time how many bytes we should read, and
* <LI>we always want to read quantities of bytes in multiples of 512.
* </OL>
* </P>
*
* @param blocks How many 512 blocks to read.
* @throws IOException for an I/O error on the underlying InputStream
* @throws TarMalformatException if no I/O error occurred, but we failed to
* read the exact number of bytes requested.
*/
public void readBlocks(int blocks)
throws IOException, TarMalformatException {
/* int for blocks should support sizes up to about 1T, according to
* my off-the-cuff calculations */
if (compressionType
!= TarFileOutputStream.Compression.NO_COMPRESSION) {
readCompressedBlocks(blocks);
return;
}
int i = readStream.read(readBuffer, 0, blocks * 512);
bytesRead += i;
if (i != blocks * 512) {
throw new TarMalformatException(
RB.insufficient_read.getString(blocks * 512, i));
}
}
/**
* Work-around for the problem that compressed InputReaders don't fill
* the read buffer before returning.
*
* Has visibility 'protected' so that subclasses may override with
* different algorithms, or use different algorithms for different
* compression stream.
*/
protected void readCompressedBlocks(int blocks) throws IOException {
int bytesSoFar = 0;
int requiredBytes = 512 * blocks;
// This method works with individual bytes!
int i;
while (bytesSoFar < requiredBytes) {
i = readStream.read(readBuffer, bytesSoFar,
requiredBytes - bytesSoFar);
if (i < 0) {
throw new EOFException(RB.decompression_ranout.getString(
bytesSoFar, requiredBytes));
}
bytesRead += i;
bytesSoFar += i;
}
}
/**
* readBlock() and readNextHeaderBlock are the methods that USERS of this
* class should use to read header blocks from the tar file.
* <P>
* readBlock() should be used when you know that the current block should
* contain what you want.
* E.g. you know that the very first block of a tar file should contain
* a Tar Entry header block.
* </P>
*
* @see #readNextHeaderBlock
*/
public void readBlock() throws IOException, TarMalformatException {
readBlocks(1);
}
/**
* readBlock() and readNextHeaderBlock are the methods that USERS of this
* class should use to read header blocks from the tar file.
* <P>
* readNextHeaderBlock continues working through the Tar File from the
* current point until it finds a block with a non-0 first byte.
* </P>
*
* @return True if a header block was read and place at beginning of the
* readBuffer array. False if EOF was encountered without finding
* any blocks with first byte != 0. If false is returned, we have
* automatically closed the this TarFileInputStream too.
* @see #readBlock
*/
public boolean readNextHeaderBlock()
throws IOException, TarMalformatException {
// We read a-byte-at-a-time because there should only be 2 empty blocks
// between each Tar Entry.
try {
while (readStream.available() > 0) {
readBlock();
if (readBuffer[0] != 0) {
return true;
}
}
} catch (EOFException ee) {
/* This is a work-around.
* Sun Java's inputStream.available() works like crap.
* Reach this point when performing a read of a GZip stream when
* .available == 1, which according to API Spec, should not happen.
* We treat this condition exactly as if readStream.available is 0,
* which it should be.
*/
}
close();
return false;
}
/**
* Implements java.io.Closeable.
*
* @see java.io.Closeable
*/
public void close() throws IOException {
if (readStream == null) {
return;
}
try {
readStream.close();
} finally {
readStream = null; // Encourage buffer GC
}
}
}