Java Network Programming (3rd ed) [Electronic resources] نسخه متنی

19.5 Addresses

The
javax.mail.Address class is very simple.
It's an abstract class that exists mainly to be
subclassed by other, protocol-specific address classes:

public abstract class Address extends Object

There are two of these subclasses in the standard JavaMail API:
InternetAddress for SMTP email and
NewsAddress for Usenet newsgroups:

public class InternetAddress extends Address
public class NewsAddress extends Address

Providers of other mail protocols would also subclass
Address with classes that represented their style
of address.

19.5.1 The Address Class

The Address class
itself is extremely simple. It has only three methods, all abstract,
two of which are simple utility methods that override the
corresponding methods in java.lang.Object:

public abstract String getType( )
public abstract String toString( )
public abstract boolean equals(Object o)

Since all three of these methods are
abstract, there aren't any guarantees about the
methods' semantics, since all must be overridden in
subclasses. However, this does require that subclasses provide their
own implementations of equals( ) and
toString( ) rather than relying on the rather
generic implementations available from
java.lang.Object. In general, the
getType( ) method returns a string such as
"rfc822" or
"news" that indicates the kind of
Address object this is.

19.5.2 The InternetAddress Class

An InternetAddress
object represents an RFC 822-style email address. This is the
standard Internet-style email address that is rapidly supplanting all
other proprietary formats. It looks like
The
state of an InternetAddress object is maintained
by three protected fields:

protected String address
protected String personal
protected String encodedPersonal

The address field is the actual email
addressfor example, ask_tim@oreilly.com.
The personal field is the namefor example,
Tim O'Reilly. Although Java
strings are pure Unicode that can express names like Erwin
Schrödinger or , the strings used in mail headers must be pure ASCII in order to pass through most existing mail software. Consequently, Java's Unicode strings need to be converted to pure ASCII using a sort of hexadecimal escape. The details of this conversion are described in RFC 2047, MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text. The encoded string is placed in the encodedPersonal field. All of these fields will be initially set in the constructor. There are four overloaded constructors for InternetAddress objects:

public InternetAddress(  )
public InternetAddress(String address) throws AddressException
public InternetAddress(String address, String personal) 
throws UnsupportedEncodingException
public InternetAddress(String address, String personal, String charset) 
throws UnsupportedEncodingException

They are used exactly as you'd expect. For example:

Address tim = new InternetAddress("ask_tim@oreilly.com", "Tim O'Reilly");

Although two of these methods are declared to throw
UnsupportedEncodingException, this should happen
only in the last method and then only if the name of the character
set is not recognized by the VM. (For example, Java 1.1 does not
recognize "ASCII", although in that
case, you don't really need to specify a character
set.)

There are nine instance methods in this classthree setter
methods, three getter methods, and three utility methods:

public void setAddress(String address)
public void setPersonal(String name, String charset) 
throws UnsupportedEncodingException
public void setPersonal(String name)
throws UnsupportedEncodingException
public String getAddress( )
public String getPersonal( )
public String getType( )
public String toString( )
public boolean equals(Object o)
public int hashCode( )

The setAddress( ) method sets the
address field of the object to the specified
value. The setPersonal( ) method sets the
personal and encodedPersonal
fields to the specified value (after encoding it, as necessary). The
getAddress( ) and getPersonal() methods return the values of the
address and personal or decoded
encodedPersonal fields, respectively. Finally, the
getType( ) method returns the string
"rfc822".

The toString( ) method returns an email address
suitable for use in a To: or From: field of an RFC 822 email message.
The equals( ) and hashCode( )
methods have their usual semantics.

There are also five static utility methods, four of which convert
addresses to and from strings:

public static String toString(Address[] addresses) 
throws ClassCastException
public static String toString(Address[] addresses, int used)
throws ClassCastException
public static InternetAddress[] parse(String addressList) 
throws AddressException
public static InternetAddress[] parse(String s, boolean strict) 
throws AddressException

