Java network programming

The java.net Package

Unless otherwise noted, classes, exceptions, and interfaces are members of the java.net package.

The full package name will be given for members of other classes such as java.io.IOException. Method names will be shown followed by (), such as close().

Classes

The classes in the networking package fall into three general categories:

• Web interface classes
• 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
• 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 29 covers using these classes in detail.
• Extension classes
• ContentHandler and URLStreamHandler abstract classes are used to extend the capabilities of the URL class. Extending Java with 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.

URL

The URL class represents a web Uniform Resource Locator. Along with the URLConnection class, this class provides access to resources located on the World Wide Web via the HTTP protocol or on the local machine through file: URLs.

Constructors

The constructors for the URL class provide for creating absolute and relative URLs. There is a constructor that takes a whole String as a URL, as well as constructors allowing 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 context and a String as the relative part.

Methods

The URL class provides methods for retrieving individual components of the represented URL (such as the protocol and the host name). It also provides comparison methods for determining if two URL objects reference the same content.

Probably the most important method is getContent( ). This returns an object representing the contents of the URL. There also is an openConnection( ) method that returns a URLConnection object that will provide a connection to the remote content. The connection object then can be used to retrieve the content, as with the getContent( ) method.

URLConnection

The URLConnection class does the actual work of retrieving content that is specified by URL objects. This class is an abstract class, and as such 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.

Constructors

The only constructor provided takes a URL object and returns a URLConnection object for that URL. However, because this is an abstract class it cannot be directly instantiated. Instead of using a constructor you probably will use the URL class openConnection( ) method. The Java runtime system will create 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 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 will try to determine the content type by observing the incoming data stream.

Methods also are provided to obtain an 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

There are several protected members that describe aspects of the connection, such as the URL connected to and whether the connection supports input or output. A variable also notes whether the connection will use a cached copy of the object or not.

Socket

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 may be given as either a String or as an InetAddress object. In either case the port number is specified as an integer.

Methods

The two most important methods 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.

ServerSocket

The ServerSocket represents a listening TCP connection. Once an incoming connection is requested, the ServerSocket object will return a Socket object representing the connection. In normal use, another thread would be spawned off to handle the connection. The ServerSocket then is free to listen for the next connection request.

Constructors

Both constructors take as an argument the local port number to listen for connection requests. A constructor is provided that also takes the maximum time to wait for a connection as a second argument.

Methods

The most important method is accept( ). This method will block 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 the socket is listening on (in InetAddress form) and the port number being listened to.

DatagramSocket

The DatagramSocket represents a connectionless datagram socket. This class works with the DatagramPacket class to provide for communication using the UDP protocol.

Constructors

Because UDP is a connectionless protocol, you do not need to specify a host name when creating a DatagramSocket—only the port number on the local host. There is a second constructor which takes no arguments. When this constructor is used the port number will be assigned arbitrarily by the operating system.

Methods

The two most important methods 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 will block execution until a packet is received by the underlying socket, at which time the data will be copied into the packet provided.

The other methods provided are a close( ) method to ask for the underlying socket to be shut down, and a getLocalPort( ) method that will return 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.

DatagramPacket

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.

Methods

There are four methods in the class allowing 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( ).

InetAddress

The InetAddress class represents a host name and its IP numbers. The class itself also provides 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 might be known by more than one IP address, there also is a method getAllByName( ), which returns an array of InetAddress objects.

Methods

Aside from the preceding static methods, there are methods that will return a String representation of the host name that the InetAddress represents (getHostName( )) and an array of the raw bytes of the address (getAddress( )). There also is an equals( ) method for the comparison of address objects. The class also supports a toString( ) method for printing out the host name and IP address textually.

URLEncoder

This class provides a method to encode arbitrary text in the x-www-form-urlencoded format. The primary use for this is in encoding arguments in URLs for CGI scripts. Nonprinting or punctuation characters are converted to a two-digit hexadecimal number preceded by a % character. Space characters are converted to a + character.

Plenty of other documentation is available at java wiki pages