Learn about how we can search for free ports for Java servers.

1. Overview

When starting a socket server in our Java application, the java.net API requires us to specify a free port number to listen on. The port number is required so that the TCP layer can identify the application that the incoming data is intended for.

Specifying a port number explicitly is not always a good option, because applications might already occupy it. This will cause an input/output exception in our Java application.

In this quick tutorial, we’ll look at how to check a specific port status and how to use an automatically allocated one. We’ll look into how this can be done with plain Java and Spring framework. We’ll also look at some other server implementations, like embedded Tomcat and Jetty.

2. Checking Port Status

Let’s look at how we can check if a specific port is free or occupied using the java.net API.

2.1. Specific Port

We’ll make use of the ServerSocket class from the java.net API to create a server socket, bound to the specified port. In its constructor, the ServerSocket accepts an explicit port number. The class also implements the Closeable interface, so it can be used in try-with-resources to automatically close the socket and free up the port:

    try (ServerSocket serverSocket = new ServerSocket(FREE_PORT_NUMBER)) {
        assertThat(serverSocket).isNotNull();
        assertThat(serverSocket.getLocalPort()).isEqualTo(FREE_PORT_NUMBER);
    } catch (IOException e) {
        fail("Port is not available");
    }

In case we use a specific port twice, or it’s already occupied by another application, the ServerSocket constructor will throw an IOException:

try (ServerSocket serverSocket = new ServerSocket(FREE_PORT_NUMBER)) {
        new ServerSocket(FREE_PORT_NUMBER);
        fail("Same port cannot be used twice");
    } catch (IOException e) {
        assertThat(e).hasMessageContaining("Address already in use");
    }

2.2. Port Range

Let’s now check how we can make use of the thrown IOException, to create a server socket using the first free port from a given range of port numbers:

for (int port : FREE_PORT_RANGE) {
        try (ServerSocket serverSocket = new ServerSocket(port)) {
            assertThat(serverSocket).isNotNull();
            assertThat(serverSocket.getLocalPort()).isEqualTo(port);
            return;
        } catch (IOException e) {
            assertThat(e).hasMessageContaining("Address already in use");
        }
    }
    fail("No free port in the range found");

#java #programming #developer