The InternetAddress.toString( ) methods convert an
array of Address objects into a comma-separated
list of addresses encoded in pure ASCII, possibly folded onto
multiple lines. The optional used argument gives
the number of characters that will precede this string in the header
field, such as To: or Cc:, into which this string will be inserted.
This information lets toString( ) decide where it
needs to break the lines. A ClassCastException is
thrown if any of the Address objects in the array
are not more specifically InternetAddress objects.

The two parse( ) methods perform this operation in
reverse, converting a comma-separated String of
addresses into an array of InternetAddress
objects. Setting the optional strict argument to
false changes the behavior so that strings that
use whitespace instead of commas (or whitespace and commas) to
separate email addresses are also understood. All four of these
methods are useful for message header fields that contain multiple
addresses; for example, a Cc: that's directed to six
people.

Finally, the getLocalAddress( ) method checks
several system properties (mail.from,
mail.user, mail.host, and
user.name) as well as
InetAddress.getLocalName( ) to determine the email
address of the current user:

public static InternetAddress getLocalAddress(Session session)

For example, this code fragment tries to use the
user's own email address rather than one hardcoded
into the program as a string:

msg.setFrom(InternetAddress.getLocalAddress( ));

However, there's no guarantee that any of these
properties will necessarily give the user's true
address.

19.5.3 The NewsAddress Class

Perhaps a little surprisingly, with an
appropriate service provider, the JavaMail API can also access
Usenet news. The API is mostly the same as
for reading a POP or IMAP mailbox. However, instead of using an
InternetAddress, you use a
NewsAddress:

public class NewsAddress extends Address

A NewsAddress object represents a Usenet newsgroup
name, such as comp.lang.java.machine. It may
include the hostname for the news server as well. The state of a
NewsAddress object is maintained by two protected
fields:

protected String newsgroup
protected String host

The newsgroup field contains the name of the
newsgroupfor example, netscape.devs-java.
The host field is either null or contains the
hostname of the news serverfor example,
secnews.netscape.com. Both of these fields are
set in the constructor. There are three overloaded constructors for
NewsAddress objects:

public NewsAddress( )
public NewsAddress(String newsgroup)
public NewsAddress(String newsgroup, String host)

They are used exactly as you'd expect. For example:

Address netscape_java = new NewsAddress("netscape.devs-java.", 
"secnews.netscape.com");

There are eight instance methods in this classthree getter
methods, two setter methods, and three utility methods:

public String  getType( )
public String  getHost( )
public String  getNewsgroup( )
public void    setNewsgroup(String newsgroup)
public void    setHost(String host)
public String  toString( )
public boolean equals(Object o)
public int     hashCode( )

The setNewsgroup( ) and setHost() methods set the newsgroup and
host fields of the object to the specified values.
The getNewsgroup( ) and getHost(
) methods return the values of the
newsgroup and host fields.
Finally, the getType( ) method returns the string
"news".

The toString( ) method returns the newsgroup name
in a form suitable for the Newsgroups: header field of a Usenet
posting. The equals( ) and hashCode() methods have their usual semantics.

There are also two static utility methods for converting addresses to
and from strings:

public static String toString(Address[] addresses) 
throws ClassCastException
public static NewsAddress[] parse(String newsgroups) 
throws AddressException

The toString( ) method converts an array of
Address objects into a comma-separated list of
newsgroup names. A ClassCastException is thrown if
any of the Address objects in the array are not
more specifically NewsAddress objects. The
parse( ) method reverses this operation,
converting a comma-separated String of newsgroup
names, such as
"comp.lang.java.programmer,comp.lang.java.gui,comp.lang.java.help",
into an array of NewsAddress objects. It throws an
AddressException if the newsgroups argument is not
a comma-separated list of newsgroup names.

Sun's implementation of the JavaMail API does not
include a service provider for news, however; so although you can
create news addresses, before you can actually read and post news,
you'll need to install a service provider that does
support it. Table 19-1 lists some possible sources of news providers.
Once you've got one, reading news is as
straightforward as talking to an IMAP server.