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