Get the Running Port in Spring Boot

1. Overview

A Spring Boot application embeds a web server, and sometimes, we may want to discover the HTTP port at runtime.

In this tutorial, we’ll address how to get the HTTP port programmatically in a Spring Boot application.

2. Introduction

2.1. Our Spring Boot Application

We’ll create a simple Spring Boot application example to quickly show the methods to discover the HTTP port at runtime:

@SpringBootApplication
public class GetServerPortApplication {
    public static void main(String[] args) {
        SpringApplication.run(GetServerPortApplication.class, args);
    }
}

2.2. Two Scenarios of Setting the Port

Usually, the most straightforward way to configure the HTTP port of a Spring Boot application is by defining the port in the configuration file application.properties or application.yml.

For example, in the application.properties file, we can set 7777 as the port our application is running on:

server.port=7777

Alternatively, instead of defining a fixed port, we can let the Spring Boot application run on a random port by setting “0” as the value of the “server.port” property:

server.port=0

Next, let’s go through the two scenarios and discuss different ways to get the port programmatically at runtime.

In this tutorial, we’ll discover the server port in unit tests.

3. Getting a Fixed Port at Runtime

Let’s create a properties file application-fixedport.properties and define a fixed port 7777 in it:

server.port=7777

Next, we’ll try to get the port in a unit test class:

@RunWith(SpringRunner.class)
@SpringBootTest(classes = GetServerPortApplication.class,
  webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
@ActiveProfiles("fixedport")
public class GetServerFixedPortUnitTest {
    private final static int EXPECTED_PORT = 7777;
    ....
}

Before we see the test methods, let’s take a quick look at the annotations of the test class:

• @RunWith(SpringRunner.class) – This will join the JUnit test with the Spring TestContext
• @SpringBootTest( … SpringBootTest.WebEnvironment.DEFINED_PORT) – In the SpringBootTest, we’ll use the DEFINED_PORT for the embedded web server
• @ActiveProfiles(“fixedport”) – With this annotation, we enabled the Spring profile “fixedport” so that our application-fixedport.properties will be loaded

3.1. Using the @Value(“${server.port}”) Annotation

Since the application-fixedport.properties file will be loaded, we can get the “server.port” property using the @Value annotation:

@Value("${server.port}")
private int serverPort;

@Test
public void givenFixedPortAsServerPort_whenReadServerPort_thenGetThePort() {
    assertEquals(EXPECTED_PORT, serverPort);
}

3.2. Using the ServerProperties Class

ServerProperties holds the properties of the embedded web server, such as the port, the address, and the server header.

We can inject a ServerProperties component and get the port from it:

@Autowired
private ServerProperties serverProperties;

@Test
public void givenFixedPortAsServerPort_whenReadServerProps_thenGetThePort() {
    int port = serverProperties.getPort();
 
    assertEquals(EXPECTED_PORT, port);
}

So far, we’ve learned two ways to get a fixed port at runtime. Next, let’s see how to discover the port in the random port scenario.

4. Getting Random Port at Runtime

This time, let’s create another properties file application-randomport.properties:

server.port=0

As the code above shows, we allow Spring Boot to choose a free port randomly when the web server starts.

In the same vein, let’s create another unit test class:

....
@ActiveProfiles("randomport")
public class GetServerRandomPortUnitTest {
...
}

Here, we need to activate the “randomport” Spring profile to load the corresponding properties file.

We’ve learned two ways to discover a fixed port at runtime. However, they can’t help us to get the random port:

@Value("${server.port}")
private int randomServerPort;

@Test
public void given0AsServerPort_whenReadServerPort_thenGet0() {
    assertEquals(0, randomServerPort);
}

@Autowired
private ServerProperties serverProperties;

@Test
public void given0AsServerPort_whenReadServerProps_thenGet0() {
    int port = serverProperties.getPort();
 
    assertEquals(0, port);
}

As the two test methods show, both @Value(“${server.port}”) and serverProperties.getPort() report “0” as the port. Clearly, it is not the correct port we are expecting.

4.1. Using ServletWebServerApplicationContext

Spring Boot starts a ServletWebServerApplicationContext if the embedded web server starts.

Therefore, we can get the WebServer from the context object to obtain the server information or manipulate the server:

@Autowired
private ServletWebServerApplicationContext webServerAppCtxt;

@Test
public void given0AsServerPort_whenReadWebAppCtxt_thenGetThePort() {
    int port = webServerAppCtxt.getWebServer().getPort();
 
    assertTrue(port > 1023);
}

In the test above, we check if the port is greater than 1023. This is because 0-1023 are system ports.

4.2. Handling ServletWebServerInitializedEvent

A Spring application can publish various events and EventListeners handle the events.

When the embedded web server has started, a ServletWebServerInitializedEvent will be published. This event contains information about the webserver.

Therefore, we can create an EventListener to get the port from this event:

@Service
public class ServerPortService {
    private int port;

    public int getPort() {
        return port;
    }

    @EventListener
    public void onApplicationEvent(final ServletWebServerInitializedEvent event) {
        port = event.getWebServer().getPort();
    }
}

We can inject the service component to our test class to get the random port quickly:

@Autowired
private ServerPortService serverPortService;

@Test
public void given0AsServerPort_whenReadFromListener_thenGetThePort() {
    int port = serverPortService.getPort();
 
    assertTrue(port > 1023);
}

5. Conclusion

Usually, we configure the server port of a Spring Boot application in a properties file or YAML file, where we can set either a fixed or random port.

In this article, we’ve discussed different approaches to obtain the fixed and random port at runtime.