Chapter 19

The Java Networking Package

by Debasis Samanta

• Introduction
• Class ContentHandler
• Class DatagramPacket
• Class DatagramSocket
• Class InetAddress
• Class ServerSocket
• Class Socket
• Class SocketImpl
• Class URL
• Class URLConnection
• Class URLEncoder
• Class URLStreamHandler
• Throwing Exceptions
• Interface ContentHandlerFactory
• Interface SocketImplFactory
• Interface URLStreamHandlerFactory
• Class MalformedURLException
• Class ProtocolException
• Class SocketException
• Class UnknownHostException
• Class UnknownServiceException

Introduction

The java.net package contains classes and interfaces, and related exception that provides a URL and a URL connection, TCP, UDP, IP, and support socket connections. It also includes classes that represents an Internetaddress, and binary-to- text converter. Following is the diffetent constituent in this package :

	Classes
		Class ContentHandler  
		Class DatagramPacket  
		Class DatagramSocket  
		Class InetAddress  
		Class ServerSocket  
		Class Socket  
		Class SocketImpl  
		Class URL  
		Class URLConnection  
		Class URLEncoder  
		Class URLStreamHandler  
	Interfaces
		Interface ContentHandlerFactory  
		Interface SocketImplFactory  
		Interface URLStreamHandlerFactory  
	Exceptions
		Class MalformedURLException  
		Class ProtocolException  
		Class SocketException  
		Class UnknownHostException  
		Class UnknownServiceException  
    

Class ContentHandler

The abstract class ContentHandler is the superclass of all classes that read an Object from a URL Connection. An application does not generally call the getContentHandler method in this class directly. Instead, an application calls the getContent method in class URL or in URLConnection. The application's content handler factory (an instance of a class that implements the interface ContentHandlerFactory set up by a call to setContentHandler and is called with a String giving the MIME type of the object being received on the socket. The factory returns an instance of a subclass of ContentHandler, and its getContent method is called to create the object.

This class has the following structure :

	public  abstract  class  java.net.ContentHandler extends  java.lang.Object   
	{
        	// 	Constructors
    	public ContentHandler();	
		//	The default constructor for class ContentHandler. 

        	// 	Methods
    	public abstract Object getContent(URLConnection  urlc);
		/*	Given an URL connect stream positioned at the beginning of the representation of an object, this method reads that stream and creates an object from it. Returns : The object read by the ContentHandler.  Throws : IOException,  if an IO error occurs while reading the object. 
		*/
	}

Class DatagramPacket

This class represents a datagram packet. Datagram packets are used to implement a connectionless packet delivery service. Each message is routed from one machine to another based solely on information contained within that packet. Multiple packets sent from a machine to another might be routed differently, and might arrive in any order.

The structure of this class is shown below :

	public  final  class  java.net.DatagramPacket extends  java.lang.Object   
	{
        	// 	Constructors
    	public DatagramPacket(byte  ibuf[], int  ilength);
		/*	Constructs a DatagramPacket for receiving packets of length ilength. The length argument must be less than or equal to ibuf.length.
		*/ 
    	public DatagramPacket(byte  ibuf[], int  ilength,	InetAddress  iaddr,int iport);
		/*	Constructs a DatagramPacket for sending packets of length ilength to the specified port number on the specified host. The length argument must be less than or equal to ibuf.length.
		*/
       	// 	Methods
    	public InetAddress getAddress();	 
    	public byte[] getData();	 
    	public int getLength();	 
    	public int getPort();	 
	}

	The operation performed by the various methods are listed in Table 8.1.

 Table 8.1

Class DatagramSocket

This class represents a socket for sending and receiving datagram packets. A datagram socket is the sending or receiving point for a connectionless packet delivery service. Each packet sent or received on a datagram socket is individually addressed and routed. Multiple packets sent from a machine to another may be routed differently, and may arrive in any order.

public  class  java.net.DatagramSocket extends  java.lang.Object  
	{
        	// 	Constructors
    	public DatagramSocket();
		/*	Constructs a datagram socket and binds it to any available port on the local host machine. 
			Throws : SocketException,  if the socket could not be opened, or the socket could not bind the specified local port.
		*/ 	 
    	public DatagramSocket(int  port);
		/*	Constructs a datagram socket and binds it to the specified port on the local host 				machine. 	 
			Throws : SocketException,  if the socket could not be opened, or the socket could not bind the specified local port.
		*/
	     	// 	Methods
    	public void close(); 
    	protected void finalize(); 
    	public int getLocalPort();	 
    	public void receive(DatagramPacket  p); 
    	public void send(DatagramPacket  p);	 
	}
	Methods are described in Table 8.2.

