001 /*
002 * Copyright 2003-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package java.util.jar;
026
027 import java.util.SortedMap;
028 import java.io.InputStream;
029 import java.io.OutputStream;
030 import java.io.File;
031 import java.io.IOException;
032 import java.beans.PropertyChangeListener;
033 import java.beans.PropertyChangeEvent;
034 import java.security.AccessController;
035 import java.security.PrivilegedAction;
036
037 /**
038 * Transforms a JAR file to or from a packed stream in Pack200 format.
039 * Please refer to Network Transfer Format JSR 200 Specification at
040 * <a href=http://jcp.org/aboutJava/communityprocess/review/jsr200/index.html>http://jcp.org/aboutJava/communityprocess/review/jsr200/index.html</a>
041 * <p>
042 * Typically the packer engine is used by application developers
043 * to deploy or host JAR files on a website.
044 * The unpacker engine is used by deployment applications to
045 * transform the byte-stream back to JAR format.
046 * <p>
047 * Here is an example using packer and unpacker:<p>
048 * <blockquote><pre>
049 * import java.util.jar.Pack200;
050 * import java.util.jar.Pack200.*;
051 * ...
052 * // Create the Packer object
053 * Packer packer = Pack200.newPacker();
054 *
055 * // Initialize the state by setting the desired properties
056 * Map p = packer.properties();
057 * // take more time choosing codings for better compression
058 * p.put(Packer.EFFORT, "7"); // default is "5"
059 * // use largest-possible archive segments (>10% better compression).
060 * p.put(Packer.SEGMENT_LIMIT, "-1");
061 * // reorder files for better compression.
062 * p.put(Packer.KEEP_FILE_ORDER, Packer.FALSE);
063 * // smear modification times to a single value.
064 * p.put(Packer.MODIFICATION_TIME, Packer.LATEST);
065 * // ignore all JAR deflation requests,
066 * // transmitting a single request to use "store" mode.
067 * p.put(Packer.DEFLATE_HINT, Packer.FALSE);
068 * // discard debug attributes
069 * p.put(Packer.CODE_ATTRIBUTE_PFX+"LineNumberTable", Packer.STRIP);
070 * // throw an error if an attribute is unrecognized
071 * p.put(Packer.UNKNOWN_ATTRIBUTE, Packer.ERROR);
072 * // pass one class file uncompressed:
073 * p.put(Packer.PASS_FILE_PFX+0, "mutants/Rogue.class");
074 * try {
075 * JarFile jarFile = new JarFile("/tmp/testref.jar");
076 * FileOutputStream fos = new FileOutputStream("/tmp/test.pack");
077 * // Call the packer
078 * packer.pack(jarFile, fos);
079 * jarFile.close();
080 * fos.close();
081 *
082 * File f = new File("/tmp/test.pack");
083 * FileOutputStream fostream = new FileOutputStream("/tmp/test.jar");
084 * JarOutputStream jostream = new JarOutputStream(fostream);
085 * Unpacker unpacker = Pack200.newUnpacker();
086 * // Call the unpacker
087 * unpacker.unpack(f, jostream);
088 * // Must explicitly close the output.
089 * jostream.close();
090 * } catch (IOException ioe) {
091 * ioe.printStackTrace();
092 * }
093 * </pre></blockquote>
094 * <p>
095 * A Pack200 file compressed with gzip can be hosted on HTTP/1.1 web servers.
096 * The deployment applications can use "Accept-Encoding=pack200-gzip". This
097 * indicates to the server that the client application desires a version of
098 * the file encoded with Pack200 and further compressed with gzip. Please
099 * 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 * @version 1.22, 05/05/07
108 * @since 1.5
109 */
110 public abstract class Pack200 {
111 private Pack200() {
112 } //prevent instantiation
113
114 // Static methods of the Pack200 class.
115 /**
116 * Obtain new instance of a class that implements Packer.
117 *
118 * <li><p>If the system property <tt>java.util.jar.Pack200.Packer</tt>
119 * is defined, then the value is taken to be the fully-qualified name
120 * of a concrete implementation class, which must implement Packer.
121 * This class is loaded and instantiated. If this process fails
122 * then an unspecified error is thrown.</p></li>
123 *
124 * <li><p>If an implementation has not been specified with the system
125 * property, then the system-default implementation class is instantiated,
126 * and the result is returned.</p></li>
127 *
128 * <p>Note: The returned object is not guaranteed to operate
129 * correctly if multiple threads use it at the same time.
130 * A multi-threaded application should either allocate multiple
131 * packer engines, or else serialize use of one engine with a lock.
132 *
133 * @return A newly allocated Packer engine.
134 */
135 public synchronized static Packer newPacker() {
136 return (Packer) newInstance(PACK_PROVIDER);
137 }
138
139 /**
140 * Obtain new instance of a class that implements Unpacker.
141 *
142 * <li><p>If the system property <tt>java.util.jar.Pack200.Unpacker</tt>
143 * is defined, then the value is taken to be the fully-qualified
144 * name of a concrete implementation class, which must implement Unpacker.
145 * The class is loaded and instantiated. If this process fails
146 * then an unspecified error is thrown.</p></li>
147 *
148 * <li><p>If an implementation has not been specified with the
149 * system property, then the system-default implementation class
150 * is instantiated, and the result is returned.</p></li>
151 *
152 * <p>Note: The returned object is not guaranteed to operate
153 * correctly if multiple threads use it at the same time.
154 * A multi-threaded application should either allocate multiple
155 * unpacker engines, or else serialize use of one engine with a lock.
156 *
157 * @return A newly allocated Unpacker engine.
158 */
159
160 public static Unpacker newUnpacker() {
161 return (Unpacker) newInstance(UNPACK_PROVIDER);
162 }
163
164 // Interfaces
165 /**
166 * The packer engine applies various transformations to the input JAR file,
167 * making the pack stream highly compressible by a compressor such as
168 * gzip or zip. An instance of the engine can be obtained
169 * using {@link #newPacker}.
170
171 * The high degree of compression is achieved
172 * by using a number of techniques described in the JSR 200 specification.
173 * Some of the techniques are sorting, re-ordering and co-location of the
174 * constant pool.
175 * <p>
176 * The pack engine is initialized to an initial state as described
177 * by their properties below.
178 * The initial state can be manipulated by getting the
179 * engine properties (using {@link #properties}) and storing
180 * the modified properties on the map.
181 * The resource files will be passed through with no changes at all.
182 * The class files will not contain identical bytes, since the unpacker
183 * is free to change minor class file features such as constant pool order.
184 * However, the class files will be semantically identical,
185 * as specified in the Java Virtual Machine Specification
186 * <a href="http://java.sun.com/docs/books/vmspec/html/ClassFile.doc.html">http://java.sun.com/docs/books/vmspec/html/ClassFile.doc.html</a>.
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, if the input JAR-files are
214 * solely comprised of 1.5 (or lesser) classfiles, a 1.5 compatible
215 * pack file is produced. Otherwise a 1.6 compatible pack200 file is
216 * produced.
217 * <p>
218 * @since 1.5
219 */
220 public interface Packer {
221 /**
222 * This property is a numeral giving the estimated target size N
223 * (in bytes) of each archive segment.
224 * If a single input file requires more than N bytes,
225 * it will be given its own archive segment.
226 * <p>
227 * As a special case, a value of -1 will produce a single large
228 * segment with all input files, while a value of 0 will
229 * produce one segment for each class.
230 * Larger archive segments result in less fragmentation and
231 * better compression, but processing them requires more memory.
232 * <p>
233 * The size of each segment is estimated by counting the size of each
234 * input file to be transmitted in the segment, along with the size
235 * of its name and other transmitted properties.
236 * <p>
237 * The default is 1000000 (a million bytes). This allows input JAR files
238 * of moderate size to be transmitted in one segment. It also puts
239 * a limit on memory requirements for packers and unpackers.
240 * <p>
241 * A 10Mb JAR packed without this limit will
242 * typically pack about 10% smaller, but the packer may require
243 * a larger Java heap (about ten times the segment limit).
244 */
245 String SEGMENT_LIMIT = "pack.segment.limit";
246
247 /**
248 * If this property is set to {@link #TRUE}, the packer will transmit
249 * all elements in their original order within the source archive.
250 * <p>
251 * If it is set to {@link #FALSE}, the packer may reorder elements,
252 * and also remove JAR directory entries, which carry no useful
253 * information for Java applications.
254 * (Typically this enables better compression.)
255 * <p>
256 * The default is {@link #TRUE}, which preserves the input information,
257 * but may cause the transmitted archive to be larger than necessary.
258 */
259 String KEEP_FILE_ORDER = "pack.keep.file.order";
260
261 /**
262 * If this property is set to a single decimal digit, the packer will
263 * use the indicated amount of effort in compressing the archive.
264 * Level 1 may produce somewhat larger size and faster compression speed,
265 * while level 9 will take much longer but may produce better compression.
266 * <p>
267 * The special value 0 instructs the packer to copy through the
268 * original JAR file directly, with no compression. The JSR 200
269 * standard requires any unpacker to understand this special case
270 * as a pass-through of the entire archive.
271 * <p>
272 * The default is 5, investing a modest amount of time to
273 * produce reasonable compression.
274 */
275 String EFFORT = "pack.effort";
276
277 /**
278 * If this property is set to {@link #TRUE} or {@link #FALSE}, the packer
279 * will set the deflation hint accordingly in the output archive, and
280 * will not transmit the individual deflation hints of archive elements.
281 * <p>
282 * If this property is set to the special string {@link #KEEP}, the packer
283 * will attempt to determine an independent deflation hint for each
284 * available element of the input archive, and transmit this hint separately.
285 * <p>
286 * The default is {@link #KEEP}, which preserves the input information,
287 * but may cause the transmitted archive to be larger than necessary.
288 * <p>
289 * It is up to the unpacker implementation
290 * to take action upon the hint to suitably compress the elements of
291 * the resulting unpacked jar.
292 * <p>
293 * The deflation hint of a ZIP or JAR element indicates
294 * whether the element was deflated or stored directly.
295 */
296 String DEFLATE_HINT = "pack.deflate.hint";
297
298 /**
299 * If this property is set to the special string {@link #LATEST},
300 * the packer will attempt to determine the latest modification time,
301 * among all the available entries in the original archive or the latest
302 * modification time of all the available entries in each segment.
303 * This single value will be transmitted as part of the segment and applied
304 * to all the entries in each segment, {@link #SEGMENT_LIMIT}.
305 * <p>
306 * This can marginally decrease the transmitted size of the
307 * archive, at the expense of setting all installed files to a single
308 * date.
309 * <p>
310 * If this property is set to the special string {@link #KEEP},
311 * the packer transmits a separate modification time for each input
312 * element.
313 * <p>
314 * The default is {@link #KEEP}, which preserves the input information,
315 * but may cause the transmitted archive to be larger than necessary.
316 * <p>
317 * It is up to the unpacker implementation to take action to suitably
318 * set the modification time of each element of its output file.
319 * @see #SEGMENT_LIMIT
320 */
321 String MODIFICATION_TIME = "pack.modification.time";
322
323 /**
324 * Indicates that a file should be passed through bytewise, with no
325 * compression. Multiple files may be specified by specifying
326 * additional properties with distinct strings appended, to
327 * make a family of properties with the common prefix.
328 * <p>
329 * There is no pathname transformation, except
330 * that the system file separator is replaced by the JAR file
331 * separator '/'.
332 * <p>
333 * The resulting file names must match exactly as strings with their
334 * occurrences in the JAR file.
335 * <p>
336 * If a property value is a directory name, all files under that
337 * directory will be passed also.
338 * <p>
339 * Examples:
340 * <pre><code>
341 * Map p = packer.properties();
342 * p.put(PASS_FILE_PFX+0, "mutants/Rogue.class");
343 * p.put(PASS_FILE_PFX+1, "mutants/Wolverine.class");
344 * p.put(PASS_FILE_PFX+2, "mutants/Storm.class");
345 * # Pass all files in an entire directory hierarchy:
346 * p.put(PASS_FILE_PFX+3, "police/");
347 * </pre></code>.
348 */
349 String PASS_FILE_PFX = "pack.pass.file.";
350
351 /// Attribute control.
352
353 /**
354 * Indicates the action to take when a class-file containing an unknown
355 * attribute is encountered. Possible values are the strings {@link #ERROR},
356 * {@link #STRIP}, and {@link #PASS}.
357 * <p>
358 * The string {@link #ERROR} means that the pack operation
359 * as a whole will fail, with an exception of type <code>IOException</code>.
360 * The string
361 * {@link #STRIP} means that the attribute will be dropped.
362 * The string
363 * {@link #PASS} means that the whole class-file will be passed through
364 * (as if it were a resource file) without compression, with a suitable warning.
365 * This is the default value for this property.
366 * <p>
367 * Examples:
368 * <pre><code>
369 * Map p = pack200.getProperties();
370 * p.put(UNKNOWN_ATTRIBUTE, ERROR);
371 * p.put(UNKNOWN_ATTRIBUTE, STRIP);
372 * p.put(UNKNOWN_ATTRIBUTE, PASS);
373 * </pre></code>
374 */
375 String UNKNOWN_ATTRIBUTE = "pack.unknown.attribute";
376
377 /**
378 * When concatenated with a class attribute name,
379 * indicates the format of that attribute,
380 * using the layout language specified in the JSR 200 specification.
381 * <p>
382 * For example, the effect of this option is built in:
383 * <code>pack.class.attribute.SourceFile=RUH</code>.
384 * <p>
385 * The special strings {@link #ERROR}, {@link #STRIP}, and {@link #PASS} are
386 * also allowed, with the same meaning as {@link #UNKNOWN_ATTRIBUTE}.
387 * This provides a way for users to request that specific attributes be
388 * refused, stripped, or passed bitwise (with no class compression).
389 * <p>
390 * Code like this might be used to support attributes for JCOV:
391 * <pre><code>
392 * Map p = packer.properties();
393 * p.put(CODE_ATTRIBUTE_PFX+"CoverageTable", "NH[PHHII]");
394 * p.put(CODE_ATTRIBUTE_PFX+"CharacterRangeTable", "NH[PHPOHIIH]");
395 * p.put(CLASS_ATTRIBUTE_PFX+"SourceID", "RUH");
396 * p.put(CLASS_ATTRIBUTE_PFX+"CompilationID", "RUH");
397 * </code></pre>
398 * <p>
399 * Code like this might be used to strip debugging attributes:
400 * <pre><code>
401 * Map p = packer.properties();
402 * p.put(CODE_ATTRIBUTE_PFX+"LineNumberTable", STRIP);
403 * p.put(CODE_ATTRIBUTE_PFX+"LocalVariableTable", STRIP);
404 * p.put(CLASS_ATTRIBUTE_PFX+"SourceFile", STRIP);
405 * </code></pre>
406 */
407 String CLASS_ATTRIBUTE_PFX = "pack.class.attribute.";
408
409 /**
410 * When concatenated with a field attribute name,
411 * indicates the format of that attribute.
412 * For example, the effect of this option is built in:
413 * <code>pack.field.attribute.Deprecated=</code>.
414 * The special strings {@link #ERROR}, {@link #STRIP}, and
415 * {@link #PASS} are also allowed.
416 * @see #CLASS_ATTRIBUTE_PFX
417 */
418 String FIELD_ATTRIBUTE_PFX = "pack.field.attribute.";
419
420 /**
421 * When concatenated with a method attribute name,
422 * indicates the format of that attribute.
423 * For example, the effect of this option is built in:
424 * <code>pack.method.attribute.Exceptions=NH[RCH]</code>.
425 * The special strings {@link #ERROR}, {@link #STRIP}, and {@link #PASS}
426 * are also allowed.
427 * @see #CLASS_ATTRIBUTE_PFX
428 */
429 String METHOD_ATTRIBUTE_PFX = "pack.method.attribute.";
430
431 /**
432 * When concatenated with a code attribute name,
433 * indicates the format of that attribute.
434 * For example, the effect of this option is built in:
435 * <code>pack.code.attribute.LocalVariableTable=NH[PHOHRUHRSHH]</code>.
436 * The special strings {@link #ERROR}, {@link #STRIP}, and {@link #PASS}
437 * are also allowed.
438 * @see #CLASS_ATTRIBUTE_PFX
439 */
440 String CODE_ATTRIBUTE_PFX = "pack.code.attribute.";
441
442 /**
443 * The unpacker's progress as a percentage, as periodically
444 * updated by the unpacker.
445 * Values of 0 - 100 are normal, and -1 indicates a stall.
446 * Observe this property with a {@link PropertyChangeListener}.
447 * <p>
448 * At a minimum, the unpacker must set progress to 0
449 * at the beginning of a packing operation, and to 100
450 * at the end.
451 * @see #addPropertyChangeListener
452 */
453 String PROGRESS = "pack.progress";
454
455 /** The string "keep", a possible value for certain properties.
456 * @see #DEFLATE_HINT
457 * @see #MODIFICATION_TIME
458 */
459 String KEEP = "keep";
460
461 /** The string "pass", a possible value for certain properties.
462 * @see #UNKNOWN_ATTRIBUTE
463 * @see #CLASS_ATTRIBUTE_PFX
464 * @see #FIELD_ATTRIBUTE_PFX
465 * @see #METHOD_ATTRIBUTE_PFX
466 * @see #CODE_ATTRIBUTE_PFX
467 */
468 String PASS = "pass";
469
470 /** The string "strip", a possible value for certain properties.
471 * @see #UNKNOWN_ATTRIBUTE
472 * @see #CLASS_ATTRIBUTE_PFX
473 * @see #FIELD_ATTRIBUTE_PFX
474 * @see #METHOD_ATTRIBUTE_PFX
475 * @see #CODE_ATTRIBUTE_PFX
476 */
477 String STRIP = "strip";
478
479 /** The string "error", a possible value for certain properties.
480 * @see #UNKNOWN_ATTRIBUTE
481 * @see #CLASS_ATTRIBUTE_PFX
482 * @see #FIELD_ATTRIBUTE_PFX
483 * @see #METHOD_ATTRIBUTE_PFX
484 * @see #CODE_ATTRIBUTE_PFX
485 */
486 String ERROR = "error";
487
488 /** The string "true", a possible value for certain properties.
489 * @see #KEEP_FILE_ORDER
490 * @see #DEFLATE_HINT
491 */
492 String TRUE = "true";
493
494 /** The string "false", a possible value for certain properties.
495 * @see #KEEP_FILE_ORDER
496 * @see #DEFLATE_HINT
497 */
498 String FALSE = "false";
499
500 /** The string "latest", a possible value for certain properties.
501 * @see #MODIFICATION_TIME
502 */
503 String LATEST = "latest";
504
505 /**
506 * Get the set of this engine's properties.
507 * This set is a "live view", so that changing its
508 * contents immediately affects the Packer engine, and
509 * changes from the engine (such as progress indications)
510 * are immediately visible in the map.
511 *
512 * <p>The property map may contain pre-defined implementation
513 * specific and default properties. Users are encouraged to
514 * read the information and fully understand the implications,
515 * before modifying pre-existing properties.
516 * <p>
517 * Implementation specific properties are prefixed with a
518 * package name associated with the implementor, beginning
519 * with <tt>com.</tt> or a similar prefix.
520 * All property names beginning with <tt>pack.</tt> and
521 * <tt>unpack.</tt> are reserved for use by this API.
522 * <p>
523 * Unknown properties may be ignored or rejected with an
524 * unspecified error, and invalid entries may cause an
525 * unspecified error to be thrown.
526 *
527 * <p>
528 * The returned map implements all optional {@link SortedMap} operations
529 * @return A sorted association of property key strings to property
530 * values.
531 */
532 SortedMap<String, String> properties();
533
534 /**
535 * Takes a JarFile and converts it into a Pack200 archive.
536 * <p>
537 * Closes its input but not its output. (Pack200 archives are appendable.)
538 * @param in a JarFile
539 * @param out an OutputStream
540 * @exception IOException if an error is encountered.
541 */
542 void pack(JarFile in, OutputStream out) throws IOException;
543
544 /**
545 * Takes a JarInputStream and converts it into a Pack200 archive.
546 * <p>
547 * Closes its input but not its output. (Pack200 archives are appendable.)
548 * <p>
549 * The modification time and deflation hint attributes are not available,
550 * for the JAR manifest file and its containing directory.
551 *
552 * @see #MODIFICATION_TIME
553 * @see #DEFLATE_HINT
554 * @param in a JarInputStream
555 * @param out an OutputStream
556 * @exception IOException if an error is encountered.
557 */
558 void pack(JarInputStream in, OutputStream out)
559 throws IOException;
560
561 /**
562 * Registers a listener for PropertyChange events on the properties map.
563 * This is typically used by applications to update a progress bar.
564 *
565 * @see #properties
566 * @see #PROGRESS
567 * @param listener An object to be invoked when a property is changed.
568 */
569 void addPropertyChangeListener(PropertyChangeListener listener);
570
571 /**
572 * Remove a listener for PropertyChange events, added by
573 * the {@link #addPropertyChangeListener}.
574 *
575 * @see #addPropertyChangeListener
576 * @param listener The PropertyChange listener to be removed.
577 */
578 void removePropertyChangeListener(
579 PropertyChangeListener listener);
580
581 }
582
583 /**
584 * The unpacker engine converts the packed stream to a JAR file.
585 * An instance of the engine can be obtained
586 * using {@link #newUnpacker}.
587 * <p>
588 * Every JAR file produced by this engine will include the string
589 * "<tt>PACK200</tt>" as a zip file comment.
590 * This allows a deployer to detect if a JAR archive was packed and unpacked.
591 * <p>
592 * This version of the unpacker is compatible with all previous versions.
593 * @since 1.5
594 */
595 public interface Unpacker {
596
597 /** The string "keep", a possible value for certain properties.
598 * @see #DEFLATE_HINT
599 */
600 String KEEP = "keep";
601
602 /** The string "true", a possible value for certain properties.
603 * @see #DEFLATE_HINT
604 */
605 String TRUE = "true";
606
607 /** The string "false", a possible value for certain properties.
608 * @see #DEFLATE_HINT
609 */
610 String FALSE = "false";
611
612 /**
613 * Property indicating that the unpacker should
614 * ignore all transmitted values for DEFLATE_HINT,
615 * replacing them by the given value, {@link #TRUE} or {@link #FALSE}.
616 * The default value is the special string {@link #KEEP},
617 * which asks the unpacker to preserve all transmitted
618 * deflation hints.
619 */
620 String DEFLATE_HINT = "unpack.deflate.hint";
621
622 /**
623 * The unpacker's progress as a percentage, as periodically
624 * updated by the unpacker.
625 * Values of 0 - 100 are normal, and -1 indicates a stall.
626 * Observe this property with a {@link PropertyChangeListener}.
627 * <p>
628 * At a minimum, the unpacker must set progress to 0
629 * at the beginning of a packing operation, and to 100
630 * at the end.
631 * @see #addPropertyChangeListener
632 */
633 String PROGRESS = "unpack.progress";
634
635 /**
636 * Get the set of this engine's properties. This set is
637 * a "live view", so that changing its
638 * contents immediately affects the Packer engine, and
639 * changes from the engine (such as progress indications)
640 * are immediately visible in the map.
641 *
642 * <p>The property map may contain pre-defined implementation
643 * specific and default properties. Users are encouraged to
644 * read the information and fully understand the implications,
645 * before modifying pre-existing properties.
646 * <p>
647 * Implementation specific properties are prefixed with a
648 * package name associated with the implementor, beginning
649 * with <tt>com.</tt> or a similar prefix.
650 * All property names beginning with <tt>pack.</tt> and
651 * <tt>unpack.</tt> are reserved for use by this API.
652 * <p>
653 * Unknown properties may be ignored or rejected with an
654 * unspecified error, and invalid entries may cause an
655 * unspecified error to be thrown.
656 *
657 * @return A sorted association of option key strings to option values.
658 */
659 SortedMap<String, String> properties();
660
661 /**
662 * Read a Pack200 archive, and write the encoded JAR to
663 * a JarOutputStream.
664 * The entire contents of the input stream will be read.
665 * It may be more efficient to read the Pack200 archive
666 * to a file and pass the File object, using the alternate
667 * method described below.
668 * <p>
669 * Closes its input but not its output. (The output can accumulate more elements.)
670 * @param in an InputStream.
671 * @param out a JarOutputStream.
672 * @exception IOException if an error is encountered.
673 */
674 void unpack(InputStream in, JarOutputStream out)
675 throws IOException;
676
677 /**
678 * Read a Pack200 archive, and write the encoded JAR to
679 * a JarOutputStream.
680 * <p>
681 * Does not close its output. (The output can accumulate more elements.)
682 * @param in a File.
683 * @param out a JarOutputStream.
684 * @exception IOException if an error is encountered.
685 */
686 void unpack(File in, JarOutputStream out) throws IOException;
687
688 /**
689 * Registers a listener for PropertyChange events on the properties map.
690 * This is typically used by applications to update a progress bar.
691 *
692 * @see #properties
693 * @see #PROGRESS
694 * @param listener An object to be invoked when a property is changed.
695 */
696 void addPropertyChangeListener(PropertyChangeListener listener);
697
698 /**
699 * Remove a listener for PropertyChange events, added by
700 * the {@link #addPropertyChangeListener}.
701 *
702 * @see #addPropertyChangeListener
703 * @param listener The PropertyChange listener to be removed.
704 */
705 void removePropertyChangeListener(
706 PropertyChangeListener listener);
707 }
708
709 // Private stuff....
710
711 private static final String PACK_PROVIDER = "java.util.jar.Pack200.Packer";
712 private static final String UNPACK_PROVIDER = "java.util.jar.Pack200.Unpacker";
713
714 private static Class packerImpl;
715 private static Class unpackerImpl;
716
717 private synchronized static Object newInstance(String prop) {
718 String implName = "(unknown)";
719 try {
720 Class impl = (prop == PACK_PROVIDER) ? packerImpl
721 : unpackerImpl;
722 if (impl == null) {
723 // The first time, we must decide which class to use.
724 implName = (String) java.security.AccessController
725 .doPrivileged(new sun.security.action.GetPropertyAction(
726 prop, ""));
727 if (implName != null && !implName.equals(""))
728 impl = Class.forName(implName);
729 else if (prop == PACK_PROVIDER)
730 impl = com.sun.java.util.jar.pack.PackerImpl.class;
731 else
732 impl = com.sun.java.util.jar.pack.UnpackerImpl.class;
733 }
734 // We have a class. Now instantiate it.
735 return impl.newInstance();
736 } catch (ClassNotFoundException e) {
737 throw new Error("Class not found: " + implName
738 + ":\ncheck property " + prop
739 + " in your properties file.", e);
740 } catch (InstantiationException e) {
741 throw new Error("Could not instantiate: " + implName
742 + ":\ncheck property " + prop
743 + " in your properties file.", e);
744 } catch (IllegalAccessException e) {
745 throw new Error("Cannot access class: " + implName
746 + ":\ncheck property " + prop
747 + " in your properties file.", e);
748 }
749 }
750
751 }
|