Package org.apache.commons.compress.archivers.sevenz

Class SevenZFile

java.lang.Object

org.apache.commons.compress.archivers.sevenz.SevenZFile

All Implemented Interfaces:

Closeable, AutoCloseable

public class SevenZFile
extends Object
implements Closeable

Reads a 7z file, using SeekableByteChannel under the covers.

The 7z file format is a flexible container that can contain many compression and encryption types, but at the moment only only Copy, LZMA, LZMA2, BZIP2, Deflate and AES-256 + SHA-256 are supported.

The format is very Windows/Intel specific, so it uses little-endian byte order, doesn't store user/group or permission bits, and represents times using NTFS timestamps (100 nanosecond units since 1 January 1601). Hence the official tools recommend against using it for backup purposes on *nix, and recommend .tar.7z or .tar.lzma or .tar.xz instead.

Both the header and file contents may be compressed and/or encrypted. With both encrypted, neither file names nor file contents can be read, but the use of encryption isn't plausibly deniable.

Multi volume archives can be read by concatenating the parts in correct order - either manually or by using {link org.apache.commons.compress.utils.MultiReadOnlySeekableByteChannel} for example.

Since:

1.6

Constructor Summary

Constructors

Constructor	Description
SevenZFile(File fileName)	Reads a file as unencrypted 7z archive
SevenZFile(File fileName, byte[] password)	Deprecated. use the char[]-arg version for the password instead
SevenZFile(File fileName, char[] password)	Reads a file as 7z archive
SevenZFile(File fileName, char[] password, SevenZFileOptions options)	Reads a file as 7z archive with additional options.
SevenZFile(File fileName, SevenZFileOptions options)	Reads a file as unencrypted 7z archive
SevenZFile(SeekableByteChannel channel)	Reads a SeekableByteChannel as 7z archive
SevenZFile(SeekableByteChannel channel, byte[] password)	Deprecated. use the char[]-arg version for the password instead
SevenZFile(SeekableByteChannel channel, char[] password)	Reads a SeekableByteChannel as 7z archive
SevenZFile(SeekableByteChannel channel, char[] password, SevenZFileOptions options)	Reads a SeekableByteChannel as 7z archive with additional options.
SevenZFile(SeekableByteChannel channel, String fileName)	Reads a SeekableByteChannel as 7z archive
SevenZFile(SeekableByteChannel channel, String fileName, byte[] password)	Deprecated. use the char[]-arg version for the password instead
SevenZFile(SeekableByteChannel channel, String fileName, char[] password)	Reads a SeekableByteChannel as 7z archive
SevenZFile(SeekableByteChannel channel, String fileName, char[] password, SevenZFileOptions options)	Reads a SeekableByteChannel as 7z archive with addtional options.
SevenZFile(SeekableByteChannel channel, String fileName, SevenZFileOptions options)	Reads a SeekableByteChannel as 7z archive with additional options.
SevenZFile(SeekableByteChannel channel, SevenZFileOptions options)	Reads a SeekableByteChannel as 7z archive with addtional options.

Method Summary

Modifier and Type	Method	Description
void	close()	Closes the archive.
String	getDefaultName()	Derives a default file name from the archive name - if known.
Iterable<SevenZArchiveEntry>	getEntries()	Returns meta-data of all archive entries.
InputStream	getInputStream(SevenZArchiveEntry entry)	Returns an InputStream for reading the contents of the given entry.
SevenZArchiveEntry	getNextEntry()	Returns the next Archive Entry in this archive.
InputStreamStatistics	getStatisticsForCurrentEntry()	Provides statistics for bytes read from the current entry.
static boolean	matches(byte[] signature, int length)	Checks if the signature matches what is expected for a 7z file.
int	read()	Reads a byte of data.
int	read(byte[] b)	Reads data into an array of bytes.
int	read(byte[] b, int off, int len)	Reads data into an array of bytes.
String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SevenZFile

public SevenZFile(File fileName,
                  char[] password)
           throws IOException

Reads a file as 7z archive

Parameters:

fileName - the file to read

password - optional password if the archive is encrypted

Throws:

IOException - if reading the archive fails

Since:

1.17

SevenZFile

public SevenZFile(File fileName,
                  char[] password,
                  SevenZFileOptions options)
           throws IOException

