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
This class is not thread-safe

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `SevenZFile.Builder`
  Builds new instances of `SevenZFile`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SevenZFile(File fileName)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(File file, byte[] password)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(File file, char[] password)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(File file, char[] password, SevenZFileOptions options)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(File file, SevenZFileOptions options)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(SeekableByteChannel channel)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(SeekableByteChannel channel, byte[] password)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(SeekableByteChannel channel, char[] password)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(SeekableByteChannel channel, char[] password, SevenZFileOptions options)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(SeekableByteChannel channel, String fileName)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(SeekableByteChannel channel, String fileName, byte[] password)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(SeekableByteChannel channel, String fileName, char[] password)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(SeekableByteChannel channel, String fileName, char[] password, SevenZFileOptions options)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(SeekableByteChannel channel, String fileName, SevenZFileOptions options)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.
  `SevenZFile(SeekableByteChannel channel, SevenZFileOptions options)`
  Deprecated.
  Use `SevenZFile.Builder.get()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static SevenZFile.Builder`
  `builder()`
  Creates a new Builder.
  `void`
  `close()`
  Closes the archive.
  `String`
  `getDefaultName()`
  Gets a default file name from the archive name - if known.
  `Iterable<SevenZArchiveEntry>`
  `getEntries()`
  Gets a copy of meta-data of all archive entries.
  `InputStream`
  `getInputStream(SevenZArchiveEntry entry)`
  Gets an InputStream for reading the contents of the given entry.
  `SevenZArchiveEntry`
  `getNextEntry()`
  Gets the next Archive Entry in this archive.
  `InputStreamStatistics`
  `getStatisticsForCurrentEntry()`
  Gets 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

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

- ## Constructor Details

  - ### SevenZFile

    @Deprecated public SevenZFile(File fileName) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    Reads a file as unencrypted 7z archive.
    Parameters:
      `fileName` - the file to read.
    Throws:
      `IOException` - if reading the archive fails.

  - ### SevenZFile

    @Deprecated public SevenZFile(File file, byte[] password) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    Reads a file as 7z archive
    Parameters:
      `file` - 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

    @Deprecated public SevenZFile(File file, char[] password) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    Reads a file as 7z archive
    Parameters:
      `file` - the file to read
      `password` - optional password if the archive is encrypted
    Throws:
      `IOException` - if reading the archive fails
    Since:
      1.17

  - ### SevenZFile

    @Deprecated public SevenZFile(File file, char[] password, SevenZFileOptions options) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    Reads a file as 7z archive with additional options.
    Parameters:
      `file` - 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 file, SevenZFileOptions options) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    Reads a file as unencrypted 7z archive
    Parameters:
      `file` - 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

  - ### SevenZFile

    @Deprecated public SevenZFile(SeekableByteChannel channel) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    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

    @Deprecated public SevenZFile(SeekableByteChannel channel, byte[] password) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    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, char[] password) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    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

    @Deprecated public SevenZFile(SeekableByteChannel channel, char[] password, SevenZFileOptions options) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    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

    @Deprecated public SevenZFile(SeekableByteChannel channel, SevenZFileOptions options) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    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
      `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, String fileName) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    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

    @Deprecated public SevenZFile(SeekableByteChannel channel, String fileName, byte[] password) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    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

    @Deprecated public SevenZFile(SeekableByteChannel channel, String fileName, char[] password) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    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

    @Deprecated public SevenZFile(SeekableByteChannel channel, String fileName, char[] password, SevenZFileOptions options) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    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
      `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(SeekableByteChannel channel, String fileName, SevenZFileOptions options) throws IOException
    Deprecated.
    Use `SevenZFile.Builder.get()`.
    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

- ## Method Details

  - ### builder

    public static SevenZFile.Builder builder()
    Creates a new Builder.
    Returns:
      a new Builder.
    Since:
      1.26.0

  - ### 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

  - ### 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

  - ### getDefaultName

    public String getDefaultName()
    Gets 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

  - ### getEntries

    public Iterable<SevenZArchiveEntry> getEntries()
    Gets a copy of meta-data of all archive entries.

    This method only provides meta-data, the entries cannot 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:
      a copy of meta-data of all archive entries.
    Since:
      1.11

  - ### getInputStream

    public InputStream getInputStream(SevenZArchiveEntry entry) throws IOException
    Gets 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 sequentially.

    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 entry
    Since:
      1.20

  - ### getNextEntry

    public SevenZArchiveEntry getNextEntry() throws IOException
    Gets 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

  - ### getStatisticsForCurrentEntry

    public InputStreamStatistics getStatisticsForCurrentEntry()
    Gets statistics for bytes read from the current entry.
    Returns:
      statistics for bytes read from the current entry
    Since:
      1.17

  - ### 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

  - ### 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

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`