Table 8.2

Class InetAddress

This class represents an Internet Protocol (IP) address. Applications should use the methods getLocalHost, getByName , or getAllByName to create a new InetAddress instance. The class structure is shown as below :

public  final  class  java.net.InetAddress extends  java.lang.Object   
	{
        	// 	Methods
    	public boolean equals(Object  obj);	 
    	public byte[] getAddress();	 
    	public static InetAddress[] getAllByName(String  host); 
    	public static InetAddress getByName(String  host);	 
    	public String getHostName();	 
    	public static InetAddress getLocalHost();	 
    	public int hashCode();	 
    	public String toString();	 
	}

	Methods are described in Table 8.3.

Table 8.3

Class ServerSocket

This class implements server sockets. A server socket waits for requests to come in over the network. It performs some operation based on that request, and then possibly returns a result to the requester.

The actual work of the server socket is performed by an instance of the SocketImpl class. An application can change the socket factory that creates the socket implementation to configure itself to create sockets appropriate to the local firewall

public  final  class  java.net.ServerSocket extends  java.lang.Object  
	{
        	// 	Constructors
    	public ServerSocket(int  port);	
		/*	Creates a server socket on a specified port. A port of 0 creates a socket on any free port. 
			The maximum queue length for incoming connection indications (a request to connect) is set to 50. If a connection indication arrives when the queue is full, the connection is refused. 
			If the application has specified a server socket factory, that factory's createSocketImpl method  is called to create the actual socket implementation. Otherwise a "plain" socket   is created. 
			Throws :  IOException, if an IO error occurs when opening the socket. 
		*/
    	public ServerSocket(int  port, int  count);
		/*	Creates a server socket and binds it to the specified local port number. A port number of 0 creates a socket on any free port. 
			The maximum queue length for incoming connection indications (a request to connect) is set to the count parameter. If a connection indication arrives when the queue is full, the connection is refused. 
			If the application has specified a server socket factory , that factory's createSocketImpl 				method  is called to create the actual socket implementation. Otherwise a "plain" socket  			is created. 	 
			Throws :  IOException, if an IO error occurs when opening the socket. 
		*/
       	// 	Methods
    	public Socket accept();	 
    	public void close();	
   	    public InetAddress getInetAddress();	 
    	public int getLocalPort();	 
    	public static void setSocketFactory(SocketImplFactory  fac);
    	public String toString();	 
	}

Table 8.4

Class Socket

This class implements client sockets (also called just "sockets"). A socket is a end point for communication between two machines.

The actual work of the socket is performed by an instance of the SocketImpl class. An application, by changing the socket factory that creates the socket implementation, can configure itself to create sockets appropriate to the local firewall.

public  final  class  java.net.Socket extends  java.lang.Object   
	{
        	// 	Constructors
    	public Socket(InetAddress  address, int  port);
		/*	Creates a stream socket and connects it to the specified port number at the specified IP address. If the application has specified a socket factory, that factory's createSocketImpl method  is called to create the actual socket implementation. Otherwise a "plain" socket   is created. 
			Throws : IOException, if an I/O error occurs when creating the socket. 
		*/ 	 
    	public Socket(InetAddress  address, int  port, boolean  stream);
		/*	Creates a socket and connects it to the specified port number at the specified IP address. If the stream argument is true, this creates a stream socket. If the stream argument is false, it creates a datagram socket. 
			Throws : IOException,  If an I/O error occurs when creating the socket.
		*/
   	    public Socket(String  host, int  port);
		/*	Creates a stream socket and connects it to the specified port number on the named host.
		Throws : IOException,  If an I/O error occurs when creating the socket.
		*/  	 
    	public Socket(String  host, int  port, boolean stream);	 
		/*	Creates a stream socket and connects it to the specified port number on the named host.If the stream argument is 	true, this creates a stream socket. If the stream argument is false, it creates a datagram socket.
			Throws : IOException,  If an I/O error occurs when creating the socket.
		*/

        	// 	Methods
    	public void close(); 
    	public InetAddress getInetAddress(); 
    	public InputStream getInputStream();	 
    	public int getLocalPort(); 
    	public OutputStream getOutputStream(); 
    	public int getPort();	 
    	public static void setSocketImplFactory(SocketImplFactory  fac);
    	public String toString();	 
	}
	Methods are described in Table 8.5

