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