java.util.jar: abstract public class: Pack200

java.util.jar
abstract public class: Pack200 [javadoc | source]

java.lang.Object
   java.util.jar.Pack200

Transforms a JAR file to or from a packed stream in Pack200 format. Please refer to Network Transfer Format JSR 200 Specification at http://jcp.org/aboutJava/communityprocess/review/jsr200/index.html

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.

Here is an example using packer and unpacker:

   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();
   }

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 Java Deployment Guide for more details and techniques.

Unless otherwise noted, passing a null argument to a constructor or method in this class will cause a NullPointerException to be thrown.

author: John - Rose

author: Kumar - Srinivasan

since: 1.5 -

Nested Class Summary:

public interface

Nested Class Summary:
public interface	Pack200.Packer	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. 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 The Java™ Virtual Machine Specification. 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.) 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. (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.) 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. Note: Unless otherwise noted, passing a `null` argument to a constructor or method in this class will cause a {@link NullPointerException} to be thrown.
public interface	Pack200.Unpacker	The unpacker engine converts the packed stream to a JAR file. An instance of the engine can be obtained using {@link #newUnpacker}. Every JAR file produced by this engine will include the string "`PACK200`" as a zip file comment. This allows a deployer to detect if a JAR archive was packed and unpacked. Note: Unless otherwise noted, passing a `null` argument to a constructor or method in this class will cause a {@link NullPointerException} to be thrown. This version of the unpacker is compatible with all previous versions.

Pack200.Packer

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.

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 The Java™ Virtual Machine Specification.

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.)

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.

(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.)

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.

Note: Unless otherwise noted, passing a null argument to a constructor or method in this class will cause a {@link NullPointerException} to be thrown.

public interface

Pack200.Unpacker

The unpacker engine converts the packed stream to a JAR file. An instance of the engine can be obtained using {@link #newUnpacker}.

Every JAR file produced by this engine will include the string "PACK200" as a zip file comment. This allows a deployer to detect if a JAR archive was packed and unpacked.

Note: Unless otherwise noted, passing a null argument to a constructor or method in this class will cause a {@link NullPointerException} to be thrown.

This version of the unpacker is compatible with all previous versions.

Method from java.util.jar.Pack200 Summary:
newPacker, newUnpacker

Methods from java.lang.Object:
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method from java.util.jar.Pack200 Detail:
public static synchronized Packer newPacker() { return (Packer) newInstance(PACK_PROVIDER); } Obtain new instance of a class that implements Packer. If the system property `java.util.jar.Pack200.Packer` 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. If an implementation has not been specified with the system property, then the system-default implementation class is instantiated, and the result is returned. 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.
public static Unpacker newUnpacker() { return (Unpacker) newInstance(UNPACK_PROVIDER); } Obtain new instance of a class that implements Unpacker. If the system property `java.util.jar.Pack200.Unpacker` 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. If an implementation has not been specified with the system property, then the system-default implementation class is instantiated, and the result is returned. 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.

Method from java.util.jar.Pack200 Detail:

 public static synchronized Packer newPacker() {
        return (Packer) newInstance(PACK_PROVIDER);
}

If the system property java.util.jar.Pack200.Packer 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.
If an implementation has not been specified with the system property, then the system-default implementation class is instantiated, and the result is returned.

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.

 public static Unpacker newUnpacker() {
        return (Unpacker) newInstance(UNPACK_PROVIDER);
}

If the system property java.util.jar.Pack200.Unpacker 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.
If an implementation has not been specified with the system property, then the system-default implementation class is instantiated, and the result is returned.

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.