19.6 The URLName Class

     

javax.mail.URLName represents the name of a URL; that is, it treats a URL as a string, but does not attempt to connect to or resolve any of the parts of the string. URL names are mainly used as convenient ways to identify folders and stores with nonstandard URLs, such as pop3://elharo:[e-mail]:110/ INBOX , that don't have a matching protocol handler:

 public class URLName Object 

The methods of URLName are very similar to those of java.net.URL discussed in Chapter 7, except that all those involving actual connections have been deleted. What's left is a bunch of methods for breaking a URL string into its component parts or building a URL from pieces.

19.6.1 The Constructors

There are three overloaded URLName constructors. One takes the individual pieces of a URL as arguments, another takes a java.net.URL object, and a third takes a String containing a URL:

 public URLName(String protocol, String host, int port, String file,   String userName, String password) public URLName(URL url) public URLName(String url) 

Constructing a URLName doesn't require a protocol handler for the scheme be available. All the operations on the URLName take place with simple substring manipulation, allowing the URLName class to support nonstandard URLs like pop3://eharold:[e-mail]/INBOX or imap://[e-mail]/Speaking/SD2005West. These URLName objects can be used to refer to particular folders on the server.

19.6.2 Parsing Methods

These seven getter methods are the main purpose for this class. They return individual pieces of the URL:

 public int    getPort( ) public String getProtocol( ) public String getFile( ) public String getRef( ) public String getHost( ) public String getUsername( ) public String getPassword( ) 

These methods can all be easily understood by analogy with the similarly named methods in java.net.URL . Except for getPort( ) , these methods all return null if the piece is missing. getPort() returns -1 if the port is not explicitly included in the URL.

There's also a getURL( ) method that converts a URLName to a java.net.URL . Since doing so requires that Java have a protocol handler for the URL's scheme, this method can throw a MalformedURLException :

 public URL getURL( ) throws MalformedURLException 

Finally, there are the usual three utility methods with the usual semantics:

 public boolean equals(Object o) public int     hashCode( ) public String  toString( ) 

The toString( ) method simply returns the string form of the URL. The equals( ) method is underspecified but in practice any two URLName objects that are character by character identical will compare equal. However, JavaMail does not consider case to be significant in domain names. http://www.example.com and http://WWW.EXAMPLE.COM are equal. Surprisingly, it does consider case to be significant in URL schemes. That is, http://www.example.com is not equal to HTTP://www.example.com . Finally, JavaMail recognizes / as the default path ; for example, http://www.example.com is equal to http://www.example.com/ . The hashCode() method is implemented accordingly .

We can use the URLName class to provide an interface for an email client that is completely protocol-independent . All information about protocol, host, and other details is provided by a URL read from the command line. Example 19-7 demonstrates .

Example 19-7. A protocol-independent mail client

 import javax.mail.*; import javax.mail.internet.*; import java.util.*; import java.io.*; public class MailClient {   public static void main(String[] args) {          if (args.length == 0) {       System.err.println(        "Usage: java MailClient protocol://username:password@host/foldername");       return;      }          URLName server = new URLName(args[0]);     try {       Session session = Session.getDefaultInstance(new Properties( ),         null);       // Connect to the server and open the folder       Folder folder = session.getFolder(server);       if (folder == null) {         System.out.println("Folder " + server.getFile( ) + " not found.");         System.exit(1);       }         folder.open(Folder.READ_ONLY);              // Get the messages from the server       Message[] messages = folder.getMessages( );       for (int i = 0; i < messages.length; i++) {         System.out.println("------------ Message " + (i+1)           + " ------------");         messages[i].writeTo(System.out);       }        // Close the connection        // but don't remove the messages from the server       folder.close(false);            }      catch (Exception ex) {       ex.printStackTrace( );     }           } } 

URLName does make the code a little more compact since it moves some information from the source code to the command line. Besides eliminating the obvious variables and string literals for username, host, and so forth, we've managed to eliminate any direct reference to the Store class. A typical run starts like this:

 %  java MailClient pop3://eharold:[e-mail]/INBOX  ------------ Message 1 ------------ Received: (from eharold@localhost)         by utopia.poly.edu (8.8.8/8.8.8) id QAA05728         for eharold; Tue, 30 Nov 1999 16:14:29 -0500 (EST) Date: Tue, 30 Nov 1999 16:14:29 -0500 (EST) From: Elliotte Harold <[e-mail]> Message-Id: <[e-mail]> To: [e-mail] Subject: test Content-Type: text X-UIDL: 87e3f1ba71738c8f772b15e3933241f0 Status: RO hello you 

For demonstration purposes, this program includes the password in the URL. In general, however, that's a huge security risk. It would be much better to use a runtime Authenticator , as Example 19-6 did. Of course, ultimately it's very questionable whether this is really a superior interface to Example 19-6 and its ilk.