Reads a file as 7z archive with additional options.

Parameters:

fileName - the file to read

password - optional password if the archive is encrypted

options - the options to apply

Throws:

IOException - if reading the archive fails or the memory limit (if set) is too small

Since:

1.19

SevenZFile

@Deprecated
public SevenZFile(File fileName,
                  byte[] password)
           throws IOException

Deprecated.

use the char[]-arg version for the password instead

Reads a file as 7z archive

Parameters:

fileName - the file to read

password - optional password if the archive is encrypted - the byte array is supposed to be the UTF16-LE encoded representation of the password.

Throws:

IOException - if reading the archive fails

SevenZFile

public SevenZFile(SeekableByteChannel channel)
           throws IOException

Reads a SeekableByteChannel as 7z archive

SeekableInMemoryByteChannel allows you to read from an in-memory archive.

Parameters:

channel - the channel to read

Throws:

IOException - if reading the archive fails

Since:

1.13

SevenZFile

public SevenZFile(SeekableByteChannel channel,
                  SevenZFileOptions options)
           throws IOException

Reads a SeekableByteChannel as 7z archive with addtional options.

SeekableInMemoryByteChannel allows you to read from an in-memory archive.

Parameters:

channel - the channel to read

options - the options to apply

Throws:

IOException - if reading the archive fails or the memory limit (if set) is too small

Since:

1.19

SevenZFile

public SevenZFile(SeekableByteChannel channel,
                  char[] password)
           throws IOException

Reads a SeekableByteChannel as 7z archive

SeekableInMemoryByteChannel allows you to read from an in-memory archive.

Parameters:

channel - the channel to read

password - optional password if the archive is encrypted

Throws:

IOException - if reading the archive fails

Since:

1.17

SevenZFile

public SevenZFile(SeekableByteChannel channel,
                  char[] password,
                  SevenZFileOptions options)
           throws IOException

Reads a SeekableByteChannel as 7z archive with additional options.

SeekableInMemoryByteChannel allows you to read from an in-memory archive.

Parameters:

channel - the channel to read

password - optional password if the archive is encrypted

options - the options to apply

Throws:

IOException - if reading the archive fails or the memory limit (if set) is too small

Since:

1.19

SevenZFile

public SevenZFile(SeekableByteChannel channel,
                  String fileName,
                  char[] password)
           throws IOException

Reads a SeekableByteChannel as 7z archive

SeekableInMemoryByteChannel allows you to read from an in-memory archive.

Parameters:

channel - the channel to read

fileName - name of the archive - only used for error reporting

password - optional password if the archive is encrypted

Throws:

IOException - if reading the archive fails

Since:

1.17

SevenZFile

public SevenZFile(SeekableByteChannel channel,
                  String fileName,
                  char[] password,
                  SevenZFileOptions options)
           throws IOException

Reads a SeekableByteChannel as 7z archive with addtional options.

SeekableInMemoryByteChannel allows you to read from an in-memory archive.

Parameters:

channel - the channel to read

fileName - name of the archive - only used for error reporting

password - optional password if the archive is encrypted

options - the options to apply

Throws:

IOException - if reading the archive fails or the memory limit (if set) is too small

Since:

1.19

SevenZFile

public SevenZFile(SeekableByteChannel channel,
                  String fileName)
           throws IOException

Reads a SeekableByteChannel as 7z archive

SeekableInMemoryByteChannel allows you to read from an in-memory archive.

Parameters:

channel - the channel to read

fileName - name of the archive - only used for error reporting

Throws:

IOException - if reading the archive fails

Since:

1.17

SevenZFile

public SevenZFile(SeekableByteChannel channel,
                  String fileName,
                  SevenZFileOptions options)
           throws IOException

Reads a SeekableByteChannel as 7z archive with additional options.

SeekableInMemoryByteChannel allows you to read from an in-memory archive.

Parameters:

channel - the channel to read

fileName - name of the archive - only used for error reporting

options - the options to apply

Throws:

IOException - if reading the archive fails or the memory limit (if set) is too small

Since:

1.19

SevenZFile

@Deprecated
public SevenZFile(SeekableByteChannel channel,
                  byte[] password)
           throws IOException

Deprecated.

use the char[]-arg version for the password instead

Reads a SeekableByteChannel as 7z archive

