1 /*
   2  * Copyright (c) 2003, 2012, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package java.util.jar;
  26 
  27 import java.util.Objects;
  28 import java.util.SortedMap;
  29 import java.io.InputStream;
  30 import java.io.OutputStream;
  31 import java.io.File;
  32 import java.io.IOException;
  33 import java.beans.PropertyChangeListener;
  34 
  35 
  36 
  37 
  38 /**
  39  * Transforms a JAR file to or from a packed stream in Pack200 format.
  40  * Please refer to Network Transfer Format JSR 200 Specification at
  41  * <a href=http://jcp.org/aboutJava/communityprocess/review/jsr200/index.html>http://jcp.org/aboutJava/communityprocess/review/jsr200/index.html</a>
  42  * <p>
  43  * Typically the packer engine is used by application developers
  44  * to deploy or host JAR files on a website.
  45  * The unpacker  engine is used by deployment applications to
  46  * transform the byte-stream back to JAR format.
  47  * <p>
  48  * Here is an example using  packer and unpacker:<p>
  49  * <blockquote><pre>
  50  *    import java.util.jar.Pack200;
  51  *    import java.util.jar.Pack200.*;
  52  *    ...
  53  *    // Create the Packer object
  54  *    Packer packer = Pack200.newPacker();
  55  *
  56  *    // Initialize the state by setting the desired properties
  57  *    Map p = packer.properties();
  58  *    // take more time choosing codings for better compression
  59  *    p.put(Packer.EFFORT, "7");  // default is "5"
  60  *    // use largest-possible archive segments (>10% better compression).
  61  *    p.put(Packer.SEGMENT_LIMIT, "-1");
  62  *    // reorder files for better compression.
  63  *    p.put(Packer.KEEP_FILE_ORDER, Packer.FALSE);
  64  *    // smear modification times to a single value.
  65  *    p.put(Packer.MODIFICATION_TIME, Packer.LATEST);
  66  *    // ignore all JAR deflation requests,
  67  *    // transmitting a single request to use "store" mode.
  68  *    p.put(Packer.DEFLATE_HINT, Packer.FALSE);
  69  *    // discard debug attributes
  70  *    p.put(Packer.CODE_ATTRIBUTE_PFX+"LineNumberTable", Packer.STRIP);
  71  *    // throw an error if an attribute is unrecognized
  72  *    p.put(Packer.UNKNOWN_ATTRIBUTE, Packer.ERROR);
  73  *    // pass one class file uncompressed:
  74  *    p.put(Packer.PASS_FILE_PFX+0, "mutants/Rogue.class");
  75  *    try {
  76  *        JarFile jarFile = new JarFile("/tmp/testref.jar");
  77  *        FileOutputStream fos = new FileOutputStream("/tmp/test.pack");
  78  *        // Call the packer
  79  *        packer.pack(jarFile, fos);
  80  *        jarFile.close();
  81  *        fos.close();
  82  *
  83  *        File f = new File("/tmp/test.pack");
  84  *        FileOutputStream fostream = new FileOutputStream("/tmp/test.jar");
  85  *        JarOutputStream jostream = new JarOutputStream(fostream);
  86  *        Unpacker unpacker = Pack200.newUnpacker();
  87  *        // Call the unpacker
  88  *        unpacker.unpack(f, jostream);
  89  *        // Must explicitly close the output.
  90  *        jostream.close();
  91  *    } catch (IOException ioe) {
  92  *        ioe.printStackTrace();
  93  *    }
  94  * </pre></blockquote>
  95  * <p>
  96  * A Pack200 file compressed with gzip can be hosted on HTTP/1.1 web servers.
  97  * The deployment applications can use "Accept-Encoding=pack200-gzip". This
  98  * indicates to the server that the client application desires a version of
  99  * the file encoded with Pack200 and further compressed with gzip. Please
 100  * refer to  <a href="{@docRoot}/../technotes/guides/deployment/deployment-guide/pack200.html">Java Deployment Guide</a> for more details and
 101  * techniques.
 102  * <p>
 103  * Unless otherwise noted, passing a <tt>null</tt> argument to a constructor or
 104  * method in this class will cause a {@link NullPointerException} to be thrown.
 105  *
 106  * @author John Rose
 107  * @author Kumar Srinivasan
 108  * @since 1.5
 109  */
 110 public abstract class Pack200 {
 111     private Pack200() {} //prevent instantiation
 112 
 113     // Static methods of the Pack200 class.
 114     /**
 115      * Obtain new instance of a class that implements Packer.
 116      *
 117      * <li><p>If the system property <tt>java.util.jar.Pack200.Packer</tt>
 118      * is defined, then the value is taken to be the fully-qualified name
 119      * of a concrete implementation class, which must implement Packer.
 120      * This class is loaded and instantiated.  If this process fails
 121      * then an unspecified error is thrown.</p></li>
 122      *
 123      * <li><p>If an implementation has not been specified with the system
 124      * property, then the system-default implementation class is instantiated,
 125      * and the result is returned.</p></li>
 126      *
 127      * <p>Note:  The returned object is not guaranteed to operate
 128      * correctly if multiple threads use it at the same time.
 129      * A multi-threaded application should either allocate multiple
 130      * packer engines, or else serialize use of one engine with a lock.
 131      *
 132      * @return  A newly allocated Packer engine.
 133      */
 134     public synchronized static Packer newPacker() {
 135         return (Packer) newInstance(PACK_PROVIDER);
 136     }
 137 
 138 
 139     /**
 140      * Obtain new instance of a class that implements Unpacker.
 141      *
 142      * <li><p>If the system property <tt>java.util.jar.Pack200.Unpacker</tt>
 143      * is defined, then the value is taken to be the fully-qualified
 144      * name of a concrete implementation class, which must implement Unpacker.
 145      * The class is loaded and instantiated.  If this process fails
 146      * then an unspecified error is thrown.</p></li>
 147      *
 148      * <li><p>If an implementation has not been specified with the
 149      * system property, then the system-default implementation class
 150      * is instantiated, and the result is returned.</p></li>
 151      *
 152      * <p>Note:  The returned object is not guaranteed to operate
 153      * correctly if multiple threads use it at the same time.
 154      * A multi-threaded application should either allocate multiple
 155      * unpacker engines, or else serialize use of one engine with a lock.
 156      *
 157      * @return  A newly allocated Unpacker engine.
 158      */
 159 
 160     public static Unpacker newUnpacker() {
 161         return (Unpacker) newInstance(UNPACK_PROVIDER);
 162     }
 163 
 164     // Interfaces
 165     /**
 166      * The packer engine applies various transformations to the input JAR file,
 167      * making the pack stream highly compressible by a compressor such as
 168      * gzip or zip. An instance of the engine can be obtained
 169      * using {@link #newPacker}.
 170 
 171      * The high degree of compression is achieved
 172      * by using a number of techniques described in the JSR 200 specification.
 173      * Some of the techniques are sorting, re-ordering and co-location of the
 174      * constant pool.
 175      * <p>
 176      * The pack engine is initialized to an initial state as described
 177      * by their properties below.
 178      * The initial state can be manipulated by getting the
 179      * engine properties (using {@link #properties}) and storing
 180      * the modified properties on the map.
 181      * The resource files will be passed through with no changes at all.
 182      * The class files will not contain identical bytes, since the unpacker
 183      * is free to change minor class file features such as constant pool order.
 184      * However, the class files will be semantically identical,
 185      * as specified in
 186      * <cite>The Java&trade; Virtual Machine Specification</cite>.
 187      * <p>
 188      * By default, the packer does not change the order of JAR elements.
 189      * Also, the modification time and deflation hint of each
 190      * JAR element is passed unchanged.
 191      * (Any other ZIP-archive information, such as extra attributes
 192      * giving Unix file permissions, are lost.)
 193      * <p>
 194      * Note that packing and unpacking a JAR will in general alter the
 195      * bytewise contents of classfiles in the JAR.  This means that packing
 196      * and unpacking will in general invalidate any digital signatures
 197      * which rely on bytewise images of JAR elements.  In order both to sign
 198      * and to pack a JAR, you must first pack and unpack the JAR to
 199      * "normalize" it, then compute signatures on the unpacked JAR elements,
 200      * and finally repack the signed JAR.
 201      * Both packing steps should
 202      * use precisely the same options, and the segment limit may also
 203      * need to be set to "-1", to prevent accidental variation of segment
 204      * boundaries as class file sizes change slightly.
 205      * <p>
 206      * (Here's why this works:  Any reordering the packer does
 207      * of any classfile structures is idempotent, so the second packing
 208      * does not change the orderings produced by the first packing.
 209      * Also, the unpacker is guaranteed by the JSR 200 specification
 210      * to produce a specific bytewise image for any given transmission
 211      * ordering of archive elements.)
 212      * <p>
 213      * In order to maintain backward compatibility, the pack file's version is
 214      * set to accommodate the class files present in the input JAR file. In
 215      * other words, the pack file version will be the latest, if the class files
 216      * are the latest and conversely the pack file version will be the oldest
 217      * if the class file versions are also the oldest. For intermediate class
 218      * file versions the corresponding pack file version will be used.
 219      * For example:
 220      *    If the input JAR-files are solely comprised of 1.5  (or  lesser)
 221      * class files, a 1.5 compatible pack file is  produced. This will also be
 222      * the case for archives that have no class files.
 223      *    If the input JAR-files contains a 1.6 class file, then the pack file
 224      * version will be set to 1.6.
 225      * <p>
 226      * Note: Unless otherwise noted, passing a <tt>null</tt> argument to a
 227      * constructor or method in this class will cause a {@link NullPointerException}
 228      * to be thrown.
 229      * <p>
 230      * @since 1.5
 231      */
 232     public interface Packer {
 233         /**
 234          * This property is a numeral giving the estimated target size N
 235          * (in bytes) of each archive segment.
 236          * If a single input file requires more than N bytes,
 237          * it will be given its own archive segment.
 238          * <p>
 239          * As a special case, a value of -1 will produce a single large
 240          * segment with all input files, while a value of 0 will
 241          * produce one segment for each class.
 242          * Larger archive segments result in less fragmentation and
 243          * better compression, but processing them requires more memory.
 244          * <p>
 245          * The size of each segment is estimated by counting the size of each
 246          * input file to be transmitted in the segment, along with the size
 247          * of its name and other transmitted properties.
 248          * <p>
 249          * The default is -1, which means the packer will always create a single
 250          * segment output file. In cases where extremely large output files are
 251          * generated, users are strongly encouraged to use segmenting or break
 252          * up the input file into smaller JARs.
 253          * <p>
 254          * A 10Mb JAR packed without this limit will
 255          * typically pack about 10% smaller, but the packer may require
 256          * a larger Java heap (about ten times the segment limit).
 257          */
 258         String SEGMENT_LIMIT    = "pack.segment.limit";
 259 
 260         /**
 261          * If this property is set to {@link #TRUE}, the packer will transmit
 262          * all elements in their original order within the source archive.
 263          * <p>
 264          * If it is set to {@link #FALSE}, the packer may reorder elements,
 265          * and also remove JAR directory entries, which carry no useful
 266          * information for Java applications.
 267          * (Typically this enables better compression.)
 268          * <p>
 269          * The default is {@link #TRUE}, which preserves the input information,
 270          * but may cause the transmitted archive to be larger than necessary.
 271          */
 272         String KEEP_FILE_ORDER = "pack.keep.file.order";
 273 
 274 
 275         /**
 276          * If this property is set to a single decimal digit, the packer will
 277          * use the indicated amount of effort in compressing the archive.
 278          * Level 1 may produce somewhat larger size and faster compression speed,
 279          * while level 9 will take much longer but may produce better compression.
 280          * <p>
 281          * The special value 0 instructs the packer to copy through the
 282          * original JAR file directly, with no compression.  The JSR 200
 283          * standard requires any unpacker to understand this special case
 284          * as a pass-through of the entire archive.
 285          * <p>
 286          * The default is 5, investing a modest amount of time to
 287          * produce reasonable compression.
 288          */
 289         String EFFORT           = "pack.effort";
 290 
 291         /**
 292          * If this property is set to {@link #TRUE} or {@link #FALSE}, the packer
 293          * will set the deflation hint accordingly in the output archive, and
 294          * will not transmit the individual deflation hints of archive elements.
 295          * <p>
 296          * If this property is set to the special string {@link #KEEP}, the packer
 297          * will attempt to determine an independent deflation hint for each
 298          * available element of the input archive, and transmit this hint separately.
 299          * <p>
 300          * The default is {@link #KEEP}, which preserves the input information,
 301          * but may cause the transmitted archive to be larger than necessary.
 302          * <p>
 303          * It is up to the unpacker implementation
 304          * to take action upon the hint to suitably compress the elements of
 305          * the resulting unpacked jar.
 306          * <p>
 307          * The deflation hint of a ZIP or JAR element indicates
 308          * whether the element was deflated or stored directly.
 309          */
 310         String DEFLATE_HINT     = "pack.deflate.hint";
 311 
 312         /**
 313          * If this property is set to the special string {@link #LATEST},
 314          * the packer will attempt to determine the latest modification time,
 315          * among all the available entries in the original archive or the latest
 316          * modification time of all the available entries in each segment.
 317          * This single value will be transmitted as part of the segment and applied
 318          * to all the entries in each segment, {@link #SEGMENT_LIMIT}.
 319          * <p>
 320          * This can marginally decrease the transmitted size of the
 321          * archive, at the expense of setting all installed files to a single
 322          * date.
 323          * <p>
 324          * If this property is set to the special string {@link #KEEP},
 325          * the packer transmits a separate modification time for each input
 326          * element.
 327          * <p>
 328          * The default is {@link #KEEP}, which preserves the input information,
 329          * but may cause the transmitted archive to be larger than necessary.
 330          * <p>
 331          * It is up to the unpacker implementation to take action to suitably
 332          * set the modification time of each element of its output file.
 333          * @see #SEGMENT_LIMIT
 334          */
 335         String MODIFICATION_TIME        = "pack.modification.time";
 336 
 337         /**
 338          * Indicates that a file should be passed through bytewise, with no
 339          * compression.  Multiple files may be specified by specifying
 340          * additional properties with distinct strings appended, to
 341          * make a family of properties with the common prefix.
 342          * <p>
 343          * There is no pathname transformation, except
 344          * that the system file separator is replaced by the JAR file
 345          * separator '/'.
 346          * <p>
 347          * The resulting file names must match exactly as strings with their
 348          * occurrences in the JAR file.
 349          * <p>
 350          * If a property value is a directory name, all files under that
 351          * directory will be passed also.
 352          * <p>
 353          * Examples:
 354          * <pre><code>
 355          *     Map p = packer.properties();
 356          *     p.put(PASS_FILE_PFX+0, "mutants/Rogue.class");
 357          *     p.put(PASS_FILE_PFX+1, "mutants/Wolverine.class");
 358          *     p.put(PASS_FILE_PFX+2, "mutants/Storm.class");
 359          *     # Pass all files in an entire directory hierarchy:
 360          *     p.put(PASS_FILE_PFX+3, "police/");
 361          * </pre></code>.
 362          */
 363         String PASS_FILE_PFX            = "pack.pass.file.";
 364 
 365         /// Attribute control.
 366 
 367         /**
 368          * Indicates the action to take when a class-file containing an unknown
 369          * attribute is encountered.  Possible values are the strings {@link #ERROR},
 370          * {@link #STRIP}, and {@link #PASS}.
 371          * <p>
 372          * The string {@link #ERROR} means that the pack operation
 373          * as a whole will fail, with an exception of type <code>IOException</code>.
 374          * The string
 375          * {@link #STRIP} means that the attribute will be dropped.
 376          * The string
 377          * {@link #PASS} means that the whole class-file will be passed through
 378          * (as if it were a resource file) without compression, with  a suitable warning.
 379          * This is the default value for this property.
 380          * <p>
 381          * Examples:
 382          * <pre><code>
 383          *     Map p = pack200.getProperties();
 384          *     p.put(UNKNOWN_ATTRIBUTE, ERROR);
 385          *     p.put(UNKNOWN_ATTRIBUTE, STRIP);
 386          *     p.put(UNKNOWN_ATTRIBUTE, PASS);
 387          * </pre></code>
 388          */
 389         String UNKNOWN_ATTRIBUTE        = "pack.unknown.attribute";
 390 
 391         /**
 392          * When concatenated with a class attribute name,
 393          * indicates the format of that attribute,
 394          * using the layout language specified in the JSR 200 specification.
 395          * <p>
 396          * For example, the effect of this option is built in:
 397          * <code>pack.class.attribute.SourceFile=RUH</code>.
 398          * <p>
 399          * The special strings {@link #ERROR}, {@link #STRIP}, and {@link #PASS} are
 400          * also allowed, with the same meaning as {@link #UNKNOWN_ATTRIBUTE}.
 401          * This provides a way for users to request that specific attributes be
 402          * refused, stripped, or passed bitwise (with no class compression).
 403          * <p>
 404          * Code like this might be used to support attributes for JCOV:
 405          * <pre><code>
 406          *     Map p = packer.properties();
 407          *     p.put(CODE_ATTRIBUTE_PFX+"CoverageTable",       "NH[PHHII]");
 408          *     p.put(CODE_ATTRIBUTE_PFX+"CharacterRangeTable", "NH[PHPOHIIH]");
 409          *     p.put(CLASS_ATTRIBUTE_PFX+"SourceID",           "RUH");
 410          *     p.put(CLASS_ATTRIBUTE_PFX+"CompilationID",      "RUH");
 411          * </code></pre>
 412          * <p>
 413          * Code like this might be used to strip debugging attributes:
 414          * <pre><code>
 415          *     Map p = packer.properties();
 416          *     p.put(CODE_ATTRIBUTE_PFX+"LineNumberTable",    STRIP);
 417          *     p.put(CODE_ATTRIBUTE_PFX+"LocalVariableTable", STRIP);
 418          *     p.put(CLASS_ATTRIBUTE_PFX+"SourceFile",        STRIP);
 419          * </code></pre>
 420          */
 421         String CLASS_ATTRIBUTE_PFX      = "pack.class.attribute.";
 422 
 423         /**
 424          * When concatenated with a field attribute name,
 425          * indicates the format of that attribute.
 426          * For example, the effect of this option is built in:
 427          * <code>pack.field.attribute.Deprecated=</code>.
 428          * The special strings {@link #ERROR}, {@link #STRIP}, and
 429          * {@link #PASS} are also allowed.
 430          * @see #CLASS_ATTRIBUTE_PFX
 431          */
 432         String FIELD_ATTRIBUTE_PFX      = "pack.field.attribute.";
 433 
 434         /**
 435          * When concatenated with a method attribute name,
 436          * indicates the format of that attribute.
 437          * For example, the effect of this option is built in:
 438          * <code>pack.method.attribute.Exceptions=NH[RCH]</code>.
 439          * The special strings {@link #ERROR}, {@link #STRIP}, and {@link #PASS}
 440          * are also allowed.
 441          * @see #CLASS_ATTRIBUTE_PFX
 442          */
 443         String METHOD_ATTRIBUTE_PFX     = "pack.method.attribute.";
 444 
 445         /**
 446          * When concatenated with a code attribute name,
 447          * indicates the format of that attribute.
 448          * For example, the effect of this option is built in:
 449          * <code>pack.code.attribute.LocalVariableTable=NH[PHOHRUHRSHH]</code>.
 450          * The special strings {@link #ERROR}, {@link #STRIP}, and {@link #PASS}
 451          * are also allowed.
 452          * @see #CLASS_ATTRIBUTE_PFX
 453          */
 454         String CODE_ATTRIBUTE_PFX       = "pack.code.attribute.";
 455 
 456         /**
 457          * The unpacker's progress as a percentage, as periodically
 458          * updated by the unpacker.
 459          * Values of 0 - 100 are normal, and -1 indicates a stall.
 460          * Progress can be monitored by polling the value of this
 461          * property.
 462          * <p>
 463          * At a minimum, the unpacker must set progress to 0
 464          * at the beginning of a packing operation, and to 100
 465          * at the end.
 466          */
 467         String PROGRESS                 = "pack.progress";
 468 
 469         /** The string "keep", a possible value for certain properties.
 470          * @see #DEFLATE_HINT
 471          * @see #MODIFICATION_TIME
 472          */
 473         String KEEP  = "keep";
 474 
 475         /** The string "pass", a possible value for certain properties.
 476          * @see #UNKNOWN_ATTRIBUTE
 477          * @see #CLASS_ATTRIBUTE_PFX
 478          * @see #FIELD_ATTRIBUTE_PFX
 479          * @see #METHOD_ATTRIBUTE_PFX
 480          * @see #CODE_ATTRIBUTE_PFX
 481          */
 482         String PASS  = "pass";
 483 
 484         /** The string "strip", a possible value for certain properties.
 485          * @see #UNKNOWN_ATTRIBUTE
 486          * @see #CLASS_ATTRIBUTE_PFX
 487          * @see #FIELD_ATTRIBUTE_PFX
 488          * @see #METHOD_ATTRIBUTE_PFX
 489          * @see #CODE_ATTRIBUTE_PFX
 490          */
 491         String STRIP = "strip";
 492 
 493         /** The string "error", a possible value for certain properties.
 494          * @see #UNKNOWN_ATTRIBUTE
 495          * @see #CLASS_ATTRIBUTE_PFX
 496          * @see #FIELD_ATTRIBUTE_PFX
 497          * @see #METHOD_ATTRIBUTE_PFX
 498          * @see #CODE_ATTRIBUTE_PFX
 499          */
 500         String ERROR = "error";
 501 
 502         /** The string "true", a possible value for certain properties.
 503          * @see #KEEP_FILE_ORDER
 504          * @see #DEFLATE_HINT
 505          */
 506         String TRUE = "true";
 507 
 508         /** The string "false", a possible value for certain properties.
 509          * @see #KEEP_FILE_ORDER
 510          * @see #DEFLATE_HINT
 511          */
 512         String FALSE = "false";
 513 
 514         /** The string "latest", a possible value for certain properties.
 515          * @see #MODIFICATION_TIME
 516          */
 517         String LATEST = "latest";
 518 
 519         /**
 520          * Get the set of this engine's properties.
 521          * This set is a "live view", so that changing its
 522          * contents immediately affects the Packer engine, and
 523          * changes from the engine (such as progress indications)
 524          * are immediately visible in the map.
 525          *
 526          * <p>The property map may contain pre-defined implementation
 527          * specific and default properties.  Users are encouraged to
 528          * read the information and fully understand the implications,
 529          * before modifying pre-existing properties.
 530          * <p>
 531          * Implementation specific properties are prefixed with a
 532          * package name associated with the implementor, beginning
 533          * with <tt>com.</tt> or a similar prefix.
 534          * All property names beginning with <tt>pack.</tt> and
 535          * <tt>unpack.</tt> are reserved for use by this API.
 536          * <p>
 537          * Unknown properties may be ignored or rejected with an
 538          * unspecified error, and invalid entries may cause an
 539          * unspecified error to be thrown.
 540          *
 541          * <p>
 542          * The returned map implements all optional {@link SortedMap} operations
 543          * @return A sorted association of property key strings to property
 544          * values.
 545          */
 546         SortedMap<String,String> properties();
 547 
 548         /**
 549          * Takes a JarFile and converts it into a Pack200 archive.
 550          * <p>
 551          * Closes its input but not its output.  (Pack200 archives are appendable.)
 552          * @param in a JarFile
 553          * @param out an OutputStream
 554          * @exception IOException if an error is encountered.
 555          */
 556         void pack(JarFile in, OutputStream out) throws IOException ;
 557 
 558         /**
 559          * Takes a JarInputStream and converts it into a Pack200 archive.
 560          * <p>
 561          * Closes its input but not its output.  (Pack200 archives are appendable.)
 562          * <p>
 563          * The modification time and deflation hint attributes are not available,
 564          * for the JAR manifest file and its containing directory.
 565          *
 566          * @see #MODIFICATION_TIME
 567          * @see #DEFLATE_HINT
 568          * @param in a JarInputStream
 569          * @param out an OutputStream
 570          * @exception IOException if an error is encountered.
 571          */
 572         void pack(JarInputStream in, OutputStream out) throws IOException ;
 573 
 574         /**
 575          * Registers a listener for PropertyChange events on the properties map.
 576          * This is typically used by applications to update a progress bar.
 577          *
 578          * <p><b>WARNING:</b> This method is not a declared method of this interface
 579          * in a subset Profile of Java SE. In other words, this method does not exist
 580          * on runtimes that only implement a profile of Java SE.</p>
 581 
 582          * @see #properties
 583          * @see #PROGRESS
 584          * @param listener  An object to be invoked when a property is changed.
 585          * @deprecated The dependency on {@code PropertyChangeListener} creates
 586          *             a significant impediment to future modularization of the
 587          *             Java platform. This method will be removed in a future
 588          *             release.
 589          *             Applications that need to monitor progress of the packer
 590          *             can poll the value of the {@link #PROGRESS PROGRESS}
 591          *             property instead.
 592          */
 593         @Deprecated
 594         default void addPropertyChangeListener(PropertyChangeListener listener) {
 595             Objects.requireNonNull(listener);
 596         }
 597 
 598         /**
 599          * Remove a listener for PropertyChange events, added by
 600          * the {@link #addPropertyChangeListener}.
 601          *
 602          * <p><b>WARNING:</b> This method is not a declared method of this interface
 603          * in a subset Profile of Java SE. In other words, this method does not exist
 604          * on runtimes that only implement a profile of Java SE.</p>
 605          *
 606          * @see #addPropertyChangeListener
 607          * @param listener  The PropertyChange listener to be removed.
 608          * @deprecated The dependency on {@code PropertyChangeListener} creates
 609          *             a significant impediment to future modularization of the
 610          *             Java platform. This method will be removed in a future
 611          *             release.
 612          */
 613         @Deprecated
 614         default void removePropertyChangeListener(PropertyChangeListener listener) {
 615             Objects.requireNonNull(listener);
 616         }
 617     }
 618 
 619     /**
 620      * The unpacker engine converts the packed stream to a JAR file.
 621      * An instance of the engine can be obtained
 622      * using {@link #newUnpacker}.
 623      * <p>
 624      * Every JAR file produced by this engine will include the string
 625      * "<tt>PACK200</tt>" as a zip file comment.
 626      * This allows a deployer to detect if a JAR archive was packed and unpacked.
 627      * <p>
 628      * Note: Unless otherwise noted, passing a <tt>null</tt> argument to a
 629      * constructor or method in this class will cause a {@link NullPointerException}
 630      * to be thrown.
 631      * <p>
 632      * This version of the unpacker is compatible with all previous versions.
 633      * @since 1.5
 634      */
 635     public interface Unpacker {
 636 
 637         /** The string "keep", a possible value for certain properties.
 638          * @see #DEFLATE_HINT
 639          */
 640         String KEEP  = "keep";
 641 
 642         /** The string "true", a possible value for certain properties.
 643          * @see #DEFLATE_HINT
 644          */
 645         String TRUE = "true";
 646 
 647         /** The string "false", a possible value for certain properties.
 648          * @see #DEFLATE_HINT
 649          */
 650         String FALSE = "false";
 651 
 652         /**
 653          * Property indicating that the unpacker should
 654          * ignore all transmitted values for DEFLATE_HINT,
 655          * replacing them by the given value, {@link #TRUE} or {@link #FALSE}.
 656          * The default value is the special string {@link #KEEP},
 657          * which asks the unpacker to preserve all transmitted
 658          * deflation hints.
 659          */
 660         String DEFLATE_HINT      = "unpack.deflate.hint";
 661 
 662 
 663 
 664         /**
 665          * The unpacker's progress as a percentage, as periodically
 666          * updated by the unpacker.
 667          * Values of 0 - 100 are normal, and -1 indicates a stall.
 668          * Progress can be monitored by polling the value of this
 669          * property.
 670          * <p>
 671          * At a minimum, the unpacker must set progress to 0
 672          * at the beginning of a packing operation, and to 100
 673          * at the end.
 674          */
 675         String PROGRESS         = "unpack.progress";
 676 
 677         /**
 678          * Get the set of this engine's properties. This set is
 679          * a "live view", so that changing its
 680          * contents immediately affects the Packer engine, and
 681          * changes from the engine (such as progress indications)
 682          * are immediately visible in the map.
 683          *
 684          * <p>The property map may contain pre-defined implementation
 685          * specific and default properties.  Users are encouraged to
 686          * read the information and fully understand the implications,
 687          * before modifying pre-existing properties.
 688          * <p>
 689          * Implementation specific properties are prefixed with a
 690          * package name associated with the implementor, beginning
 691          * with <tt>com.</tt> or a similar prefix.
 692          * All property names beginning with <tt>pack.</tt> and
 693          * <tt>unpack.</tt> are reserved for use by this API.
 694          * <p>
 695          * Unknown properties may be ignored or rejected with an
 696          * unspecified error, and invalid entries may cause an
 697          * unspecified error to be thrown.
 698          *
 699          * @return A sorted association of option key strings to option values.
 700          */
 701         SortedMap<String,String> properties();
 702 
 703         /**
 704          * Read a Pack200 archive, and write the encoded JAR to
 705          * a JarOutputStream.
 706          * The entire contents of the input stream will be read.
 707          * It may be more efficient to read the Pack200 archive
 708          * to a file and pass the File object, using the alternate
 709          * method described below.
 710          * <p>
 711          * Closes its input but not its output.  (The output can accumulate more elements.)
 712          * @param in an InputStream.
 713          * @param out a JarOutputStream.
 714          * @exception IOException if an error is encountered.
 715          */
 716         void unpack(InputStream in, JarOutputStream out) throws IOException;
 717 
 718         /**
 719          * Read a Pack200 archive, and write the encoded JAR to
 720          * a JarOutputStream.
 721          * <p>
 722          * Does not close its output.  (The output can accumulate more elements.)
 723          * @param in a File.
 724          * @param out a JarOutputStream.
 725          * @exception IOException if an error is encountered.
 726          */
 727         void unpack(File in, JarOutputStream out) throws IOException;
 728 
 729         /**
 730          * Registers a listener for PropertyChange events on the properties map.
 731          * This is typically used by applications to update a progress bar.
 732          *
 733          * <p><b>WARNING:</b> This method is not a declared method of this interface
 734          * in a subset Profile of Java SE. In other words, this method does not exist
 735          * on runtimes that only implement a profile of Java SE.</p>
 736          *
 737          * @see #properties
 738          * @see #PROGRESS
 739          * @param listener  An object to be invoked when a property is changed.
 740          * @deprecated The dependency on {@code PropertyChangeListener} creates
 741          *             a significant impediment to future modularization of the
 742          *             Java platform. This method will be removed in a future
 743          *             release.
 744          *             Applications that need to monitor progress of the
 745          *             unpacker can poll the value of the {@link #PROGRESS
 746          *             PROGRESS} property instead.
 747          */
 748         @Deprecated
 749         default void addPropertyChangeListener(PropertyChangeListener listener) {
 750             Objects.requireNonNull(listener);
 751         }
 752 
 753         /**
 754          * Remove a listener for PropertyChange events, added by
 755          * the {@link #addPropertyChangeListener}.
 756          *
 757          * <p><b>WARNING:</b> This method is not a declared method of this interface
 758          * in a subset Profile of Java SE. In other words, this method does not exist
 759          * on runtimes that only implement a profile of Java SE.</p>
 760          *
 761          * @see #addPropertyChangeListener
 762          * @param listener  The PropertyChange listener to be removed.
 763          * @deprecated The dependency on {@code PropertyChangeListener} creates
 764          *             a significant impediment to future modularization of the
 765          *             Java platform. This method will be removed in a future
 766          *             release.
 767          */
 768         @Deprecated
 769         default void removePropertyChangeListener(PropertyChangeListener listener) {
 770             Objects.requireNonNull(listener);
 771         }
 772     }
 773 
 774     // Private stuff....
 775 
 776     private static final String PACK_PROVIDER = "java.util.jar.Pack200.Packer";
 777     private static final String UNPACK_PROVIDER = "java.util.jar.Pack200.Unpacker";
 778 
 779     private static Class<?> packerImpl;
 780     private static Class<?> unpackerImpl;
 781 
 782     private synchronized static Object newInstance(String prop) {
 783         String implName = "(unknown)";
 784         try {
 785             Class<?> impl = (PACK_PROVIDER.equals(prop))? packerImpl: unpackerImpl;
 786             if (impl == null) {
 787                 // The first time, we must decide which class to use.
 788                 implName = java.security.AccessController.doPrivileged(
 789                     new sun.security.action.GetPropertyAction(prop,""));
 790                 if (implName != null && !implName.equals(""))
 791                     impl = Class.forName(implName);
 792                 else if (PACK_PROVIDER.equals(prop))
 793                     impl = com.sun.java.util.jar.pack.PackerImpl.class;
 794                 else
 795                     impl = com.sun.java.util.jar.pack.UnpackerImpl.class;
 796             }
 797             // We have a class.  Now instantiate it.
 798             return impl.newInstance();
 799         } catch (ClassNotFoundException e) {
 800             throw new Error("Class not found: " + implName +
 801                                 ":\ncheck property " + prop +
 802                                 " in your properties file.", e);
 803         } catch (InstantiationException e) {
 804             throw new Error("Could not instantiate: " + implName +
 805                                 ":\ncheck property " + prop +
 806                                 " in your properties file.", e);
 807         } catch (IllegalAccessException e) {
 808             throw new Error("Cannot access class: " + implName +
 809                                 ":\ncheck property " + prop +
 810                                 " in your properties file.", e);
 811         }
 812     }
 813 
 814 }