Table 8.5

Class SocketImpl

The abstract class SocketImpl is a common superclass of all classes that actually implement sockets. It is used to create both client and server sockets. A "plain" socket implements these methods exactly as described, without attempting to go through a firewall or proxy.

public  abstract  class  java.net.SocketImpl extends  java.lang.Object  
	{
        	// 	Member elements
    	protected InetAddress address;	
 		//	The IP address of the remote end of this socket.
   	    protected FileDescriptor fd;	
		//	The file descriptor object for this socket. 
    	protected int localport;
		//	The local port number to which this socket is connected. 	 
    	protected int port; 
		//	The port number on the remote host to which this socket is connected.

        	// 	Constructors
    	public SocketImpl(); 
		//	The default constructor for a socket implementation.

        	// 	Methods
    	protected abstract void accept(SocketImpl  s); 
    	protected abstract int available(); 
    	protected abstract void bind(InetAddress  host, int  port);	 
    	protected abstract void close(); 
    	protected abstract void connect(InetAddress  address, int  port);
    	protected abstract void connect(String  host, int  port); 
    	protected abstract void create(boolean  stream); 
    	protected FileDescriptor getFileDescriptor();	 
    	protected InetAddress getInetAddress();	 
    	protected abstract InputStream getInputStream(); 
    	protected int getLocalPort();	 
    	protected abstract OutputStream getOutputStream();	 
    	protected int getPort();	 
    	protected abstract void listen(int  count); 
    	public String toString(); 
	}

	Methods are described in Table 8.6.

Table 8.6

Class URL

Class URL represents a Uniform Resource Locator-a pointer to a "resource" on the World Wide Web. A resource can be something as simple as a file or a directory, or it can be a reference to a more complicated object, such as a query to a database or to a search engine.

The class structure is shown below :

public  final  class  java.net.URL extends  java.lang.Object  
	{
        	// 	Constructors
    	public URL(String  spec);
		/*	Creates a URL object from the String representation. This constructor is equivalent to a call to the two-argument constructor with a null first argument. 
			Throws :  MalformedURLException,   if the string specifies an unknown protocol.	
		*/ 
    	public URL(String  protocol, String  host, int  port, String  file);
		/*	Creates a URL object from the specified protocol, host, port number, and file.
			Throws :  MalformedURLException,   if the string specifies an unknown protocol.
		*/
  	public URL(String  protocol, String  host, String  file); 
		/*	Creates an absolute URL from the specified protocol name, host name, and file name. The default port for the specified protocol is used.
			Throws :  MalformedURLException,   if the string specifies an unknown protocol.
		*/
	public URL(URL  context, String  spec);
		/*	Creates a URL by parsing the String specification within a specified context: If the context argument is not null and the spec argument is a partial URL specification, then any of the strings missing components are inherited from the context argument.
			Throws :  MalformedURLException, if no protocol is specified, or an unknown protocol is found.
		*/ 

        	// 	Methods
    	public boolean equals(Object  obj); 
    	public final Object getContent(); 
    	public String getFile(); 
    	public String getHost(); 
    	public int getPort(); 
    	public String getProtocol(); 
    	public String getRef(); 
    	public int hashCode(); 
    	public URLConnection openConnection(); 
    	public final InputStream openStream();	 
    	public boolean sameFile(URL  other); 
    	public static void setURLStreamHandlerFactory(URLStreamHandlerFactory fac);
    	public String toExternalForm();	 
    	public String toString(); 
	}

Methods are stated in Table 8.7.

Table 8.7

Class URLConnection

The abstract class URLConnection is the superclass of all classes that represent a communications link between the application and a URL. Instances of this class can be used both to read from and to write to the resource referenced by the URL. In general, creating a connection to a URL is a multi-step process.

First, the connection object is created by invoking openConnection on a URL, then setup parameters are manipulated, then the actual connection to the remote object is made, and finally the remote object is available. There are a set of properties that apply before the connection is made, and a set that apply after:

Most of these properties have a set and a get method. The first three in the "before" column also have corresponding "Default" properties that specify the default values used in subsequent requests where the property is not specified.

In the common case, all of these properties can be ignored: the pre-connection properties default to sensible values, and the post-connection properties are often uninteresting. For most clients of this interface, there are only two interesting methods: getInputStream and getObject, which are mirrored in the URL class by convenience methods.

