| ## 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 s`tring` 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.