## HTTPClient
Class Codecs

    java.lang.Object
      HTTPClient.Codecs

public class Codecs
extends Object

This class collects various encoders and decoders.

Method Summary
`static byte[]` `base64Decode(byte[] data)` This method decodes the given byte[] using the base64-encoding specified in RFC-2045 (Section 6.8).
`static String` `base64Decode(String str)` This method decodes the given string using the base64-encoding specified in RFC-2045 (Section 6.8).
`static byte[]` `base64Encode(byte[] data)` This method encodes the given byte[] using the base64-encoding specified in RFC-2045 (Section 6.8).
`static String` `base64Encode(String str)` This method encodes the given string using the base64-encoding specified in RFC-2045 (Section 6.8).
`static Object` `chunkedDecode(InputStream input)` Decodes chunked data.
`static byte[]` `chunkedEncode(byte[] data, int off, int len, NVPair[] ftrs, boolean last)` Encodes data used the chunked encoding.
`static byte[]` `chunkedEncode(byte[] data, NVPair[] ftrs, boolean last)` Encodes data used the chunked encoding.
`(package private) static long` `getChunkLength(InputStream input)` Gets the length of the chunk.
`static NVPair[]` `mpFormDataDecode(byte[] data, String cont_type, String dir)` This method decodes a multipart/form-data encoded string.
`static NVPair[]` `mpFormDataDecode(byte[] data, String cont_type, String dir, FilenameMangler mangler)` This method decodes a multipart/form-data encoded string.
`static byte[]` `mpFormDataEncode(NVPair[] opts, NVPair[] files, NVPair[] ct_hdr)` This method encodes name/value pairs and files into a byte array using the multipart/form-data encoding.
`static byte[]` `mpFormDataEncode(NVPair[] opts, NVPair[] files, NVPair[] ct_hdr, FilenameMangler mangler)` This method encodes name/value pairs and files into a byte array using the multipart/form-data encoding.
`static String` `nv2query(NVPair[] pairs)` Turns an array of name/value pairs into the string "name1=value1&name2=value2&name3=value3".
`static NVPair[]` `query2nv(String query)` Turns a string of the form "name1=value1&name2=value2&name3=value3" into an array of name/value pairs.
`static String` `quotedPrintableDecode(String str)` This method does a quoted-printable decoding of the given string according to RFC-2045 (Section 6.7).
`static String` `quotedPrintableEncode(String str)` This method does a quoted-printable encoding of the given string according to RFC-2045 (Section 6.7).
`static String` `URLDecode(String str)` This method decodes the given urlencoded string.
`static String` `URLEncode(String str)` This method urlencodes the given string.
`static byte[]` `uudecode(char[] data)` This method decodes the given uuencoded char[].
`static char[]` `uuencode(byte[] data)` This method encodes the given byte[] using the unix uuencode encding.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### base64Encode

    public static final String base64Encode(String str)

  This method encodes the given string using the base64-encoding specified in RFC-2045 (Section 6.8). It's used for example in the "Basic" authorization scheme.

  Parameters:
    `str` - the string
  Returns:
    the base64-encoded str

### base64Encode

    public static final byte[] base64Encode(byte[] data)

  This method encodes the given byte[] using the base64-encoding specified in RFC-2045 (Section 6.8).

  Parameters:
    `data` - the data
  Returns:
    the base64-encoded data

### base64Decode

    public static final String base64Decode(String str)

  This method decodes the given string using the base64-encoding specified in RFC-2045 (Section 6.8).

  Parameters:
    `str` - the base64-encoded string.
  Returns:
    the decoded str.

### base64Decode

    public static final byte[] base64Decode(byte[] data)

  This method decodes the given byte[] using the base64-encoding specified in RFC-2045 (Section 6.8).

  Parameters:
    `data` - the base64-encoded data.
  Returns:
    the decoded data.

