Java 1.1 Unleashed - 13 - The Networking Package by Mike Fletcher IN THIS CHAPTER Classes Exceptions Interfaces This chapter serves as an introduction to the package containing Java's networking facilities. It covers the classes, interfaces, and exceptions that make up the java.net package. Unless otherwise noted, classes, exceptions, and interfaces are members of the java.net package. The full package name is given for members of other classes (for example, java.io.IOException). Method names are shown followed by parentheses () (for example, close()). Classes The classes in the networking package fall into three general categories: Web interface classes. The URL and URLConnection classes provide a quick and easy way to access content using Uniform Resource Locators. This content may be located on the local machine or anywhere on the WWW. The URLEncoder class provides a way to convert text for use as arguments for CGI scripts. Raw network interface classes Socket, ServerSocket, DatagramSocket, and InetAddress are the classes that provide access to plain, bare-bones networking facilities. They are the building blocks for implementing new protocols, talking to preexisting servers, and the like. Chapter 26, "Java Socket Programming," covers using these classes in detail. Extension classes The ContentHandler and URLStreamHandler abstract classes are used to extend the capabilities of the URL class. Chapter 25, "Developing Content and Protocol Handlers," explains how to write handlers for new protocols and content types. Keep in mind that some of the java.net classes (such as URLConnection and ContentHandler) are abstract classes and cannot be directly instantiated. Subclasses provide the actual implementations for the different protocols and contents. Table 13.1 lists all the classes in the package along with brief descriptions of the functionality each provides. Table 13.1. Classes of the java.net package. Class Purpose URL Represents a Uniform Resource Locator URLConnection Retrieves content addressed by URL objects Socket Provides a TCP (connected, ordered stream) socket ServerSocket Provides a server (listening) TCP socket DatagramSocket Provides a UDP (connectionless datagram) socket DatagramPacket Represents a datagram to be sent using a DatagramSocket object InetAddress Represents a host name and its corresponding IP number or numbers URLEncoder Encodes text in the x-www-form-urlencoded format URLStreamHandler Subclasses implement communications streams for different URL protocols ContentHandler Subclasses know how to turn MIME objects into corresponding Java objects SocketImpl Subclasses provide access to TCP/IP facilities The URL Class The URL class represents a Web Uniform Resource Locator. Along with the URLConnection class, the URL class provides access to resources located on the World Wide Web using the HTTP protocol. The URL class also allows resources to be accessed from the local machine or from the FTP protocol with file: URLs. Constructors. The constructors for the URL class allow the creation of absolute and relative URLs. One constructor takes a whole String as a URL; other constructors allow the protocol, host, and file to be specified in separate String objects. The class also provides for relative URLs with a constructor that takes another URL object for the context and a String as the relative part of the URL. Constructor Description URL( String url ) Takes the entire URL as a String. URL( String protocol, String host, int port, String file ) Takes each component of the URL as a separate argument. URL( String protocol, String host, String file) As above, but uses the default port number for the protocol. URL( URL context, String file ) Replaces the file part of the URL with the second argument. Methods. The methods for the URL class retrieve individual components of the represented URL (such as the protocol and the host name). The class also provides comparison methods for determining whether two URL objects reference the same content. Probably the most important method is getContent(). This method returns an object representing the content of the URL. Another method, openConnection(), returns a URLConnection object that provides a connection to the remote content. The connection object can then be used to retrieve the content, as it can be with the getContent() method. The URLConnection Class The URLConnection class does the actual work of retrieving the content specified by URL objects. This class is an abstract class; as such, it cannot be directly instantiated. Instead, subclasses of the class provide the implementation to handle different protocols. The subclasses know how to use the appropriate subclasses of the URLStreamHandler class to connect and retrieve the content. Constructor. The only constructor provided for the URLConnection class takes a URL object and returns a URLConnection object for that URL. However, because URLConnection is an abstract class, it cannot be directly instantiated. Instead of using a constructor, you will probably use the URL class openConnection() method. The Java runtime system creates an instance of the proper connection subclass to handle the URL. Methods. The getContent() method acts just like the URL class method of the same name. The URLConnection class also provides methods to get information such as the content type of the resource or HTTP header information sent with the resource. Examples of these methods are getContentType(), which returns what the HTTP content-type header contained, and the verbosely named guessContentTypeFromStream(), which tries to determine the content type by observing the incoming data stream. Methods also are provided to obtain a java.io.InputStream object that reads data from the connection. For URLs that provide for output, there is a corresponding getOutputStream() method. The remaining URLConnection methods deal with retrieving or setting class variables. Variables. Several protected members describe aspects of the connection, such as the URL connected to and whether the connection supports input or output. A variable also notes whether or not the connection uses a cached copy of the object. The Socket Class A Socket object is the Java representation of a TCP connection. When a Socket is created, a connection is opened to the specified destination. Stream objects can be obtained to send and receive data to the other end. Constructors. The constructors for the Socket class take two arguments: the name (or IP address) of the host to connect to, and the port number on that host to connect to. The host name can be given as either a String or as an InetAddress object. In either case, the port number is specified as an integer. Constructor Description Socket( String host, int port, boolean stream ) Takes the host name and port to contact, and whether to use a stream (true) or datagram connection. Socket( String host, int port ) As above, but defaults to a stream connection. Socket( InetAddress host, int port, boolean stream ) Uses an InetAddress object rather than a String to specify the host name. Socket( InetAddress host, int port ) As above, but defaults to a stream connection. Methods. The two most important methods in the Socket class are getInputStream() and getOutputStream(), which return stream objects that can be used to communicate through the socket. A close() method is provided to tell the underlying operating system to terminate the connection. Methods also are provided to retrieve information about the connection such as the local and remote port numbers and an InetAddress representing the remote host. New in Java 1.1 are three methods that control how the TCP connection represented by a Socket object behaves. These new methods are listed here with a short description of what each does. A more detailed explanation of the options that can be set for a connection is given later in this chapter, in the discussion of the SocketOptions interface. Constructor Description setSoLinger( boolean on, int val ) Sets whether the close() method blocks for val seconds until all pending data is sent and acknowledged by the receiver. If val is zero, the connection is closed immediately. setTcpNoDelay( boolean on ) Controls whether data is buffered until an acknowledgment is received for any data already sent. setSoTimeout( int timeout ) Sets a timeout (in milliseconds) for read() calls on the socket. A timeout value of zero indicates an infinite timeout (wait until data is ready). Three corresponding methods read the options set by the three methods just described: The getSoLinger() and getSoTimeout() methods both return an int representing the corresponding delay. A -1 for getSoLinger() and a 0 for getSoTimeout() indicate that the option is disabled. The getTcpNoDelay() method returns a boolean value indicating whether the option is enabled. The ServerSocket Class The ServerSocket class represents a listening TCP connection. Once an incoming connection is requested, the ServerSocket object returns a Socket object representing the connection. In normal use, another thread is spawned to handle the connection. The ServerSocket object is then free to listen for the next connection request. Constructors. Both constructors for this class take as an argument the local port number to listen to for connection requests. One constructor also takes the maximum time to wait for a connection as a second argument. Constructor Description ServerSocket( int port, int count ) Takes the port number to listen to for connections and the amount of time to listen. ServerSocket( int port ) As above, but the socket waits until a connection is received. Methods. The most important method in the ServerSocket class is accept(). This method blocks the calling thread until a connection is received. A Socket object is returned representing this new connection. The close() method tells the operating system to stop listening for requests on the socket. Also provided are methods to retrieve the host name on which the socket is listening (in InetAddress form) and the port number being listened to. The DatagramSocket Class The DatagramSocket class represents a connectionless datagram socket. This class works with the DatagramPacket class to provide for communication using the UDP (User Datagram Protocol). Constructors. Because UDP is a connectionless protocol, you do not have to specify a host name when creating a DatagramSocket--only the port number on the local host. A second constructor takes no arguments. When this second constructor is used, the port number is assigned arbitrarily by the operating system. Constructor Description DatagramSocket( int port ) Creates a socket on the specified port number. DatagramSocket() Creates a socket on an available port. Methods. The two most important methods for the DatagramSocket class are send() and receive(). Each takes as an argument an appropriately constructed DatagramPacket (described in the following section). In the case of the send() method, the data contained in the packet is sent to the specified host and port. The receive() method blocks execution until a packet is received by the underlying socket, at which time the data is copied into the packet provided. A close() method is also provided, which asks for the underlying socket to be shut down, as is a getLocalPort() method, which returns the local port number associated with the socket. This last method is particularly useful when you let the system pick the port number for you. The DatagramPacket Class DatagramPacket objects represent one packet of data that is sent using the UDP protocol (using a DatagramSocket). Constructors. The DatagramPacket class provides two constructors: one for outgoing packets and one for incoming packets. The incoming version takes as arguments a byte array to hold the received data and an int specifying the size of the array. The outgoing version also takes the remote host name (as an InetAddress object) and the port number on that host to send the packet to. Constructor Description DatagramPacket( byte[] buffer, int length ) Creates a packet to receive the specified number of bytes into the given buffer. DatagramPacket( byte[] buffer, int length, InetAddress addr, int port ) Creates a packet to send the specified number of bytes from the given buffer to the host and port given. Methods. Four methods in the DatagramPacket class allow the data, datagram length, and addressing (InetAdress and port number) information for the packet to be extracted. The methods are named, respectively, getData(), getLength(), getAddress(), and getPort(). The MulticastSocket Class The MulticastSocket class extends the DatagramSocket class to provide a way of sending and receiving multicast UDP packets. A multicast packet is sent to all members of a multicast group on the Internet (network routing and firewalls willing). Each group is specified by an IP address between 224.0.0.1 and 239.255.255.255 (inclusive) as well as a port number. In addition to the methods provided by the DatagramSocket class, the MulticastSocket class provides methods to set and get the limit of the number of network hops the packet will travel, methods to join and leave a particular multicast group, and methods to specify which network interface is used to send multicast messages. The InetAddress Class The InetAddress class represents a host name and its IP numbers. The class itself also pro- vides the functionality to obtain the IP number for a given host name--similar to the C gethostbyname() function on UNIX and UNIX-like platforms. Constructors. There are no explicit constructors for InetAddress objects. Instead, you use the static class method getByName(), which returns a reference to an InetAddress. Because some hosts may be known by more than one IP address, there also is a method getAllByName(), which returns an array of InetAddress objects. Methods. In addition to the static methods just listed, the getHostName() method returns a String representation of the host name that the InetAddress represents; the getAddress() method returns an array of the raw bytes of the address. The equals() method compares address objects. The class also supports a toString() method, which prints out the host name and IP address textually. The URLEncoder Class The URLEncoder class provides a method to encode arbitrary text in the x-www-form-urlencoded format. The primary use for this format is when you are encoding arguments in URLs for CGI scripts. Nonprinting or punctuation characters are converted to a two-digit hexadecimal number preceded by a percent (%) character. Space characters are converted to plus (+) characters. Constructors. There is no constructor for the URLEncoder class. All the functionality is provided by means of a static method. Methods. The URLEncoder class provides one static class method, encode(), which takes a String representing the text to encode and returns the translated text as a String. The URLStreamHandler Class The subclasses of the URLStreamHandler class provide the implementation of objects that know how to open communications streams for different URL protocol types. More information on how to write handlers for new protocols can be found in Chapter 25, "Developing Content and Protocol Handlers." Constructors. The constructor for the URLStreamHandler class cannot be called because URLStreamHandler is an abstract class. Methods. Each subclass provides its own implementation of the openConnection() method, which opens an input stream to the URL specified as an argument. The method should return an appropriate subclass of the URLConnection class. The ContentHandler Class Subclasses of the ContentHandler abstract class are responsible for turning a raw data stream for a MIME type into a Java object of the appropriate type. Constructors. Because ContentHandler is an abstract class, ContentHandler objects cannot be instantiated. An object implementing the ContentHandlerFactory interface decides what the appropriate subclass is for a given MIME content type. Methods. The important method for ContentHandler objects is the getContent() method, which does the actual work of turning into a Java object the data read using URLConnection. This method takes as its argument a reference to a URLConnection that provides an InputStream at the beginning of the representation of an object. The SocketImpl Class The SocketImpl abstract class provides a mapping from the raw networking classes to the native TCP/IP networking facilities of the host. This means that the Java application does not have to concern itself with the operating system specifics of creating network connections. At run time, the Java interpreter loads the proper native code for the implementation, which is accessed by means of a SocketImpl object. Each Socket or ServerSocket then uses the SocketImpl object to access the network. This scheme also allows for flexibility in different network environments. An application does not have to bother with details such as being behind a firewall because the interpreter takes care of loading the proper socket implementation (such as one that knows how to use the SOCKS proxy TCP/IP service). TIP: SOCKS provides TCP and UDP access through a firewall. A SOCKS daemon runs on the firewall (or the inside machine of a DMZ setup). Clients on the inside network call up the SOCKS daemon and ask it to make a connection to an outside host. The daemon connects to the outside host directly or through another SOCKS daemon. SOCKS is pretty cool because the client application doesn't even know it's there if things are set up properly. For more information about SOCKS, take a look at this URL: http://www.socks.nec.com/socks5.html Unless you are porting Java to a new platform or adding support for something such as connecting through a firewall, you probably will never see or use SocketImpl. Constructors. The SocketImpl abstract class has one constructor that takes no arguments. Methods. The methods provided by the SocketImpl class look very familiar to anyone who has done socket programming under a UNIX variant. All the methods are protected and may be used only by subclasses of SocketImpl that provide specific socket implementations. The create() method creates a socket with the underlying operating system. It takes one boolean argument that specifies whether the created socket should be a stream (TCP) or datagram (UDP) socket. Two calls, connect() and bind(), cause the socket to be associated with a particular address and port. For server sockets, there is the listen() method, which tells the operating system how many connections may be pending on the socket. The accept() method waits for an incoming connection request. It takes another SocketImpl object as a parameter, which represents the new connection once it has been established. To allow reading and writing from the socket, the class provides the getInputStream() and getOutputStream() methods, which return a reference to the corresponding stream. Once communication on a socket is finished, the close() method can be used to ask the operating system to close the connection. The remaining methods allow read access to the member variables as well as a toString() method for printing a textual representation of the object. Variables. Each SocketImpl object has four protected members: Member Description fd A java.io.FileDescriptor object used to access the underlying operating system network facilities. address An InetAddress object representing the host at the remote end of the connection. port The remote port number, stored as an int. localport The local port number, stored as an int. Exceptions Java's exception system allows for flexible error handling. The java.net package defines five exceptions, which are described in the following sections. All these exceptions provide the same functionality as any java.lang.Exception object. Because each exception is a subclass of java.io.IOException, the exceptions can be handled with code such as this: try { // Code that might cause an exception goes here } catch( java.net.IOException e ) { System.err.println( "Error on socket operation:\n" + e ); return; } This code can be placed inside a for loop--for example, when trying to create a Socket to connect to a heavily loaded host. The UnknownHostException Exception The UnknownHostException exception is thrown when a host name cannot be resolved into a machine address. The most probable causes for this condition are listed here: The host name is misspelled. The host does not actually exist. There is a problem with the network and the host, or the host that is providing name-to-IP number mapping is unreachable. TIP: If you are sure that you are using the right host name and are still getting this exception, you may have to fix the name-to-IP number mapping. How to go about this depends on the platform you are using. If you are using DNS, you must contact the administrator for the domain. If you are using Sun's NIS, you must have the system administrator change the entry on the NIS server. Finally, you may have to change the local machine's host file, usually named hosts or HOSTS (/etc/hosts on UNIX variants, \WINDOWS\HOSTS on Windows 95). In any case, using the IP number itself to connect to the host should work. The UnknownServiceException Exception The URLConnection class uses the UnknownServiceException exception to signal that a given connection does not support a requested facility such as input or output. If you write your own protocol or content handlers and do not override the default methods for getting input or output stream objects, the inherited method throws this exception. An application to which a user can give an arbitrary URL should watch for this exception. (Users being the malicious creatures they are!) The SocketException Exception The SocketException exception is the superclass for the exceptions thrown when there is a problem using a socket. An exception is thrown if a bad value is passed for a socket option (see "The SocketOptions Interface," later in this chapter). The SocketException exception is also thrown if you try to use the setSocketImplFactory() method of the Socket or ServerSocket classes when the SocketImplFactory already has been set. Usually, the Java interpreter sets this to a reasonable value for you, but if you are writing your own socket factory (for example, to provide sockets through a firewall), this exception may be thrown. The BindException Exception A BindException exception is thrown to indicate an error binding a socket to a local address and port number. One possible cause for this exception is that the local port you are asking for is already in use (that is, another process already has that particular port open). Some operating systems may wait for a period of time after a socket has been closed before allowing it to be reopened. Another cause for this exception is that the user cannot bind to that particular port. On most UNIX systems, ports numbered less than 1024 cannot be used by accounts other than the root or superuser account. This is a security measure; most well-known services reside on ports in this range. Normal users cannot start their own servers in place of the system version. While you are developing a service, you may want to run the server on a port with a higher number. Once the service has been developed and debugged, you can move it to a normal port. The ProtocolException Exception The ProtocolException exception is raised by the underlying network support library. It is thrown by a native method of the PlainSocketImpl class when the underlying socket facilities return a protocol error. The MalformedURLException Exception The URL class throws the MalformedURLException exception if it is given a syntactically invalid URL. One cause can be that the URL specifies a protocol that the URL class does not support. Another cause is that the URL cannot be parsed. A URL for the http or file protocols should have the following general form: protocol://hostname[:port]/[/path/_/path]/object In this syntax, the following components are used: Component Description protocol The protocol to use to connect to the resource (http or file). hostname[:port] The host name to contact, optionally followed by a colon (:) and the port number to connect to (for example, kremvax. gov.su:8000). The host name also may be given as an IP address. [/path/.../path] The (optional) path to the object, separated by / characters. object The name of the actual object itself. This syntax for a URL depends on the protocol. The complete URL specification can be found in RFC 1738 (see Chapter 24, "Introduction to Network Programming," for details on retrieving RFC documents, or check out the World Wide Web Consortium's site at http://www.w3.org/ for the latest version). The ConnectException and NoRouteToHostException Exceptions These two exceptions are thrown if an error occurs while you are trying to connect to a remote host. A ConnectException exception indicates that a connection could not be made, usually because there is a problem with the destination host or because nothing is listening on the other end. A NoRouteToHostException exception indicates that the remote host cannot be reached. This condition can be caused by network problems or if a firewall machine is blocking the connection. Other Exceptions In addition to the exceptions in the java.net package, several methods throw exceptions from the java.io package. The most common of these is java.io.IOException--which is thrown when there is a problem reading a Web resource by the URL class or if there is a problem creating a Socket object. Interfaces The java.net package defines five interfaces. These interfaces are used primarily behind the scenes by the other networking classes rather than by user classes. Unless you are porting Java to a new platform or are extending it to use a new socket protocol, you probably will have no need to implement these interfaces in a class. They are included here for completeness and for those people who like to take off the cover and poke around in the innards to find out how things work. The SocketImplFactory Interface The SocketImplFactory interface defines a method that returns a SocketImpl instance appropriate to the underlying operating system. The socket classes use an object implementing this interface to create the SocketImpl objects they need to use the network. The SocketOptions Interface The SocketOptions interface provides methods that allow options to be set or read on socket connections provided by the underlying implementation classes (such as SocketImpl). Unless you are writing a subclass of one of the socket implementation classes, you should not use these methods directly; instead, use the access methods provided by the socket class. The URLStreamHandlerFactory Interface Classes that implement the URLStreamHandlerFactory interface provide a mapping from protocols such as HTTP or FTP into the corresponding URLStreamHandler subclasses. The URL class uses this factory object to obtain a protocol handler. The ContentHandlerFactory Interface The URLStreamHandler class uses the ContentHandlerFactory interface to obtain ContentHandler objects for different content types. The interface specifies one method, createContentHandler(), which takes the MIME type for which a handler is desired as a String. The FileNameMap Interface The FileNameMap interface provides one method, getContentTypeFor(), which provides a way to map between a filename and a string containing the MIME type. This interface is used by the URLConnection class to provide the guessContentTypeFromName() method. Summary This chapter provided a quick introduction to the networking facilities that the java.net package provides. For more specific information about java.net classes, consult the online class documentation that accompanies the JDK. You can also refer to Part V of this book, "Networking with Java"; the four chapters in that part of the book go into more detail about how to use Java's network capabilities and also provide examples of their use.

©Copyright, Macmillan Computer Publishing. All rights reserved.