How to use Java URLConnection and HttpURLConnection

Details: Written by Nam Ha Minh; Last Updated on 18 July 2019 | Print Email

In this Java network programming tutorial, you will learn how to use the URLConnection and HttpURLConnection classes for developing Java programs that communicate to a server via URLs (mostly using HTTP protocol).

You will be able to write code for uploading and downloading files, web pages; sending and retrieving HTTP requests and responses; and the like.

The URLConnection and HttpURLConnection Classes

URLConnection is the superclass of all classes that represent a connection between a Java application and a URL. The URLConnection class provides API for generic URLs, and its subclass HttpURLConnection provides additional support for HTTP-specific features.

Note that both of these classes are abstract - meaning that you can’t directly create new instances of URLConnection and HttpURLConnection. Instead, an instance of URLConnection is obtained by opening the connection from a URL object.

Typically, a client program communicates with a server via a URL follows this sequence of steps:

Create a URL object
Obtain a URLConnection object from the URL
Configure the URLConnection
Read the header fields
Get an input stream and read data
Get an output stream and write data
Close the connection

The steps 3 to 6 are optional, and the steps 5 and 6 are interchangeable.

Let’s explore the API of URLConnection and HttpURLConnection classes based on this sequence.

1. Create a URL object

Simply create a new URL object for a given URL like this:

URL url = new URL("http://www.google.com");

This constructor will throw a MalformedURLException if the URL is malformed. This checked exception is a subclass of IOException.

2. Obtain a URLConnection object from the URL

A URLConnection instance is obtained by invoking the openConnection() method on the URL object:

URLConnection urlCon = url.openConnection();

If the protocol is http://, you can cast the returned object to an HttpURLConnection object:

HttpURLConnection httpCon = (HttpURLConnection) url.openConnection();

Note that the openConnection() method doesn’t establish an actual network connection. It just returns an instance of URLConnection class.

The network connection is made explicitly when the connect() method is invoked, or implicitly when reading header fields or getting an input stream / output stream.

The URL’s openConnection() method throws IOException if an I/O error occurs.

3. Configure the URLConnection

Before actually establish the connection, you can configure various aspects that affect the ongoing communication between the client and the server, such as timeout, cache, HTTP request method, etc.

The URLConnection class provides the following methods for configuring the connection:

setConnectTimeout(int timeout): sets the connection timeout in milliseconds. A java.net.SocketTimeoutException is thrown if the timeout expires before the connection can be established. A timeout of zero indicates infinite timeout (the default value).

setReadTimeout(int timeout): sets the read timeout in milliseconds. After the timeout expires and there’s no data available to read from the connection’s input stream, a SocketTimeoutException is raised. A timeout of zero indicates infinite timeout (the default value).

setDefaultUseCaches(boolean default): sets whether the URLConnection uses caches by default or not (default is true). This method affects future instances of the URLConnection class.

setUseCaches(boolean useCaches): sets whether this connection uses cache or not (default is true).

setDoInput(boolean doInput): sets whether this URLConnection can be used for reading content from the server (default is true).

setDoOutput(boolean doOutput): sets whether this URLConnection can be used for sending data to the server (default is false).

setIfModifiedSince(long time): sets the last modified time of the content retrieved by the client, primarily for HTTP protocol. For example, if the server finds that the content has not changed since the specified time, it doesn’t fetch the content and returns status code 304 - not modified. The client will get the fresh content if it has been modified more recently than the specified time.

setAllowUserInteraction(boolean allow): enables or disables user interaction, e.g. popping up an authentication dialog if required (default is false).

setDefaultAllowUserInteraction(boolean default): sets the default value for user interaction for all future URLConnection objects.

setRequestProperty(String key, String value): sets a general request property specified by a key=value pair. If a property with the key already exists, the old value is overwritten with the new value.

Note that these methods should be invoked before establishing the connection. Some methods throw IllegalStateException if the connection is already made.

In addition, the subclass HttpURLConnection provides the following methods for configuring the connection with HTTP-specific features:

setRequestMethod(String method): sets the method for the URL request, which is one of HTTP methods GET, POST, HEAD, OPTIONS, PUT, DELETE and TRACE. The default method is GET.

setChunkedStreamingMode(int chunkLength): enables streaming of a HTTP request body without internal buffering, when the content length is not known in advanced.

setFixedLengthStreamingMode(long contentLength): enables streaming of a HTTP request body without internal buffering, when the content length is known in advanced.

setFollowRedirects(boolean follow): this static method sets whether HTTP redirects should be automatically followed by future objects of this class (default is true).

setInstanceFollowRedirects(boolean follow): sets whether HTTP redirects should be automatically followed by instance of this HttpURLConnection class (default is true).

The above methods are setters. And the URLConnection and HttpURLConnection classes also provide corresponding getters:

getConnectTimeout()
getReadTimeout()
getDefaultUseCaches()
getUseCaches()
getDoInput()
getDoOutput()
getIfModifiedSince()
getAllowUserInteraction()
getDefaultAllowUserInteraction()
getRequestProperty(String key)
getRequestMethod()
getFollowRedirects()
getInstanceFollowRedirects()

4. Read the header fields

Once the connection is made, the server processes the URL request and sends back a response that consists of metadata and actual content. The metadata is a collection of key=value pairs which are called header fields.

The header fields reveal information about the server, status code, protocol information, etc. The actual content can be in text, HTML, image, etc. depending on the type of the document.

The URLConnection class provides the following methods for reading the header fields:

getHeaderFields(): returns a map that contains all header fields. The key is field name and the value is a list of String represents the corresponding field values.

getHeaderField(int n): reads the value of the n-th header field.

getHeaderField(String name): reads the value of the named header field.

getHeaderFieldKey(int n): reads the key of the n-th header field.

getHeaderFieldDate(String name, long default): reads the value of the named field parsed as Date. If the field is missing or value is malformed, the default value is returned instead.

getHeaderFieldInt(String name, int default): reads the value of the named field parsed as an integer number. If the field is missing or value is malformed, the default value is returned instead.

getHeaderFieldLong(String name, long default): reads the value of the named field parsed as a long number. If the field is missing or value is malformed, the default value is returned instead.

These are general methods for reading any header fields. And for some frequently-accessed header fields, the URLConnection class provides more specific methods:

getContentEncoding(): reads the value of the content-encoding header field, which indicates the encoding type of the content.

getContentLength(): reads the value of the content-length header field, which indicates the size of the content (in bytes).

getContentType(): reads the value of the content-type header field, which indicates the type of the content.

getDate(): reads the value of the date header field, which indicates the date time on the server.

getExpiration(): reads the value of the expires header field, indicates the time after which the response is considered stale. This is for cache control.

getLastModified(): reads the value of the last-modified header field, which indicates the last modified time of the content.

And the subclass HttpURLConnection provides an additional method:

getResponseCode(): returns the HTTP status code sent by the server.

Note that when the header fields are read, the connection is implicitly established, without calling connect().

5. Get an input stream and read data

To read the actual content, you need to obtain an InputStream instance from the connection, and then use the InputStream’s read() methods to read the data:

InputStream inputStream = urlCon.getInputStream();
byte[] data = new byte[1024];
inputStream.read(data);

The InputStream’s read() is a low-level method that reads data to an array of bytes. So it is more convenient to wrap the InputStream in an InputStreamReader for reading data to characters:

InputStream inputStream = urlCon.getInputStream();
InputStreamReader reader = new InputStreamReader(inputStream);

int character = reader.read();	// reads a single character
char[] buffer = new char[4096];
reader.read(buffer);	// reads to an array of characters

Or wrap the InputStream in a BufferedReader for reading data to Strings:

BufferedReader reader = new BufferedReader(new InputStreamReader(input));
String line = reader.readLine(); // reads a line

Note that the getInputStream() method can throw the following exceptions:

IOException: if an I/O error occurs while creating the input stream.
SocketTimeoutException: if the read timeout expires before data is available for read.
UnknownServiceExcepetion: if the protocol does not support input.

6. Get an output stream and write data

To send data to the server, you have to enable output on the connection first:

urlCon.setDoOutput(true);

Then get the OutputStream object associated with the connection, and then use the OutputStream’s write() methods to write the data:

OutputStream outputStream = urlCon.getOutputStream();
byte[] data = new byte[1024];
outputStream.write(data);

As you can see, the OutputStream’s write() is a low-level method that writes an array of bytes. So it is more convenient to wrap the OutputStream in an OutputStreamWriter for writing characters:

OutputStreamWriter writer = new OutputStreamWriter(outputStream);
int character = 'a';
writer.write(character); // writes a single character

char[] buffer = new char[4096];
writer.write(buffer); // writes an array of characters

Or wrap the OutputStream in a PrintWriter for writing Strings:

PrintWriter writer = new PrintWriter(outputStream);
String line = "This is String";
writer.print(line);

Note that the getOutputStream() method can throw IOException or UnknownServiceException.

7. Close the connection

To close the connection, invoke the close() method on either the InputStream or OutputStream object. Doing that may free the network resources associated with the URLConnection instance.

That’s about how to use the API of URLConnection and HttpURLConnection. Check the following articles for real-world examples:

So you can use URLConnection and HttpURLConnection for simple network programming, i.e. send and receive data to and from a server. I recommend you to read this book to learn more in-depth about Java network programming, or take this Java masterclass course to dive deep into Java programming.

About the Author:

Nam Ha Minh is certified Java programmer (SCJP and SCWCD). He began programming with Java back in the days of Java 1.4 and has been passionate about it ever since. You can connect with him on Facebook and watch his Java videos on YouTube.