| The way the URL , URLStreamHandler , URLConnection , and URLStreamHandlerFactory classes work together can be confusing. Everything starts with a URL, which represents a pointer to a particular Internet resource. Each URL specifies the protocol used to access the resource; typical values for the protocol include mailto , http , and ftp . When you construct a URL object from the URL's string representation, the constructor strips the protocol field and passes it to the URLStreamHandlerFactory . The factory's job is to take the protocol, locate the right subclass of URLStreamHandler for the protocol, and create a new instance of that stream handler, which is stored as a field within the URL object. Each application has at most one URLStreamHandlerFactory ; once the factory has been installed, attempting to install another will throw an Error . Now that the URL object has a stream handler, it asks the stream handler to finish parsing the URL string and create a subclass of URLConnection that knows how to talk to servers using this protocol. URLStreamHandler subclasses and URLConnection subclasses always come in pairs; the stream handler for a protocol always knows how to find an appropriate URLConnection for its protocol. It is worth noting that the stream handler does most of the work of parsing the URL. The format of the URL, although standard, depends on the protocol; therefore, it must be parsed by a URLStreamHandler , which knows about a particular protocol, and not by the URL object, which is generic and has no knowledge of specific protocols. This also means that if you are writing a new stream handler, you can define a new URL format that's appropriate to your task.  | New URL schemes should be defined only for genuinely new protocols. They should not be defined for different uses of existing protocols. The iTunes Music Store itms scheme and the RSS feed scheme are examples of what not to do. Both of these should use http . | |
The URLConnection class, which you learned about in the previous chapter, represents an active connection to an Internet resource. It is responsible for interacting with the server. A URLConnection knows how to generate requests and interpret the headers that the server returns. The output from a URLConnection is the raw data requested with all traces of the protocol (headers, etc.) stripped, ready for processing by a content handler. In most applications, you don't need to worry about URLConnection objects and stream handlers; they are hidden by the URL class, which provides a simple interface to the functionality you need. When you call the getInputStream( ) , getOutputStream() , and getContent( ) methods of the URL class, you are really calling similarly named methods in the URLConnection class. We have seen that interacting directly with a URLConnection can be convenient when you need a little more control over communication with a server, such as when downloading binary files or posting data to a server-side program. However, the URLConnection and URLStreamHandler classes are even more important when you need to add new protocols. By writing subclasses of these classes, you can add support for standard protocols such as finger, whois, or NTP that Java doesn't support out of the box. Furthermore, you're not limited to established protocols with well-known services. You can create new protocols that perform database queries, search across multiple Internet search engines, view pictures from binary newsgroups, and more. You can add new kinds of URLs as needed to represent the new types of resources. Furthermore, Java applications can be built so that they load new protocol handlers at runtime. Unlike current browsers such as Mozilla and Internet Explorer, which contain explicit knowledge of all the protocols and content types they can handle, a Java browser can be a relatively lightweight skeleton that loads new handlers as needed. Supporting a new protocol just means adding some new classes in predefined locations, not writing an entirely new release of the browser. What's involved in adding support for a new protocol? As I said earlier, you need to write two new classes: a subclass of URLConnection and a subclass of URLStreamHandler . You may also need to write a class that implements the URLStreamHandlerFactory interface. The URLConnection subclass handles the interaction with the server, converts anything the server sends into an InputStream , and converts anything the client sends into an OutputStream . This subclass must implement the abstract method connect( ) ; it may also override the concrete methods getInputStream( ) , getOutputStream( ) , and getContentType( ) . The URLStreamHandler subclass parses the string representation of the URL into its separate parts and creates a new URLConnection object that understands that URL's protocol. This subclass must implement the abstract openConnection( ) method, which returns the new URLConnection to its caller. If the String representation of the URL doesn't look like a standard hierarchical URL, you should also override the parseURL( ) and toExternalForm( ) methods. Finally, you may need to create a class that implements the URLStreamHandlerFactory interface. The URLStreamHandlerFactory helps the application find the right protocol handler for each type of URL. The URLStreamHandlerFactory interface has a single method, createURLStreamHandler( ) , which returns a URLStreamHandler object. This method must find the appropriate subclass of URLStreamHandler given only the protocol (e.g., ftp ); that is, it must understand the package and class-naming conventions used for stream handlers. Since URLStreamHandlerFactory is an interface, you can place the createURLStreamHandler( ) method in any convenient class, perhaps the main class of your application. When it first encounters a protocol, Java looks for URLStreamHandler classes in this order: -
First, Java checks to see whether a URLStreamHandlerFactory is installed. If it is, the factory is asked for a URLStreamHandler for the protocol. -
If a URLStreamHandlerFactory isn't installed or if Java can't find a URLStreamHandler for the protocol, Java looks in the packages named in the java.protocol.handler.pkgs system property for a sub-package that shares the protocol name and a class called Handler . The value of this property is a list of package names separated by a vertical bar ( ). Thus, to indicate that Java should seek protocol handlers in the com.macfaq.net.www and org.cafeaulait.protocols packages, you would add this line to your properties file: java.protocol.handler.pkgs=com.macfaq.net.wwworg.cafeaulait.protocols To find an FTP protocol handler (for example), Java first looks for the class com.macfaq.net.www.ftp.Handler . If that's not found, Java next tries to instantiate org.cafeaulait.protocols.ftp.Handler . -
Finally, if all else fails, Java looks for a URLStreamHandler named sun.net.www.protocol . name .Handler , where name is replaced by the name of the protocol; for example, sun.net.www.protocol.ftp.Handler .  | In the early days of Java (circa 1995), Sun promised that protocols could be installed at runtime from the server that used them. For instance, in 1996, James Gosling and Henry McGilton wrote: "The HotJava Browser is given a reference to an object (a URL). If the handler for that protocol is already loaded, it will be used. If not, the HotJava Browser will search first the local system and then the system that is the target of the URL." ( The Java Language Environment, A White Paper , May 1996, http://java.sun.com/docs/white/langenv/HotJava.doc1.html) However, the loading of protocol handlers from web sites was never implemented, and Sun doesn't talk much about it anymore. | | Most of the time, an end user who wants to permanently install an extra protocol handler in a program such as HotJava will place the necessary classes in the program's class path and add the package prefix to the java.protocol.handler.pkgs property. However, a programmer who just wants to add a custom protocol handler to their program at compile time will write and install a URLStreamHandlerFactory that knows how to find their custom protocol handlers. The factory can tell an application to look for URLStreamHandler classes in any place that's convenient: on a web site, in the same directory as the application, or somewhere in the user's class path. When each of these classes has been written and compiled, you're ready to write an application that uses the new protocol handler. Assuming that you're using a URLStreamHandlerFactory , pass the factory object to the static URL . setURLStreamHandlerFactory() method like this: URL.setURLStreamHandlerFactory(new MyURLStreamHandlerFactory( ));
This method can be called only once in the lifetime of an application. If it is called a second time, it will throw an Error . Untrusted code will generally not be allowed to install factories or change the java.protocol.handler.pkgs property. Consequently, protocol handlers are primarily of use to standalone applications such as HotJava; Netscape and Internet Explorer use their own native C code instead of Java to handle protocols, so they're limited to a fixed set of protocols. To summarize, here's the sequence of events: -
The program constructs a URL object. -
The constructor uses the arguments it's passed to determine the protocol part of the URL, e.g., http . -
The URL( ) constructor tries to find a URLStreamHandler for the given protocol like this: -
If the protocol has been used before, the URLStreamHandler object is retrieved from a cache. -
Otherwise, if a URLStreamHandlerFactory has been set, the protocol string is passed to the factory's createURLStreamHandler( ) method. -
If the protocol hasn't been seen before and there's no URLStreamHandlerFactory , the constructor attempts to instantiate a URLStreamHandler object named protocol .Handler in one of the packages listed in the java.protocol.handler.pkgs property. -
Failing that, the constructor attempts to instantiate a URLStreamHandler object named protocol .Handler in the sun.net.www.protocol package. -
If any of these attempts succeed in retrieving a URLStreamHandler object, the URL constructor sets the URL object's handler field. If none of the attempts succeed, the constructor throws a MalformedURLException . -
The program calls the URL object's openConnection( ) method. -
The URL object asks the URLStreamHandler to return a URLConnection object appropriate for this URL. If there's any problem, an IOException is thrown. Otherwise, a URLConnection object is returned. -
The program uses the methods of the URLConnection class to interact with the remote resource. Instead of calling openConnection( ) in step 4, the program can call getContent( ) or getInputStream( ) . In this case, the URLStreamHandler still instantiates a URLConnection object of the appropriate class. However, instead of returning the URLConnection object itself, the URLStreamHandler returns the result of URLConnection 's getContent( ) or getInputStream() method. |