This very useful class is having the following constituents :

	public  abstract  class  java.net.URLConnection extends  java.lang.Object   
	{
			// 	Member elements
		protected boolean allowUserInteraction;
		/*	This value of this field can be set by the setAllowUserInteraction method. Its value can be accessed by the getAllowUserInteraction method . Its default value is the value of the argument method to the last call to the setDefaultAllowUserInteraction method.
			If true, this URL is being examined in a context which it makes sense to allow user interactions such as popping up an authentication dialog. If false, then no user interaction is allowed.
		*/
		protected boolean connected;
		/*	If false, this connection object has not created a communications link to the specified URL. If true, the communications link has been established.
		*/ 	 
		protected boolean doInput; 
		/*	This variable is set by the setDoInput method. Its value can be accessed by the getDoInput method . 
			A URL connection can be used for input and/or output. Setting the doInput flag to true indicates that the application intends to read data from the URL connection. 
			The default value of this field is true.
		*/
		protected boolean doOutput;
		/*	This variable is set by the setDoOutput method. Its value can be accessed by the 				getDoInput method.
			A URL connection can be used for input and/or output. Setting the do-Output flag to true indicates that the application intends to write data to the URL connection. 
			The default value of this field is false. 
		*/
		protected long ifModifiedSince;	
		/*	Some protocols support skipping the fetching of the object unless the object has been modified more recently than a certain time. 
			A non-zero value is interpreted as the time corresponding to if-Modified-Since seconds since January 1, 1970, GMT. The object is fetched only if it has been modified more recently than that time. 
			This variable is set by the setIfModifiedSince method . Its value can be accessed by the getIfModifiedSince method.
			The default value of this field is 0, indicating that the fetching must always occur. 
		*/
		protected URL url;	 
		/*	The URL representing the remote object on the World Wide Web to which this connection is opened. 
			The value of this field can be accessed by the getURL method.
			The default value of this variable is the value of the URL argument in the URLConnection constructor.
		*/
		protected boolean useCaches;
		/*	This field is set by the setUseCaches method. Its value can be accessed by the getUseCaches method . Its default value is the value of the last argument to the method setDefaultUseCaches.
			If true, the protocol is allowed to use caching whenever it can. If false, the protocol must always try to get a fresh copy of the object.
		*/
		// 	Constructors
		protected URLConnection(URL  url); 
		/*	Constructs a URL connection to the specified URL. A connection to the object referenced by the URL is not created.
		*/
			// 	Methods
		public abstract void connect(); 
		public boolean getAllowUserInteraction();	 
		public Object getContent();	 
		public String getContentEncoding(); 
		public int getContentLength();	 
		public String getContentType();	 
		public long getDate(); 
		public static boolean getDefaultAllowUserInteraction(); 
		public static String getDefaultRequestProperty(String  key);
		public boolean getDefaultUseCaches(); 
		public boolean getDoInput(); 
		public boolean getDoOutput(); 
		public long getExpiration(); 
		public String getHeaderField(int  n);	 
		public String getHeaderField(String  name);	 
		public long getHeaderFieldDate(String  name, long  Default);  
		public int getHeaderFieldInt(String  name, int  Default); 
		public String getHeaderFieldKey(int  n);
		public long getIfModifiedSince();
		public InputStream getInputStream(); 
		public long getLastModified();	
		public OutputStream getOutputStream();	 
		public String getRequestProperty(String  key);	 
		public URL getURL();	 
		public boolean getUseCaches();	 
		protected static String guessContentTypeFromName(String  fname);
		protected static String guessContentTypeFromStream(InputStream  is);
		public void  setAllowUserInteraction(boolean  allow);
		public static void setContentHandlerFactory(ContentHandlerFactory  fac);
		public static void setDefaultAllowUserInteraction(boolean  default);
		public static void setDefaultRequestProperty(String  key, String  value);
		public void setDefaultUseCaches(boolean  uCaches);
		public void setDoInput(boolean  doinput); 
		public void setDoOutput(boolean  dooutput);	 
		public void setIfModifiedSince(long   modify); 
		public void setRequestProperty(String  key, String  value);   
		public void setUseCaches(boolean  uCaches);	 
		public String toString(); 
	}

	Methods are stated in Table 8.8.

Table 8.8

