SevenZFile
Date: 2017-02-08

org.apache.commons.compress.archivers.sevenz

## Class SevenZFile

- java.lang.Object
- - org.apache.commons.compress.archivers.sevenz.SevenZFile

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable

      public class SevenZFile
      extends java.lang.Object
      implements java.io.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.

  Since:
    1.6

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SevenZFile(java.io.File filename)` Reads a file as unencrypted 7z archive
    `SevenZFile(java.io.File filename, byte[] password)` Reads a file as 7z archive
    `SevenZFile(java.nio.channels.SeekableByteChannel channel)` Reads a SeekableByteChannel as 7z archive
    `SevenZFile(java.nio.channels.SeekableByteChannel channel, byte[] password)` Reads a SeekableByteChannel as 7z archive
    `SevenZFile(java.nio.channels.SeekableByteChannel channel, java.lang.String filename, byte[] password)` Reads a SeekableByteChannel as 7z archive

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes the archive.
    `java.lang.Iterable<SevenZArchiveEntry>` | `getEntries()` Returns meta-data of all archive entries.
    `SevenZArchiveEntry` | `getNextEntry()` Returns the next Archive Entry in this archive.
    `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.
    `java.lang.String` | `toString()`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### SevenZFile

          public SevenZFile(java.io.File filename,
                    byte[] password)
                     throws java.io.IOException

      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:
        `java.io.IOException` - if reading the archive fails

    - #### SevenZFile

          public SevenZFile(java.nio.channels.SeekableByteChannel channel)
                     throws java.io.IOException

      Reads a SeekableByteChannel as 7z archive

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

      Parameters:
        `channel` - the channel to read
      Throws:
        `java.io.IOException` - if reading the archive fails
      Since:
        1.13

    - #### SevenZFile

          public SevenZFile(java.nio.channels.SeekableByteChannel channel,
                    byte[] password)
                     throws java.io.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 - the byte array is supposed to be the UTF16-LE encoded representation of the password.
      Throws:
        `java.io.IOException` - if reading the archive fails
      Since:
        1.13

    - #### SevenZFile

          public SevenZFile(java.nio.channels.SeekableByteChannel channel,
                    java.lang.String filename,
                    byte[] password)
                     throws java.io.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 - the byte array is supposed to be the UTF16-LE encoded representation of the password.
      Throws:
        `java.io.IOException` - if reading the archive fails
      Since:
        1.13

    - #### SevenZFile

          public SevenZFile(java.io.File filename)
                     throws java.io.IOException

      Reads a file as unencrypted 7z archive
      Parameters:
        `filename` - the file to read
      Throws:
        `java.io.IOException` - if reading the archive fails

  - ### Method Detail

    - #### close

          public void close()
                     throws java.io.IOException

      Closes the archive.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Throws:
        `java.io.IOException` - if closing the file fails

    - #### getNextEntry

          public SevenZArchiveEntry getNextEntry()
                                          throws java.io.IOException

      Returns the next Archive Entry in this archive.
      Returns:
        the next entry, or `null` if there are no more entries
      Throws:
        `java.io.IOException` - if the next entry could not be read

    - #### getEntries

          public java.lang.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 java.io.IOException

      Reads a byte of data.
      Returns:
        the byte read, or -1 if end of input is reached
      Throws:
        `java.io.IOException` - if an I/O error has occurred

    - #### read

          public int read(byte[] b)
                   throws java.io.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:
        `java.io.IOException` - if an I/O error has occurred

    - #### read

          public int read(byte[] b,
                 int off,
                 int len)
                   throws java.io.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:
        `java.io.IOException` - if an I/O error has occurred

    - #### 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 java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`