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

Starting from Java version 20, all the constructors of the java.net.URL have been deprecated, so we will use java.net.URI constructors instead.

Let’s first create a URL object by using URI.toURL(). We create a URI by passing in a String representing the human readable address of the resource then construct a URL from it:

URL home = new URI("http://baeldung.com/a-guide-to-java-sockets").toURL();

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 URI object; It is however important to note that the toURL() method prevents the creation of URLs if the URI is not absolute as shown in this test:

@Test
    public void givenRelativeUrl_whenCreatesRelativeUrl_thenThrows() {
    URI uri = new URI("/a-guide-to-java-sockets");
    Assert.assertThrows(IllegalArgumentException.class, () -> uri.toURL());
}

There are other ways to create a URL by calling the available java.net.URI constructors 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 URI class exposes.

3.1. The Protocol

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

@Test
public void givenUrl_whenCanIdentifyProtocol_thenCorrect(){
    URL url = new URI("http://baeldung.com").toURL();
    
    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 URI("http://baeldung.com").toURL();
    
    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 URI("http://baeldung.com:8090").toURL();
    
    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 URI("http://baeldung.com").toURL();
    
    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 URI("http://baeldung.com/guidelines.txt").toURL();
    
    assertEquals("/guidelines.txt", url.getFile());
}

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

@Test
public void givenUrl_whenCanGetFileName_thenCorrect2() {
    URL url = new URI("http://baeldung.com/articles?topic=java&version=8").toURL();
    
    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 URI("http://baeldung.com/articles?topic=java&version=8").toURL();
    
    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 URI("http://baeldung.com/articles?topic=java&version=8").toURL();
    
    assertEquals("topic=java&version=8", 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.

4.1. Using the URI() Constructors

One of the available constructors takes the protocol, the hostname, the file name, and the fragment respectively:

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

You can also use the constructor with the additional userInfo, port, and query:

@Test
public void givenUrlComponents_whenConstructsCompleteUrl_thenCorrect2() {
    String protocol = "http";
    String username = "admin";
    String host = "baeldung.com";
    String file = "/articles";
    String query = "topic=java&version=8";
    String fragment = "myImage";
    URL url = new URI(protocol, username, host, -1, file, query, fragment).toURL();
    assertEquals("http://[email protected]/articles?topic=java&version=8#myImage", url.toString());
}

4.2. Using Apache HttpClient’s URIBuilder

We’ve seen how to build a URL object using the standard URI() constructors. However, it could be error-prone when the URL contains many query parameters.

Some popular frameworks and libraries have provided nice URL builders to allow us to build a URL object easily.

First, let’s look at Apache HttpClient.

Apache HttpClient is a popular library to help us handle HTTP requests and responses. Further, it ships with a URIBuilder, which allows us to conveniently construct URL objects.

To use the URIBuilder class, we need first to add the Apache HttpClient dependency to our project:

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.14</version>
</dependency>

The latest version can be found here.

Using URIBuilder, we can easily set different URL components, such as port, path, parameters, and so on, and build the URL object:

@Test
public void givenUrlParameters_whenBuildUrlWithURIBuilder_thenSuccess() throws URISyntaxException, MalformedURLException {
    URIBuilder uriBuilder = new URIBuilder("http://baeldung.com/articles");
    uriBuilder.setPort(9090);
    uriBuilder.addParameter("topic", "java");
    uriBuilder.addParameter("version", "8");
    URL url = uriBuilder.build().toURL();
    assertEquals("http://baeldung.com:9090/articles?topic=java&version=8", url.toString());
}

As we can see in the test above, we can add parameters with URIBuilder‘s addParameter() method. Additionally, URIBuilder provides the addParameters() method, which allows us to add multiple parameters in one shot. It’s particularly useful when we’ve prepared all parameters in a special data structure, such as a Map:

@Test
public void givenUrlParametersInMap_whenBuildUrlWithURIBuilder_thenSuccess() 
  throws URISyntaxException, MalformedURLException {
    Map<String, String> paramMap = ImmutableMap.of("topic", "java", "version", "8");
    URIBuilder uriBuilder = new URIBuilder("http://baeldung.com/articles");
    uriBuilder.setPort(9090);
    uriBuilder.addParameters(paramMap.entrySet()
      .stream()
      .map(entry -> new BasicNameValuePair(entry.getKey(), entry.getValue()))
      .collect(toList()));
               
    URL url = uriBuilder.build().toURL();
    assertEquals("http://baeldung.com:9090/articles?topic=java&version=8", url.toString());
}

In the example above, we use the Java Stream API to convert the parameter Map to a list of BasicNameValuePair objects.

4.3. Using Spring-web’s UriComponentsBuilder

Spring is a widely used framework. Spring-web offers us UriComponentsBuilder, a nice class to build URL objects straightforwardly.

Again, first, we must make sure our project has included the spring-web dependency:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>6.0.8</version>
</dependency>

We can find Spring-web’s latest version in the Maven central repository.

Finally, let’s build a URL object using UriComponentsBuilder:

@Test
public void givenUrlParameters_whenBuildUrlWithSpringUriComponentsBuilder_thenSuccess() 
  throws MalformedURLException {
    URL url = UriComponentsBuilder.newInstance()
      .scheme("http")
      .host("baeldung.com")
      .port(9090)
      .path("articles")
      .queryParam("topic", "java")
      .queryParam("version", "8")
      .build()
      .toUri()
      .toURL();
    
    assertEquals("http://baeldung.com:9090/articles?topic=java&version=8", url.toString());
}

5. Conclusion

In this article, we discussed the URL class and saw how to use it in Java to access network resources programmatically.