com.hunnysoft.jmime
Class Text

java.lang.Object
  com.hunnysoft.jmime.Node
      com.hunnysoft.jmime.FieldBody
          com.hunnysoft.jmime.Text

All Implemented Interfaces:

java.lang.Cloneable

public class Text

extends FieldBody

Class that represents text in an unstructured header field body.

Header fields in messages that conform to RFC 2822 may contain only 7-bit ASCII characters. RFC 2047, part of the MIME standard, describes a method for encoding non-ASCII characters into 7-bit ASCII characters so that they may be inserted into message header fields. The method encodes text into encoded words. Each encoded word indentifies a character encoding (that is, a charset) and a transfer encoding, and contains the text encoded into 7-bit ASCII characters.

In Hunny JMIME, Text is a container for EncodedWord objects, and it has several methods to manage these EncodedWord objects. To get or set the literal text of the field body, call the inherited Node.string() and Node.setString(ByteString) methods. To get or set the text of the field body as a Unicode string, call the unicodeText() and setUnicodeText(String) convenience methods.

Field Summary

Fields inherited from class com.hunnysoft.jmime.FieldBody

mText

Fields inherited from class com.hunnysoft.jmime.Node

mIsModified, mParent, mString

Constructor Summary

Text()
Default constructor.

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

Text(Text other)
Copy constructor.

Method Summary

void	addEncodedWord(EncodedWord word) Adds an encoded word to the end of the list.
void	assemble() Assembles the string representation.
java.lang.String	charset() Gets the charset identifier for the text content.
java.lang.Object	clone() Creates a copy of this object.
void	deleteAllEncodedWords() Deletes all encoded words in the list.
EncodedWord	encodedWordAt(int index) Gets the encoded word at the specified position.
void	insertEncodedWordAt(int index, EncodedWord word) Inserts an encoded word at the specified position.
int	numEncodedWords() Gets the number of encoded words in the list.
void	parse() Parses the string representation.
EncodedWord	removeEncodedWordAt(int index) Removes the encoded word at the specified position.
void	setUnicodeText(java.lang.String text) Sets the text from a Unicode string.
void	setUnicodeText(java.lang.String text, java.lang.String charset) Sets the text from a Unicode string, with a charset hint.
java.lang.String	unicodeText() Gets the text as a Unicode string.

Methods inherited from class com.hunnysoft.jmime.FieldBody

fold, isFoldingEnabled, maybeFold, setFoldingEnabled, setText, text, unfold

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

Constructor Detail

Text

public Text()

Default constructor.

This constructor sets the Text object's string representation to the empty string and sets its parent node to null. The list of EncodedWord objects is initially empty.

Text

public Text(Text other)

Copy constructor.

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

Parameters:

other - Text instance to copy

Text

public Text(ByteString bstr)

Constructor that takes an initial byte string argument.

This constructor sets the Text 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 Text object that has the same value as this Text object. The parent node of the new Text object is set to null.

Overrides:

clone in class FieldBody

Returns:

a copy of this object

parse

public void parse()

Parses the string representation.

This method, inherited from Node, executes the parse operation for Text objects. The parse operation creates or updates the broken-down representation from the string representation. For Text objects, the parse operation parses the string representation to create a list of EncodedWord objects. This method also calls the parse() method of each EncodedWord object in its list.

You should call this method after you set or modify the string representation, and before you access any of the contained EncodedWord objects.

This method clears the is-modified flag.

Overrides:

parse in class FieldBody

assemble

public void assemble()

Assembles the string representation.

This method, inherited from Node, executes the assemble operation for Text objects. The assemble operation creates or updates the string representation from the broken-down representation. For Text objects, the assemble operation builds the string representation from the list of contained EncodedWord objects. Before it builds the string representation for the Text object, this method first calls the assemble() method of each EncodedWord object in its list.

You should call this method after you set or modify any of the contained EncodedWord objects, and before you retrieve the string representation.

This method clears the is-modified flag.

Overrides:

assemble in class FieldBody

unicodeText

public java.lang.String unicodeText()

Gets the text as a Unicode string.

This convenience method decodes all the encoded words and converts all the characters to Unicode characters.

