/* Copyright (c) 2001, Oracle Corporation. All rights reserved. */
package oracle.portal.utils.v1;

import java.io.*;
import oracle.webdb.utils.SimpleStringBuffer;
import oracle.webdb.utils.HTTPUtils;

/**
 * The class contains a utility method for encoding an arbitrary
 * <code>String</code> using the set of characters allowed in a URI, as defined
 * in <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396 - "Uniform
 * Resource Identifiers (URI): Generic Syntax"</a>. The method does not suffer
 * from the limitations of the <code>java.net.URLEncoder</code> in that it
 * provides control over the character encoding used for character to byte
 * conversions and is capable of encoding characters that are encoded by a
 * sequence of several bytes.<p>
 *
 * To convert a <code>String</code>, each character is examined in turn:
 * <ul>
 * <li>The ASCII characters '<code>a</code>' through '<code>z</code>',
 *     '<code>A</code>' through '<code>Z</code>', and '<code>0</code>' through
 *     '<code>9</code>' remain the same.
 * <li>Additional 'mark characters', i.e. '<code>-</code>', '<code>_</code>',
 *     '<code>.</code>', '<code>!</code>', '<code>~</code>', '<code>*</code>',
 *     '<code>'</code>' , '<code>(</code>', '<code>)</code>', remain the same.
 * <li>The space character '<code>&nbsp;</code>' is converted into a
 *     plus sign '<code>+</code>'.
 * <li>All other characters are converted into a sequence of bytes using the
 *     specified IANA character encoding, and each of these bytes is then
 *     encoded as a string "<code>%<i>xy</i></code>", where <i>xy</i> is the
 *     two-digit hexadecimal representation of the byte value.
 * </ul>
 */
public class MultiByteEncoder
{

    
    /**
     * Encodes a String using the set of characters allowed in a URI.
     *
     * @param value <code>String</code> to be translated.
     * @param encoding the IANA character encoding to be used to convert
     * non-ASCII characters into bytes (e.g. <code>"UTF-8"</code>).
     * @return the translated <code>String</code>.
     * @exception UnsupportedEncodingException if the given encoding is not a
     * supported IANA character encoding.
     */
    public static String encode(String value, String encoding)
        throws UnsupportedEncodingException
    {
        return HTTPUtils.encode(value, encoding);
    }

    /**
     * Encodes a String using the set of characters allowed in a URI.
     * This method encodes a multibyte string in UTF-8
     *
     * @param value <code>String</code> to be translated.
     * @return the translated <code>String</code>.
     */
    public static String encodeUTF(String value)
    {
        return HTTPUtils.encodeUTF(value);
    }

}
