A Guide to the Java URL

1. Overview

In this article, we are going to explore low-level operations with Java network programming. We’ll be taking a deeper look at URLs.

A URL is a reference or an address to a resource on the network. And simply put, Java code communicating over the network can use the java.net.URL class to represent the addresses of resources.

The Java platform ships with built-in networking support, bundled up in the java.net package:

import java.net.*;

2. Creating a URL

Let’s first create a java.net.URL object by using its constructor and passing in a String representing the human readable address of the resource:

URL url = new URL("http://www.baeldung.com/a-guide-to-java-sockets");

We’ve just created an absolute URL object. The address has all the parts required to reach the desired resource.

We can also create a relative URL; assuming we have the URL object representing the home page of Baeldung:

URL home = new URL("http://baeldung.com");

Next, let’s create a new URL pointing to a resource we already know; we’re going to use another constructor, that takes both an existing URL and a resource name relative to that URL:

URL url = new URL(home, "a-guide-to-java-sockets");

We have now created a new URL object url relative to home; so the relative URL is only valid within the context of the base URL.

We can see this in a test:

@Test
public void givenBaseUrl_whenCreatesRelativeUrl_thenCorrect() {
    URL baseUrl = new URL("http://baeldung.com");
    URL relativeUrl = new URL(baseUrl, "a-guide-to-java-sockets");
    
    assertEquals(
      "http://baeldung.com/a-guide-to-java-sockets", 
      relativeUrl.toString());
}

However if the relative URL is detected to be absolute in its component parts, then the baseURL is ignored:

@Test
public void givenAbsoluteUrl_whenIgnoresBaseUrl_thenCorrect() {
    URL baseUrl = new URL("http://baeldung.com");
    URL relativeUrl = new URL(
      baseUrl, "http://baeldung.com/a-guide-to-java-sockets");
    
    assertEquals(
      "http://baeldung.com/a-guide-to-java-sockets", 
      relativeUrl.toString());
}

Finally, we can create a URL by calling another constructor which takes in the component parts of the URL string. We will cover this in the next section after covering URL components.

3. URL Components

A URL is made up of a few components – which we’ll explore in this section.

Let’s first look at the separation between the protocol identifier and the resource – these two components are separated by a colon followed by two forward slashes i.e. ://. 

If we have a URL such as http://baeldung.com then the part before the separator, http, is the protocol identifier while the one that follows is the resource name, baeldung.com.

Let’s have a look at the API that the URL object exposes.

3.1. The Protocol

To retrieve the protocol – we use the getProtocol() method:

@Test
public void givenUrl_whenCanIdentifyProtocol_thenCorrect(){
    URL url = new URL("http://baeldung.com");
    
    assertEquals("http", url.getProtocol());
}

3.2. The Port

To get the port – we use the getPort() method:

@Test
public void givenUrl_whenGetsDefaultPort_thenCorrect(){
    URL url = new URL("http://baeldung.com");
    
    assertEquals(-1, url.getPort());
    assertEquals(80, url.getDefaultPort());
}

Note that this method retrieves the explicitly defined port. If no port is defined explicitly, it will return -1.

And because HTTP communication uses port 80 by default – no port is defined.

Here’s an example where we do have an explicitly defined port:

@Test
public void givenUrl_whenGetsPort_thenCorrect(){
    URL url = new URL("http://baeldung.com:8090");
    
    assertEquals(8090, url.getPort());
}

3.3. The Host

The host is the part of the resource name that starts right after the :// separator and ends with the domain name extension, in our case .com.

We call the getHost() method to retrieve the hostname:

@Test
public void givenUrl_whenCanGetHost_thenCorrect(){
    URL url = new URL("http://baeldung.com");
    
    assertEquals("baeldung.com", url.getHost());
}

3.4. The File Name

Whatever follows after the hostname in a URL is referred to as the file name of the resource. It can include both path and query parameters or just a file name:

@Test
public void givenUrl_whenCanGetFileName_thenCorrect1() {
    URL url = new URL("http://baeldung.com/guidelines.txt");
    
    assertEquals("/guidelines.txt", url.getFile());
}

Assuming Baeldung has java 8 articles under the URL http://baeldung.com/articles?topic=java&version=8. Everything after the hostname is the file name:

@Test
public void givenUrl_whenCanGetFileName_thenCorrect2() {
    URL url = new URL(
      "http://baeldung.com/articles?topic=java&version=8");
    
    assertEquals("/articles?topic=java&version=8", url.getFile());
}

3.5. Path Parameters

We can also only inspect the path parameters which in our case is /articles:

@Test
public void givenUrl_whenCanGetPathParams_thenCorrect() {
    URL url = new URL(
      "http://baeldung.com/articles?topic=java&version=8");
    
    assertEquals("/articles", url.getPath());
}

3.6. Query Parameters

Likewise, we can inspect the query parameters which is topic=java&version=8:

@Test
public void givenUrl_whenCanGetQueryParams_thenCorrect() {
    URL url = new URL("http://baeldung.com/articles?topic=java<em>&amp;version=8</em>");
    
    assertEquals("topic=java<em>&amp;version=8</em>", url.getQuery());
}

4. Creating URL with Component Parts

Since we have now looked at the different URL components and their place in forming the complete address to the resource, we can look at another method of creating a URL object by passing in the component parts.

The first constructor takes the protocol, the hostname and the file name respectively:

@Test
public void givenUrlComponents_whenConstructsCompleteUrl_thenCorrect() {
    String protocol = "http";
    String host = "baeldung.com";
    String file = "/guidelines.txt";
    URL url = new URL(protocol, host, file);
    
    assertEquals("http://baeldung.com/guidelines.txt", url.toString());
}

Keep in mind the meaning of filename in this context, the following test should make it clearer:

@Test
public void givenUrlComponents_whenConstructsCompleteUrl_thenCorrect2() {
    String protocol = "http";
    String host = "baeldung.com";
    String file = "/articles?topic=java&version=8";
    URL url = new URL(protocol, host, file);
    
    assertEquals("http://baeldung.com/guidelines.txt", url.toString());
}

The second constructor takes the protocol, the hostname, the port number and the filename respectively:

@Test
public void givenUrlComponentsWithPort_whenConstructsCompleteUrl_
  thenCorrect() {
    String protocol = "http";
    String host = "baeldung.com";
    int port = 9000;
    String file = "/guidelines.txt";
    URL url = new URL(protocol, host, port, file);
    
    assertEquals(
      "http://baeldung.com:9000/guidelines.txt", url.toString());
}

5. Conclusion

In this tutorial, we covered the URL class and showed how to use it in Java to access network resources programmatically.

As always, the full source code for the article and all code snippets can be found in the GitHub project.