com.hunnysoft.jmime.Node
com.hunnysoft.jmime.FieldBody
com.hunnysoft.jmime.Address
com.hunnysoft.jmime.Mailbox
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
Class that represents an RFC 2822 mailbox.
RFC 2822 defines a mailbox as an entity that can be the recipient of a message. A mailbox is more specific than an address, which may be either a mailbox or a group. An RFC 2822 mailbox contains a display name, a local part, an optional route, and a domain. For example, in the mailbox
Joe Schmoe <jschmoe@example.com>
"Joe Schmoe" is the display name, "jschmoe" is the local part, and "example.com" is the domain. The optional route is rarely seen in current usage, and is deprecated according to RFC 2822.
Note: The terms are not as precise as they should be. Technically, we should make a distinction between a mailbox and a mailbox name. We don't make that distinction because RFC 2822 doesn't make that distinction.
In Hunny JMIME, an RFC 2822 mailbox is represented by a
Mailbox object. Mailbox is a subclass of
Address, which reflects the fact that a mailbox is also an
address. A Mailbox contains strings for the display name,
local part, route, and domain of a mailbox.
Mailbox has methods for getting or setting the strings
it contains.
In the document tree representation of a message, a
Mailbox object may be only a leaf node, having a parent
node but no child nodes. Its parent node should be a Field
object or an AddressList object.
Usage
To use Mailbox to parse a mailbox string, create an
instance using the constructor that takes a ByteString argument.
Call the parse() method to parse the string representation. Then
call displayName(), localPart(), and domain() to
get the parsed substrings.
To use Mailbox to generate a mailbox string, create an
instance using the default constructor. Call setLocalPart(String), setDomain(String), and optionally
setDisplayName(String) to set the local part, domain, and
display name, respectively. Call assemble() to update the string
representation. Then, call Node.string() to retrieve the string
representation.
Mailbox Formats
The format of mailboxes found in Internet mail varies. The following shows some alternative formats:
In example (2), the quotation marks are required because the display name contains the characters "." and ",". In example (3), there is no display name. The format in example (4) is the traditional format for Usenet articles. Examples (5) and (6) use the encoding specified in RFC 2047. The encoding is not needed in these examples, because all the characters are 7-bit US-ASCII characters. However, the encoding is required if the display name contains characters not in the 7-bit US-ASCII character set. Example (5) uses a modified form of the quoted-printable transfer encoding (RFC 2045) to encode the display name "Joe H. Schmoe, Jr.", which uses the ISO 8859-1 character set. Example (6) uses the base64 transfer encoding (RFC 2045) to encode only the second "word" of the display name "Joe Schmoe", which uses the UTF-8 encoding of Unicode.
Hunny JMIME correctly parses mailboxes in all the formats shown above. When mailboxes are assembled (that is, generated), one of the formats in examples (1), (2), or (5) is selected in that order.
| Field Summary |
| Fields inherited from class com.hunnysoft.jmime.Address |
mIsValid |
| Fields inherited from class com.hunnysoft.jmime.FieldBody |
mText |
| Fields inherited from class com.hunnysoft.jmime.Node |
mIsModified, mParent, mString |
| Constructor Summary | |
Mailbox()
Default constructor. |
|
Mailbox(ByteString bstr)
Constructor that takes an initial byte string argument. |
|
Mailbox(Mailbox other)
Copy constructor. |
|
| Method Summary | |
void |
assemble()
Assembles the string representation. |
java.lang.String |
charset()
Gets the charset for the display name. |
java.lang.Object |
clone()
Creates a copy of this object. |
java.lang.String |
displayName()
Gets the display name as a Unicode string. |
java.lang.String |
domain()
Gets the domain. |
java.lang.String |
encodedDisplayName()
Gets the encoded display name. |
java.lang.String |
localPart()
Gets the local part. |
void |
parse()
Parses the string representation. |
java.lang.String |
route()
Gets the route. |
void |
setDisplayName(java.lang.String name)
Sets the display name from a Unicode string. |
void |
setDisplayName(java.lang.String name,
java.lang.String charset)
Sets the display name from a Unicode string, with a hint about the character encoding to use. |
void |
setDomain(java.lang.String domain)
Sets the domain. |
void |
setEncodedDisplayName(java.lang.String name)
Sets the encoded display name. |
void |
setLocalPart(java.lang.String localPart)
Sets the local part. |
void |
setRoute(java.lang.String route)
Sets the route. |
| Methods inherited from class com.hunnysoft.jmime.Address |
isValid |
| 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 |
public Mailbox()
This constructor sets the Mailbox object's string
representation to the empty string and sets its parent node to
null.
public Mailbox(Mailbox other)
This constructor performs a deep copy of its argument. The
parent node of the new Mailbox object is set to
null.
other - Mailbox instance to copypublic Mailbox(ByteString bstr)
This constructor sets the Mailbox 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.
bstr - initial value for the string representation| Method Detail |
public java.lang.Object clone()
This method, inherited from Object, creates a new
Mailbox object that has the same value as this
Mailbox object. The parent node of the new
Mailbox object is set to null.
clone in class FieldBodypublic void parse()
This method, inherited from Node, executes the parse
operation for Mailbox objects. The parse operation
creates or updates the broken-down representation from the string
representation. For Mailbox objects, the parse method
parses the string representation into the substrings for the display
name, local part, route, and domain.
You should call this method after you set or modify the string representation, and before you retrieve the display name, local part, route, or domain.
This method clears the is-modified flag.
parse in class FieldBodypublic void assemble()
This method, inherited from Node, executes the assemble
operation for Mailbox objects. The assemble operation
creates or updates the string representation from the broken-down
representation. For Mailbox objects, the assemble
method builds the string representation from the display name, local
part, route, and domain strings.
You should call this method after you set or modify the display name, local part, route, or domain, and before you retrieve the string representation.
This method clears the is-modified flag.
assemble in class FieldBodypublic void setDisplayName(java.lang.String name)
This method automatically determines the character encoding (charset) to use by examining the content of its string argument. The charset chosen is one of the following: US-ASCII, ISO-8859-1, or UTF-8.
Use this method to set the display name if:
If you want to specify an external character encoding other than
US-ASCII, ISO-8859-1, or UTF-8, then use the
setDisplayName(String,String) method.
name - the display name to set
public void setDisplayName(java.lang.String name,
java.lang.String charset)
throws java.io.UnsupportedEncodingException
This method attempts to use the specified character encoding
(charset) when the display name is encoded. The character encoding
uses the Java library, so only encodings supported by your Java
implementation will succeed. If the character encoding fails, the
method throws a
java.io.UnsupportedEncodingException exception.
As a special case, if all characters are in the US-ASCII character set, the charset will be changed to US-ASCII and no encoding will be performed.
Use this method to set the display name if:
name - the display namecharset - a hint about the character encoding to use for the
display name
java.io.UnsupportedEncodingException - thrown by the Java
library if an encoding is not supportedpublic java.lang.String displayName()
Note that many character encodings (charsets) are used in Internet mail. This method is a convenience method that performs the conversion from the original character set and encoding to Unicode. It is possible that the host Java implementation does not fully support the required conversion. It is also possible that some information will be lost by the conversion. For this reason, Hunny JMIME provides other methods to get the unconverted characters of the display name.
encodedDisplayName()public java.lang.String charset()
The returned string indicates the character encoding identifier (charset) of the encoded display name.
public void setEncodedDisplayName(java.lang.String name)
If the display name contains non-ASCII characters, it must be encoded before it can be used in a header field. This method provides a way to set the encoded display name directly. The argument is used "as is": when the string representation is assembled, no additional conversion is performed on the display name.
This method is useful in certain situations. If you never
display Internet mail addresses, there is no need to convert the
display name to a displayable form. For example, if you were
managing a mailing list, you could get the display name from a
mailbox using encodedDisplayName(), store it in a database,
and insert it into another mailbox using setEncodedDisplayName(String). The encoded display name is
handy for databases, because it keeps the display name and its
character encoding identifier together.
The following is a simple example of a display name encoded with the modified quoted-printable encoding:
Decoded: Jürgen König
Encoded: =?iso-8859-1?Q?J=FCrgen_K=F6nig?=
For more information about the encoding of text in header fields, see RFC 2047.
name - the encoded display namepublic java.lang.String encodedDisplayName()
If the display name contains non-ASCII characters, it must be encoded before it can be used in a header field. This method provides a way to get the encoded display name directly.
This method is useful if you want to store the display name in its encoded form in a database. It is also useful if you are just "editing" a message: perhaps you want to copy addresses from one message to another. By getting the encoded display name, you can be sure that there is no loss of information when character encodings are converted.
The following is a simple example of a display name encoded with the modified quoted-printable encoding:
Decoded: Jürgen König
Encoded:
=?iso-8859-1?Q?J=FCrgen_K=F6nig?=
For more information about the encoding of text in header fields, see RFC 2047.
public java.lang.String route()
The route, sometimes called the "source route", is deprecated in current usage, and is rarely seen. Hunny JMIME supports it only to be fully compliant with standards, and to provide compatibility with obsolete mail systems.
public void setRoute(java.lang.String route)
The route, sometimes called the "source route", is deprecated in current usage, and is rarely seen. Hunny JMIME supports it only to be fully compliant with standards, and to provide compatibility with obsolete mail systems.
route - the mailbox routepublic java.lang.String localPart()
When the local part is parsed, white space and comments are removed if they are present. For example, if the mailbox string is
"John Doe" < john . (average) doe @example.net>
then the local part returned by this method is
john.doe
However, double quote characters are not removed, since they are rarely needed and rarely seen.
public void setLocalPart(java.lang.String localPart)
When the string representation is assembled, the local part is not interpreted in any way. In particular, characters that are not allowed in the local part of a valid mailbox are not quoted. If you need to set a local part that requires quotes, then you must quote the local part before setting it.
Rationale: Most mail addresses that are assigned by mail administrators do not allow a local part that must be quoted. Consequently, a local part that requires quoting is very rarely seen. (They are seen, however. A typical situation in which a local part requires quoting is when a message originates from an X.400 mail system.)
localPart - the mailbox local partpublic java.lang.String domain()
When the domain is parsed, white space and comments are removed if they are present. For example, if the mailbox string is
"John Doe" <john.doe @ example (yeah,right!) . net >
then the domain returned by this method is
example.net
public void setDomain(java.lang.String domain)
When the string representation is assembled, the domain is not interpreted in any way. White space characters are not removed and the domain is not checked for invalid characters.
domain - the mailbox domain
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||