### uuencode

    public static final char[] uuencode(byte[] data)

  This method encodes the given byte[] using the unix uuencode encding. The output is split into lines starting with the encoded number of encoded octets in the line and ending with a newline. No line is longer than 45 octets (60 characters), not including length and newline.

  Note: just the raw data is encoded; no 'begin' and 'end' lines are added as is done by the unix `uuencode` utility.

  Parameters:
    `data` - the data
  Returns:
    the uuencoded data

### uudecode

    public static final byte[] uudecode(char[] data)

  This method decodes the given uuencoded char[].

  Note: just the actual data is decoded; any 'begin' and 'end' lines such as those generated by the unix `uuencode` utility must not be included.

  Parameters:
    `data` - the uuencode-encoded data.
  Returns:
    the decoded data.

### quotedPrintableEncode

    public static final String quotedPrintableEncode(String str)

  This method does a quoted-printable encoding of the given string according to RFC-2045 (Section 6.7). Note: this assumes 8-bit characters.

  Parameters:
    `str` - the string
  Returns:
    the quoted-printable encoded string

### quotedPrintableDecode

    public static final String quotedPrintableDecode(String str)
                                              throws ParseException

  This method does a quoted-printable decoding of the given string according to RFC-2045 (Section 6.7). Note: this method expects the whole message in one chunk, not line by line.

  Parameters:
    `str` - the message
  Returns:
    the decoded message
  Throws:
    `ParseException` - If a '=' is not followed by a valid 2-digit hex number or '\r\n'.

### URLEncode

    public static final String URLEncode(String str)

  This method urlencodes the given string. This method is here for symmetry reasons and just calls java.net.URLEncoder.encode().

  Parameters:
    `str` - the string
  Returns:
    the url-encoded string

### URLDecode

    public static final String URLDecode(String str)
                                  throws ParseException

  This method decodes the given urlencoded string.

  Parameters:
    `str` - the url-encoded string
  Returns:
    the decoded string
  Throws:
    `ParseException` - If a '%' is not followed by a valid 2-digit hex number.

### mpFormDataDecode

    public static final NVPair[] mpFormDataDecode(byte[] data,
                                                  String cont_type,
                                                  String dir)
                                           throws IOException,
                                                  ParseException

  This method decodes a multipart/form-data encoded string.

  Parameters:
    `data` - the form-data to decode.
    `cont_type` - the content type header (must contain the boundary string).
    `dir` - the directory to create the files in.
  Returns:
    an array of name/value pairs, one for each part; the name is the 'name' attribute given in the Content-Disposition header; the value is either the name of the file if a filename attribute was found, or the contents of the part.
  Throws:
    `IOException` - If any file operation fails.
    `ParseException` - If an error during parsing occurs.
  See Also:
    `mpFormDataDecode(byte[], java.lang.String, java.lang.String, HTTPClient.FilenameMangler)`

### mpFormDataDecode

    public static final NVPair[] mpFormDataDecode(byte[] data,
                                                  String cont_type,
                                                  String dir,
                                                  FilenameMangler mangler)
                                           throws IOException,
                                                  ParseException

  This method decodes a multipart/form-data encoded string. The boundary is parsed from the cont_type parameter, which must be of the form 'multipart/form-data; boundary=...'. Any encoded files are created in the directory specified by dir using the encoded filename.

  Note: Does not handle nested encodings (yet).

  Examples: If you're receiving a multipart/form-data encoded response from a server you could use something like:

           NVPair[] opts = Codecs.mpFormDataDecode(resp.getData(),
                                        resp.getHeader("Content-type"), ".");

  If you're using this in a Servlet to decode the body of a request from a client you could use something like:

           byte[] body = new byte[req.getContentLength()];
           new DataInputStream(req.getInputStream()).readFully(body);
           NVPair[] opts = Codecs.mpFormDataDecode(body, req.getContentType(),
                                                   ".");

  (where 'req' is the HttpServletRequest).

  Assuming the data received looked something like:

       -----------------------------114975832116442893661388290519
       Content-Disposition: form-data; name="option"

       doit
       -----------------------------114975832116442893661388290519
       Content-Disposition: form-data; name="comment"; filename="comment.txt"

       Gnus and Gnats are not Gnomes.
       -----------------------------114975832116442893661388290519--

  you would get one file called comment.txt in the current directory, and opts would contain two elements: {"option", "doit"} and {"comment", "comment.txt"}

  Parameters:
    `data` - the form-data to decode.
    `cont_type` - the content type header (must contain the boundary string).
    `dir` - the directory to create the files in.
    `mangler` - the filename mangler, or null if no mangling is to be done. This is invoked just before each file is created and written, thereby allowing you to control the names of the files.
  Returns:
    an array of name/value pairs, one for each part; the name is the 'name' attribute given in the Content-Disposition header; the value is either the name of the file if a filename attribute was found, or the contents of the part.
  Throws:
    `IOException` - If any file operation fails.
    `ParseException` - If an error during parsing occurs.

