com.hunnysoft.jmime
Class EncodedWord

java.lang.Object
  com.hunnysoft.jmime.Node
      com.hunnysoft.jmime.EncodedWord

All Implemented Interfaces:

java.lang.Cloneable

public class EncodedWord

extends Node

Class that represents an encoded-word in a header field.

EncodedWord represents an encoded word in a non-structured header field. In Internet email, and in MIME, only 7-bit ASCII characters are allowed in the header fields. RFC 2047 describes the method by which non-ASCII text can be encoded and inserted into certain header fields. In Hunny JMIME, EncodedWord represents a segment of encoded text and performs the encoding/decoding.

Encoded words have a charset identifier attribute, such as ISO-8859-1, and a transfer encoding type, which can be quoted-printable or base64. EncodedWord provides methods to set or get the charset identifier and the transfer encoding type. The charset identifier must be an identifier registered with the Internet Assigned Numbers Authority (IANA). The transfer encoding type must be either quoted-printable (the 'Q' encoding) or base64 (the 'B' encoding).

EncodedWord also contains strings for the decoded text and the entire encoded word. Use the inherited methods Node.setString(ByteString) and Node.string() to set or get the text of the entire encoded word.

To use EncodedWord to decode an encoded word, set the encoded word string using either the constructor EncodedWord(ByteString) or the inherited method Node.setString(ByteString). Then call parse(). You can then get the charset identifier and the decoded text.

To use EncodedWord to encode non-ASCII text, set the non-ASCII text using setDecodedText(ByteString). Also set the charset identifier using setCharset(String) and the encoding type using setEncodingType(char). Then call assemble(). You can then get the encoded word using the inherited method Node.string().

To set an encoded word into a header field (which must be a non-structured header field), use the method Text.addEncodedWord(EncodedWord).

Because encoded words can be mixed with unencoded ASCII text, Hunny JMIME provides pseudo-encoded words, which are treated like encoded words but are not really encoded. If the encoding type of an EncodedWord is the NUL character, then no encoding or decoding is done. Other than the fact that no encoding is done, such pseudo-encoded words can be treated exactly like regular encoded words.

If there is an error decoding an encoded word, EncodedWord will present the entire encoded word as the decoded text.

Field Summary

protected static byte	SAFE
protected static byte	SPECIAL
protected static byte	UNSAFE

Fields inherited from class com.hunnysoft.jmime.Node

mIsModified, mParent, mString

Constructor Summary

EncodedWord()
Default constructor.

EncodedWord(ByteString bstr)
Constructor that takes an initial byte string argument.

EncodedWord(EncodedWord other)
Copy constructor.

Method Summary

void	assemble() Assembles the string representation.
static ByteString	bDecode(ByteString str) Decodes a byte string with the B encoding.
static ByteString	bEncode(ByteString str) Encodes a byte string with the B encoding.
java.lang.String	charset() Gets the charset identifier.
java.lang.Object	clone() Creates a copy of this object.
ByteString	decodedText() Gets the decoded text.
char	encodingType() Gets the encoding type.
java.lang.String	language()
void	parse() Parses the string representation.
static ByteString	qDecode(ByteString str) Decodes a byte string with the Q encoding.
static ByteString	qEncode(ByteString str) Encodes a byte string with the Q encoding.
void	setCharset(java.lang.String charset) Sets the charset identifier.
void	setDecodedText(ByteString text) Sets the decoded text.
void	setEncodingType(char encodingType) Sets the encoding type.
void	setLanguage(java.lang.String lang)

Methods inherited from class com.hunnysoft.jmime.Node

_setString, isModified, parent, setModified, setParent, setString, string, toString

Methods inherited from class java.lang.Object

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

Field Detail

SAFE

protected static final byte SAFE

See Also:

Constant Field Values

UNSAFE

protected static final byte UNSAFE

See Also:

Constant Field Values

SPECIAL

protected static final byte SPECIAL

See Also:

Constant Field Values

Constructor Detail

EncodedWord

public EncodedWord()

Default constructor.

This constructor sets the EncodedWord object's string representation to the empty string and sets its parent node to null.

EncodedWord

public EncodedWord(EncodedWord other)

Copy constructor.

This constructor performs a deep copy of its argument. The parent node of the new EncodedWord object is set to null.

Parameters:

other - EncodedWord instance to copy

EncodedWord

public EncodedWord(ByteString bstr)

Constructor that takes an initial byte string argument.

