| 1 |
/* |
| 2 |
* Licensed to the Apache Software Foundation (ASF) under one |
| 3 |
* or more contributor license agreements. See the NOTICE file |
| 4 |
* distributed with this work for additional information |
| 5 |
* regarding copyright ownership. The ASF licenses this file |
| 6 |
* to you under the Apache License, Version 2.0 (the |
| 7 |
* "License"); you may not use this file except in compliance |
| 8 |
* with the License. You may obtain a copy of the License at |
| 9 |
* |
| 10 |
* http://www.apache.org/licenses/LICENSE-2.0 |
| 11 |
* |
| 12 |
* Unless required by applicable law or agreed to in writing, |
| 13 |
* software distributed under the License is distributed on an |
| 14 |
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 15 |
* KIND, either express or implied. See the License for the |
| 16 |
* specific language governing permissions and limitations |
| 17 |
* under the License. |
| 18 |
*/ |
| 19 |
|
| 20 |
package org.apache.tools.zip; |
| 21 |
|
| 22 |
import java.io.IOException; |
| 23 |
import java.nio.ByteBuffer; |
| 24 |
|
| 25 |
/** |
| 26 |
* An interface for encoders that do a pretty encoding of ZIP |
| 27 |
* filenames. |
| 28 |
* |
| 29 |
* <p>There are mostly two implementations, one that uses java.nio |
| 30 |
* {@link java.nio.charset.Charset Charset} and one implementation, |
| 31 |
* which copes with simple 8 bit charsets, because java-1.4 did not |
| 32 |
* support Cp437 in java.nio.</p> |
| 33 |
* |
| 34 |
* <p>The main reason for defining an own encoding layer comes from |
| 35 |
* the problems with {@link java.lang.String#getBytes(String) |
| 36 |
* String.getBytes}, which encodes unknown characters as ASCII |
| 37 |
* quotation marks ('?'). Quotation marks are per definition an |
| 38 |
* invalid filename on some operating systems like Windows, which |
| 39 |
* leads to ignored ZIP entries.</p> |
| 40 |
* |
| 41 |
* <p>All implementations should implement this interface in a |
| 42 |
* reentrant way.</p> |
| 43 |
*/ |
| 44 |
interface ZipEncoding { |
| 45 |
/** |
| 46 |
* Check, whether the given string may be losslessly encoded using this |
| 47 |
* encoding. |
| 48 |
* |
| 49 |
* @param name A filename or ZIP comment. |
| 50 |
* @return Whether the given name may be encoded with out any losses. |
| 51 |
*/ |
| 52 |
boolean canEncode(String name); |
| 53 |
|
| 54 |
/** |
| 55 |
* Encode a filename or a comment to a byte array suitable for |
| 56 |
* storing it to a serialized zip entry. |
| 57 |
* |
| 58 |
* <p>Examples for CP 437 (in pseudo-notation, right hand side is |
| 59 |
* C-style notation):</p> |
| 60 |
* <pre> |
| 61 |
* encode("\u20AC_for_Dollar.txt") = "%U20AC_for_Dollar.txt" |
| 62 |
* encode("\u00D6lf\u00E4sser.txt") = "\231lf\204sser.txt" |
| 63 |
* </pre> |
| 64 |
* |
| 65 |
* @param name A filename or ZIP comment. |
| 66 |
* @return A byte buffer with a backing array containing the |
| 67 |
* encoded name. Unmappable characters or malformed |
| 68 |
* character sequences are mapped to a sequence of utf-16 |
| 69 |
* words encoded in the format <code>%Uxxxx</code>. It is |
| 70 |
* assumed, that the byte buffer is positioned at the |
| 71 |
* beinning of the encoded result, the byte buffer has a |
| 72 |
* backing array and the limit of the byte buffer points |
| 73 |
* to the end of the encoded result. |
| 74 |
* @throws IOException |
| 75 |
*/ |
| 76 |
ByteBuffer encode(String name) throws IOException; |
| 77 |
|
| 78 |
/** |
| 79 |
* @param data The byte values to decode. |
| 80 |
* @return The decoded string. |
| 81 |
* @throws IOException |
| 82 |
*/ |
| 83 |
String decode(byte [] data) throws IOException; |
| 84 |
} |