SeekableInMemoryByteChannel allows you to read from an in-memory archive.

Parameters:

channel - the channel to read

password - optional password if the archive is encrypted - the byte array is supposed to be the UTF16-LE encoded representation of the password.

Throws:

IOException - if reading the archive fails

Since:

1.13

SevenZFile

@Deprecated
public SevenZFile(SeekableByteChannel channel,
                  String fileName,
                  byte[] password)
           throws IOException

Deprecated.

use the char[]-arg version for the password instead

Reads a SeekableByteChannel as 7z archive

SeekableInMemoryByteChannel allows you to read from an in-memory archive.

Parameters:

channel - the channel to read

fileName - name of the archive - only used for error reporting

password - optional password if the archive is encrypted - the byte array is supposed to be the UTF16-LE encoded representation of the password.

Throws:

IOException - if reading the archive fails

Since:

1.13

SevenZFile

public SevenZFile(File fileName)
           throws IOException

Reads a file as unencrypted 7z archive

Parameters:

fileName - the file to read

Throws:

IOException - if reading the archive fails

SevenZFile

public SevenZFile(File fileName,
                  SevenZFileOptions options)
           throws IOException

Reads a file as unencrypted 7z archive

Parameters:

fileName - the file to read

options - the options to apply

Throws:

IOException - if reading the archive fails or the memory limit (if set) is too small

Since:

1.19

Method Detail

close

public void close()
           throws IOException

Closes the archive.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - if closing the file fails

getNextEntry

public SevenZArchiveEntry getNextEntry()
                                throws IOException

Returns the next Archive Entry in this archive.

Returns:

the next entry, or null if there are no more entries

Throws:

IOException - if the next entry could not be read

getEntries

public Iterable<SevenZArchiveEntry> getEntries()

Returns meta-data of all archive entries.

This method only provides meta-data, the entries can not be used to read the contents, you still need to process all entries in order using getNextEntry() for that.

The content methods are only available for entries that have already been reached via getNextEntry().

Returns:

meta-data of all archive entries.

Since:

1.11

read

public int read()
         throws IOException

Reads a byte of data.

Returns:

the byte read, or -1 if end of input is reached

Throws:

IOException - if an I/O error has occurred

getInputStream

public InputStream getInputStream(SevenZArchiveEntry entry)
                           throws IOException

Returns an InputStream for reading the contents of the given entry.

For archives using solid compression randomly accessing entries will be significantly slower than reading the archive sequentiallly.

Parameters:

entry - the entry to get the stream for.

Returns:

a stream to read the entry from.

Throws:

IOException - if unable to create an input stream from the zipentry

Since:

Compress 1.20

read

public int read(byte[] b)
         throws IOException

Reads data into an array of bytes.

Parameters:

b - the array to write data to

Returns:

the number of bytes read, or -1 if end of input is reached

Throws:

IOException - if an I/O error has occurred

read

public int read(byte[] b,
                int off,
                int len)
         throws IOException

Reads data into an array of bytes.

Parameters:

b - the array to write data to

off - offset into the buffer to start filling at

len - of bytes to read

Returns:

the number of bytes read, or -1 if end of input is reached

Throws:

IOException - if an I/O error has occurred

getStatisticsForCurrentEntry

public InputStreamStatistics getStatisticsForCurrentEntry()

Provides statistics for bytes read from the current entry.

Returns:

statistics for bytes read from the current entry

Since:

1.17

matches

public static boolean matches(byte[] signature,
                              int length)

Checks if the signature matches what is expected for a 7z file.

Parameters:

signature - the bytes to check

length - the number of bytes to check

Returns:

true, if this is the signature of a 7z archive.

Since:

1.8

toString

public String toString()

Overrides:

toString in class Object

getDefaultName

public String getDefaultName()

Derives a default file name from the archive name - if known.

This implements the same heuristics the 7z tools use. In 7z's case if an archive contains entries without a name - i.e. SevenZArchiveEntry.getName() returns null - then its command line and GUI tools will use this default name when extracting the entries.

Returns:

null if the name of the archive is unknown. Otherwise if the name of the archive has got any extension, it is stripped and the remainder returned. Finally if the name of the archive hasn't got any extension then a ~ character is appended to the archive name.

Since:

1.19