1<?xml version="1.0"?>
2<!--
3
4   Licensed to the Apache Software Foundation (ASF) under one or more
5   contributor license agreements.  See the NOTICE file distributed with
6   this work for additional information regarding copyright ownership.
7   The ASF licenses this file to You under the Apache License, Version 2.0
8   (the "License"); you may not use this file except in compliance with
9   the License.  You may obtain a copy of the License at
10
11       http://www.apache.org/licenses/LICENSE-2.0
12
13   Unless required by applicable law or agreed to in writing, software
14   distributed under the License is distributed on an "AS IS" BASIS,
15   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   See the License for the specific language governing permissions and
17   limitations under the License.
18
19-->
20<document>
21  <properties>
22    <title>Commons Compress Pack200 Package</title>
23    <author email="dev@commons.apache.org">Commons Documentation Team</author>
24  </properties>
25  <body>
26    <section name="The Pack200 package">
27
28      <p>The Pack200 algorithm is not a general purpose compression
29      algorithm but one specialized for compressing JAR archives.  JAR
30      archives compressed with Pack200 will in general be different
31      from the original archive when decompressed again.  More
32      information can be found in the Javadocs of the <a
33      href="https://docs.oracle.com/javase/7/docs/api/java/util/jar/Pack200.Packer.html">Pack200.Packer
34      class</a>.</p>
35
36      <p>While the <code>pack200</code> command line utility of the
37      JDK creates GZip compressed archives (<code>.pack.gz</code>) by
38      default, the streams provided by the Pack200 package only
39      perform the actual Pack200 operation.  Wrap them in an
40      additional <code>GzipCompressor(In|Out)putStream</code> in order to deal
41      with deflated streams.</p>
42
43      <subsection name="Pack200Strategy">
44
45        <p>The Pack200-API provided by the java class library is not
46        streaming friendly as it wants to consume its input completely
47        in a single operation.  Because of this
48        <code>Pack200CompressorInputStream</code>'s constructor will immediately
49        unpack the stream, cache the results and provide an input
50        stream to the cache.</p>
51
52        <p><code>Pack200CompressorOutputStream</code> will cache all data that
53        is written to it and then pack it once the <code>finish</code>
54        or <code>close</code> method is called.</p>
55
56        <p>Two different caching modes are available - "in memory",
57        which is the default, and "temporary file".  By default data
58        is cached in memory but you should switch to the temporary
59        file option if your archives are really big.</p>
60
61        <p>Given there always is an intermediate result
62        the <code>getBytesRead</code> and <code>getCount</code>
63        methods of <code>Pack200CompressorInputStream</code> are
64        meaningless (read from the real stream or from the
65        intermediate result?)  and always return 0.</p>
66
67      </subsection>
68
69      <subsection name="Normalization">
70
71        <p>As a pack/unpack cycle may create a JAR archive that is
72        different from the original, digital signatures created for
73        the initial JAR will be broken by the process.  There is a way
74        to "normalize" JAR archives prior to packing them that ensures
75        signatures applied to the "normalized" JAR will still be valid
76        aftre a pack/unpack cycle - see <a
77        href="https://download.oracle.com/javase/7/docs/api/java/util/jar/Pack200.Packer.html">Pack200.Packer</a>'s
78        javadocs.</p>
79
80        <p>The <code>Pack200Utils</code> class in the
81        <code>pack200</code> package provides several overloads of a
82        <code>normalize</code> method that can be used to prepare a
83        JAR archive in place or to a separate file.</p>
84
85      </subsection>
86
87    </section>
88</body>
89</document>
90