<?xml version="1.0"?>
<!--

   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

-->
<document>
    <properties>
        <title>Overview</title>
        <author email="dev@commons.apache.org">Commons Documentation Team</author>
    </properties>
    <body>
        <section name="Apache Commons Compress&#x2122;">
            <p>
                The Apache Commons Compress library defines an API for
                working with ar, cpio, Unix dump, tar, zip, gzip, XZ,
                Pack200, bzip2, 7z, arj, lzma, snappy, DEFLATE, lz4,
                Brotli, Zstandard, DEFLATE64 and Z files.
            </p>
            <p>
                The code in this component has many origins:
            </p>
            <ul>
              <li>The bzip2, tar and zip support came from Avalon's
                Excalibur, but originally from Ant, as far as life in
                Apache goes. The tar package is originally Tim Endres'
                public domain package. The bzip2 package is based on
                the work done by Keiron Liddle as well as Julian Seward's
                <a href="http://www.bzip.org/index.html">libbzip2</a>.
                It has migrated
                via:<br/> Ant -&gt; Avalon-Excalibur -&gt; Commons-IO
                -&gt; Commons-Compress.</li>
              <li>The cpio package has been contributed by Michael Kuss
                and
                the <a href="http://jrpm.sourceforge.net/">jRPM</a>
                project.</li>
              <li>The pack200 code has originally been part of the now
                retired <a href="https://harmony.apache.org/">Apache
                Harmony&#x2122;</a> project.</li>
            </ul>

        </section>

        <section name="Status">
          <p>The current release is 1.22 and requires Java 8.</p>

          <p>Below we highlight some new features, for a full list
          of changes see the <a href="changes-report.html">Changes
          Report</a>.</p>

          <subsection name="What's new in 1.22?">
            <ul>
              <li>The zip package now uses NIO.</li>
              <li>Support for APK files (JAR format) has been added
                to <code>ArchiveStreamFactory</code>.</li>
              <li>Improved TAR support for file times.</li>
              <li>Added <code>SevenZArchiveEntry::setContentMethods</code></li>
              <li>Fixed <code>Expander</code> error when extracting archive
                entries with names beginning with <code>./</code></li>
              <li>Fixed various fuzz testing and static analysis issues
                discovered in pack200.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.21?">
            <ul>
              <li>A new class <code>TarFile</code> provides random
              access to TAR archives.</li>
              <li>Commons Compress now ships with a copy of the
              Pack200 code of the retired Apache Harmony project. The
              pack200 support in Commons Compress no longer uses the
              implementation of the Java class library - and thus also
              works for Java 14 and later.</li>
              <li>Added new methods supporting
              <code>java.nio.Path</code> as an alternative to
              <code>java.io.File</code> to many classes.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.20?">
            <ul>
              <li><code>SevenZFile</code> now supports random
              access.</li>
              <li>The zip package now supports split archives.</li>
              <li>The tar package now supports reading sparse entries.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.19?">
            <ul>
              <li><code>ParallelScatterZipCreator</code> now writes
              entries in the same order they have been added to the
              archive.</li>
              <li><code>ZipArchiveInputStream</code> and
              <code>ZipFile</code> are more forgiving when parsing
              extra fields by default now.</li>
              <li><code>TarArchiveInputStream</code> has a new lenient
              mode that may allow it to read certain broken
              archives.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.18?">
            <ul>
              <li>The CPIO package now properly handles file names
              using a multi-byte encoding.</li>
              <li>ZipArchiveInputStream can now deal with APK files
              containing an APK signing block.</li>
              <li>It is no possible to specify various parameters
              for Zstd output.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.17?">
            <ul>
              <li>A new <code>InputStreamStatistics</code> interface
              is implemented by many streams and may be used to
              provide feedback or detect abnormally high compression
              ratios that may indicate a ZIP bomb during
              decompression.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.16.1?">
            <ul>
              <li>Fixed the OSGi manifest that was broken in Compress 1.16.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.16?">
            <ul>
              <li>Support for Zstandard compression.</li>
              <li>Read-only support for DEFLATE64 compression as
              stand-alone <code>CompressorInputStream</code> and as method used in
              ZIP and 7z archives.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.15?">
            <ul>
              <li>Added <code>Automatic-Module-Name</code> so the module
              name will be org.apache.commons.compress when the jar is used
              as an automatic module in Java9+.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.14?">
            <ul>
              <li>Added support for writing the Snappy format</li>
              <li>Added support for the LZ4 compression format</li>
              <li>Added read-only support for Brotli decompression by
              using the <a
              href="https://github.com/google/brotli">Google Brotli
              decoder</a>.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.13?">
            <ul>
              <li>The 7z package as well as
              <code>ZipArchiveOutputStream</code> and
              <code>ZipFile</code> can now use
              <code>SeekableByteChannel</code> when random access is
              needed. This allows archives to be read from inputs and
              written to outputs that are seekable but are not
              represented by <code>File</code>s.</li>
              <li>It is now possible to add Compressor- and
              <code>ArchiverStream</code> implementations using the JDK's
              <code>ServiceLoader</code> mechanism. Please see
              <a href="examples.html#Extending_Commons_Compress">Extending Commons Compress</a>.</li>
              <li>Added support for writing the legacy LZMA format as
              compressor stream and inside 7z archives - this requires
              XZ for Java 1.6.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.12?">
            <ul>
              <li>Added support for the Snappy dialect used in iWork archives.</li>
              <li><code>SevenZFile</code> throws an
              IllegalStateException for empty entries.</li>
              <li>BZip2CompressorOutputStream no longer tries to
              finish the output stream in finalize. This is a breaking
              change for code that relied on the finalizer.</li>
              <li>Various fixes and improvements for tar, cpio
              and zip.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.11?">
            <ul>
              <li>Added read-only support for BZIP2 compression used
              inside of ZIP archives.</li>
              <li>Speed improvements in <code>SevenZFile</code></li>
              <li>Various fixes and improvements for tar, ar, snappy
              and zip.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.10?">
            <ul>
              <li>The old
              <code>org.apache.commons.compress.compressors.z._internal_</code>
              now is
              <code>org.apache.commons.compress.compressors.lzw</code>
              and the code is now an official part of Commons
              Compress' API.</li>
              <li>Added support for parallel ZIP compression.</li>
              <li>Added support for raw transfer of entries from one ZIP file to another without uncompress/compress.</li>
              <li>Performance improvements for creating ZIP files with lots of small entries.</li>
              <li>Added auto-detection for LZMA.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.9?">
            <ul>
              <li>support for raw DEFLATE streams</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.8.1?">
            <p>Compress 1.8.1 is a bug fix release with fixes for the
            tar, ar and snappy formats as well as the
            <code>IOUtils</code> class.  In addition
            <code>CompressorStreamFactory</code> can now autodetect
            the .Z compress format.</p>
          </subsection>
          <subsection name="What's new in 1.8?">
            <ul>
              <li>Bug fixes to the tar, zip and 7z packages</li>
              <li>Access to metadata when reading gzip streams</li>
              <li>Finer grained control over the methods used when
              creating 7z archives and support for some the most
              important filter methods used in 7z archives.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.7?">
            <ul>
              <li>Read-only support for the Snappy compression.</li>
              <li>Read-only support for the traditional Unix compress
              format used for <code>.Z</code> files.</li>
            </ul>
          </subsection>
          <subsection name="What's new in 1.6?">
            <ul>
              <li>Support for the 7z format.</li>
              <li>Read-only support for uncompressed ARJ
              archives.</li>
              <li>Read-only support for the "stand-alone" LZMA
              format.</li>
            </ul>
          </subsection>
        </section>

        <section name="Documentation">
          <p>The compress component is split into <em>compressors</em> and
            <em>archivers</em>.  While <em>compressors</em>
            (un)compress streams that usually store a single
            entry, <em>archivers</em> deal with archives that contain
            structured content represented
            by <code>ArchiveEntry</code> instances which in turn
            usually correspond to single files or directories.</p>

          <p>Currently the bzip2, Pack200, XZ, gzip, lzma, brotli,
            Zstandard and Z formats are
            supported as compressors where gzip support is mostly provided by
            the <code>java.util.zip</code> package of the Java
            class library.  XZ and lzma support is provided by the public
            domain <a href="https://tukaani.org/xz/java.html">XZ for
            Java</a> library.  Brotli support is provided by the MIT
            licensed <a href="https://github.com/google/brotli">Google
            Brotli decoder</a>. Zstandard support is provided by the BSD
            licensed <a href="https://github.com/luben/zstd-jni">Zstd-jni</a>.
            As of Commons Compress 1.21 support for the DEFLATE64, Z and Brotli
            formats is read-only.</p>

          <p>The ar, arj, cpio, dump, tar, 7z and zip formats are supported as
            archivers where the <a href="zip.html">zip</a>
            implementation provides capabilities that go beyond the
            features found in java.util.zip.  As of Commons Compress
            1.21 support for the dump and arj formats is
            read-only - 7z can read most compressed and encrypted
            archives but only write unencrypted ones.  LZMA(2) support
            in 7z requires <a href="https://tukaani.org/xz/java.html">XZ for
            Java</a> as well.</p>

          <p>The compress component provides abstract base classes for
            compressors and archivers together with factories that can
            be used to choose implementations by algorithm name.  In
            the case of input streams the factories can also be used
            to guess the format and provide the matching
            implementation.</p>

          <ul>
            <li>The <a href="examples.html">user guide</a> contains
            more detailed information and some examples.</li>
            <li>The <a href="limitations.html">known limitations and
            problems</a> page lists the currently known problems
            grouped by the format they apply to.</li>
            <li>The <a href="apidocs/index.html">Javadoc</a> of the latest GIT</li>
            <li>The <a href="https://gitbox.apache.org/repos/asf?p=commons-compress.git;a=tree">GIT
                repository</a> can be browsed.</li>
            </ul>
        </section>
        <section name="Releases">
          <p>
            <a href="https://commons.apache.org/compress/download_compress.cgi">Download now!</a>
          </p>
        </section>
    </body>
</document>
