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 [e-mail] or [e-mail]. However, it can contain a name as wellfor instance, [e-mail] (Tim O'Reilly) .

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, [e-mail] . 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("[e-mail]", "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.