| /* |
| * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| package java.util.jar; |
| |
| import java.util.SortedMap; |
| import java.io.InputStream; |
| import java.io.OutputStream; |
| import java.io.File; |
| import java.io.IOException; |
| import java.beans.PropertyChangeListener; |
| |
| |
| |
| |
| /** |
| * Transforms a JAR file to or from a packed stream in Pack200 format. |
| * Please refer to Network Transfer Format JSR 200 Specification at |
| * <a href=http://jcp.org/aboutJava/communityprocess/review/jsr200/index.html>http://jcp.org/aboutJava/communityprocess/review/jsr200/index.html</a> |
| * <p> |
| * Typically the packer engine is used by application developers |
| * to deploy or host JAR files on a website. |
| * The unpacker engine is used by deployment applications to |
| * transform the byte-stream back to JAR format. |
| * <p> |
| * Here is an example using packer and unpacker: |
| * <pre>{@code |
| * import java.util.jar.Pack200; |
| * import java.util.jar.Pack200.*; |
| * ... |
| * // Create the Packer object |
| * Packer packer = Pack200.newPacker(); |
| * |
| * // Initialize the state by setting the desired properties |
| * Map p = packer.properties(); |
| * // take more time choosing codings for better compression |
| * p.put(Packer.EFFORT, "7"); // default is "5" |
| * // use largest-possible archive segments (>10% better compression). |
| * p.put(Packer.SEGMENT_LIMIT, "-1"); |
| * // reorder files for better compression. |
| * p.put(Packer.KEEP_FILE_ORDER, Packer.FALSE); |
| * // smear modification times to a single value. |
| * p.put(Packer.MODIFICATION_TIME, Packer.LATEST); |
| * // ignore all JAR deflation requests, |
| * // transmitting a single request to use "store" mode. |
| * p.put(Packer.DEFLATE_HINT, Packer.FALSE); |
| * // discard debug attributes |
| * p.put(Packer.CODE_ATTRIBUTE_PFX+"LineNumberTable", Packer.STRIP); |
| * // throw an error if an attribute is unrecognized |
| * p.put(Packer.UNKNOWN_ATTRIBUTE, Packer.ERROR); |
| * // pass one class file uncompressed: |
| * p.put(Packer.PASS_FILE_PFX+0, "mutants/Rogue.class"); |
| * try { |
| * JarFile jarFile = new JarFile("/tmp/testref.jar"); |
| * FileOutputStream fos = new FileOutputStream("/tmp/test.pack"); |
| * // Call the packer |
| * packer.pack(jarFile, fos); |
| * jarFile.close(); |
| * fos.close(); |
| * |
| * File f = new File("/tmp/test.pack"); |
| * FileOutputStream fostream = new FileOutputStream("/tmp/test.jar"); |
| * JarOutputStream jostream = new JarOutputStream(fostream); |
| * Unpacker unpacker = Pack200.newUnpacker(); |
| * // Call the unpacker |
| * unpacker.unpack(f, jostream); |
| * // Must explicitly close the output. |
| * jostream.close(); |
| * } catch (IOException ioe) { |
| * ioe.printStackTrace(); |
| * } |
| * }</pre> |
| * <p> |
| * A Pack200 file compressed with gzip can be hosted on HTTP/1.1 web servers. |
| * The deployment applications can use "Accept-Encoding=pack200-gzip". This |
| * indicates to the server that the client application desires a version of |
| * the file encoded with Pack200 and further compressed with gzip. Please |
| * refer to <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/deployment/deployment-guide/pack200.html">Java Deployment Guide</a> for more details and |
| * techniques. |
| * <p> |
| * Unless otherwise noted, passing a <tt>null</tt> argument to a constructor or |
| * method in this class will cause a {@link NullPointerException} to be thrown. |
| * |
| * @author John Rose |
| * @author Kumar Srinivasan |
| * @since 1.5 |
| */ |
| public abstract class Pack200 { |
| private Pack200() {} //prevent instantiation |
| |
| // Static methods of the Pack200 class. |
| /** |
| * Obtain new instance of a class that implements Packer. |
| * <ul> |
| * <li><p>If the system property <tt>java.util.jar.Pack200.Packer</tt> |
| * is defined, then the value is taken to be the fully-qualified name |
| * of a concrete implementation class, which must implement Packer. |
| * This class is loaded and instantiated. If this process fails |
| * then an unspecified error is thrown.</p></li> |
| * |
| * <li><p>If an implementation has not been specified with the system |
| * property, then the system-default implementation class is instantiated, |
| * and the result is returned.</p></li> |
| * </ul> |
| * |
| * <p>Note: The returned object is not guaranteed to operate |
| * correctly if multiple threads use it at the same time. |
| * A multi-threaded application should either allocate multiple |
| * packer engines, or else serialize use of one engine with a lock. |
| * |
| * @return A newly allocated Packer engine. |
| */ |
| public synchronized static Packer newPacker() { |
| return (Packer) newInstance(PACK_PROVIDER); |
| } |
| |
| |
| /** |
| * Obtain new instance of a class that implements Unpacker. |
| * <ul> |
| * <li><p>If the system property <tt>java.util.jar.Pack200.Unpacker</tt> |
| * is defined, then the value is taken to be the fully-qualified |
| * name of a concrete implementation class, which must implement Unpacker. |
| * The class is loaded and instantiated. If this process fails |
| * then an unspecified error is thrown.</p></li> |
| * |
| * <li><p>If an implementation has not been specified with the |
| * system property, then the system-default implementation class |
| * is instantiated, and the result is returned.</p></li> |
| * </ul> |
| * |
| * <p>Note: The returned object is not guaranteed to operate |
| * correctly if multiple threads use it at the same time. |
| * A multi-threaded application should either allocate multiple |
| * unpacker engines, or else serialize use of one engine with a lock. |
| * |
| * @return A newly allocated Unpacker engine. |
| */ |
| |
| public static Unpacker newUnpacker() { |
| return (Unpacker) newInstance(UNPACK_PROVIDER); |
| } |
| |
| // Interfaces |
| /** |
| * The packer engine applies various transformations to the input JAR file, |
| * making the pack stream highly compressible by a compressor such as |
| * gzip or zip. An instance of the engine can be obtained |
| * using {@link #newPacker}. |
| |
| * The high degree of compression is achieved |
| * by using a number of techniques described in the JSR 200 specification. |
| * Some of the techniques are sorting, re-ordering and co-location of the |
| * constant pool. |
| * <p> |
| * The pack engine is initialized to an initial state as described |
| * by their properties below. |
| * The initial state can be manipulated by getting the |
| * engine properties (using {@link #properties}) and storing |
| * the modified properties on the map. |
| * The resource files will be passed through with no changes at all. |
| * The class files will not contain identical bytes, since the unpacker |
| * is free to change minor class file features such as constant pool order. |
| * However, the class files will be semantically identical, |
| * as specified in |
| * <cite>The Java™ Virtual Machine Specification</cite>. |
| * <p> |
| * By default, the packer does not change the order of JAR elements. |
| * Also, the modification time and deflation hint of each |
| * JAR element is passed unchanged. |
| * (Any other ZIP-archive information, such as extra attributes |
| * giving Unix file permissions, are lost.) |
| * <p> |
| * Note that packing and unpacking a JAR will in general alter the |
| * bytewise contents of classfiles in the JAR. This means that packing |
| * and unpacking will in general invalidate any digital signatures |
| * which rely on bytewise images of JAR elements. In order both to sign |
| * and to pack a JAR, you must first pack and unpack the JAR to |
| * "normalize" it, then compute signatures on the unpacked JAR elements, |
| * and finally repack the signed JAR. |
| * Both packing steps should |
| * use precisely the same options, and the segment limit may also |
| * need to be set to "-1", to prevent accidental variation of segment |
| * boundaries as class file sizes change slightly. |
| * <p> |
| * (Here's why this works: Any reordering the packer does |
| * of any classfile structures is idempotent, so the second packing |
| * does not change the orderings produced by the first packing. |
| * Also, the unpacker is guaranteed by the JSR 200 specification |
| * to produce a specific bytewise image for any given transmission |
| * ordering of archive elements.) |
| * <p> |
| * In order to maintain backward compatibility, the pack file's version is |
| * set to accommodate the class files present in the input JAR file. In |
| * other words, the pack file version will be the latest, if the class files |
| * are the latest and conversely the pack file version will be the oldest |
| * if the class file versions are also the oldest. For intermediate class |
| * file versions the corresponding pack file version will be used. |
| * For example: |
| * If the input JAR-files are solely comprised of 1.5 (or lesser) |
| * class files, a 1.5 compatible pack file is produced. This will also be |
| * the case for archives that have no class files. |
| * If the input JAR-files contains a 1.6 class file, then the pack file |
| * version will be set to 1.6. |
| * <p> |
| * Note: Unless otherwise noted, passing a <tt>null</tt> argument to a |
| * constructor or method in this class will cause a {@link NullPointerException} |
| * to be thrown. |
| * <p> |
| * @since 1.5 |
| */ |
| public interface Packer { |
| /** |
| * This property is a numeral giving the estimated target size N |
| * (in bytes) of each archive segment. |
| * If a single input file requires more than N bytes, |
| * it will be given its own archive segment. |
| * <p> |
| * As a special case, a value of -1 will produce a single large |
| * segment with all input files, while a value of 0 will |
| * produce one segment for each class. |
| * Larger archive segments result in less fragmentation and |
| * better compression, but processing them requires more memory. |
| * <p> |
| * The size of each segment is estimated by counting the size of each |
| * input file to be transmitted in the segment, along with the size |
| * of its name and other transmitted properties. |
| * <p> |
| * The default is -1, which means the packer will always create a single |
| * segment output file. In cases where extremely large output files are |
| * generated, users are strongly encouraged to use segmenting or break |
| * up the input file into smaller JARs. |
| * <p> |
| * A 10Mb JAR packed without this limit will |
| * typically pack about 10% smaller, but the packer may require |
| * a larger Java heap (about ten times the segment limit). |
| */ |
| String SEGMENT_LIMIT = "pack.segment.limit"; |
| |
| /** |
| * If this property is set to {@link #TRUE}, the packer will transmit |
| * all elements in their original order within the source archive. |
| * <p> |
| * If it is set to {@link #FALSE}, the packer may reorder elements, |
| * and also remove JAR directory entries, which carry no useful |
| * information for Java applications. |
| * (Typically this enables better compression.) |
| * <p> |
| * The default is {@link #TRUE}, which preserves the input information, |
| * but may cause the transmitted archive to be larger than necessary. |
| */ |
| String KEEP_FILE_ORDER = "pack.keep.file.order"; |
| |
| |
| /** |
| * If this property is set to a single decimal digit, the packer will |
| * use the indicated amount of effort in compressing the archive. |
| * Level 1 may produce somewhat larger size and faster compression speed, |
| * while level 9 will take much longer but may produce better compression. |
| * <p> |
| * The special value 0 instructs the packer to copy through the |
| * original JAR file directly, with no compression. The JSR 200 |
| * standard requires any unpacker to understand this special case |
| * as a pass-through of the entire archive. |
| * <p> |
| * The default is 5, investing a modest amount of time to |
| * produce reasonable compression. |
| */ |
| String EFFORT = "pack.effort"; |
| |
| /** |
| * If this property is set to {@link #TRUE} or {@link #FALSE}, the packer |
| * will set the deflation hint accordingly in the output archive, and |
| * will not transmit the individual deflation hints of archive elements. |
| * <p> |
| * If this property is set to the special string {@link #KEEP}, the packer |
| * will attempt to determine an independent deflation hint for each |
| * available element of the input archive, and transmit this hint separately. |
| * <p> |
| * The default is {@link #KEEP}, which preserves the input information, |
| * but may cause the transmitted archive to be larger than necessary. |
| * <p> |
| * It is up to the unpacker implementation |
| * to take action upon the hint to suitably compress the elements of |
| * the resulting unpacked jar. |
| * <p> |
| * The deflation hint of a ZIP or JAR element indicates |
| * whether the element was deflated or stored directly. |
| */ |
| String DEFLATE_HINT = "pack.deflate.hint"; |
| |
| /** |
| * If this property is set to the special string {@link #LATEST}, |
| * the packer will attempt to determine the latest modification time, |
| * among all the available entries in the original archive or the latest |
| * modification time of all the available entries in each segment. |
| * This single value will be transmitted as part of the segment and applied |
| * to all the entries in each segment, {@link #SEGMENT_LIMIT}. |
| * <p> |
| * This can marginally decrease the transmitted size of the |
| * archive, at the expense of setting all installed files to a single |
| * date. |
| * <p> |
| * If this property is set to the special string {@link #KEEP}, |
| * the packer transmits a separate modification time for each input |
| * element. |
| * <p> |
| * The default is {@link #KEEP}, which preserves the input information, |
| * but may cause the transmitted archive to be larger than necessary. |
| * <p> |
| * It is up to the unpacker implementation to take action to suitably |
| * set the modification time of each element of its output file. |
| * @see #SEGMENT_LIMIT |
| */ |
| String MODIFICATION_TIME = "pack.modification.time"; |
| |
| /** |
| * Indicates that a file should be passed through bytewise, with no |
| * compression. Multiple files may be specified by specifying |
| * additional properties with distinct strings appended, to |
| * make a family of properties with the common prefix. |
| * <p> |
| * There is no pathname transformation, except |
| * that the system file separator is replaced by the JAR file |
| * separator '/'. |
| * <p> |
| * The resulting file names must match exactly as strings with their |
| * occurrences in the JAR file. |
| * <p> |
| * If a property value is a directory name, all files under that |
| * directory will be passed also. |
| * <p> |
| * Examples: |
| * <pre>{@code |
| * Map p = packer.properties(); |
| * p.put(PASS_FILE_PFX+0, "mutants/Rogue.class"); |
| * p.put(PASS_FILE_PFX+1, "mutants/Wolverine.class"); |
| * p.put(PASS_FILE_PFX+2, "mutants/Storm.class"); |
| * # Pass all files in an entire directory hierarchy: |
| * p.put(PASS_FILE_PFX+3, "police/"); |
| * }</pre> |
| */ |
| String PASS_FILE_PFX = "pack.pass.file."; |
| |
| /// Attribute control. |
| |
| /** |
| * Indicates the action to take when a class-file containing an unknown |
| * attribute is encountered. Possible values are the strings {@link #ERROR}, |
| * {@link #STRIP}, and {@link #PASS}. |
| * <p> |
| * The string {@link #ERROR} means that the pack operation |
| * as a whole will fail, with an exception of type <code>IOException</code>. |
| * The string |
| * {@link #STRIP} means that the attribute will be dropped. |
| * The string |
| * {@link #PASS} means that the whole class-file will be passed through |
| * (as if it were a resource file) without compression, with a suitable warning. |
| * This is the default value for this property. |
| * <p> |
| * Examples: |
| * <pre>{@code |
| * Map p = pack200.getProperties(); |
| * p.put(UNKNOWN_ATTRIBUTE, ERROR); |
| * p.put(UNKNOWN_ATTRIBUTE, STRIP); |
| * p.put(UNKNOWN_ATTRIBUTE, PASS); |
| * }</pre> |
| */ |
| String UNKNOWN_ATTRIBUTE = "pack.unknown.attribute"; |
| |
| /** |
| * When concatenated with a class attribute name, |
| * indicates the format of that attribute, |
| * using the layout language specified in the JSR 200 specification. |
| * <p> |
| * For example, the effect of this option is built in: |
| * <code>pack.class.attribute.SourceFile=RUH</code>. |
| * <p> |
| * The special strings {@link #ERROR}, {@link #STRIP}, and {@link #PASS} are |
| * also allowed, with the same meaning as {@link #UNKNOWN_ATTRIBUTE}. |
| * This provides a way for users to request that specific attributes be |
| * refused, stripped, or passed bitwise (with no class compression). |
| * <p> |
| * Code like this might be used to support attributes for JCOV: |
| * <pre><code> |
| * Map p = packer.properties(); |
| * p.put(CODE_ATTRIBUTE_PFX+"CoverageTable", "NH[PHHII]"); |
| * p.put(CODE_ATTRIBUTE_PFX+"CharacterRangeTable", "NH[PHPOHIIH]"); |
| * p.put(CLASS_ATTRIBUTE_PFX+"SourceID", "RUH"); |
| * p.put(CLASS_ATTRIBUTE_PFX+"CompilationID", "RUH"); |
| * </code></pre> |
| * <p> |
| * Code like this might be used to strip debugging attributes: |
| * <pre><code> |
| * Map p = packer.properties(); |
| * p.put(CODE_ATTRIBUTE_PFX+"LineNumberTable", STRIP); |
| * p.put(CODE_ATTRIBUTE_PFX+"LocalVariableTable", STRIP); |
| * p.put(CLASS_ATTRIBUTE_PFX+"SourceFile", STRIP); |
| * </code></pre> |
| */ |
| String CLASS_ATTRIBUTE_PFX = "pack.class.attribute."; |
| |
| /** |
| * When concatenated with a field attribute name, |
| * indicates the format of that attribute. |
| * For example, the effect of this option is built in: |
| * <code>pack.field.attribute.Deprecated=</code>. |
| * The special strings {@link #ERROR}, {@link #STRIP}, and |
| * {@link #PASS} are also allowed. |
| * @see #CLASS_ATTRIBUTE_PFX |
| */ |
| String FIELD_ATTRIBUTE_PFX = "pack.field.attribute."; |
| |
| /** |
| * When concatenated with a method attribute name, |
| * indicates the format of that attribute. |
| * For example, the effect of this option is built in: |
| * <code>pack.method.attribute.Exceptions=NH[RCH]</code>. |
| * The special strings {@link #ERROR}, {@link #STRIP}, and {@link #PASS} |
| * are also allowed. |
| * @see #CLASS_ATTRIBUTE_PFX |
| */ |
| String METHOD_ATTRIBUTE_PFX = "pack.method.attribute."; |
| |
| /** |
| * When concatenated with a code attribute name, |
| * indicates the format of that attribute. |
| * For example, the effect of this option is built in: |
| * <code>pack.code.attribute.LocalVariableTable=NH[PHOHRUHRSHH]</code>. |
| * The special strings {@link #ERROR}, {@link #STRIP}, and {@link #PASS} |
| * are also allowed. |
| * @see #CLASS_ATTRIBUTE_PFX |
| */ |
| String CODE_ATTRIBUTE_PFX = "pack.code.attribute."; |
| |
| /** |
| * The unpacker's progress as a percentage, as periodically |
| * updated by the unpacker. |
| * Values of 0 - 100 are normal, and -1 indicates a stall. |
| * Progress can be monitored by polling the value of this |
| * property. |
| * <p> |
| * At a minimum, the unpacker must set progress to 0 |
| * at the beginning of a packing operation, and to 100 |
| * at the end. |
| */ |
| String PROGRESS = "pack.progress"; |
| |
| /** The string "keep", a possible value for certain properties. |
| * @see #DEFLATE_HINT |
| * @see #MODIFICATION_TIME |
| */ |
| String KEEP = "keep"; |
| |
| /** The string "pass", a possible value for certain properties. |
| * @see #UNKNOWN_ATTRIBUTE |
| * @see #CLASS_ATTRIBUTE_PFX |
| * @see #FIELD_ATTRIBUTE_PFX |
| * @see #METHOD_ATTRIBUTE_PFX |
| * @see #CODE_ATTRIBUTE_PFX |
| */ |
| String PASS = "pass"; |
| |
| /** The string "strip", a possible value for certain properties. |
| * @see #UNKNOWN_ATTRIBUTE |
| * @see #CLASS_ATTRIBUTE_PFX |
| * @see #FIELD_ATTRIBUTE_PFX |
| * @see #METHOD_ATTRIBUTE_PFX |
| * @see #CODE_ATTRIBUTE_PFX |
| */ |
| String STRIP = "strip"; |
| |
| /** The string "error", a possible value for certain properties. |
| * @see #UNKNOWN_ATTRIBUTE |
| * @see #CLASS_ATTRIBUTE_PFX |
| * @see #FIELD_ATTRIBUTE_PFX |
| * @see #METHOD_ATTRIBUTE_PFX |
| * @see #CODE_ATTRIBUTE_PFX |
| */ |
| String ERROR = "error"; |
| |
| /** The string "true", a possible value for certain properties. |
| * @see #KEEP_FILE_ORDER |
| * @see #DEFLATE_HINT |
| */ |
| String TRUE = "true"; |
| |
| /** The string "false", a possible value for certain properties. |
| * @see #KEEP_FILE_ORDER |
| * @see #DEFLATE_HINT |
| */ |
| String FALSE = "false"; |
| |
| /** The string "latest", a possible value for certain properties. |
| * @see #MODIFICATION_TIME |
| */ |
| String LATEST = "latest"; |
| |
| /** |
| * Get the set of this engine's properties. |
| * This set is a "live view", so that changing its |
| * contents immediately affects the Packer engine, and |
| * changes from the engine (such as progress indications) |
| * are immediately visible in the map. |
| * |
| * <p>The property map may contain pre-defined implementation |
| * specific and default properties. Users are encouraged to |
| * read the information and fully understand the implications, |
| * before modifying pre-existing properties. |
| * <p> |
| * Implementation specific properties are prefixed with a |
| * package name associated with the implementor, beginning |
| * with <tt>com.</tt> or a similar prefix. |
| * All property names beginning with <tt>pack.</tt> and |
| * <tt>unpack.</tt> are reserved for use by this API. |
| * <p> |
| * Unknown properties may be ignored or rejected with an |
| * unspecified error, and invalid entries may cause an |
| * unspecified error to be thrown. |
| * |
| * <p> |
| * The returned map implements all optional {@link SortedMap} operations |
| * @return A sorted association of property key strings to property |
| * values. |
| */ |
| SortedMap<String,String> properties(); |
| |
| /** |
| * Takes a JarFile and converts it into a Pack200 archive. |
| * <p> |
| * Closes its input but not its output. (Pack200 archives are appendable.) |
| * @param in a JarFile |
| * @param out an OutputStream |
| * @exception IOException if an error is encountered. |
| */ |
| void pack(JarFile in, OutputStream out) throws IOException ; |
| |
| /** |
| * Takes a JarInputStream and converts it into a Pack200 archive. |
| * <p> |
| * Closes its input but not its output. (Pack200 archives are appendable.) |
| * <p> |
| * The modification time and deflation hint attributes are not available, |
| * for the JAR manifest file and its containing directory. |
| * |
| * @see #MODIFICATION_TIME |
| * @see #DEFLATE_HINT |
| * @param in a JarInputStream |
| * @param out an OutputStream |
| * @exception IOException if an error is encountered. |
| */ |
| void pack(JarInputStream in, OutputStream out) throws IOException ; |
| |
| /** |
| * Registers a listener for PropertyChange events on the properties map. |
| * This is typically used by applications to update a progress bar. |
| * |
| * <p> The default implementation of this method does nothing and has |
| * no side-effects.</p> |
| * |
| * <p><b>WARNING:</b> This method is omitted from the interface |
| * declaration in all subset Profiles of Java SE that do not include |
| * the {@code java.beans} package. </p> |
| |
| * @see #properties |
| * @see #PROGRESS |
| * @param listener An object to be invoked when a property is changed. |
| * @deprecated The dependency on {@code PropertyChangeListener} creates |
| * a significant impediment to future modularization of the |
| * Java platform. This method will be removed in a future |
| * release. |
| * Applications that need to monitor progress of the packer |
| * can poll the value of the {@link #PROGRESS PROGRESS} |
| * property instead. |
| */ |
| @Deprecated |
| default void addPropertyChangeListener(PropertyChangeListener listener) { |
| } |
| |
| /** |
| * Remove a listener for PropertyChange events, added by |
| * the {@link #addPropertyChangeListener}. |
| * |
| * <p> The default implementation of this method does nothing and has |
| * no side-effects.</p> |
| * |
| * <p><b>WARNING:</b> This method is omitted from the interface |
| * declaration in all subset Profiles of Java SE that do not include |
| * the {@code java.beans} package. </p> |
| * |
| * @see #addPropertyChangeListener |
| * @param listener The PropertyChange listener to be removed. |
| * @deprecated The dependency on {@code PropertyChangeListener} creates |
| * a significant impediment to future modularization of the |
| * Java platform. This method will be removed in a future |
| * release. |
| */ |
| @Deprecated |
| default void removePropertyChangeListener(PropertyChangeListener listener) { |
| } |
| } |
| |
| /** |
| * The unpacker engine converts the packed stream to a JAR file. |
| * An instance of the engine can be obtained |
| * using {@link #newUnpacker}. |
| * <p> |
| * Every JAR file produced by this engine will include the string |
| * "<tt>PACK200</tt>" as a zip file comment. |
| * This allows a deployer to detect if a JAR archive was packed and unpacked. |
| * <p> |
| * Note: Unless otherwise noted, passing a <tt>null</tt> argument to a |
| * constructor or method in this class will cause a {@link NullPointerException} |
| * to be thrown. |
| * <p> |
| * This version of the unpacker is compatible with all previous versions. |
| * @since 1.5 |
| */ |
| public interface Unpacker { |
| |
| /** The string "keep", a possible value for certain properties. |
| * @see #DEFLATE_HINT |
| */ |
| String KEEP = "keep"; |
| |
| /** The string "true", a possible value for certain properties. |
| * @see #DEFLATE_HINT |
| */ |
| String TRUE = "true"; |
| |
| /** The string "false", a possible value for certain properties. |
| * @see #DEFLATE_HINT |
| */ |
| String FALSE = "false"; |
| |
| /** |
| * Property indicating that the unpacker should |
| * ignore all transmitted values for DEFLATE_HINT, |
| * replacing them by the given value, {@link #TRUE} or {@link #FALSE}. |
| * The default value is the special string {@link #KEEP}, |
| * which asks the unpacker to preserve all transmitted |
| * deflation hints. |
| */ |
| String DEFLATE_HINT = "unpack.deflate.hint"; |
| |
| |
| |
| /** |
| * The unpacker's progress as a percentage, as periodically |
| * updated by the unpacker. |
| * Values of 0 - 100 are normal, and -1 indicates a stall. |
| * Progress can be monitored by polling the value of this |
| * property. |
| * <p> |
| * At a minimum, the unpacker must set progress to 0 |
| * at the beginning of a packing operation, and to 100 |
| * at the end. |
| */ |
| String PROGRESS = "unpack.progress"; |
| |
| /** |
| * Get the set of this engine's properties. This set is |
| * a "live view", so that changing its |
| * contents immediately affects the Packer engine, and |
| * changes from the engine (such as progress indications) |
| * are immediately visible in the map. |
| * |
| * <p>The property map may contain pre-defined implementation |
| * specific and default properties. Users are encouraged to |
| * read the information and fully understand the implications, |
| * before modifying pre-existing properties. |
| * <p> |
| * Implementation specific properties are prefixed with a |
| * package name associated with the implementor, beginning |
| * with <tt>com.</tt> or a similar prefix. |
| * All property names beginning with <tt>pack.</tt> and |
| * <tt>unpack.</tt> are reserved for use by this API. |
| * <p> |
| * Unknown properties may be ignored or rejected with an |
| * unspecified error, and invalid entries may cause an |
| * unspecified error to be thrown. |
| * |
| * @return A sorted association of option key strings to option values. |
| */ |
| SortedMap<String,String> properties(); |
| |
| /** |
| * Read a Pack200 archive, and write the encoded JAR to |
| * a JarOutputStream. |
| * The entire contents of the input stream will be read. |
| * It may be more efficient to read the Pack200 archive |
| * to a file and pass the File object, using the alternate |
| * method described below. |
| * <p> |
| * Closes its input but not its output. (The output can accumulate more elements.) |
| * @param in an InputStream. |
| * @param out a JarOutputStream. |
| * @exception IOException if an error is encountered. |
| */ |
| void unpack(InputStream in, JarOutputStream out) throws IOException; |
| |
| /** |
| * Read a Pack200 archive, and write the encoded JAR to |
| * a JarOutputStream. |
| * <p> |
| * Does not close its output. (The output can accumulate more elements.) |
| * @param in a File. |
| * @param out a JarOutputStream. |
| * @exception IOException if an error is encountered. |
| */ |
| void unpack(File in, JarOutputStream out) throws IOException; |
| |
| /** |
| * Registers a listener for PropertyChange events on the properties map. |
| * This is typically used by applications to update a progress bar. |
| * |
| * <p> The default implementation of this method does nothing and has |
| * no side-effects.</p> |
| * |
| * <p><b>WARNING:</b> This method is omitted from the interface |
| * declaration in all subset Profiles of Java SE that do not include |
| * the {@code java.beans} package. </p> |
| * |
| * @see #properties |
| * @see #PROGRESS |
| * @param listener An object to be invoked when a property is changed. |
| * @deprecated The dependency on {@code PropertyChangeListener} creates |
| * a significant impediment to future modularization of the |
| * Java platform. This method will be removed in a future |
| * release. |
| * Applications that need to monitor progress of the |
| * unpacker can poll the value of the {@link #PROGRESS |
| * PROGRESS} property instead. |
| */ |
| @Deprecated |
| default void addPropertyChangeListener(PropertyChangeListener listener) { |
| } |
| |
| /** |
| * Remove a listener for PropertyChange events, added by |
| * the {@link #addPropertyChangeListener}. |
| * |
| * <p> The default implementation of this method does nothing and has |
| * no side-effects.</p> |
| * |
| * <p><b>WARNING:</b> This method is omitted from the interface |
| * declaration in all subset Profiles of Java SE that do not include |
| * the {@code java.beans} package. </p> |
| * |
| * @see #addPropertyChangeListener |
| * @param listener The PropertyChange listener to be removed. |
| * @deprecated The dependency on {@code PropertyChangeListener} creates |
| * a significant impediment to future modularization of the |
| * Java platform. This method will be removed in a future |
| * release. |
| */ |
| @Deprecated |
| default void removePropertyChangeListener(PropertyChangeListener listener) { |
| } |
| } |
| |
| // Private stuff.... |
| |
| private static final String PACK_PROVIDER = "java.util.jar.Pack200.Packer"; |
| private static final String UNPACK_PROVIDER = "java.util.jar.Pack200.Unpacker"; |
| |
| private static Class<?> packerImpl; |
| private static Class<?> unpackerImpl; |
| |
| private synchronized static Object newInstance(String prop) { |
| String implName = "(unknown)"; |
| try { |
| Class<?> impl = (PACK_PROVIDER.equals(prop))? packerImpl: unpackerImpl; |
| if (impl == null) { |
| // The first time, we must decide which class to use. |
| implName = java.security.AccessController.doPrivileged( |
| new sun.security.action.GetPropertyAction(prop,"")); |
| if (implName != null && !implName.equals("")) |
| impl = Class.forName(implName); |
| // Android-changed: Remove default Packer Impl. |
| // |
| // else if (PACK_PROVIDER.equals(prop)) |
| // impl = com.sun.java.util.jar.pack.PackerImpl.class; |
| // else |
| // impl = com.sun.java.util.jar.pack.UnpackerImpl.class; |
| } |
| // We have a class. Now instantiate it. |
| return impl.newInstance(); |
| } catch (ClassNotFoundException e) { |
| throw new Error("Class not found: " + implName + |
| ":\ncheck property " + prop + |
| " in your properties file.", e); |
| } catch (InstantiationException e) { |
| throw new Error("Could not instantiate: " + implName + |
| ":\ncheck property " + prop + |
| " in your properties file.", e); |
| } catch (IllegalAccessException e) { |
| throw new Error("Cannot access class: " + implName + |
| ":\ncheck property " + prop + |
| " in your properties file.", e); |
| } |
| } |
| |
| } |