Top Description Inners Fields Constructors Methods
org.apache.commons.compress.archivers.tar

public Class TarFile

extends Object
implements Closeable
Class Inheritance
All Implemented Interfaces
java.io.Closeable, java.lang.AutoCloseable
Imports
java.io.ByteArrayOutputStream, .Closeable, .File, .IOException, .InputStream, java.nio.ByteBuffer, java.nio.channels.SeekableByteChannel, java.nio.file.Files, .Path, java.util.ArrayList, .Arrays, .HashMap, .LinkedList, .List, .Map, org.apache.commons.compress.archivers.zip.ZipEncoding, .ZipEncodingHelper, org.apache.commons.compress.utils.ArchiveUtils, .BoundedArchiveInputStream, .BoundedInputStream, .BoundedSeekableByteChannelInputStream, .SeekableInMemoryByteChannel

Provides random access to UNIX archives.
Since
1.21

Nested and Inner Type Summary

Modifier and TypeClass and Description
private class

Field Summary

Modifier and TypeField and Description
private final SeekableByteChannel
private final int
private TarArchiveEntry
currEntry

The meta-data about the current entry

private final LinkedList<TarArchiveEntry>
private Map<String, String>
private final List<TarArchiveStructSparse>
private boolean
private final boolean
private final ByteBuffer
private final int
private static final int
private final byte[]
private final Map<String, List<InputStream>>
private final ZipEncoding
zipEncoding

The encoding of the tar file

Constructor Summary

AccessConstructor and Description
public
TarFile(final byte[]
the content to use
content
)

Constructor for TarFile.

public
TarFile(final byte[]
the content to use
content
,
final boolean
when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to TarArchiveEntry#UNKNOWN. When set to false such illegal fields cause an exception instead.
lenient
)

Constructor for TarFile.

public
TarFile(final byte[]
the content to use
content
,
final String
the encoding to use
encoding
)

Constructor for TarFile.

public
TarFile(final File
the file of the archive to use
archive
)

Constructor for TarFile.

public
TarFile(final File
the file of the archive to use
archive
,
final boolean
when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to TarArchiveEntry#UNKNOWN. When set to false such illegal fields cause an exception instead.
lenient
)

Constructor for TarFile.

public
TarFile(final File
the file of the archive to use
archive
,
final String
the encoding to use
encoding
)

Constructor for TarFile.

public
TarFile(final Path
the path of the archive to use
archivePath
)

Constructor for TarFile.

public
TarFile(final Path
the path of the archive to use
archivePath
,
final boolean
when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to TarArchiveEntry#UNKNOWN. When set to false such illegal fields cause an exception instead.
lenient
)

Constructor for TarFile.

public
TarFile(final Path
the path of the archive to use
archivePath
,
final String
the encoding to use
encoding
)

Constructor for TarFile.

public
TarFile(final SeekableByteChannel
the content to use
content
)

Constructor for TarFile.

public
TarFile(final SeekableByteChannel
the seekable byte channel to use
archive
,
final int
the blocks size to use
blockSize
,
final int
the record size to use
recordSize
,
final String
the encoding to use
encoding
,
final boolean
when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to TarArchiveEntry#UNKNOWN. When set to false such illegal fields cause an exception instead.
lenient
)

Constructor for TarFile.

Method Summary

Modifier and TypeMethod and Description
private void
applyPaxHeadersToCurrentEntry(final Map<String, String>
Headers read from the pax header
headers
,
final List<TarArchiveStructSparse>
Sparse headers read from pax header
sparseHeaders
)

Update the current entry with the read pax headers

private void
buildSparseInputStreams()

Build the input streams consisting of all-zero input streams and non-zero input streams.

public void
close()

Implements java.io.Closeable.close.

Closes this stream and releases any system resources associated with it.
private void
consumeRemainderOfLastBlock()

This method is invoked once the end of the archive is hit, it tries to consume the remaining bytes under the assumption that the tool creating this archive has padded the last block.

public List<TarArchiveEntry>

Returns:

All entries from the tar file
getEntries
()

Gets all TAR Archive Entries from the TarFile

public InputStream

Returns:

Input stream of the provided entry
getInputStream
(final TarArchiveEntry
Entry to get the input stream from
entry
)

Gets the input stream for the provided Tar Archive Entry.

private byte[]

Returns:

The next entry in the archive as long name data, or null.
getLongNameData
()

Gets the next entry in this tar archive as long name data.

private TarArchiveEntry

Returns:

The next TarEntry in the archive, or null if there is no next entry.
getNextTarEntry
()

Gets the next entry in this tar archive.

private ByteBuffer

Returns:

The next TarEntry in the archive, or null if there is no next entry.
getRecord
()

Gets the next record in this tar archive.

protected final boolean
private boolean
private boolean
isEOFRecord(final ByteBuffer headerBuf)

private void
paxHeaders()

For PAX Format 0.0, the sparse headers(GNU.sparse.offset and GNU.sparse.numbytes) may appear multi times, and they look like:

GNU.sparse.size=size
GNU.sparse.numblocks=numblocks
repeat numblocks times
  GNU.sparse.offset=offset
  GNU.sparse.numbytes=numbytes
end repeat
private void
private void
readOldGNUSparse()

Adds the sparse chunks from the current entry to the sparse chunks, including any additional sparse entries following the current entry.

private ByteBuffer

Returns:

The record data or null if EOF has been hit.
readRecord
()

Read a record from the input stream and return the data.

private void
repositionForwardBy(final long offset)

private void
repositionForwardTo(final long newPosition)

protected final void
setAtEOF(final boolean b)

private void
skipRecordPadding()

The last record block should be written at the full size, so skip any additional space used to fill a record after an entry

private void
throwExceptionIfPositionIsNotInArchive()

Checks if the current position of the SeekableByteChannel is in the archive.

private void
tryToConsumeSecondEOFRecord()

Tries to read the next record resetting the position in the archive if it is not an EOF record.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

archiveback to summary
private final SeekableByteChannel archive
blockSizeback to summary
private final int blockSize
currEntryback to summary
private TarArchiveEntry currEntry

The meta-data about the current entry

entriesback to summary
private final LinkedList<TarArchiveEntry> entries
globalPaxHeadersback to summary
private Map<String, String> globalPaxHeaders
globalSparseHeadersback to summary
private final List<TarArchiveStructSparse> globalSparseHeaders
hasHitEOFback to summary
private boolean hasHitEOF
lenientback to summary
private final boolean lenient
recordBufferback to summary
private final ByteBuffer recordBuffer
recordSizeback to summary
private final int recordSize
SMALL_BUFFER_SIZEback to summary
private static final int SMALL_BUFFER_SIZE
smallBufback to summary
private final byte[] smallBuf
sparseInputStreamsback to summary
private final Map<String, List<InputStream>> sparseInputStreams
zipEncodingback to summary
private final ZipEncoding zipEncoding

The encoding of the tar file

Constructor Detail

TarFileback to summary
public TarFile(final byte[] content) throws IOException

Constructor for TarFile.

Parameters
content:byte[]

the content to use

Exceptions
IOException:
when reading the tar archive fails
TarFileback to summary
public TarFile(final byte[] content, final boolean lenient) throws IOException

Constructor for TarFile.

Parameters
content:byte[]

the content to use

lenient:boolean

when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to TarArchiveEntry#UNKNOWN. When set to false such illegal fields cause an exception instead.

Exceptions
IOException:
when reading the tar archive fails
TarFileback to summary
public TarFile(final byte[] content, final String encoding) throws IOException

Constructor for TarFile.

Parameters
content:byte[]

the content to use

encoding:String

the encoding to use

Exceptions
IOException:
when reading the tar archive fails
TarFileback to summary
public TarFile(final File archive) throws IOException

Constructor for TarFile.

Parameters
archive:File

the file of the archive to use

Exceptions
IOException:
when reading the tar archive fails
TarFileback to summary
public TarFile(final File archive, final boolean lenient) throws IOException

Constructor for TarFile.

Parameters
archive:File

the file of the archive to use

lenient:boolean

when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to TarArchiveEntry#UNKNOWN. When set to false such illegal fields cause an exception instead.

Exceptions
IOException:
when reading the tar archive fails
TarFileback to summary
public TarFile(final File archive, final String encoding) throws IOException

Constructor for TarFile.

Parameters
archive:File

the file of the archive to use

encoding:String

the encoding to use

Exceptions
IOException:
when reading the tar archive fails
TarFileback to summary
public TarFile(final Path archivePath) throws IOException

Constructor for TarFile.

Parameters
archivePath:Path

the path of the archive to use

Exceptions
IOException:
when reading the tar archive fails
TarFileback to summary
public TarFile(final Path archivePath, final boolean lenient) throws IOException

Constructor for TarFile.

Parameters
archivePath:Path

the path of the archive to use

lenient:boolean

when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to TarArchiveEntry#UNKNOWN. When set to false such illegal fields cause an exception instead.

Exceptions
IOException:
when reading the tar archive fails
TarFileback to summary
public TarFile(final Path archivePath, final String encoding) throws IOException

Constructor for TarFile.

Parameters
archivePath:Path