Method	Description
connect()	Opens a communications link to the resource referenced by this URL, if such a connection hasn't already been established. If the connect method is called when the connection has already been opened (indicated by the connected field having the value true), the call is ignored. Throws : IOException, if an IO error occurs while opening the connection.
getAllowUserInteraction()	Returns : the value of the allowUserInteraction field for this object.
getContent()	Retrieves the contents of this URL connection. Throws : IOException, if an IO error occurs while getting the content. Throws : UnknownServiceException, if the protocol does not support the content type.
getContentEncoding()	Returns : the content encoding of the resource that the URL references, or null if not known.
getContentLength()	Returns : the content length of the resource that this connection's URL referncees, or -1 if the content length is not known.
getContentType()	Returns : the content type of the resource that the URL references, or null if not known.
getDate()	Returns : the sending date of the resource that the URL refernces, or 0 if not known. The value returned is the number of seconds since January 1, 1970 GMT.
getDefaultAllowUserInteraction()	Returns : The default value of the allowUserInteraction field.
getDefaultRequestProperty(String key)	Gets the value of the default request property. Default request properties are set for every connection.
getDefaultUseCaches()	Returns : the default value of this URLConnection's useCaches flag.
getDoInput()	Returns : the value of this URLConnection's doInput flag..
getDoOutput()	Returns : the value of this URLConnection's doOutput flag.
getExpiration()	Returns : the expiration date of the resource that this URL references, or 0 if not known. The value is number of seconds since January 1, 1970 GMT.
getHeaderField(int n)	Gets the value for the nth header field. It returns null if there are fewer than n fields.
getHeaderField(String name)	Returns : the value of the named header field, or null if not known.
getHeaderFieldDate(String name, long Default)	Returns : the value of the field, parsed as a date. The result is the number of seconds since January 1, 1970 GMT represented by the named field. The value of the Default argument is returned if the field is missing or malformed.
getHeaderFieldInt(String name, int Default)	Returns : the value of the named field, parsed as an integer. The Default value is returned if the field is missing or malformed.
getHeaderFieldKey(int n)	Returns : the key for the nth header field, or null if there are fewer than n fields.
getIfModifiedSince()	Returns : the value of this object's ifModifiedSince flag.
getInputStream()	Returns : an input stream that reads from this open connection. Throws : IOException (If an IO error occurs while creating the input stream ), UnknownServiceException, if the protocol does not support input.
getLastModified()	Returns : the date the resource referenced by this URLConnection was last modified, or 0 if not known. The result is the number of seconds since January 1, 1970 GMT.203203
getOutputStream()	Returns : an output stream that writes to this connection. Throws : IOException (If an IO error occurs while creating the output stream ), UnknownServiceException, if the protocol does not support output.
getRequestProperty(String key)	Returns : The value of the named general request property for this connection.
getURL()	Returns : the value of this URLConnection's URL flag.
getUseCaches()	Returns : the value of this URLConnection's useCaches flag.
guessContentTypeFromName (String fname)	Returns : a guess as to what the content type of the object is, based upon its name.
guessContentTypeFromStream (InputStream is)	Tries to determine the type of an input stream based on the characters at the beginning of the input stream.
setAllowUserInteraction(boolean allow)	Set the value of the allowUserInteraction.
setContentHandlerFactory(ContentHandlerFactory fac)	Sets the ContentHandlerFactory of an application. It can be called at most once by an application. Throws : Error, if the factory has already been defined.
setDefaultAllowUserInteraction(boolean default)	Sets the default value of the allow-User-Interaction flag for this URLConnection to the specified value.
setDefaultRequestProperty(String key, String value)	Sets the default value of a general request property. When a URL-Connection is created, it is initialized with these properties.
setDefaultUseCaches(boolean uCaches)	Sets the default value of the useCaches flag for this URLConnection to the specified value.
setDoInput(boolean doinput)	Sets the value of the doInput flag for this URLConnection to the specified value.
setDoOutput(boolean dooutput)	Sets the value of the doOutput flag for this URL-Connection to the specified value.
setIfModifiedSince(long modify)	Sets the value of the ifModifiedSince field of this URLConnection to the specified value.
setRequestProperty(String key, String value)	Sets the general request property.
setUseCaches(boolean uCaches)	Sets the value of the useCaches field of this URL-Connection to the specified value.
toString()	Returns : a string representation of this URLConnection.

Class URLEncoder

The class contains a utility method for converting a String into a MIME format called "x- www-form-urlencoded" format. To convert a String, each character is examined in turn :