Skip navigation links

oracle.i18n.net
Class MimeUtility

java.lang.Object
oracle.i18n.net.MimeUtility

public class MimeUtility

extends Object

The MimeUtility contains encoder and decoder information for MIME header and body text. This is an alternative to the javax.mail.internet.MimeUtility class, but MimeUtillity allows you to use Oracle or IANA character set names.

RFC 2047 specifies the MIME-safe header and body format. The mail header must be in the following US-ASCII character set encoding:

=? <charset> ? <encoding> ? <encoded-text> ?=

This output can be generated using the MimeUtility.encodeHeader(String, String, String) method. The receiver of the data is able to decode the data based on the included character set (for example, iso-8859-1) and encoding ("B" or "Q") information using MimeUtility.decodeHeader(String).

Since:

10.2.0.0

See Also:

RFC 2045, RFC 2047

Method Summary

static String	decodeHeader(String instr) Decodes a MIME-safe form into a String object for MIME header as per RFC 2047.
static String	decodeText(String intext) Decode "unstructured" headers, that is, headers that are defined as '*text' as per RFC 822.
static String	decodeText(String intext, String charset) Decode "unstructured" headers, that is, headers that are defined as '*text' as per RFC 822.
static String	decodeWord(String eword) The string is parsed using the rules in RFC 2047 for parsing an "encoded-word".
static String	decodeWord(String eword, String charset) Same as decodeWord(String), except that the specified charset is used and the one declared in the string is ignored.
static String	encodeHeader(String srcstr, String charset, String encoding) Encodes a String object into a MIME-safe form for MIME header as per RFC 2047.
static String	encodeText(String text) Encode a RFC 822 "text" token into mail-safe form as per RFC 2047.
static String	encodeText(String text, String charset, String encoding) Encode a RFC 822 "text" token into mail-safe form as per RFC 2047.
static String	encodeWord(String word) Encode a RFC 822 "word" token into mail-safe form as per RFC 2047.
static String	encodeWord(String word, String charset, String encoding) Encode a RFC 822 "word" token into mail-safe form as per RFC 2047.
static String	getDefaultJavaCharset() Get the default charset corresponding to the system's current default locale.
static String	javaCharset(String charset) Convert a MIME charset name into a valid Java encoding name.
static String	mimeCharset(String encoding) Convert a java encoding into its MIME charset name.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

encodeHeader

public static String encodeHeader(String srcstr,
                                  String charset,
                                  String encoding)
                           throws UnsupportedEncodingException

Encodes a String object into a MIME-safe form for MIME header as per RFC 2047.

Currently, AL16UTF16 (also known as UTF-16BE) is not supported.

The output includes the character set and encoding (for example, base64 or quoted-printable) information in the following form:

=? <charset> ? <encoding> ? <encoded-text> ?=

Parameters:

srcstr - a String object to be encoded

charset - an Oracle or IANA character set name

encoding - base64 ("B") or quoted-printable ("Q")

Returns:

an encoded String object

Throws:

UnsupportedEncodingException - if the character set name is invalid or not supported

decodeHeader

public static String decodeHeader(String instr)
                           throws UnsupportedEncodingException

Decodes a MIME-safe form into a String object for MIME header as per RFC 2047.

The input is expected to include the character set and encoding (for example, base64 or quoted-printable) information in the following form:

=? <charset> ? <encoding> ? <encoded-text> ?=

Parameters:

instr - a String object to be decoded.

Returns:

a decoded String object

Throws:

UnsupportedEncodingException - - if the character set name is invalid or not supported

mimeCharset

public static String mimeCharset(String encoding)

Convert a java encoding into its MIME charset name.

Parameters:

encoding - a Java encoding

Returns:

the MIME/IANA equivalent. If no mapping is available, the passed in encoding is returned.

javaCharset

public static String javaCharset(String charset)

Convert a MIME charset name into a valid Java encoding name.

Parameters:

charset - the MIME charset name

Returns:

the Java encoding equivalent. If a suitable mapping is not available, the passed in charset is returned.

getDefaultJavaCharset

public static String getDefaultJavaCharset()

Get the default charset corresponding to the system's current default locale. If the System property mail.mime.charset is set, a system charset corresponding to this MIME charset will be returned.

Returns:

the default charset of the system's default locale, as a Java charset. (NOT a MIME charset)

Since:

JavaMail 1.1

decodeWord

public static String decodeWord(String eword,
                                String charset)
                         throws UnsupportedEncodingException

Same as decodeWord(String), except that the specified charset is used and the one declared in the string is ignored.

Parameters:

eword - the possibly encoded value

charset - MIME charset name

Throws:

ParseException - if the string is not an encoded-word as per RFC 2047.

UnsupportedEncodingException - if the charset conversion failed.

decodeWord

public static String decodeWord(String eword)
                         throws UnsupportedEncodingException

The string is parsed using the rules in RFC 2047 for parsing an "encoded-word". If the parse fails, a ParseException is thrown. Otherwise, it is transfer-decoded, and then charset-converted into Unicode. If the charset-conversion fails, an UnsupportedEncodingException is thrown.

Parameters:

eword - the possibly encoded value

Throws:

ParseException - if the string is not an encoded-word as per RFC 2047.

UnsupportedEncodingException - if the charset conversion failed.

encodeText

public static String encodeText(String text)
                         throws UnsupportedEncodingException

Encode a RFC 822 "text" token into mail-safe form as per RFC 2047.

