Debian Codegraph @

src/main/java/org/apache/tools/zip/ZipEncoding.java

raw
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 }