Returns:

the string representation as a String.

setUnicodeText

public void setUnicodeText(java.lang.String text)

Sets the text from a Unicode string.

This convenience method creates and adds encoded words to the Text object. If all the characters in the Unicode string are ASCII characters, then the method adds the string unchanged -- no encoded words are created. Otherwise, if all the characters have code points less than 256, then the method creates encoded words that contain ISO-8859-1 characters encoded with the Q transfer encoding. If there are any characters that have code points greater than or equal to 256, then the method encodes the characters with the UTF-8 encoding and creates encoded words with either the B or Q transfer encoding, whichever yields the shortest length.

If you require an encoding other than ISO-8859-1 or UTF-8, then you may use the method setUnicodeText(String,String), which allows you to specify a particular encoding.

This method sets the is-modified flag.

Reference: The encoding of unstructured text using encoded words is described in RFC 2047.

Parameters:

text - the text to set

setUnicodeText

public void setUnicodeText(java.lang.String text,
                           java.lang.String charset)
                    throws java.io.UnsupportedEncodingException

Sets the text from a Unicode string, with a charset hint.

This convenience method sets the content of the Text object from a Unicode string. The method converts the Unicode characters to the specified character encoding (charset), then creates and adds encoded words using either the B transfer encoding (base64) or Q transfer encoding (a modified form of quoted-printable).

As a special case, if all the characters in the string have code points less than 128 (that is, ASCII characters), then the method adds the string unchanged and does not create encoded words.

The library uses the capability of the Java library to perform character set conversions and encodings. Therefore, the supported character encodings are those that are supported by the Java library. The method throws an UnsupportedEncodingException exception if the specified charset is not supported or recognized. Since the UTF-8 charset is always available, you should consider using UTF-8 as a fallback charset for any charset that is not supported.

The library uses the Q transfer encoding for all 8-bit character sets, and the B transfer encoding for all multi-byte character encodings. There are two exceptions: If the charset is UTF-8, then the library chooses between the Q and B transfer encodings, whichever yields the shortest length. If the charset is UTF-7, then the library uses the Q encoding.

This method sets the is-modified flag.

Reference: RFC 2047 describes the encoding of unstructured text using encoded words.

Parameters:

text - the text to set

charset - a charset identifier for the external encoding

Throws:

java.io.UnsupportedEncodingException - if the specified character encoding is not supported.

charset

public java.lang.String charset()

Gets the charset identifier for the text content.

To find the charset identifier, this convenience method finds the first encoded word that specifies a charset other than US-ASCII, then gets the charset from that encoded word.

Returns:

the character encoding identifier for the text content

numEncodedWords

public int numEncodedWords()

Gets the number of encoded words in the list.

Returns:

number of encoded words in the list

addEncodedWord

public void addEncodedWord(EncodedWord word)

Adds an encoded word to the end of the list.

Parameters:

word - EncodedWord object to add

deleteAllEncodedWords

public void deleteAllEncodedWords()

Deletes all encoded words in the list.

encodedWordAt

public EncodedWord encodedWordAt(int index)

Gets the encoded word at the specified position.

Parameters:

index - position of the EncodedWord object to get (0 <= index < numEncodedWords())

Returns:

EncodedWord object at the specified position

Throws:

java.lang.IndexOutOfBoundsException - if index is out of range

insertEncodedWordAt

public void insertEncodedWordAt(int index,
                                EncodedWord word)

Inserts an encoded word at the specified position.

Inserting at position 0 inserts the encoded word at the beginning. Inserting at position numEncodedWords() appends the encoded word to the end.

Parameters:

index - position in the list to insert the EncodedWord object (0 <= index <= numEncodedWords()).

word - EncodedWord object to insert

Throws:

java.lang.IndexOutOfBoundsException - if index is out of range

removeEncodedWordAt

public EncodedWord removeEncodedWordAt(int index)

Removes the encoded word at the specified position.

Parameters:

index - position of the EncodedWord object to remove (0 <= index < numEncodedWords()).

Returns:

the removed EncodedWord object

Throws:

java.lang.IndexOutOfBoundsException - if index is out of range