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 does not require that a protocol handler for the scheme be available. All the operations on the URLName take place with simple substring manipulation. This allows the URLName class to support very nonstandard URLs like pop3://eharold:[email protected]/INBOX or imap://[email protected]/Speaking/SD99West. These URLName objects can be used to refer to particular folders on the server.

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

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

These can all be easily understood by analogy with the similarly named methods in java.net.URL. Except for getPort( ), these 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.

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.

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 e) {
      e.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:[email protected]/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 <[email protected]>
Message-Id: <[email protected]>
To: [email protected]
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.