the path of the archive to use

encoding:String

the encoding to use

Exceptions
IOException:
when reading the tar archive fails
TarFileback to summary
public TarFile(final SeekableByteChannel content) throws IOException

Constructor for TarFile.

Parameters
content:SeekableByteChannel

the content to use

Exceptions
IOException:
when reading the tar archive fails
TarFileback to summary
public TarFile(final SeekableByteChannel archive, final int blockSize, final int recordSize, final String encoding, final boolean lenient) throws IOException

Constructor for TarFile.

Parameters
archive:SeekableByteChannel

the seekable byte channel to use

blockSize:int

the blocks size to use

recordSize:int

the record size to use

encoding:String

the encoding to use

lenient:boolean

when set to true illegal values for group/userid, mode, device numbers and timestamp will be ignored and the fields set to TarArchiveEntry#UNKNOWN. When set to false such illegal fields cause an exception instead.

Exceptions
IOException:
when reading the tar archive fails

Method Detail

applyPaxHeadersToCurrentEntryback to summary
private void applyPaxHeadersToCurrentEntry(final Map<String, String> headers, final List<TarArchiveStructSparse> sparseHeaders) throws IOException

Update the current entry with the read pax headers

Parameters
headers:Map<String, String>

Headers read from the pax header

sparseHeaders:List<TarArchiveStructSparse>

Sparse headers read from pax header

buildSparseInputStreamsback to summary
private void buildSparseInputStreams() throws IOException

Build the input streams consisting of all-zero input streams and non-zero input streams. When reading from the non-zero input streams, the data is actually read from the original input stream. The size of each input stream is introduced by the sparse headers.

Implementation Note

Some all-zero input streams and non-zero input streams have the size of 0. We DO NOT store the 0 size input streams because they are meaningless.

closeback to summary
public void close() throws IOException

Implements java.io.Closeable.close.

Doc from java.io.Closeable.close.

Closes this stream and releases any system resources associated with it. If the stream is already closed then invoking this method has no effect.

As noted in AutoCloseable#close(), cases where the close may fail require careful attention. It is strongly advised to relinquish the underlying resources and to internally mark the Closeable as closed, prior to throwing the IOException.

Annotations
@Override
Exceptions
IOException:
if an I/O error occurs
consumeRemainderOfLastBlockback to summary
private void consumeRemainderOfLastBlock() throws IOException

This method is invoked once the end of the archive is hit, it tries to consume the remaining bytes under the assumption that the tool creating this archive has padded the last block.

getEntriesback to summary
public List<TarArchiveEntry> getEntries()

Gets all TAR Archive Entries from the TarFile

Returns:List<TarArchiveEntry>

All entries from the tar file

getInputStreamback to summary
public InputStream getInputStream(final TarArchiveEntry entry) throws IOException

Gets the input stream for the provided Tar Archive Entry.

Parameters
entry:TarArchiveEntry

Entry to get the input stream from

Returns:InputStream

Input stream of the provided entry

Exceptions
IOException:
Corrupted TAR archive. Can't read entry.
getLongNameDataback to summary
private byte[] getLongNameData() throws IOException

Gets the next entry in this tar archive as long name data.

Returns:byte[]

The next entry in the archive as long name data, or null.

Exceptions
IOException:
on error
getNextTarEntryback to summary
private TarArchiveEntry getNextTarEntry() throws IOException

Gets the next entry in this tar archive. This will skip to the end of the current entry, if there is one, and place the position of the channel at the header of the next entry, and read the header and instantiate a new TarEntry from the header bytes and return that entry. If there are no more entries in the archive, null will be returned to indicate that the end of the archive has been reached.

Returns:TarArchiveEntry

The next TarEntry in the archive, or null if there is no next entry.

Exceptions
IOException:
when reading the next TarEntry fails
getRecordback to summary
private ByteBuffer getRecord() throws IOException

Gets the next record in this tar archive. This will skip over any remaining data in the current entry, if there is one, and place the input stream at the header of the next entry.

If there are no more entries in the archive, null will be returned to indicate that the end of the archive has been reached. At the same time the hasHitEOF marker will be set to true.

Returns:ByteBuffer

The next TarEntry in the archive, or null if there is no next entry.

Exceptions
IOException:
when reading the next TarEntry fails
isAtEOFback to summary
protected final boolean isAtEOF()
isDirectoryback to summary
private boolean isDirectory()
isEOFRecordback to summary
private boolean isEOFRecord(final ByteBuffer headerBuf)
paxHeadersback to summary
private void paxHeaders() throws IOException

For PAX Format 0.0, the sparse headers(GNU.sparse.offset and GNU.sparse.numbytes) may appear multi times, and they look like:

GNU.sparse.size=size
GNU.sparse.numblocks=numblocks
repeat numblocks times
  GNU.sparse.offset=offset
  GNU.sparse.numbytes=numbytes
end repeat

For PAX Format 0.1, the sparse headers are stored in a single variable : GNU.sparse.map

GNU.sparse.map
   Map of non-null data chunks. It is a string consisting of comma-separated values "offset,size[,offset-1,size-1...]"

For PAX Format 1.X:
The sparse map itself is stored in the file data block, preceding the actual file data. It consists of a series of decimal numbers delimited by newlines. The map is padded with nulls to the nearest block boundary. The first number gives the number of entries in the map. Following are map entries, each one consisting of two numbers giving the offset and size of the data block it describes.

readGlobalPaxHeadersback to summary
private void readGlobalPaxHeaders() throws IOException
readOldGNUSparseback to summary
private void readOldGNUSparse() throws IOException

Adds the sparse chunks from the current entry to the sparse chunks, including any additional sparse entries following the current entry.

Exceptions
IOException:
when reading the sparse entry fails
readRecordback to summary
private ByteBuffer readRecord() throws IOException

Read a record from the input stream and return the data.

Returns:ByteBuffer

The record data or null if EOF has been hit.

Exceptions
IOException:
if reading from the archive fails
repositionForwardByback to summary
private void repositionForwardBy(final long offset) throws IOException
repositionForwardToback to summary
private void repositionForwardTo(final long newPosition) throws IOException
setAtEOFback to summary
protected final void setAtEOF(final boolean b)
skipRecordPaddingback to summary
private void skipRecordPadding() throws IOException

The last record block should be written at the full size, so skip any additional space used to fill a record after an entry

Exceptions
IOException:
when skipping the padding of the record fails
throwExceptionIfPositionIsNotInArchiveback to summary
private void throwExceptionIfPositionIsNotInArchive() throws IOException

Checks if the current position of the SeekableByteChannel is in the archive.

Exceptions
IOException:
If the position is not in the archive
tryToConsumeSecondEOFRecordback to summary
private void tryToConsumeSecondEOFRecord() throws IOException

Tries to read the next record resetting the position in the archive if it is not an EOF record.

This is meant to protect against cases where a tar implementation has written only one EOF record when two are expected. Actually this won't help since a non-conforming implementation likely won't fill full blocks consisting of - by default - ten records either so we probably have already read beyond the archive anyway.

Exceptions
IOException:
if reading the record of resetting the position in the archive fails
org.apache.commons.compress.archivers.tar back to summary

private final Class TarFile.BoundedTarEntryInputStream

extends BoundedArchiveInputStream
Class Inheritance

Field Summary

Modifier and TypeField and Description
private final SeekableByteChannel
private int
private final TarArchiveEntry
private long

Constructor Summary

AccessConstructor and Description
pack-priv

Method Summary

Modifier and TypeMethod and Description
protected int
read(final long
position to start the read.
pos
,
final ByteBuffer
buffer to add the read content.
buf
)

Implements abstract org.apache.commons.compress.utils.BoundedArchiveInputStream.read.

Reads content of the stream into a ByteBuffer.
private int
readArchive(final long pos, final ByteBuffer buf)

private int
readSparse(final long pos, final ByteBuffer buf, final int numToRead)

Inherited from org.apache.commons.compress.utils.BoundedArchiveInputStream:
readread

Field Detail

channelback to summary
private final SeekableByteChannel channel
currentSparseInputStreamIndexback to summary
private int currentSparseInputStreamIndex
entryback to summary
private final TarArchiveEntry entry
entryOffsetback to summary
private long entryOffset

Constructor Detail

BoundedTarEntryInputStreamback to summary
pack-priv BoundedTarEntryInputStream(final TarArchiveEntry entry, final SeekableByteChannel channel) throws IOException

Method Detail

readback to summary
protected int read(final long pos, final ByteBuffer buf) throws IOException

Implements abstract org.apache.commons.compress.utils.BoundedArchiveInputStream.read.

Doc from org.apache.commons.compress.utils.BoundedArchiveInputStream.read.

Reads content of the stream into a ByteBuffer.

Parameters
pos:long

position to start the read.

buf:ByteBuffer

buffer to add the read content.

Returns:int

number of read bytes.

Annotations
@Override
Exceptions
IOException:
if I/O fails.
readArchiveback to summary
private int readArchive(final long pos, final ByteBuffer buf) throws IOException
readSparseback to summary
private int readSparse(final long pos, final ByteBuffer buf, final int numToRead) throws IOException