### mpFormDataEncode

    public static final byte[] mpFormDataEncode(NVPair[] opts,
                                                NVPair[] files,
                                                NVPair[] ct_hdr)
                                         throws IOException

  This method encodes name/value pairs and files into a byte array using the multipart/form-data encoding.

  Parameters:
    `opts` - the simple form-data to encode (may be null); for each NVPair the name refers to the 'name' attribute to be used in the header of the part, and the value is contents of the part.
    `files` - the files to encode (may be null); for each NVPair the name refers to the 'name' attribute to be used in the header of the part, and the value is the actual filename (the file will be read and it's contents put in the body of that part).
    `ct_hdr` - this returns a new NVPair in the 0'th element which contains name = "Content-Type", value = "multipart/form-data; boundary=..." (the reason this parameter is an array is because a) that's the only way to simulate pass-by-reference and b) you need an array for the headers parameter to the Post() or Put() anyway).
  Returns:
    an encoded byte array containing all the opts and files.
  Throws:
    `IOException` - If any file operation fails.
  See Also:
    `mpFormDataEncode(HTTPClient.NVPair[], HTTPClient.NVPair[], HTTPClient.NVPair[], HTTPClient.FilenameMangler)`

### mpFormDataEncode

    public static final byte[] mpFormDataEncode(NVPair[] opts,
                                                NVPair[] files,
                                                NVPair[] ct_hdr,
                                                FilenameMangler mangler)
                                         throws IOException

  This method encodes name/value pairs and files into a byte array using the multipart/form-data encoding. The boundary is returned as part of ct_hdr.
  Example:

           NVPair[] opts = { new NVPair("option", "doit") };
           NVPair[] file = { new NVPair("comment", "comment.txt") };
           NVPair[] hdrs = new NVPair[1];
           byte[]   data = Codecs.mpFormDataEncode(opts, file, hdrs);
           con.Post("/cgi-bin/handle-it", data, hdrs);

  data will look something like the following:

       -----------------------------114975832116442893661388290519
       Content-Disposition: form-data; name="option"

       doit
       -----------------------------114975832116442893661388290519
       Content-Disposition: form-data; name="comment"; filename="comment.txt"
       Content-Type: text/plain

       Gnus and Gnats are not Gnomes.
       -----------------------------114975832116442893661388290519--

  where the "Gnus and Gnats ..." is the contents of the file comment.txt in the current directory.

  If no elements are found in the parameters then a zero-length byte[] is returned and the content-type is set to application/octet-string (because a multipart must always have at least one part.

  For files an attempt is made to discover the content-type, and if found a Content-Type header will be added to that part. The content type is retrieved using java.net.URLConnection.guessContentTypeFromName() - see java.net.URLConnection.setFileNameMap() for how to modify that map. Note that under JDK 1.1 by default the map seems to be empty. If you experience troubles getting the server to accept the data then make sure the fileNameMap is returning a content-type for each file (this may mean you'll have to set your own).

  Parameters:
    `opts` - the simple form-data to encode (may be null); for each NVPair the name refers to the 'name' attribute to be used in the header of the part, and the value is contents of the part. null elements in the array are ingored.
    `files` - the files to encode (may be null); for each NVPair the name refers to the 'name' attribute to be used in the header of the part, and the value is the actual filename (the file will be read and it's contents put in the body of that part). null elements in the array are ingored.
    `ct_hdr` - this returns a new NVPair in the 0'th element which contains name = "Content-Type", value = "multipart/form-data; boundary=..." (the reason this parameter is an array is because a) that's the only way to simulate pass-by-reference and b) you need an array for the headers parameter to the Post() or Put() anyway). The exception to this is that if no opts or files are given the type is set to "application/octet-stream" instead.
    `mangler` - the filename mangler, or null if no mangling is to be done. This allows you to change the name used in the filename attribute of the Content-Disposition header. Note: the mangler will be invoked twice for each filename.
  Returns:
    an encoded byte array containing all the opts and files.
  Throws:
    `IOException` - If any file operation fails.

### nv2query

    public static final String nv2query(NVPair[] pairs)

  Turns an array of name/value pairs into the string "name1=value1&name2=value2&name3=value3". The names and values are first urlencoded. This is the form in which form-data is passed to a cgi script.

  Parameters:
    `pairs` - the array of name/value pairs
  Returns:
    a string containg the encoded name/value pairs

### query2nv

    public static final NVPair[] query2nv(String query)
                                   throws ParseException

  Turns a string of the form "name1=value1&name2=value2&name3=value3" into an array of name/value pairs. The names and values are urldecoded. The query string is in the form in which form-data is received in a cgi script.

  Parameters:
    `query` - the query string containing the encoded name/value pairs
  Returns:
    an array of NVPairs
  Throws:
    `ParseException` - If the '=' is missing in any field, or if the urldecoding of the name or value fails

### chunkedEncode

    public static final byte[] chunkedEncode(byte[] data,
                                             NVPair[] ftrs,
                                             boolean last)

  Encodes data used the chunked encoding. last signales if this is the last chunk, in which case the appropriate footer is generated.

  Parameters:
    `data` - the data to be encoded; may be null.
    `ftrs` - optional headers to include in the footer (ignored if not last); may be null.
    `last` - whether this is the last chunk.
  Returns:
    an array of bytes containing the chunk

### chunkedEncode

    public static final byte[] chunkedEncode(byte[] data,
                                             int off,
                                             int len,
                                             NVPair[] ftrs,
                                             boolean last)

  Encodes data used the chunked encoding. last signales if this is the last chunk, in which case the appropriate footer is generated.

  Parameters:
    `data` - the data to be encoded; may be null.
    `off` - an offset into the data
    `len` - the number of bytes to take from data
    `ftrs` - optional headers to include in the footer (ignored if not last); may be null.
    `last` - whether this is the last chunk.
  Returns:
    an array of bytes containing the chunk

### chunkedDecode

    public static final Object chunkedDecode(InputStream input)
                                      throws ParseException,
                                             IOException

  Decodes chunked data. The chunks are read from an InputStream, which is assumed to be correctly positioned. Use 'xxx instanceof byte[]' and 'xxx instanceof NVPair[]' to determine if this was data or the last chunk.

  Parameters:
    `input` - the stream from which to read the next chunk.
  Returns:
    If this was a data chunk then it returns a byte[]; else it's the footer and it returns a NVPair[] containing the footers.
  Throws:
    `ParseException` - If any exception during parsing occured.
    `IOException` - If any exception during reading occured.

### getChunkLength

    static final long getChunkLength(InputStream input)
                              throws ParseException,
                                     IOException

  Gets the length of the chunk.

  Parameters:
    `input` - the stream from which to read the next chunk.
  Returns:
    the length of chunk to follow (w/o trailing CR LF).
  Throws:
    `ParseException` - If any exception during parsing occured.
    `IOException` - If any exception during reading occured.