Java HttpURLConnection (how to open and read a url with Java)

On this blog I’ve shown a variety of ways to use Java to open a URL connection, and then read data from that connection, including my How to open and read from a URL with the Java URL and URLConnection classes tutorial. In this example I’ll show how to open a URL using the Java HttpURLConnection class. As the Javadoc states, this class is a subclass of the URLConnection class that “provides support for HTTP-specific features.”

A Java HttpURLConnection example

Jumping right into it ... here’s the source code for a complete Java class that demonstrates how to open a URL and then read from it, using the HttpURLConnection class. This class also demonstrates how to properly encode your URL using the encode method of the URLEncoder class:

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;

/**
 *
 * A complete Java class that shows how to open a URL, then read data (text) from that URL,
 * HttpURLConnection class (in combination with an InputStreamReader and BufferedReader).
 *
 * @author alvin alexander, http://alvinalexander.com.
 *
 */
public class JavaHttpUrlConnectionReader
{
  public static void main(String[] args)
  throws Exception
  {
    new JavaHttpUrlConnectionReader();
  }
  
  public JavaHttpUrlConnectionReader()
  {
    try
    {
      String myUrl = "http://localhost:8080/";
      // if your url can contain weird characters you will want to 
      // encode it here, something like this:
      // myUrl = URLEncoder.encode(myUrl, "UTF-8");

      String results = doHttpUrlConnectionAction(myUrl);
      System.out.println(results);
    }
    catch (Exception e)
    {
      // deal with the exception in your "controller"
    }
  }

  /**
   * Returns the output from the given URL.
   * 
   * I tried to hide some of the ugliness of the exception-handling
   * in this method, and just return a high level Exception from here.
   * Modify this behavior as desired.
   * 
   * @param desiredUrl
   * @return
   * @throws Exception
   */
  private String doHttpUrlConnectionAction(String desiredUrl)
  throws Exception
  {
    URL url = null;
    BufferedReader reader = null;
    StringBuilder stringBuilder;

    try
    {
      // create the HttpURLConnection
      url = new URL(desiredUrl);
      HttpURLConnection connection = (HttpURLConnection) url.openConnection();
      
      // just want to do an HTTP GET here
      connection.setRequestMethod("GET");
      
      // uncomment this if you want to write output to this url
      //connection.setDoOutput(true);
      
      // give it 15 seconds to respond
      connection.setReadTimeout(15*1000);
      connection.connect();

      // read the output from the server
      reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
      stringBuilder = new StringBuilder();

      String line = null;
      while ((line = reader.readLine()) != null)
      {
        stringBuilder.append(line + "\n");
      }
      return stringBuilder.toString();
    }
    catch (Exception e)
    {
      e.printStackTrace();
      throw e;
    }
    finally
    {
      // close the reader; this can throw an exception too, so
      // wrap it in another try/catch block.
      if (reader != null)
      {
        try
        {
          reader.close();
        }
        catch (IOException ioe)
        {
          ioe.printStackTrace();
        }
      }
    }
  }
}

Discussion: Java HttpUrlConnection example

Here’s a quick walk-through of how this Java HttpUrlConnection code works:

1. The main method is called, and it creates a new instance of this class.
2. I define a URL, pass that URL to the doHttpUrlConnectionAction method, then print the String output received from that method.
3. The doHttpUrlConnectionAction method works like this:
   1. It creates a new URL.
   2. It opens a connection, then casts that connection to a HttpURLConnection.
   3. It sets the request method to GET (as opposed to something else, like POST).
   4. (Optional: The setDoOutput tells the object that we will be writing output to this URL.)
   5. I set the read timeout to 15 seconds, then ope the connection.
   6. I read the data as usual, using an InputStreamReader and BufferedReader.
   7. As I read each line of output from the URL, I add it to my StringBuilder, then convert the StringBuilder to a String when the method returns.

As mentioned, the setDoOutput method is optional. Here’s a brief description of it from its Javadoc:

A URL connection can be used for input and/or output. Set the DoOutput flag to true if you intend to use the URL connection for output, false if not. The default is false.

In this example, because I’m not writing anything to the URL, I leave this set to its default value of false.

In summary, when you know that you are specifically dealing with an HTTP connection, the HttpURLConnection class offers many convenience methods and fields that can make your programming life a little easier.