The given Unicode string is examined for non US-ASCII characters. If the string contains only US-ASCII characters, it is returned as-is. If the string contains non US-ASCII characters, it is first character-encoded using the platform's default charset, then transfer-encoded using either the B or Q encoding. The resulting bytes are then returned as a Unicode string containing only ASCII characters.

Note that this method should be used to encode only "unstructured" RFC 822 headers.

Example of usage:

  MimePart part = ...
  String rawvalue = "FooBar Mailer, Japanese version 1.1"
  try {
    // If we know for sure that rawvalue contains only US-ASCII 
    // characters, we can skip the encoding part
    part.setHeader("X-mailer", MimeUtility.encodeText(rawvalue));
  } catch (UnsupportedEncodingException e) {
    // encoding failure
  } catch (MessagingException me) {
   // setHeader() failure
  }

 

Parameters:

text - Unicode string

Returns:

Unicode string containing only US-ASCII characters

Throws:

UnsupportedEncodingException - if the encoding fails

encodeText

public static String encodeText(String text,
                                String charset,
                                String encoding)
                         throws UnsupportedEncodingException

Encode a RFC 822 "text" token into mail-safe form as per RFC 2047.

The given Unicode string is examined for non US-ASCII characters. If the string contains only US-ASCII characters, it is returned as-is. If the string contains non US-ASCII characters, it is first character-encoded using the specified charset, then transfer-encoded using either the B or Q encoding. The resulting bytes are then returned as a Unicode string containing only ASCII characters.

Note that this method should be used to encode only "unstructured" RFC 822 headers.

Parameters:

text - the header value

charset - the charset. If this parameter is null, the platform's default chatset is used.

encoding - the encoding to be used. Currently supported values are "B" and "Q". If this parameter is null, then the "Q" encoding is used if most of characters to be encoded are in the ASCII charset, otherwise "B" encoding is used.

Returns:

Unicode string containing only US-ASCII characters

Throws:

UnsupportedEncodingException

decodeText

public static String decodeText(String intext)
                         throws UnsupportedEncodingException

Decode "unstructured" headers, that is, headers that are defined as '*text' as per RFC 822.

The string is decoded using the algorithm specified in RFC 2047, Section 6.1.1. If the charset-conversion fails for any sequence, an UnsupportedEncodingException is thrown. If the String is not an RFC 2047 style encoded header, it is returned as-is

Example of usage:

  MimePart part = ...
  String rawvalue = null;
  String  value = null;
  try {
    if ((rawvalue = part.getHeader("X-mailer")[0]) != null)
      value = MimeUtility.decodeText(rawvalue);
  } catch (UnsupportedEncodingException e) {
      // Don't care
      value = rawvalue;
  } catch (MessagingException me) { }

  return value;

 

Parameters:

intext - the possibly encoded value

Throws:

UnsupportedEncodingException - if the charset conversion failed.

decodeText

public static String decodeText(String intext,
                                String charset)
                         throws UnsupportedEncodingException

Decode "unstructured" headers, that is, headers that are defined as '*text' as per RFC 822.

The string is decoded using the algorithm specified in RFC 2047, Section 6.1.1. If the charset-conversion fails for any sequence, an UnsupportedEncodingException is thrown. If the String is not an RFC 2047 style encoded header, it is returned as-is

Example of usage:

  MimePart part = ...
  String rawvalue = null;
  String  value = null;
  try {
    if ((rawvalue = part.getHeader("X-mailer")[0]) != null)
      value = MimeUtility.decodeText(rawvalue);
  } catch (UnsupportedEncodingException e) {
      // Don't care
      value = rawvalue;
  } catch (MessagingException me) { }

  return value;

 

Parameters:

intext - the possibly encoded value

charset - charset of intext

Throws:

UnsupportedEncodingException - if the charset conversion failed.

encodeWord

public static String encodeWord(String word)
                         throws UnsupportedEncodingException

Encode a RFC 822 "word" token into mail-safe form as per RFC 2047.

The given Unicode string is examined for non US-ASCII characters. If the string contains only US-ASCII characters, it is returned as-is. If the string contains non US-ASCII characters, it is first character-encoded using the platform's default charset, then transfer-encoded using either the B or Q encoding. The resulting bytes are then returned as a Unicode string containing only ASCII characters.

This method is meant to be used when creating RFC 822 "phrases". The InternetAddress class, for example, uses this to encode it's 'phrase' component.

Parameters:

word - Unicode string

Returns:

Array of Unicode strings containing only US-ASCII characters.

Throws:

UnsupportedEncodingException - if the encoding fails

encodeWord

public static String encodeWord(String word,
                                String charset,
                                String encoding)
                         throws UnsupportedEncodingException

Encode a RFC 822 "word" token into mail-safe form as per RFC 2047.

The given Unicode string is examined for non US-ASCII characters. If the string contains only US-ASCII characters, it is returned as-is. If the string contains non US-ASCII characters, it is first character-encoded using the specified charset, then transfer-encoded using either the B or Q encoding. The resulting bytes are then returned as a Unicode string containing only ASCII characters.

Parameters:

word - Unicode string

charset - the MIME charset

encoding - the encoding to be used. Currently supported values are "B" and "Q". If this parameter is null, then the "Q" encoding is used if most of characters to be encoded are in the ASCII charset, otherwise "B" encoding is used.

Returns:

Unicode string containing only US-ASCII characters

Throws:

UnsupportedEncodingException - if the encoding fails

Skip navigation links