This constructor sets the EncodedWord object's string representation to bstr and sets its parent node to null.

Normally, you call the parse() method immediately after this constructor to create the broken-down representation.

Parameters:

bstr - initial value for the string representation

Method Detail

clone

public java.lang.Object clone()

Creates a copy of this object.

This method, inherited from Object, creates a new EncodedWord object that has the same value as this EncodedWord object. The parent node of the new EncodedWord object is set to null.

Overrides:

clone in class Node

Returns:

a copy of this object

parse

public void parse()

Parses the string representation.

This method, inherited from Node, executes the parse operation for EncodedWord objects. The parse operation creates or updates the broken-down representation from the string representation. For EncodedWord objects, the parse operation parses the string representation to extract the charset identifier, encoding type, and the decoded text.

You should call this method after you set or modify the string representation, and before you access the charset, encoding type, or decoded text.

This method clears the is-modified flag.

Specified by:

parse in class Node

See Also:

Node.assemble()

assemble

public void assemble()

Assembles the string representation.

This method, inherited from Node, executes the assemble operation for EncodedWord objects. The assemble operation creates or updates the string representation from the broken-down representation. For EncodedWord objects, the assemble operation builds the string representation from the charset, encoding type, and decoded text.

You should call this method after you set or modify the charset, encoding type, or decoded text, and before you retrieve the string representation.

This method clears the is-modified flag.

Specified by:

assemble in class Node

See Also:

Node.parse()

charset

public java.lang.String charset()

Gets the charset identifier.

The charset identifier should be an identifier that has been registered with IANA. Examples of common charset identifiers include "US-ASCII", "ISO-8859-1" (Western Europe), "GB2312" (China), "BIG5" (Taiwan), "EUC-KR" (Korea), "UTF-8" and others.

Returns:

the character encoding identifier

setCharset

public void setCharset(java.lang.String charset)

Sets the charset identifier.

The charset identifier should be an identifier that has been registered with IANA. Examples of common charset identifiers include "US-ASCII", "ISO-8859-1" (Western Europe), "GB2312" (China), "BIG5" (Taiwan), "EUC-KR" (Korea), "UTF-8" and others.

Parameters:

charset - the character encoding identifier

language

public java.lang.String language()

setLanguage

public void setLanguage(java.lang.String lang)

encodingType

public char encodingType()

Gets the encoding type.

The encoding type must be one of: 'Q', 'q', 'B', 'b', or NUL. 'Q' and 'q' are equivalent and indicate the quoted-printable encoding. 'B' and 'b' are equivalent, and indicate the base64 encoding. The NUL character indicates no encoding, making this a pseudo-encoded word.

Returns:

encoding type

setEncodingType

public void setEncodingType(char encodingType)

Sets the encoding type.

The encoding type must be one of: 'Q', 'q', 'B', 'b', or NUL. 'Q' and 'q' are equivalent and indicate the quoted-printable encoding. 'B' and 'b' are equivalent, and indicate the base64 encoding. The NUL character indicates no encoding, making this a pseudo-encoded word.

Parameters:

encodingType - encoding type

decodedText

public ByteString decodedText()

Gets the decoded text.

Returns:

decoded text

setDecodedText

public void setDecodedText(ByteString text)

Sets the decoded text.

Parameters:

text - decoded text

qEncode

public static ByteString qEncode(ByteString str)

Encodes a byte string with the Q encoding.

The Q encoding is a modified form the the quoted-printable encoding. In the Q encoding, white space characters, including the end of line characters, are not allowed. The space character (ASCII 32) may be encoded as an underscore character ('_', ASCII 95), and the underscore character itself is always encoded using the hexadecimal encoding form ("_" encoded as "=5F"). In addition, other special characters such as '?' must be encoded using the hexadecimal encoding.

Parameters:

str - the string to encode

Returns:

the encoded string

bEncode

public static ByteString bEncode(ByteString str)

Encodes a byte string with the B encoding.

The 'B' encoding is the same as base64 encoding, except that white space characters (including the end of line characters) are not allowed in the encoded text.

Parameters:

str - the string to encode

Returns:

the encoded string

qDecode

public static ByteString qDecode(ByteString str)

Decodes a byte string with the Q encoding.

Parameters:

str - encoded string

Returns:

if successful, the decoded string; if unsuccessful, null

bDecode

public static ByteString bDecode(ByteString str)

Decodes a byte string with the B encoding.

Parameters:

str - encoded string

Returns:

if successful, the decoded string; if unsuccessful, null