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

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