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