1. Overview

Java plays a pivotal role in modern software development, empowering many applications and systems. To harness the power of Java on our machine, we need to install the Java Development Kit (JDK). While Oracle JDK is a popular choice, OpenJDK offers an open-source alternative with similar functionality.

In this article, we’ll explore various approaches to installing OpenJDK on a Windows environment, catering to different preferences and requirements.

2. Manual Installation

This method involves downloading the OpenJDK distribution directly from the official website or trusted repositories such as AdoptOpenJDK.

Once downloaded, extract the archive’s contents to a preferred location on our machine. It’s essential to configure environment variables such as PATH and JAVA_HOME to point to the directory where OpenJDK is installed. Let’s proceed by accessing the control panel and navigating to System settings:

Selecting the Advanced system settings will prompt a dialog box to appear:

Let’s see the system and user variables now by clicking on Environment Variables. Here, we’ll modify the PATH variable and include the JAVA_HOME variable. The JAVA_HOME variable should indicate the installation directory of OpenJDK, while the PATH variable should direct to the bin directory of the JDK.

In our case, JAVA_HOME will be C:\Program Files\Java\jdk-21.0.2 and PATH will be C:\Program Files\Java\jdk-21.0.2\bin

Finally, we can confirm the installation’s success by running the following command in the command prompt:

> java -version

After running the command above, a similar output will be displayed in the command prompt:

3. Chocolatey Package Manager

Chocolatey is a popular package manager for Windows that simplifies the installation and management of software packages. It provides a command-line interface (CLI) that allows users to search for, install, and uninstall software packages with ease, similar to package managers like apt on Ubuntu or Homebrew on macOS.

We need to first install Chocolatey on our machine before proceeding. Let’s open an elevated command and run the following command:

> Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Once Chocolatey is installed, we can move forward with installing OpenJDK using it. Running the below command will install Java:

> choco install openjdk

4. Scoop Package Manager

Similar to Chocolatey, Scoop is another package manager designed specifically for Windows. Scoop is geared towards individual users rather than system-wide installations. It installs packages in the user’s home directory, which doesn’t require administrative privileges.

To get started with Scoop, we must first install it:

> <span class="token">Set-ExecutionPolicy</span> <span class="token">-</span>ExecutionPolicy RemoteSigned <span class="token">-</span>Scope CurrentUser
> <span class="token">Invoke-RestMethod</span> <span class="token">-</span>Uri https:<span class="token">/</span><span class="token">/</span>get<span class="token">.</span>scoop<span class="token">.</span>sh <span class="token">|</span> <span class="token">Invoke-Expression</span>

Now, to install OpenJDK using Scoop, we need to open PowerShell as an administrator and execute the following commands:

> scoop bucket add java
> scoop install openjdk

5. Using Third-Party Installers

Some third-party tools and utilities offer simplified installation procedures for OpenJDK on Windows. For instance, tools like SDKMAN! and WinGet provide an easy-to-use interface for managing software installations, including OpenJDK.

We can explore these options if we prefer a more streamlined installation process with additional features and customization options.

6. Conclusion

In this article, we explored different ways to install OpenJDK on our Windows machine. We can either opt for manual installation, package managers like Chocolatey or Scoop, or third-party installers, each method offers its advantages in simplicity, customization, and automation.

We can choose the approach that best fits our preferences and workflow.

       

1. Overview

In this tutorial, we’ll implement the OAuth2 Backend for Frontend (BFF) pattern with Spring Cloud Gateway and spring-addons.

If we inspect any of the major websites known for using OAuth2 (Google, Facebook, Github, LinkedIn, etc.) we won’t find Bearer headers with tokens. Why that?

According to security experts, we should not configure single-page applications (Angular, React, Vue, etc.) or mobile applications as “public” OAuth2 clients anymore. The best alternative is probably to authorize both mobile and web apps with sessions on a BFF running on a server we trust.

As a reminder, JSON Web Tokens (JWTs) can’t be invalidated and we can hardly delete it on end-users devices when terminating sessions on the server. If we send JWTs over the network, all we can do is waiting for it to expire, access to resource servers still being authorized until then. But if tokens never leave the backend, then we can delete it with the user session on the BFF, immediately revoking access to resources.

The good news is that we can connect a Single Page Applications (SPAs) to an OAuth2 BFF in a few simple steps. Even better, we have no modification at all to apply to resource servers (REST APIs authorized with Bearer access tokens).

In this tutorial, we’ll use:

• Spring Cloud Gateway as OAuth2 BFF: “confidential” OAuth2 client with TokenRelay filter
• a Spring Boot REST API configured as a stateless OAuth2 resource server
• 3 frontends written with Angular, React (Next.js) and Vue (Vite)
• Keycloak as main OpenID Provider (OP), but the companion repo also contains Spring profiles to easily get started with Auth0 and Amazon Cognito.
• a reverse proxy to have the same origin for at least the SPAs and the BFF
• spring-addons-starter-oidc, an open-source Spring Boot starter, to further simplify OAuth2 configuration in Spring Boot applications

2. OAuth2 Backend for Frontend Pattern

The Backend for Frontend pattern is an architecture with a middleware between a frontend and REST APIs. When OAuth2 is involved, requests are authorized with:

• session cookie and CSRF protection between the frontend and the BFF
• access token between the BFF and REST API (and between backend services)

Such an OAuth2 BFF is responsible for:

• driving the authorization-code flow using a “confidential” OAuth2 client
• storing tokens in session
• replacing the session cookie with the access token in session before forwarding a request from the frontend to a resource server

The OAuth2 BFF pattern is safer than configuring a single-page or mobile application as a “public” OAuth2 client because:

• the BFF running on a server we trust, it can keep a secret to call the authorization server token endpoint
• we can set firewall rules to allow only requests from our backend to access the token endpoint
• tokens are kept on the server (sessions). Usage of session cookies requires protection against CSRF, but cookies can be flagged with HttpOnly, Secure and SameSite, which is safer than exposing tokens to the code running on end-user devices.

As BFF, we’ll use Spring Cloud Gateway with:

• spring-boot-starter-oauth2-client and oauth2Login() to handle the authorization-code flow and store tokens in the session
• the TokenRelay= filter to replace the session cookie with the access token in the session when forwarding requests from the frontend to a resource server

3. Architecture

So far, we listed quite a few services: frontends (SPAs), REST API, BFF, authorization server, and reverse proxy. Let’s have a look at how it makes a coherent system.

3.1. System Overview

Here is a representation of services, ports, and path-prefixes we’ll use with the main profile:

A few points to note from this schema are:

• from the perspective of the end-user device, there is a single point of contact with the backend: the reverse proxy
• we expose three different single-page applications to demo the integration with each of the major frameworks (Angular, React, and Vue)
• the reverse-proxy uses a path prefix to route requests to the right service

The reasons why the only link to the authorization server is from the reverse-proxy are:

• when configuring Keycloak in section 4 we’ll set the hostname-url property with a value pointing to the reverse proxy, with /auth as path-prefix. This influences the value of tokens issuer claim, but also of all endpoint URIs in the OpenID configuration (authorization, token, endsession, …).
• the reverse proxy is configured to route to Keycloak all requests with a path starting with /auth

Note that in the companion project, the profiles for Auth0 and Amazon Cognito are configured differently: no route to the authorization server on the reverse proxy and issuer as well as endpoint URIs are kept with their defaults on the authorization servers. This leads to this slightly different alternative architecture:

Using path-prefix to make a distinction between SPAs is nice when working on a single dev machine, but when going to a production-like environment, we might as well configure the reverse-proxy to use (sub)domains for routing, or even use a distinct reverse-proxy for each frontend.

3.2. Reverse Proxy

We need the same origin for a SPA and its BFF because:

• the requests are authorized with session cookies between the frontend and the BFF
• Spring session cookies are flagged with SameSite=Lax

For that, we’ll use a reverse proxy as a single contact point for browsers. It will route requests to the right service using path-prefix.

In the companion repo, we use a very basic Spring Cloud Gateway instance with just some routing (no security, no other filter than a StripPrefix=1 on the route to the BFF), but there are plenty of other options to achieve the same goal, some being more adapted to specific environments: nginx container in Docker, ingress on K8s, etc.

3.3. Whether to Hide the Authorization Server Behind the Reverse Proxy

For security reasons, an authorization server should always set the X-Frame-Options header. As Keycloak allows to set it to SAMEORIGIN, if the authorization server and the SPA share the same origin, then it’s possible to display Keycloak login & registration forms in an iframe embedded in this SPA.

From the end-user perspective, it’s probably a better experience to stay in the same web app with authorization forms displayed in a modal, rather than being redirected back and forth between the SPA and an authorization server.

On the other hand, Single Sign-On (SSO) relies on cookies flagged with SameOrigin. As a consequence, for two SPAs to benefit from Single Sign-On they should not only authenticate users on the same authorization server but also use the same authority for it (both https://appa.net and https://appy.net authenticate users on https://sso.net).

A solution to match both conditions is using the same origin for all SPAs and the authorization server, with URIs like:

• https://domain.net/appa
• https://domain.net/appy
• https://domain.net/auth

This is the option we’ll use when working with Keycloak, but sharing the same origin between the SPAs and the authorization server isn’t a requirement for the BFF pattern to work, only sharing the same origin between the SPAs and the BFF is.

The projects in the companion repo are preconfigured to use Amazon Cognito and Auth0 with their origin (no smart proxy rewriting redirection URLs on the fly). For this reason, login from an iframe is available only when using the default profile (with Keycloak).

3.4. Implementation

First, using our IDE or https://start.spring.io/, we create a new Spring Boot project named reverse-proxy with Reactive Gateway as a dependency.

Then we rename src/main/resources/application.properties to src/main/resources/application.yml.

We should then define the routing properties for Spring Cloud Gateway:

# Custom properties to ease configuration overrides
# on command-line or IDE launch configurations
scheme: http
hostname: localhost
reverse-proxy-port: 7080
angular-port: 4201
angular-prefix: /angular-ui
angular-uri: http://${hostname}:${angular-port}${angular-prefix}
vue-port: 4202
vue-prefix: /vue-ui
vue-uri: http://${hostname}:${vue-port}${vue-prefix}
react-port: 4203
react-prefix: /react-ui
react-uri: http://${hostname}:${react-port}${react-prefix}
authorization-server-port: 8080
authorization-server-prefix: /auth
authorization-server-uri: ${scheme}://${hostname}:${authorization-server-port}${authorization-server-prefix}
bff-port: 7081
bff-prefix: /bff
bff-uri: ${scheme}://${hostname}:${bff-port}
server:
  port: ${reverse-proxy-port}
spring:
  cloud:
    gateway:
      default-filters:
      - DedupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin
      routes:
      # SPAs assets
      - id: angular-ui
        uri: ${angular-uri}
        predicates:
        - Path=${angular-prefix}/**
      - id: vue-ui
        uri: ${vue-uri}
        predicates:
        - Path=${vue-prefix}/**
      - id: react-ui
        uri: ${react-uri}
        predicates:
        - Path=${react-prefix}/**
      
      # Authorization-server
      - id: authorization-server
        uri: ${authorization-server-uri}
        predicates:
        - Path=${authorization-server-prefix}/**
      
      # BFF
      - id: bff
        uri: ${bff-uri}
        predicates:
        - Path=${bff-prefix}/**
        filters:
        - StripPrefix=1

With this configuration added, we can start our reverse-proxy!

4. Authorization Server

In the companion project on GitHub the default profile is designed for Keycloak but, thanks to spring-addons-starter-oidc, switching to any other OpenID Provider is just a matter of editing application.yml. The files provided in the companion project contain profiles to get started easily with Auth0 and Amazon Cognito.

4.1. Keycloak in Docker

The companion repo contains a docker compose file. To use it, all we need to do is:

• edit the .env file to change the KEYCLOAK_ADMIN_PASSWORD
• run “docker compose -f docker-compose.yaml up” from the keycloak directory

4.2. Standalone Keycloak

We could also download a distribution powered by Quarkus from the Keycloak website.

First, we’d need to edit keycloak.conf to add something like the following:

hostname-url=http://localhost:7080/auth
hostname-admin-url=http://localhost:7080/auth
http-relative-path=/auth
http-port=8080

Then we should:

• check that the reverse proxy is running
• start Keycloak with either “bin\kc.bat start-dev” or “bash ./bin/kc.sh start-dev”
• visit http://localhost:7080/auth/ to set the admin password

4.3. Realm and Test User

To sandbox the labs in a Keycloak realm, we’ll:

1. click the dropdown in the top left corner displaying master
2. click the Create Realm button
3. input baeldung as Realm name

Then, we’ll create a user:

1. click on Users from the left menu
2. click the Add user button
3. fill the form
4. click the Create button
5. switch to Credentials tab
6. click the Set password button

4.3. Confidential Client With Authorization-Code

By browsing http://localhost:7080/auth/admin/master/console/#/baeldung/clients, we can create a baeldung-confidential client:

Client authentication is turned on to specify we want a “confidential” client and only Standard flow is selected because we’ll only use authorization-code.

We should have as a very minimum:

• http://localhost:7080/bff/login/oauth2/code/baeldung as redirect URI
• http://localhost:7080/* as post logout URI
• + as web origin (allows origins configured in redirect and post logout URIs)

When debugging from other devices (like mobile devices or emulators), we should add more network interfaces for our dev machine than just localhost (and adapt hostname-url as well as hostname-admin-url in the Keycloak configuration).

4.4. Working With Other OpenID Providers

Each OpenID Provider has its way of declaring “confidential” OAuth2 clients, therefore we should refer to its documentation for details, but all have similar configuration parameters.

For instance, on Auth0, we’d create a new Regular Web Application named baeldung-confidential and its Settings tab would expect the same values as those visible in the second Keycloak screenshot from the preceding section. It would also be the place to collect client-id and client-secret. Last, we’d create an API with bff.baeldung.com as an identifier and with baeldung-confidential enabled in the Machine To Machine Applications tab.

5. BFF Implementation With Spring Cloud Gateway and spring-addons-starter-oidc

First, using our IDE or https://start.spring.io/, we create a new Spring Boot project named bff with Reactive Gateway and OAuth2 client as dependencies.

Then we rename src/main/resources/application.properties to src/main/resources/application.yml.

Last, we’ll add spring-addons-starter-oidc to our dependencies:

<dependency>
    <groupId>com.c4-soft.springaddons</groupId>
    <artifactId>spring-addons-starter-oidc</artifactId>
    <version>7.5.3</version>
</dependency>

5.1. Re-Used Properties

Let’s start with a few constants in application.yml that will help us in other sections and when needing to override some values on the command line or IDE launch configuration:

scheme: http
hostname: localhost
reverse-proxy-port: 7080
reverse-proxy-uri: ${scheme}://${hostname}:${reverse-proxy-port}
authorization-server-prefix: /auth
issuer: ${reverse-proxy-uri}${authorization-server-prefix}/realms/baeldung
client-id: baeldung-confidential
client-secret: change-me
username-claim-json-path: $.preferred_username
authorities-json-path: $.realm_access.roles
bff-port: 7081
bff-prefix: /bff
resource-server-port: 7084
audience: 

Of course, we’ll have to override the value of client-secret with, for instance, an environment variable, a command line argument, or an IDE launch configuration.

5.2. Server Properties

Now come the usual server properties:

server:
  port: ${bff-port}

5.3. Spring Cloud Gateway Routing

As we have a single resource server behind the gateway, we need only one route definition:

spring:
  cloud:
    gateway:
      routes:
      - id: bff
        uri: ${scheme}://${hostname}:${resource-server-port}
        predicates:
        - Path=/api/**
        filters:
        - DedupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin
        - TokenRelay=
        - SaveSession
        - StripPrefix=1

The most important parts are the SaveSession and TokenRelay= which form a cornerstone for the OAuth2 BFF pattern implementation: the first ensures that the session is persisted (with the tokens fetched by oauth2Login()) and the second replaces the session cookie with the access token in session when routing a request.

The StripPrefix=1 filter removes /api prefix from the path when routing a request. Notably, the /bff prefix was already stripped during the reverse-proxy routing. As a consequence, a request sent from the frontend to /bff/api/me lands as /me on the resource server.

5.4. Spring Security

We can now get into configuring OAuth2 client security with the standard Boot properties:

spring:
  security:
    oauth2:
      client:
        provider:
          baeldung:
            issuer-uri: ${issuer}
        registration:
          baeldung:
            provider: baeldung
            authorization-grant-type: authorization_code
            client-id: ${client-id}
            client-secret: ${client-secret}
            scope: openid,profile,email,offline_access

Really nothing special here, just a very standard authorization-code registration with the required provider.

5.5. spring-addons-starter-oidc

To complete the configuration, let’s tune the security with spring-addons-starter-oidc:

com:
  c4-soft:
    springaddons:
      oidc:
        # Trusted OpenID Providers configuration (with authorities mapping)
        ops:
        - iss: ${issuer}
          authorities:
          - path: ${authorities-json-path}
          aud: ${audience}
        # SecurityFilterChain with oauth2Login() (sessions and CSRF protection enabled)
        client:
          client-uri: ${reverse-proxy-uri}${bff-prefix}
          security-matchers:
          - /api/**
          - /login/**
          - /oauth2/**
          - /logout
          permit-all:
          - /api/**
          - /login/**
          - /oauth2/**
          csrf: cookie-accessible-from-js
          oauth2-redirections:
            rp-initiated-logout: ACCEPTED
        # SecurityFilterChain with oauth2ResourceServer() (sessions and CSRF protection disabled)
        resourceserver:
          permit-all:
          - /login-options
          - /error
          - /actuator/health/readiness
          - /actuator/health/liveness

Let’s understand the three main sections:

• ops, with provider(s) specific values. This enables us to specify the JSON path of the claims to convert to Spring authorities (with optional prefixes and case transformation for each). If aud property is not empty, spring-addons adds an audience validator to the JWT decoders.
• client, when security-matchers are not empty, this section triggers the creation of a SecurityFilterChain bean with oauth2Login(). Here, with client-uri property, we force the usage of the reverse-proxy URI as a base for all redirections (instead of the BFF internal URI). Also, as we are using SPAs, we ask the BFF to expose the CSRF token in a cookie accessible to Javascript. Last, to prevent CORS errors, we ask that the BFF respond to the RP-Initiated Logout with 201 status (instead of 3xx), which gives SPAs the ability to intercept this response and ask the browser to process it in a request with a new origin.
• resourceserver, this requests for a second SecurityFilterChain bean with oauth2ResourceServer(). This filter chain having an @Order with the lowest precedence will process all of the requests that weren’t matched by the security matchers from the client SecurityFilterChain. We use it for all resources for which a session is not desirable: endpoints that aren’t involved in login or routing with TokenRelay.

We can now run the BFF application, carefully providing the client-secret on the command line or run configuration.

5.6. /login-options Endpoint

The BFF is the place where we define login configuration: Spring OAuth2 client registration(s) with authorization code. To avoid configuration duplication in each SPA (and possible inconsistencies), we’ll host on the BFF a REST endpoint exposing the login option(s) it supports for users.

For that, all we have to do is expose a @RestController with a single endpoint returning a payload built from configuration properties:

@RestController
public class LoginOptionsController {
    private final List<LoginOptionDto> loginOptions;
    public LoginOptionsController(OAuth2ClientProperties clientProps, SpringAddonsOidcProperties addonsProperties) {
        final var clientAuthority = addonsProperties.getClient()
          .getClientUri()
          .getAuthority();
        this.loginOptions = clientProps.getRegistration()
          .entrySet()
          .stream()
          .filter(e -> "authorization_code".equals(e.getValue().getAuthorizationGrantType()))
          .map(e -> {
              final var label = e.getValue().getProvider();
              final var loginUri = "%s/oauth2/authorization/%s".formatted(addonsProperties.getClient().getClientUri(), e.getKey());
              final var providerId = clientProps.getRegistration()
                .get(e.getKey())
                .getProvider();
              final var providerIssuerAuthority = URI.create(clientProps.getProvider()
                .get(providerId)
                .getIssuerUri())
                .getAuthority();
              return new LoginOptionDto(label, loginUri, Objects.equals(clientAuthority, providerIssuerAuthority));
          })
          .toList();
    }
    @GetMapping(path = "/login-options", produces = MediaType.APPLICATION_JSON_VALUE)
    public Mono<List<LoginOptionDto>> getLoginOptions() throws URISyntaxException {
        return Mono.just(this.loginOptions);
    }
    public static record LoginOptionDto(@NotEmpty String label, @NotEmpty String loginUri, boolean isSameAuthority) {
    }
}

5.7. Non-Standard RP-Initiated Logout

RP-Initiated Logout is part of the OpenID standard, but some providers don’t implement it strictly. This is the case of Auth0 and Amazon Cognito for instance which don’t provide an end_session endpoint in their OpenID configuration and use some non-standard query parameters for logout.

spring-addons-starter-oidc supports such logout endpoints “almost” complying with the standard. The BFF configuration in the companion project contains profiles with the required configuration:

---
spring:
  config:
    activate:
      on-profile: cognito
issuer: https://cognito-idp.us-west-2.amazonaws.com/us-west-2_RzhmgLwjl
client-id: 12olioff63qklfe9nio746es9f
client-secret: change-me
username-claim-json-path: username
authorities-json-path: $.cognito:groups
com:
  c4-soft:
    springaddons:
      oidc:
        client:
          oauth2-logout:
            baeldung:
              uri: https://spring-addons.auth.us-west-2.amazoncognito.com/logout
              client-id-request-param: client_id
              post-logout-uri-request-param: logout_uri
---
spring:
  config:
    activate:
      on-profile: auth0
issuer: https://dev-ch4mpy.eu.auth0.com/
client-id: yWgZDRJLAksXta8BoudYfkF5kus2zv2Q
client-secret: change-me
username-claim-json-path: $['https://c4-soft.com/user']['name']
authorities-json-path: $['https://c4-soft.com/user']['roles']
audience: bff.baeldung.com
com:
  c4-soft:
    springaddons:
      oidc:
        client:
          authorization-request-params:
            baeldung:
            - name: audience
              value: ${audience}
          oauth2-logout:
            baeldung:
              uri: ${issuer}v2/logout
              client-id-request-param: client_id
              post-logout-uri-request-param: returnTo

In the snippet above, baeldung is a reference to the client registration in Spring Boot properties. If we used another key in spring.security.oauth2.client.registration, we’d have to use it here too.

In addition to the required properties overrides, we can note in the second profile, the specification for an additional request parameter when we send an authorization request to Auth0: audience.

6. Resource Server With spring-addons-starter-oidc

Our need for this system is very simple: a stateless REST API authorized with JWT access tokens, exposing a single endpoint to reflect some user info contained in the token (or a payload with empty values if the request isn’t authorized).

For this, we’ll create a new Spring Boot project named resource-server with Spring Web and OAuth2 Resource Server as dependencies.

Then we rename src/main/resources/application.properties to src/main/resources/application.yml.

Last, we’ll add spring-addons-starter-oidc to our dependencies:

<dependency>
    <groupId>com.c4-soft.springaddons</groupId>
    <artifactId>spring-addons-starter-oidc</artifactId>
    <version>7.5.3</version>
</dependency>

6.1. Configuration

Here are the properties we need for our resource server:

scheme: http
hostname: localhost
reverse-proxy-port: 7080
reverse-proxy-uri: ${scheme}://${hostname}:${reverse-proxy-port}
authorization-server-prefix: /auth
issuer: ${reverse-proxy-uri}${authorization-server-prefix}/realms/baeldung
username-claim-json-path: $.preferred_username
authorities-json-path: $.realm_access.roles
resource-server-port: 7084
audience: 
server:
  port: ${resource-server-port}
com:
  c4-soft:
    springaddons:
      oidc:
        ops:
        - iss: ${issuer}
          username-claim: ${username-claim-json-path}
          authorities:
          - path: ${authorities-json-path}
          aud: ${audience}
        resourceserver:
          permit-all:
          - /me
          - /actuator/health/readiness
          - /actuator/health/liveness

Thanks to spring-addons-starter-oidc, this is enough to declare a stateless resource server with:

• authorities mapping from a claim of our choice (realm_access.roles in the case of Keycloak with realm roles)
• making /me accessible to anonymous requests

The application.yaml  in the companion repo contains profiles for other OpenID Providers using other private claims for roles.

6.2. @RestController

Let’s implement a REST endpoint returning some data from the Authentication in the security context (if any):

@RestController
public class MeController {
    @GetMapping("/me")
    public UserInfoDto getMe(Authentication auth) {
        if (auth instanceof JwtAuthenticationToken jwtAuth) {
            final var email = (String) jwtAuth.getTokenAttributes()
                .getOrDefault(StandardClaimNames.EMAIL, "");
            final var roles = auth.getAuthorities()
                .stream()
                .map(GrantedAuthority::getAuthority)
                .toList();
            final var exp = Optional.ofNullable(jwtAuth.getTokenAttributes()
                .get(JwtClaimNames.EXP)).map(expClaim -> {
                    if(expClaim instanceof Long lexp) {
                        return lexp;
                    }
                    if(expClaim instanceof Instant iexp) {
                        return iexp.getEpochSecond();
                    }
                    if(expClaim instanceof Date dexp) {
                        return dexp.toInstant().getEpochSecond();
                    }
                    return Long.MAX_VALUE;
                }).orElse(Long.MAX_VALUE);
            return new UserInfoDto(auth.getName(), email, roles, exp);
        }
        return UserInfoDto.ANONYMOUS;
    }
    /**
     * @param username a unique identifier for the resource owner in the token (sub claim by default)
     * @param email OpenID email claim
     * @param roles Spring authorities resolved for the authentication in the security context
     * @param exp seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time when the access token expires
     */
    public static record UserInfoDto(String username, String email, List<String> roles, Long exp) {
        public static final UserInfoDto ANONYMOUS = new UserInfoDto("", "", List.of(), Long.MAX_VALUE);
    }
}

6.3. Resource Server Multi-Tenancy

What if the frontends consuming our REST API don’t all authorize their users on the same authorization server or realm (or if they offer a choice of authorization servers)?

With spring-security-starter-oidc, this is dead simple: com.c4-soft.springaddons.oidc.ops configuration property is an array and we can add as many issuers as we trust, each with its mapping for user name and authorities. A valid token issued by any of these issuers will be accepted by our resource server and roles correctly mapped to Spring authorities.

7. SPAs

Because there are some differences between the frameworks used to connect SPAs to an OAuth2  BFF, we’ll cover the three major ones: Angular, React, and Vue.

But, creating SPAs is out of the scope of this article. Hereafter, we’ll focus only on what it takes for a web application to log users in & out on an OAuth2 BFF and query a REST API behind it. Please refer to the companion repo for complete implementations.

An effort was made for the apps to have the same structure:

• two routes to demo how the current one can be restored after authentication
• a Login component offers a choice of login experience if both iframe and default are available. It also handles iframe display status or redirection to the authorization server.
• a Logout component sends a POST request to the BFF /logout endpoint and then redirects to the authorization server for RP-Initiated Logout
• a UserService fetches current user data from the resource server through the BFF. It also holds some logic for scheduling a refresh of this data just before the access token on the BFF expires.

There is however a difference in the way the current user data is managed because of the very different way frameworks handle state:

• in an Angular app, the UserService is a singleton managing current user with a BehaviorSubject
• in a React app, we used createContext in app/layout.tsx to expose the current user to all components,  and useContext wherever we need to access it
• in a Vue app, the UserService is a singleton (instantiated in main.ts) managing the current user with a ref

7.1. Running SPAs in Companion Repo

The first thing to do is to cd in the folder of the project we want to run.

Then, we should run “npm install” to pull all required npm packages.

Lastly, depending on the framework:

• Angular: run “npm run start” and open http://localhost:7080/angular-ui/
• Vue: run “npm run serve” and open http://localhost:7080/vue-ui/
• React (Next.js): run “npm run dev” and open http://localhost:7080/react-ui/

We should be careful to use only URLs pointing to the reverse proxy and not to the SPAs dev-servers (http://localhost:7080, not http://localhost:4201, http://localhost:4202 and http://localhost:4203).

7.2. User Service

The responsibility for the UserService is to:

• define the user representations (internal and DTO)
• expose a function to fetch user data from the resource server through the BFF
• schedule a refresh() call just before the access token expires (keep the session alive)

7.3. Login

As we already saw, when possible, we provide two different login experiences:

• the user is redirected to the authorization server using the current browser tab (the SPA temporarily “exits”). This is the default behavior and is always available.
• authorization server forms are displayed in an iframe inside the SPA, which requires SameOrigin for the SPA and the authorization server and, as so, works only when the BFF and resource server run with the default profile (with Keycloak)

The logic is implemented by a Login component which displays a drop-down to select the login experience (iframe or default) and a button.

Login options are fetched from the BFF when the component is initialized. In the case of this tutorial, we expect only one option, so we pick only the 1st entry in the response payload.

When the user clicks the Login button, what happens depends on the chosen login experience:

• if iframe is selected, the iframe source is set to the login URI, and the modal div containing the iframe displayed
• otherwise, the window.location.href is set to the login URI, which “exits” the SPA and sets the current tab with a brand-new origin

When the user selects the iframe login experience, we register an event listener for the iframe load events to check if the user authentication is successful and hide the modal. This call-back runs each time a redirection happens in the iframe.

Last, we can note how the SPAs add a post_login_success_uri request parameter to the authorization-code flow initiation request. spring-addons-starter-oidc saves the value of this parameter in session and, after the authorization code is exchanged for tokens, uses it to build the redirection URI returned to the frontend.

7.4. Logout

The logout button and associated logic are handled by the Logout component.

By default, Spring /logout endpoint expects a POST request and, as any request modifying state on a server with sessions, it should contain a CSRF token. Angular and React handle transparently CSRF cookies flagged with http-only=false and request headers, but we have to manually read the XSRF-TOKEN cookie and set the X-XSRF-TOKEN header in Vue for every POST, PUT, PATCH and DELETE requests.

When involving a Spring OAuth2 client, the RP-Initiated Logout happens in two requests:

• first, a POST request is sent to the Spring OAuth2 client which closes its own session
• the response of the 1st request has a Location header with a URI on the authorization server to close the other session that the user has there

The default Spring behavior is to use 302 status for the 1st request, which makes the browser follow automatically to the authorization server, but keeping the same origin. To avoid CORS errors, we configured the BFF to use a status in the 2xx field. This requires the SPA to manually follow the redirection but gives it the opportunity to do it with window.location.href (request having a new origin).

Last, we can note how the post-logout URI is provided by SPAs using a X-POST-LOGOUT-SUCCESS-URI header with the logout request. spring-addons-starter-oidc uses the value of this header to insert a request parameter in the URI of the logout request from the authorization server.

7.5. Client Multi-Tenancy

In the companion project, there is a single OAuth2 client registration with an authorization code. But what if we had more? This might happen for instance if we share a BFF across several frontends, some having distinct issuer or scope.

The user should be prompted to choose only between OpenID Providers he can authenticate on, and in many cases, we can filter the login options.

Here are a few samples of situations where we can drastically shrink the number of possible choices, ideally to one so that the user isn’t prompted for a choice:

• the SPA is configured with a specific option to use
• there are several reverse-proxies and each can set something like a header with the option to use
• some technical info, like the IP of the frontend device, can tell us that a user should be authorized here or there

In such situations, we have two choices:

• send the filtering criteria with the request to /login-options and filter in the BFF controller
• filter /login-options response inside the frontend

8. Back-Channel Logout

What if, in a SSO configuration, a user with an opened session on our BFF logs-out using another OAuth2 client?

In OIDC, the Back-Channel Logout specification was made for such scenarios: when declaring a client on an authorization server, we can register an URL to be called when a user logs-out.

Because the BFF runs on a server, it can expose an endpoint to be notified with such log-out events. Since version 6.2, Spring Security supports Back-Channel Logout and spring-addons-starter-oidc exposes a flag to enable it.

Once the session ended on the BFF with Back-Channel Logout, the requests from the frontend to the resource server(s) won’t be authorized anymore (even before tokens expiration). So for a perfect user experience, when activating Back-Channel Logout on a BFF, we should probably also add a mechanism like WebSockets to notify frontends with user status changes.

9. Why Using spring-addons-starter-oidc?

All along this article, we modified quite a few default behaviors of both spring-boot-starter-oauth2-client and spring-boot-starter-oauth2-resource-server:

• change OAuth2 redirect URIs to point to a reverse-proxy instead of the internal OAuth2 client
• give SPAs the control of where the user is redirected after login / logout
• expose CSRF token in a cookie accessible to Javascript code running in a browser
• adapt to not exactly standard RP-Initiated Logout (Auth0 and Amazon Cognito for instance)
• add optional parameters to the authorization request (Auth0 audience or whatever)
• change the HTTP status of OAuth2 redirections so that SPAs can choose how to follow to Location header
• register two distinct SecurityFilterChain beans with respectively oauth2Login() (with session-based security and CSRF protection) and oauth2ResourceServer() (stateless, with token-based security) to secure different groups of resources
• define which endpoints are accessible to anonymous
• on resource servers, accept tokens issued by more than just one  OpenID Provider
• add an audience validator to JWT decoder(s)
• map authorities from any claim(s) (and add prefix or force upper / lower case)

This usually requires quite some Java code and a deep knowledge of Spring Security. But here, we did it with just application properties and could use the guidance of our IDE auto-completion!

We should refer to the starter README on Github for a complete list of features, auto-configuration tuning and defaults overrides.

10. Conclusion

In this tutorial, we saw how to implement the OAuth2 Backend for Frontend pattern with Spring Cloud Gateway and spring-addons.

We also saw:

• why we should favor this solution over configuring SPAs as “public” OAuth2 clients
• introducing a BFF has very little impact on the SPA itself
• this pattern changes nothing at all on resource servers
• because we use a server-side OAuth2 client, we can get complete control on user session, even in SSO configurations, thanks to Back-Channel Logout

Last, we started to explore how convenient spring-addons-starter-oidc can be to configure, with just properties, what usually requires quite some Java configuration.

As usual, all the code implementations are available over on GitHub.

       

1. Overview

Starting in Java 18 we’ve access to the Simple Web Server, which was introduced in JEP 408.  We can access its functionality through a command line tool and an API.

The Simple Web Server offers a bare-bones web server that serves static files. It’s described as being useful for testing, prototyping, and education. The server is intentionally very simple to set up and run and doesn’t aim to compete with or replace more fully functional options such as Apache Tomcat or Jetty.

One of the goals of introducing the tool is to get developers up and running with web development with the fewest possible barriers.

In this tutorial, we’ll learn about Simple Web Server and how it works.

2. jwebserver Command-Line Tool

The first and easiest way to start up a server is to use the provided command-line tool.

2.1. Startup

The command we need here is jwebserver. Using the command jwebserver by itself is enough to start the server up.

We see this response if everything is working:

$ jwebserver         
Binding to loopback by default. For all interfaces use "-b 0.0.0.0" or "-b ::".
Serving /usr and subdirectories on 127.0.0.1 port 8000
URL http://127.0.0.1:8000/

By default, the directory we’re in when we run the command is the one served, so /usr, in the example above. However, we can change the directory with the -d flag:

$ jwebserver -d /opt
Binding to loopback by default. For all interfaces use "-b 0.0.0.0" or "-b ::".
Serving /opt and subdirectories on 127.0.0.1 port 8000
URL http://127.0.0.1:8000/

Notably, we have to provide an absolute path here.

We can also change the port and address with the -p and -b flags:

$ jwebserver -b 0.0.0.0 -p 3003    
Serving / and subdirectories on 0.0.0.0 (all interfaces) port 3003
URL http://192.168.1.1:3003/

Running the above configuration exposes our current directory to anyone on our network at the IP address given in the output. While this may be useful if we’re trying to transfer files we should be sure we’re happy to share them first.

2.2. GET Requests

We can access the web server using a browser to navigate to the correct address and port. Once we’re there we’ll see a list of files and subdirectories from within the directory from where we started the server:

If we then access any of these files we’ll see them in our browser and also a new line in our terminal:

127.0.0.1 - - [09/Feb/2024:12:06:26 +0000] "GET /file.txt HTTP/1.1" 200 -

Similarly, when entering a new subdirectory we’ll see the GET request logged with the directory we’re accessing:

127.0.0.1 - - [09/Feb/2024:12:06:52 +0000] "GET /subdirectory/ HTTP/1.1" 200 -

3. API

The second option for working with the Simple Web Server is the API. By using it, we can gain a lot more control and customize how requests are handled.

3.1. Defining a Server

To start let’s recreate our command-line web server using the API.

To do this we’ll use the class SimpleFileServer. We can use this class for three things – creating a HttpServer, creating a HttpHandler, and creating a HttpFilter.

First, we’ll just create and start a server using createFileServer():

public static void main(String[] args) {
    InetSocketAddress address = new InetSocketAddress(8080);
    Path path = Path.of("/");
    HttpServer server = SimpleFileServer.createFileServer(address, path, SimpleFileServer.OutputLevel.VERBOSE);
    server.start();
}

Here we’ve specified an address, using the InetSocketAddress class. We also could have changed the rest of the address here and not just the port.

We’ve then set up a Path object leading to the directory we want to serve.

Next, we’ve passed these in as arguments, along with the logging level, to createFileServer(). As before, we can configure any of these to meet our needs. The resulting web server is identical to the one created using the command line tool and can be accessed via our browser at 127.0.0.1:8080.

3.2. Handlers

Clearly, creating the server above didn’t offer any benefits over the command line tool. To start gaining some control, we’ll need to introduce a HttpHandler.

Let’s look at adding a custom one to our server. We can create a handler using another method from SimpleFileServer, createFileHandler(). Assuming we then already have a server like the one created earlier, we can attach our new handler to it:

HttpHandler handler = SimpleFileServer.createFileHandler(Path.of("/Users"));
server.createContext("/test", handler);

This results in all traffic to 127.0.0.1:8080/test going through our new handler.

We can use handlers to do much more than this. For example, let’s set up a server that simulates being allowed and denied access on different endpoints. We can use the method HttpHandlers.of() to create responses for both allowing and denying access:

HttpHandler allowedResponse = HttpHandlers.of(200, Headers.of("Allow", "GET"), "Welcome");
HttpHandler deniedResponse = HttpHandlers.of(401, Headers.of("Deny", "GET"), "Denied");

Next, we need a Predicate defined to decide when to return each response:

Predicate<Request> findAllowedPath = r -> r.getRequestURI()
  .getPath().equals("/test/allowed");

This returns true only when we try and access the URL /test/allowed. All other endpoints fail.

We can now use HttpHandlers.handleOrElse(), which takes our Predicate and both options. It performs the first if the Predicate passes, otherwise the second:

HttpHandler handler = HttpHandlers.handleOrElse(findAllowedPath, allowedResponse, deniedResponse);

Finally, we can set up our HttpServer as before using the new HttpHandler:

HttpServer server = SimpleFileServer.createFileServer(address, path, SimpleFileServer.OutputLevel.VERBOSE);
server.createContext("/test", handler);

The result is that navigating to http://127.0.0.1:8080/test/allowed shows the text ‘Welcome‘ with a 200 response. Navigating to any other path displays ‘Denied‘ with a 401 response. We can use this as needed to set up test environments. The potential complexity is quite low, however.

3.3. Filters

The final aspect of the SimpleFileServer class is the ability to create a Filter. The role of this Filter will be to handle log messages. By defining our own we can redirect our messages to an OutputStream of our choosing.

The creation of the server is different when applying a Filter. First, let’s create the Filter using createOutputFilter():

Filter filter = SimpleFileServer.createOutputFilter(System.out, SimpleFileServer.OutputLevel.INFO);

We’ve used System.out as a simple example of an OutputStream here, but we could have used a logger or anything else we wanted.

Next, we’ll use the create() method from the HttpServer class with the filter we just made:

HttpServer server = HttpServer.create(new InetSocketAddress(8080), 10, "/test", handler, filter);

There are a few arguments there, so let’s go through them. First, the address is in the form of an InetSocketAddress as before. Second, an integer specifies the socket backlog. This is the maximum number of TCP connections allowed to queue at once. Third, we have the context. Here we’ve specified we want to deal with traffic hitting 127.0.0.1:8080/test. The fourth argument is a HttpHandler, similar to the one we created earlier. Finally comes our Filter as the fifth argument.

This provides the same functionality as when we used a handler before. However, we now have complete control over the log output.

4. Conclusion

In this article, we’ve seen that we can quickly spin up Java 18’s Simple Web Server and that it provides a small amount of helpful functionality.

First, we saw that by using the command-line tool jwebserver we can have a server up and running in moments. This server provides read access to the files and subdirectories in the location we run it.

Following that, we looked at the API and the new classes available such as SimpleFileServer. Using this API we could achieve the same results as the command-line tool, but programmatically. We could also extend our control using HttpHandler and Filter.

As always, the full code for the examples is available over on GitHub.

       

1. Overview

Acknowledgment of messages is a standard mechanism within messaging systems, signaling to the message broker that the message has been received and should not be delivered again. In Amazon’s SQS (Simple Queue Service), acknowledgment is executed through the deletion of messages in the queue.

In this tutorial, we’ll explore the three acknowledgment modes Spring Cloud AWS SQS v3 provides out-of-the-box: ON_SUCCESS, MANUAL, and ALWAYS.

We’ll use an event-driven scenario to illustrate our use cases, leveraging the environment and test setup from the Spring Cloud AWS SQS V3 introductory article.

2. Dependencies

We’ll first import the Spring Cloud AWS Bill of Materials to ensure all dependencies in our pom.xml are compatible with each other:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.awspring.cloud</groupId>
            <artifactId>spring-cloud-aws</artifactId>
            <version>3.1.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

We’ll also add the Core and SQS starter dependencies:

<dependency>
    <groupId>io.awspring.cloud</groupId>
    <artifactId>spring-cloud-aws-starter-sqs</artifactId>
</dependency>
<dependency>
    <groupId>io.awspring.cloud</groupId>
    <artifactId>spring-cloud-aws-starter</artifactId>
</dependency>

Finally, we’ll add the dependencies required for our tests, namely LocalStack and TestContainers with JUnit 5, the awaitility library for verifying asynchronous message consumption, and AssertJ to handle the assertions:

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>localstack</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.awaitility</groupId>
    <artifactId>awaitility</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.assertj</groupId>
    <artifactId>assertj-core</artifactId>
    <scope>test</scope>
</dependency>

3. Setting up the Local Test Environment

First, we’ll configure a LocalStack environment with Testcontainers for local testing:

@Testcontainers
public class BaseSqsLiveTest {
    private static final String LOCAL_STACK_VERSION = "localstack/localstack:2.3.2";
    @Container
    static LocalStackContainer localStack = new LocalStackContainer(DockerImageName.parse(LOCAL_STACK_VERSION));
    @DynamicPropertySource
    static void overrideProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.cloud.aws.region.static", () -> localStack.getRegion());
        registry.add("spring.cloud.aws.credentials.access-key", () -> localStack.getAccessKey());
        registry.add("spring.cloud.aws.credentials.secret-key", () -> localStack.getSecretKey());
        registry.add("spring.cloud.aws.sqs.endpoint", () -> localStack.getEndpointOverride(SQS)
          .toString());
    }
}

Although this setup makes testing easy and repeatable, note that the code in this tutorial can also be used to target AWS directly.

4. Setting up the Queue Names

events:
  queues:
    order-processing-retry-queue: order_processing_retry_queue
    order-processing-async-queue: order_processing_async_queue
    order-processing-no-retries-queue: order_processing_no_retries_queue
  acknowledgment:
    order-processing-no-retries-queue: ALWAYS

product:
  id:
    smartphone: 123e4567-e89b-12d3-a456-426614174000
    wireless-headphones: 123e4567-e89b-12d3-a456-426614174001
    laptop: 123e4567-e89b-12d3-a456-426614174002
    tablet: 123e4567-e89b-12d3-a456-426614174004

@ConfigurationProperties(prefix = "events.queues")
public class EventsQueuesProperties {
    private String orderProcessingRetryQueue;
    private String orderProcessingAsyncQueue;
    private String orderProcessingNoRetriesQueue;
    // getters and setters
}

@ConfigurationProperties("product.id")
public class ProductIdProperties {
    private UUID smartphone;
    private UUID wirelessHeadphones;
    private UUID laptop;
    // getters and setters
}

@EnableConfigurationProperties({ EventsQueuesProperties.class, ProductIdProperties.class})
@Configuration
public class OrderProcessingConfiguration {
}

5. Acknowledgement on Successful Processing

@Service
public class OrderService {
    Map<UUID, OrderStatus> ORDER_STATUS_STORAGE = new ConcurrentHashMap<>();
    public void updateOrderStatus(UUID orderId, OrderStatus status) {
        ORDER_STATUS_STORAGE.put(orderId, status);
    }
    public OrderStatus getOrderStatus(UUID orderId) {
        return ORDER_STATUS_STORAGE.getOrDefault(orderId, OrderStatus.UNKNOWN);
    }
}

@Service
public class InventoryService implements InitializingBean {
    private ProductIdProperties productIdProperties;
    private Map<UUID, Integer> inventory;
    public InventoryService(ProductIdProperties productIdProperties) {
        this.productIdProperties = productIdProperties;
    }
    @Override
    public void afterPropertiesSet() {
        this.inventory = new ConcurrentHashMap<>(Map.of(productIdProperties.getSmartphone(), 10,
          productIdProperties.getWirelessHeadphones(), 15,
          productIdProperties.getLaptop(), 5);
    }
}

public void checkInventory(UUID productId, int quantity) {
    Integer stock = inventory.get(productId);
    if (stock < quantity) {
        inventory.put(productId, stock + (int) (Math.random() * 5));
        throw new OutOfStockException(
          "Product with id %s is out of stock. Quantity requested: %s ".formatted(productId, quantity));
    };
    inventory.put(productId, stock - quantity);
}

@Component
public class OrderProcessingListeners {
    private static final Logger logger = LoggerFactory.getLogger(OrderProcessingListeners.class);
    private InventoryService inventoryService;
    private OrderService orderService;
    public OrderProcessingListeners(InventoryService inventoryService, OrderService orderService) {
        this.inventoryService = inventoryService;
        this.orderService = orderService;
    }
}

@SqsListener(value = "${events.queues.order-processing-retry-queue}", id = "retry-order-processing-container", messageVisibilitySeconds = "1")
public void stockCheckRetry(OrderCreatedEvent orderCreatedEvent) {
    logger.info("Message received: {}", orderCreatedEvent);
    orderService.updateOrderStatus(orderCreatedEvent.id(), OrderStatus.PROCESSING);
    inventoryService.checkInventory(orderCreatedEvent.productId(), orderCreatedEvent.quantity());
    orderService.updateOrderStatus(orderCreatedEvent.id(), OrderStatus.PROCESSED);
    logger.info("Message processed successfully: {}", orderCreatedEvent);
}

@SpringBootTest
class OrderProcessingApplicationLiveTest extends BaseSqsLiveTest {
    private static final Logger logger = LoggerFactory.getLogger(OrderProcessingApplicationLiveTest.class);
    @Autowired
    private EventsQueuesProperties eventsQueuesProperties;
    @Autowired
    private ProductIdProperties productIdProperties;
    @Autowired
    private SqsTemplate sqsTemplate;
    @Autowired
    private OrderService orderService;
    @Autowired
    private MessageListenerContainerRegistry registry;
}

private void assertQueueIsEmpty(String queueName, String containerId) {
    logger.info("Stopping container {}", containerId);
    var container = Objects
      .requireNonNull(registry.getContainerById(containerId), () -> "could not find container " + containerId);
    container.stop();
    // ...
}

// ...
logger.info("Checking for messages in queue {}", queueName);
var message = sqsTemplate.receive(from -> from.queue(queueName)
  .pollTimeout(Duration.ofSeconds(5)));
assertThat(message).isEmpty();
logger.info("No messages found in queue {}", queueName);

@Test
public void givenOnSuccessAcknowledgementMode_whenProcessingThrows_shouldRetry() {
    var orderId = UUID.randomUUID();
    var queueName = eventsQueuesProperties.getOrderProcessingRetryQueue();
    sqsTemplate.send(queueName, new OrderCreatedEvent(orderId, productIdProperties.getLaptop(), 10));
    Awaitility.await()
      .atMost(Duration.ofMinutes(1))
      .until(() -> orderService.getOrderStatus(orderId)
        .equals(OrderStatus.PROCESSED));
    assertQueueIsEmpty(queueName, "retry-order-processing-container");
}

Message received: OrderCreatedEvent[id=83f27bf2-1bd4-460a-9006-d784ec7eff47, productId=123e4567-e89b-12d3-a456-426614174002, quantity=10]

Caused by: com.baeldung.spring.cloud.aws.sqs.acknowledgement.exception.OutOfStockException: Product with id 123e4567-e89b-12d3-a456-426614174002 is out of stock. Quantity requested: 10 

Message processed successfully: OrderCreatedEvent[id=83f27bf2-1bd4-460a-9006-d784ec7eff47, productId=123e4567-e89b-12d3-a456-426614174002, quantity=10]

INFO 2699 --- [main] a.s.a.OrderProcessingApplicationLiveTest : Stopping container retry-order-processing-container
INFO 2699 --- [main] a.c.s.l.AbstractMessageListenerContainer : Container retry-order-processing-container stopped
INFO 2699 --- [main] a.s.a.OrderProcessingApplicationLiveTest : Checking for messages in queue order_processing_retry_queue
INFO 2699 --- [main] a.s.a.OrderProcessingApplicationLiveTest : No messages found in queue order_processing_retry_queue

Note that “connection refused” errors might be thrown after the test completes — that’s because the Docker container stops before the framework can stop polling for messages. We can safely ignore these errors.

6. Manual Acknowledgement

The framework supports manual acknowledgment of messages, which is useful for scenarios where we need greater control over the acknowledgment process.

6.1. Creating the Listener

To illustrate this, we’ll create an asynchronous scenario where the InventoryService has a slow connection and we want to release the listener thread before it completes:

@SqsListener(value = "${events.queues.order-processing-async-queue}", acknowledgementMode = SqsListenerAcknowledgementMode.MANUAL, id = "async-order-processing-container", messageVisibilitySeconds = "3")
public void slowStockCheckAsynchronous(OrderCreatedEvent orderCreatedEvent, Acknowledgement acknowledgement) {
    orderService.updateOrderStatus(orderCreatedEvent.id(), OrderStatus.PROCESSING);
    CompletableFuture.runAsync(() -> inventoryService.slowCheckInventory(orderCreatedEvent.productId(), orderCreatedEvent.quantity()))
      .thenRun(() -> orderService.updateOrderStatus(orderCreatedEvent.id(), OrderStatus.PROCESSED))
      .thenCompose(voidFuture -> acknowledgement.acknowledgeAsync())
      .thenRun(() -> logger.info("Message for order {} acknowledged", orderCreatedEvent.id()));
    logger.info("Releasing processing thread.");
}

In this logic, we use Java’s CompletableFuture to run the inventory check asynchronously. We added the Acknowledge object to the listener method and SqsListenerAcknowledgementMode.MANUAL to the annotation’s acknowledgementMode property. This property is a String and accepts property placeholders and SpEL. The Acknowledgement object is only available when we set AcknowledgementMode to MANUAL.

Note that, in this example, we leverage Spring Boot auto-configuration, which provides sensible defaults, and the @SqsListener annotation properties to change between acknowledgment modes. An alternative would be declaring a SqsMessageListenerContainerFactory bean, which allows setting up more complex configurations.

6.2. Simulating a Slow Connection

Now, let’s add the slowCheckInventory method to the InventoryService class, simulating a slow connection using Thread.sleep:

public void slowCheckInventory(UUID productId, int quantity) {
    simulateBusyConnection();
    checkInventory(productId, quantity);
}
private void simulateBusyConnection() {
    try {
        Thread.sleep(2000);
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        throw new RuntimeException(e);
    }
}

6.3. Testing

Next, let’s write our test:

@Test
public void givenManualAcknowledgementMode_whenManuallyAcknowledge_shouldAcknowledge() {
    var orderId = UUID.randomUUID();
    var queueName = eventsQueuesProperties.getOrderProcessingAsyncQueue();
    sqsTemplate.send(queueName, new OrderCreatedEvent(orderId, productIdProperties.getSmartphone(), 1));
    Awaitility.await()
      .atMost(Duration.ofMinutes(1))
      .until(() -> orderService.getOrderStatus(orderId)
        .equals(OrderStatus.PROCESSED));
    assertQueueIsEmpty(queueName, "async-order-processing-container");
}

This time, we’re requesting a quantity available in the inventory, so we should see no errors thrown.

When running the test, we’ll see a log message indicating the message was received:

INFO 2786 --- [ing-container-1] c.b.s.c.a.s.a.l.OrderProcessingListeners : Message received: OrderCreatedEvent[id=013740a3-0a45-478a-b085-fbd634fbe66d, productId=123e4567-e89b-12d3-a456-426614174000, quantity=1]

Then, we’ll see the thread release message:

INFO 2786 --- [ing-container-1] c.b.s.c.a.s.a.l.OrderProcessingListeners : Releasing processing thread.

This is because we’re processing and acknowledging the message asynchronously. After about two seconds, we should see the log that the message has been acknowledged:

INFO 2786 --- [onPool-worker-1] c.b.s.c.a.s.a.l.OrderProcessingListeners : Message for order 013740a3-0a45-478a-b085-fbd634fbe66d acknowledged

Finally, we’ll see the logs for stopping the container and asserting that the queue is empty:

INFO 2786 --- [main] a.s.a.OrderProcessingApplicationLiveTest : Stopping container async-order-processing-container
INFO 2786 --- [main] a.c.s.l.AbstractMessageListenerContainer : Container async-order-processing-container stopped
INFO 2786 --- [main] a.s.a.OrderProcessingApplicationLiveTest : Checking for messages in queue order_processing_async_queue
INFO 2786 --- [main] a.s.a.OrderProcessingApplicationLiveTest : No messages found in queue order_processing_async_queue

7. Acknowledgement on Both Success and Error

The last acknowledgment mode we’ll explore is ALWAYS, which causes the framework to acknowledge the message regardless of whether the listener method throws an error.

7.1. Creating the Listener

Let’s simulate a sales event during which our inventory is limited and we don’t want to reprocess any messages, regardless of any failures. We’ll set the acknowledgment mode to ALWAYS using the property we defined earlier in our application.yml:

@SqsListener(value = "${events.queues.order-processing-no-retries-queue}", acknowledgementMode = ${events.acknowledgment.order-processing-no-retries-queue}, id = "no-retries-order-processing-container", messageVisibilitySeconds = "3")
public void stockCheckNoRetries(OrderCreatedEvent orderCreatedEvent) {
    logger.info("Message received: {}", orderCreatedEvent);
    orderService.updateOrderStatus(orderCreatedEvent.id(), OrderStatus.RECEIVED);
    inventoryService.checkInventory(orderCreatedEvent.productId(), orderCreatedEvent.quantity());
    logger.info("Message processed: {}", orderCreatedEvent);
}

In the test, we’ll create an order with a quantity greater than our stock:

7.2. Testing

@Test
public void givenAlwaysAcknowledgementMode_whenProcessThrows_shouldAcknowledge() {
    var orderId = UUID.randomUUID();
    var queueName = eventsQueuesProperties.getOrderProcessingNoRetriesQueue();
    sqsTemplate.send(queueName, new OrderCreatedEvent(orderId, productIdProperties.getWirelessHeadphones(), 20));
    Awaitility.await()
      .atMost(Duration.ofMinutes(1))
      .until(() -> orderService.getOrderStatus(orderId)
        .equals(OrderStatus.RECEIVED));
    assertQueueIsEmpty(queueName, "no-retries-order-processing-container");
}

Now, even when the OutOfStockException is thrown, the message is acknowledged and no retries are attempted for the message:

Message received: OrderCreatedEvent[id=7587f1a2-328f-4791-8559-ee8e85b25259, productId=123e4567-e89b-12d3-a456-426614174001, quantity=20]
Caused by: com.baeldung.spring.cloud.aws.sqs.acknowledgement.exception.OutOfStockException: Product with id 123e4567-e89b-12d3-a456-426614174001 is out of stock. Quantity requested: 20
INFO 2835 --- [main] a.s.a.OrderProcessingApplicationLiveTest : Stopping container no-retries-order-processing-container
INFO 2835 --- [main] a.c.s.l.AbstractMessageListenerContainer : Container no-retries-order-processing-container stopped
INFO 2835 --- [main] a.s.a.OrderProcessingApplicationLiveTest : Checking for messages in queue order_processing_no_retries_queue
INFO 2835 --- [main] a.s.a.OrderProcessingApplicationLiveTest : No messages found in queue order_processing_no_retries_queue

8. Conclusion

In this article, we used an event-driven scenario to showcase the three acknowledgment modes provided by Spring Cloud AWS v3 SQS integration: ON_SUCCESS (the default), MANUAL, and ALWAYS.

We leveraged the auto-configured settings and used the @SqsListener annotation properties to switch between modes. We also created live tests to assert the behavior using Testcontainers and LocalStack.

       

1. Introduction

Email addresses make application software more efficient in user identification and communication. In the case of a list of email addresses, the distinction between unique addresses and the removal of duplicates becomes necessary.

In this tutorial, we’ll analyze multiple methods that can be applied to find unique email addresses in a list using Java.

2. String Manipulation Approach

For the list of email addresses, the goal is to pick up the unique email addresses, ignoring case sensitivity. For example, “User@example.com” and “user@example.com” are the same email addresses.

In this approach, we can use a HashSet to store unique emails efficiently, as the nature of a Hashset ensures that duplicate emails are automatically discarded. Let’s take an example:

@Test
public void givenEmailList_whenUsingStringManipulation_thenFindUniqueEmails() {
    Set<String> uniqueEmails = new HashSet<>();
    for (String email : emailList) {
        uniqueEmails.add(email.toLowerCase());
    }
    assertEquals(expectedUniqueEmails, uniqueEmails);
}

Here, we start by initializing a HashSet named uniqueEmails to store unique email addresses. Afterward, the loop iterates through each email in the provided list, converting it to lowercase using the toLowerCase() method to make the comparison case-insensitive. Then, we add this pre-processed email to the uniqueEmails HashSet.

Finally, we employ the assertEquals() method to verify that the emails in expectedUniqueEmails match the email uniqueEmails set obtained through the string manipulation process.

3. Java Streams Approach

Java Streams provides an easy solution for processing collections by utilizing the filtering option and collecting unique email addresses. Let’s delve into a simple example:

@Test
public void givenEmailList_whenUsingJavaStreams_thenFindUniqueEmails() {
    Set<String> uniqueEmails = Arrays.stream(emailList)
      .map(String::toLowerCase)
      .collect(Collectors.toSet());
    assertEquals(expectedUniqueEmails, uniqueEmails);
}

In this test method, we first convert each email to lowercase using the toLowerCase() method. Also, we utilize the toSet() method to collect elements into a HashSet.

4. Conclusion

In conclusion, we have presented various techniques for isolating exclusive email addresses from the list in Java. Whether through basic string manipulation or by utilizing Java Streams, the target is to discover and eliminate duplicates using the domain and username.

As always, the complete code samples for this article can be found over on GitHub.

       

1. Introduction

While working with Jackson, we might face situations where we’ll have to produce a JavaType from the given Class object.

In this tutorial, we’ll see how to create a JavaType from a Class with the aid of Jackson library.

2. Introduction to JavaType and Class

Before getting into details, let’s glance at JavaType and Class.

2.1. The JavaType in Java

In Jackson, the JavaType class represents Java types. It is a mechanism that enables working with generic types, such as parameterized types and arrays.

Creating the JavaType instance is important, especially when we are processing generic structures during the JSON handling.

2.2. The Class in Java

In Java, the Class class is a member of the reflection API and is used at runtime to represent a class or interface.

Moreover, it offers the class information, including its name, fields, methods, and constructors.

3. Using TypeFactory to Create JavaType

To generate a JavaType instance from a provided Class object using Jackson, we harness the TypeFactory class.

The TypeFactory provides a default instance, and as such, we can construct different types, whether generic or parameterized.

Let’s take an example using TypeFactory to generate a JavaType object from a generic class:

class MyGenericClass<T> {
    // Class Implementation
}

@Test
void givenGenericClass_whenCreatingJavaType_thenJavaTypeNotNull() {
    Class<?> myClass = MyGenericClass.class;
    JavaType javaType = TypeFactory.defaultInstance().constructType(myClass);
    assertNotNull(javaType);
}

Here, we first define a Class object named myClass, representing the generic class MyGenericClass.

Then, we use the constructType() method to create a JavaType instance based on the provided Class object (myClass).

In addition, we use the assertNotNull() assertion to ensure that the JavaType instance is successfully created, validating the correctness of the process.

4. Handling Parameterized Types

To smoothly build upon our knowledge of JavaType creation, we’ll see working with parameterized types with the TypeFactory class.

Additionally, this will be based on the section that we have just discussed, which talks about the generation of JavaType instances for generic classes. 

Let’s see an example:

class Container<T> {
    // Class Implementation
}

@Test
void givenParametricType_whenCreatingJavaType_thenJavaTypeNotNull() {
    Class<?> containerClass = Container.class;
    Class<?> elementType = String.class;
    JavaType javaType = TypeFactory.defaultInstance().constructParametricType(containerClass, elementType);
    assertNotNull(javaType);
}

In this case, we have a Container parameterized class with String elements. Moreover, an instance of JavaType is created with the constructParametricType() method representing the parameterized type.

The assertion is also used to verify that the JavaType object is successfully created, hence the routine of handling parameterized type is correct. 

5. Conclusion

In this tutorial, we learned how to build instances of JavaType from Class objects with the help of the Jackson library.

As always, the source code for the examples is available over on GitHub.

       

1. Overview

IntelliJ IDEA is a popular integrated development environment (IDE) with robust features and capabilities. However, as projects become complex, we may encounter scenarios in which the amount of memory IntelliJ allocates by default is insufficient for our needs.

In this tutorial, we’ll learn to increase the memory size limit on IntelliJ IDEA. Overall, this ensures a smoother and more responsive development experience.

2. Adjusting the Memory Settings

Adjusting memory settings involves modifying the configuration to allocate sufficient memory resources for the Java Virtual Machine (JVM) to operate efficiently. This process is crucial when working on large projects or dealing with memory-intensive tasks.

Let’s now go through the step-by-step process of adjusting the memory allocation.

2.1. Updating the idea.vmoptions File

The first step is to determine the installation directory of the IntelliJ IDEA application on the machine. Further, we’ll locate the idea.vmoptions file inside the installation directory. This file is generally present inside the bin folder.

Once we’ve located the idea.vmoptions file, let’s now adjust the JVM parameters -Xms (minimum heap size) and -Xmx (maximum heap size) to allocate more memory:

The above settings will allocate an initial heap size of 256 megabytes and a maximum heap size of 2048 megabytes. Make sure to adjust these values based on the project’s requirements and available system resources.

At last, save the changes and restart IntelliJ IDEA to apply the new memory settings.

2.2. Updating Memory Settings from the UI

Alternatively, we can also modify memory settings from the IntelliJ UI, using the “Help” ->“Change Memory Settings” menu option:

Using this method, we can only update the maximum heap size. Moreover, all the changes made from the UI will be saved to the idea.vmoptions file:

At last, we need to restart IntelliJ IDEA for our changes to take effect. Click on the “Save and Restart” button.

3. Monitor Memory Usage

After updating the allocated memory to a desired value, monitoring memory usage is essential to ensure optimal performance. IntelliJ IDEA provides a way to track memory consumption to help developers identify potential issues.

Right-click on the bottom right part of the taskbar. Select the “Memory Indicator” option to enable the memory indicator:

After enabling it, we can easily monitor memory consumption by heap and JVM. Hover over the bottom right corner of the status bar to view the breakdown:

Alternatively, we can double-press the “Shift” key and search for the “Memory Indicator”.

4. Conclusion

This article discussed the importance of memory allocation in a development environment and how to increase it for IntelliJ IDEA. Firstly, we updated the memory using the configuration file. Further, we learned to update it using IntelliJ’s UI.

Remember to regularly evaluate the project’s requirements and adjust memory settings accordingly.

       

1. Introduction

Pretty-printing a Map in Java involves formatting and displaying the key-value pairs of the map in a visually appealing and readable manner. While Java doesn’t provide a built-in method for pretty-printing maps, we have to implement a custom solution.

In this tutorial, we’ll learn how to achieve this goal. Depending on our preferences and the level of detail, we’ll explore multiple approaches, using only standard JDK and then external libraries.

2. Creating a Map

Before we move on, let’s create a map to work with:

Map<String, Object> map = Map.of(
  "one", 1,
  "two", 2,
  "inner", Map.of(
    "ten", 10,
    "eleven", 11
  )
);

Notably, we’ve extended our example by adding an inner nested map.

3. Using Core Java

As we know, Java can print maps using a built-in toString() method:

{one=1, two=2, inner={eleven=11, ten=10}}

The output is preformatted in a simple way, displaying key-value pairs separated by commas on a single line. It works fine for simple maps or during debugging.

But if we want a pretty-printed map, we have to implement custom methods.

3.1. Using a for-each Loop

When we need to iterate over all the elements, we can use a for-each loop:

for (Map.Entry<?, ?> entry : map.entrySet()) {
     System.out.printf("%-15s : %s%n", entry.getKey(), entry.getValue());
}

This loop will print:

one             : 1
two             : 2
inner           : {ten=10, eleven=11}

The output looks better now, but our inner map still isn’t pretty-printed, so we have to manually handle complex structures.

To format our inner entries, let’s implement a helper function with a recursion and a left padding parametrized:

void printMap(int leftPadding, Map<?, ?> map) {
    for (Map.Entry<?, ?> entry : map.entrySet()) {
        if (entry.getValue() instanceof Map) {
            System.out.printf("%-15s :%n", entry.getKey());
            printMap(leftPadding + 4, (Map<?, ?>) entry.getValue());
        }
        else {
            System.out.printf("%" + (leftPadding > 0 ? leftPadding : "") + "s" // adding padding
              + "%-15s : %s%n",
              "", entry.getKey(), entry.getValue());
        }
    }
}

Now, if we execute the method by calling printMap(0, map), it’ll print:

one             : 1
two             : 2
inner           :
    ten             : 10
    eleven          : 11

By implementing our custom solution, we’ll always have full control while printing our maps. We can customize our output by using built-in formatters such as the Formatter class, String.format(), or even System.out.printf(). On the other hand, a custom function might be a bit complicated if we’d like to handle multi-type or inner structures.

3.2. Using Stream

In Java, we can replace almost any for-each loop with a Stream. We can use one line to print and format our map:

map.forEach((k, v) -> System.out.printf("%-15s : %s%n", k, v));

If we want more control, we can expand the stream and use map() or Collectors.joining() functions:

System.out.println(MAP.entrySet().stream()
  .map(entry -> String.format("%-15s : %s", entry.getKey(), entry.getValue()))
  .collect(Collectors.joining("\n")));

In both examples, we’ll get:

one             : 1
two             : 2
inner           : {ten=10, eleven=11}

Once again, this approach gives us more control over formatting and works great for simple types. We must remember to manually handle any complex structures, as we did previously.

4. External Libraries

Implementing a custom pretty-print feature might be a good choice if we don’t have a complex map. Any additional mappings will make our code more complicated and not worth implementing. Let’s check the solutions provided by external libraries.

4.1. Jackson

If we compare JSON and map, we can find many similarities. In both cases, key-value pairs are used to represent entries.

First, let’s inspect Jackson, one of the most popular JSON libraries, by including its dependency in our pom.xml:

<dependency> 
    <groupId>com.fasterxml.jackson.core</groupId> 
    <artifactId>jackson-databind</artifactId> 
    <version>2.16.1</version>
</dependency>

Jackson provides an ObjectMapper class that can be used not only to work with JSON but also with standard maps:

String json = new ObjectMapper().writerWithDefaultPrettyPrinter().writeValueAsString(map);

As a result, Jackson API pretty-prints our map:

{
  "one" : 1,
  "two" : 2,
  "inner" : {
    "ten" : 10,
    "eleven" : 11
  }
}

This solution automatically handles our inner map, and it’s much simpler than previous ones. Unfortunately, we don’t have full control over the mapping.

4.2. Gson

Of course, other JSON libraries also support maps for pretty-printing. Let’s check out Gson by adding the latest version of its dependency:

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>

Just like we did previously, let’s configure a GsonBuilder:

String json = new GsonBuilder().setPrettyPrinting().create().toJson(MAP);

And here’s the result now:

{
  "one": 1,
  "two": 2,
  "inner": {
    "ten": 10,
    "eleven": 11
  }
}

Notably, we have slightly different formatting (no space after the key), but again, it’s much easier to pretty-print maps supporting nested values.

4.3. Apache Commons Collections

When we know that JSON libraries often support JSON and maps for pretty-printing, let’s explore other solutions provided by non-JSON libraries.

Let’s check out Apache Commons Collections by adding a dependency to our project:

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-collections4</artifactId>
    <version>4.4</version>
</dependency>

The library brings us the MapUtils class. Let’s use it to print our map:

MapUtils.debugPrint(System.out, "map", map);

As a result, we’ll get the map formatted like this:

map = 
{
    one = 1 java.lang.Integer
    two = 2 java.lang.Integer
    inner = 
    {
        ten = 10 java.lang.Integer
        eleven = 11 java.lang.Integer
    } java.util.HashMap
} java.util.HashMap

We’ve just used a debugPrint() method to format the map. If we want to omit the class name of our values, we can use a verbosePrint().

4.4. Google Guava

Finally, let’s check out the approach provided by the Google Guava library. Before starting, let’s update our pom.xml:

<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>33.0.0-jre</version>
</dependency>

To print our map, we can use the Joiner class:

String mapStr = Joiner.on(",\n").withKeyValueSeparator("=").join(map);

If we now check the result, we’ll get:

one=1,
two=2,
inner={ten=10, eleven=11}

Unfortunately, this approach can’t handle nested entries, but it works well for single-level structures.

5. Conclusion

In this article, we learned different approaches to pretty-print maps in Java. As we know, printing using the built-in toString() method can result in an unreadable, single-line string.

We started by implementing the custom pretty-print methods using standard Java API, especially the for-each loops, streams, and formatters. This approach suits us if we have simple, non-nested maps or want full control over the mapping.

After that, we inspected the solutions provided by external libraries like Jackson, Gson, Apache Commons Collections, or Guava. An external API is always simpler than implementing the custom solution, but we have less control over the predefined print format.

As always, the source code accompanying the article can be found over on GitHub.

       

1. Overview

In this tutorial, we’ll demonstrate the use of the Apache POI, JExcel, and Fastexcel APIs for working with Excel spreadsheets.

These libraries can be used to dynamically read, write and modify the content of an Excel spreadsheet and provide an effective way of integrating Microsoft Excel into a Java Application.

2. Maven Dependencies

To begin, we will need to add the following dependencies to our pom.xml file:

<dependency> 
  <groupId>org.apache.poi</groupId>
  <artifactId>poi</artifactId> 
  <version>5.2.5</version> 
</dependency> 
<dependency> 
  <groupId>org.apache.poi</groupId> 
  <artifactId>poi-ooxml</artifactId> 
  <version>5.2.5</version> 
</dependency>
<dependency>
  <groupId>org.jxls</groupId>
  <artifactId>jxls-jexcel</artifactId>
  <version>1.0.9</version>
</dependency>
<dependency>
    <groupId>org.dhatim</groupId>
    <artifactId>fastexcel-reader</artifactId>
    <version>0.17.0</version>
</dependency>
<dependency>
    <groupId>org.dhatim</groupId>
    <artifactId>fastexcel</artifactId>
    <version>0.17.0</version>
</dependency>

The latest versions of poi, poi-ooxml, jxls-jexcel, fastexcel-reader, and fastexcel can be downloaded from Maven Central.

3. Apache POI

The Apache POI library supports both .xls and .xlsx files and is a more complex library than other Java libraries for working with Excel files.

It provides the Workbook interface for modeling an Excel file, and the Sheet, Row, and Cell interfaces that model the elements of an Excel file, as well as implementations of each interface for both file formats.

When working with the newer .xlsx file format, we’d use the XSSFWorkbook, XSSFSheet, XSSFRow, and XSSFCell classes.

To work with the older .xls format, we use the HSSFWorkbook, HSSFSheet, HSSFRow, and HSSFCell classes.

3.1. Reading From Excel

Let’s create a method that opens a .xlsx file and then reads content from the first sheet of the file.

The method for reading cell content varies depending on the type of data in the cell. The type of cell content can be determined using the getCellType() method of the Cell interface.

First, let’s open the file from a given location:

FileInputStream file = new FileInputStream(new File(fileLocation));
Workbook workbook = new XSSFWorkbook(file);

Next, let’s retrieve the first sheet of the file and iterate through each row:

Sheet sheet = workbook.getSheetAt(0);
Map<Integer, List<String>> data = new HashMap<>();
int i = 0;
for (Row row : sheet) {
    data.put(i, new ArrayList<String>());
    for (Cell cell : row) {
        switch (cell.getCellType()) {
            case STRING: ... break;
            case NUMERIC: ... break;
            case BOOLEAN: ... break;
            case FORMULA: ... break;
            default: data.get(new Integer(i)).add(" ");
        }
    }
    i++;
}

Apache POI has different methods for reading each type of data. Let’s expand on the content of each switch case above.

When the cell type enum value is STRING, the content will be read using the getRichStringCellValue() method of the Cell interface:

data.get(new Integer(i)).add(cell.getRichStringCellValue().getString());

Cells having the NUMERIC content type can contain either a date or a number and are read in the following manner:

if (DateUtil.isCellDateFormatted(cell)) {
    data.get(i).add(cell.getDateCellValue() + "");
} else {
    data.get(i).add(cell.getNumericCellValue() + "");
}

For BOOLEAN values, we have the getBooleanCellValue() method:

data.get(i).add(cell.getBooleanCellValue() + "");

And when the cell type is FORMULA, we can use the getCellFormula() method:

data.get(i).add(cell.getCellFormula() + "");

3.2. Writing to Excel

Apache POI uses the same interfaces presented in the previous section for writing to an Excel file and has better support for styling than JExcel.

Let’s create a method that writes a list of persons to a sheet titled “Persons”.

First, we will create and style a header row that contains “Name” and “Age” cells:

Workbook workbook = new XSSFWorkbook();
Sheet sheet = workbook.createSheet("Persons");
sheet.setColumnWidth(0, 6000);
sheet.setColumnWidth(1, 4000);
Row header = sheet.createRow(0);
CellStyle headerStyle = workbook.createCellStyle();
headerStyle.setFillForegroundColor(IndexedColors.LIGHT_BLUE.getIndex());
headerStyle.setFillPattern(FillPatternType.SOLID_FOREGROUND);
XSSFFont font = ((XSSFWorkbook) workbook).createFont();
font.setFontName("Arial");
font.setFontHeightInPoints((short) 16);
font.setBold(true);
headerStyle.setFont(font);
Cell headerCell = header.createCell(0);
headerCell.setCellValue("Name");
headerCell.setCellStyle(headerStyle);
headerCell = header.createCell(1);
headerCell.setCellValue("Age");
headerCell.setCellStyle(headerStyle);

Next, let’s write the content of the table in a different style:

CellStyle style = workbook.createCellStyle();
style.setWrapText(true);
Row row = sheet.createRow(2);
Cell cell = row.createCell(0);
cell.setCellValue("John Smith");
cell.setCellStyle(style);
cell = row.createCell(1);
cell.setCellValue(20);
cell.setCellStyle(style);

Finally, let’s write the content to a “temp.xlsx” file in the current directory and close the workbook:

File currDir = new File(".");
String path = currDir.getAbsolutePath();
String fileLocation = path.substring(0, path.length() - 1) + "temp.xlsx";
FileOutputStream outputStream = new FileOutputStream(fileLocation);
workbook.write(outputStream);
workbook.close();

Let’s test the above methods in a JUnit test that writes content to the temp.xlsx file and then reads the same file to verify it contains the text we have written:

public class ExcelIntegrationTest {
    private ExcelPOIHelper excelPOIHelper;
    private static String FILE_NAME = "temp.xlsx";
    private String fileLocation;
    @Before
    public void generateExcelFile() throws IOException {
        File currDir = new File(".");
        String path = currDir.getAbsolutePath();
        fileLocation = path.substring(0, path.length() - 1) + FILE_NAME;
        excelPOIHelper = new ExcelPOIHelper();
        excelPOIHelper.writeExcel();
    }
    @Test
    public void whenParsingPOIExcelFile_thenCorrect() throws IOException {
        Map<Integer, List<String>> data
          = excelPOIHelper.readExcel(fileLocation);
        assertEquals("Name", data.get(0).get(0));
        assertEquals("Age", data.get(0).get(1));
        assertEquals("John Smith", data.get(1).get(0));
        assertEquals("20", data.get(1).get(1));
    }
}

4. JExcel

The JExcel library is a lightweight library with the advantage that it’s easier to use than Apache POI, but with the disadvantage that it only provides support for processing Excel files in the .xls (1997-2003) format.

At the moment, .xlsx files are not supported.

4.1. Reading From Excel

In order to work with Excel files, this library provides a series of classes that represent the different parts of an Excel file. The Workbook class represents the entire collection of sheets. The Sheet class represents a single sheet, and the Cell class represents a single cell of a spreadsheet.

Let’s write a method that creates a workbook from a specified Excel file, gets the first sheet of the file, and then traverses its content and adds each row in a HashMap:

public class JExcelHelper {
    public Map<Integer, List<String>> readJExcel(String fileLocation) 
      throws IOException, BiffException {
 
        Map<Integer, List<String>> data = new HashMap<>();
        Workbook workbook = Workbook.getWorkbook(new File(fileLocation));
        Sheet sheet = workbook.getSheet(0);
        int rows = sheet.getRows();
        int columns = sheet.getColumns();
        for (int i = 0; i < rows; i++) {
            data.put(i, new ArrayList<String>());
            for (int j = 0; j < columns; j++) {
                data.get(i)
                  .add(sheet.getCell(j, i)
                  .getContents());
            }
        }
        return data;
    }
}

4.2. Writing to Excel

For writing to an Excel file, the JExcel library offers classes similar to the ones used above, which model a spreadsheet file: WritableWorkbook, WritableSheet, and WritableCell.

The WritableCell class has subclasses corresponding to the different types of content that can be written: Label, DateTime, Number, Boolean, Blank, and Formula.

This library also supports basic formatting, such as controlling font, color, and cell width.

Let’s write a method that creates a workbook called “temp.xls” in the current directory and then writes the same content we wrote in the Apache POI section.

First, let’s create the workbook:

File currDir = new File(".");
String path = currDir.getAbsolutePath();
String fileLocation = path.substring(0, path.length() - 1) + "temp.xls";
WritableWorkbook workbook = Workbook.createWorkbook(new File(fileLocation));

Next, let’s create the first sheet and write the header of the Excel file, containing the “Name” and “Age” cells:

WritableSheet sheet = workbook.createSheet("Sheet 1", 0);
WritableCellFormat headerFormat = new WritableCellFormat();
WritableFont font
  = new WritableFont(WritableFont.ARIAL, 16, WritableFont.BOLD);
headerFormat.setFont(font);
headerFormat.setBackground(Colour.LIGHT_BLUE);
headerFormat.setWrap(true);
Label headerLabel = new Label(0, 0, "Name", headerFormat);
sheet.setColumnView(0, 60);
sheet.addCell(headerLabel);
headerLabel = new Label(1, 0, "Age", headerFormat);
sheet.setColumnView(0, 40);
sheet.addCell(headerLabel);

With a new style, let’s write the content of the table we’ve created:

WritableCellFormat cellFormat = new WritableCellFormat();
cellFormat.setWrap(true);
Label cellLabel = new Label(0, 2, "John Smith", cellFormat);
sheet.addCell(cellLabel);
Number cellNumber = new Number(1, 2, 20, cellFormat);
sheet.addCell(cellNumber);

It’s very important to remember to write to the file and close it at the end so it can be used by other processes, using the write() and close() methods of the Workbook class:

workbook.write();
workbook.close();

5. Fastexcel

Fastexcel is an easy-to-use library with limited features and a lower memory footprint compared to Apache POI.

Its multi-threaded support using CompletableFuture makes it a great alternative when working with large files that aren’t feature-extensive. At the moment, the library has only basic style support and doesn’t support graphs.

5.1. Reading From Excel

Let’s write a method to access the Excel file and read the data from its first sheet. Let’s add the data to a Map of row indices as keys and a list of the content from that row as value:

public class FastexcelHelper {
    public Map<Integer, List<String>> readExcel(String fileLocation) throws IOException {
        Map<Integer, List<String>> data = new HashMap<>();
        try (FileInputStream file = new FileInputStream(fileLocation); ReadableWorkbook wb = new ReadableWorkbook(file)) {
            Sheet sheet = wb.getFirstSheet();
            try (Stream<Row> rows = sheet.openStream()) {
                rows.forEach(r -> {
                    data.put(r.getRowNum(), new ArrayList<>());
                    for (Cell cell : r) {
                        data.get(r.getRowNum()).add(cell.getRawValue());
                    }
                });
            }
        }
        return data;
    }
}

Here, we’re using cell.getRawValue() which returns the value of that cell as a String. Alternatively, based on CellType we can use the getCellAsBoolean(int cellIndex), getCellAsDate(int cellIndex), getCellAsString(int cellIndex) or getCellAsNumber(int cellIndex) methods from the Row class to read a cell’s content.

5.2. Writing to Excel

Unlike the libraries mentioned above, Fastexcel uses different interfaces to write to an Excel file than the ones used to read Excel.

We’ll begin by creating a Workbook from an OutputStream. We’ll then write the “Name” and “Age” headers in the default first sheet and add style details to the cells. Next, let’s add another row with a person’s name and age:

public void writeExcel() throws IOException {
    File currDir = new File(".");
    String path = currDir.getAbsolutePath();
    String fileLocation = path.substring(0, path.length() - 1) + "fastexcel.xlsx";
    try (OutputStream os = Files.newOutputStream(Paths.get(fileLocation)); Workbook wb = new Workbook(os, "MyApplication", "1.0")) {
        Worksheet ws = wb.newWorksheet("Sheet 1");
        ws.width(0, 25);
        ws.width(1, 15);
        
        ws.range(0, 0, 0, 1).style().fontName("Arial").fontSize(16).bold().fillColor("3366FF").set();
        ws.value(0, 0, "Name");
        ws.value(0, 1, "Age");
        
        ws.range(2, 0, 2, 1).style().wrapText(true).set();
        ws.value(2, 0, "John Smith");
        ws.value(2, 1, 20L);
    }
}

Let’s write a small test to verify our code:

@Test
public void whenParsingExcelFile_thenCorrect() throws IOException {
    Map<Integer, List<String>> data = fastexcelHelper.readExcel(fileLocation);
    assertEquals("Name", data.get(1).get(0));
    assertEquals("Age", data.get(1).get(1));
    assertEquals("John Smith", data.get(3).get(0));
    assertEquals("20", data.get(3).get(1));
}

Here, we also see that the Row class in the fastexcel-reader library uses the variable rowNum with an offset of 1. Whereas, the value(int r, int c, Object value) method from the Worksheet class from the fastexcel library expects the row’s index with an offset of 0.

6. Conclusion

In this article, we saw how to use the Apache POI API, JExcel API, and Fastexcel API to read and write an Excel file from a Java program.

When deciding on which library to use, we should consider the benefits and drawbacks of each library. For example, Apache POI is feature-rich and has support for graphs but has a high memory footprint. In contrast, Fastexcel has limited features but consumes less memory than Apache POI.

The complete source code for this article can be found over on GitHub.

       

1. Introduction

When working with Spring Boot applications that utilize Spring Data JPA for data persistence, it’s crucial to test the repositories that interact with the database. In this tutorial, we’ll explore how to effectively test Spring Data JPA repositories using the @DataJpaTest annotation provided by Spring Boot along with JUnit.

2. Understanding @DataJpaTest and Repository Class

In this section, we’ll delve into the interaction between @DataJpaTest and class repositories within the context of Spring Boot applications.

2.1. @DataJpaTest

The @DataJpaTest annotation is used to test JPA repositories in Spring Boot applications. It’s a specialized test annotation that provides a minimal Spring context for testing the persistence layer. This annotation can be used in conjunction with other testing annotations like @RunWith and @SpringBootTest.

In addition, the scope of @DataJpaTest is limited to the JPA repository layer of the application. It doesn’t load the entire application context, which can make testing faster and more focused. This annotation also provides a pre-configured EntityManager and TestEntityManager for testing JPA entities.

2.2. Repository Class

In Spring Data JPA, repositories serve as an abstraction layer on top of JPA entities. It provides a set of methods for performing CRUD (Create, Read, Update, Delete) operations and executing custom queries. These repositories typically extend from interfaces like JpaRepository and are responsible for handling database interactions related to specific entity types.

3. Optional Parameters

@DataJpaTest does have some optional parameters we can use to customize the test environment.

3.1. properties

This parameter allows us to specify Spring Boot configuration properties that will be applied to our test context. This can be useful for adjusting settings like database connection details, transaction behavior, or other application properties relevant to our testing needs:

@DataJpaTest(properties = {
    "spring.datasource.url=jdbc:h2:mem:testdb",
    "spring.jpa.hibernate.ddl-auto=create-drop"
})
public class UserRepositoryTest {
    // ... test methods
}

3.2. showSql

This enables SQL logging for our tests and allows us to see the actual SQL queries executed by the repository methods. Moreover, this can help debug or understand how the JPA queries are translated. By default, the SQL logging is enabled. We can turn it off by setting the value to false:

@DataJpaTest(showSql = false)
public class UserRepositoryTest {
    // ... test methods
}

3.3. includeFilters and excludeFilters

These parameters enable us to include or exclude specific components during component scanning. We can use them to narrow down the scanning scope and optimize test performance by focusing only on the relevant components:

@DataJpaTest(includeFilters = @ComponentScan.Filter(
    type = FilterType.ASSIGNABLE_TYPE, 
    classes = UserRepository.class),
  excludeFilters = @ComponentScan.Filter(
    type = FilterType.ASSIGNABLE_TYPE, 
    classes = SomeIrrelevantRepository.class))
public class UserRepositoryTest {
    // ... test methods
}

4. Key Features

When it comes to testing JPA repositories in Spring Boot applications, the @DataJpaTest annotation can be a handy tool. Let’s explore its key features and benefits in detail.

4.1. Test Environment Configuration

Setting up a proper test environment for JPA repositories can be time-consuming and tricky. @DataJpaTest provides a ready-made testing environment that includes essential components for testing JPA repositories, such as the EntityManager and DataSource.

This environment is specifically designed for testing JPA repositories. It ensures that our repository methods run within the context of a test transaction, interacting with a safe, in-memory database like H2 instead of the production database.

4.2. Dependency Injection

@DataJpaTest simplifies the process of dependency injection within our test classes. Repositories, along with other essential beans, are automatically injected into the test context. This seamless integration enables developers to focus on writing concise and effective test cases without the hassle of explicit bean wiring.

4.3. Rollback by Default

Moreover, keeping tests independent and reliable is crucial. By default, each test method annotated with @DataJpaTest runs within a transactional boundary. This ensures that changes made to the database are automatically rolled back at the end of the test, leaving a clean slate for the next test.

5. Configuration and Setup

To use @DataJpaTest, we need to add the spring-boot-starter-test dependency to our project with scope “test“. This lightweight dependency includes essential testing libraries like JUnit for testing, ensuring it’s not included in our production build.

5.1. Adding Dependency to pom.xml

Let’s add the following dependency to the pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-test</artifactId>
    <scope>test</scope>
</dependency>

Once we’ve added the dependency, we can use the @DataJpaTest annotation in our tests. This annotation sets up an in-memory H2 database and configure Spring Data JPA for us, allowing us to write tests that interact with our repository classes.

5.2. Creating the Entity Class

Now, let’s create the User entity class, which will represent user data:

@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String username;
    private String password;
    
    // getters and setters
}

5.3. Creating the Repository Interface

Next, we define the UserRepository, a Spring Data JPA repository interface for managing User entities:

public interface UserRepository extends JpaRepository<User, Long> {
    // Add custom methods if needed
}

By extending JpaRepository<User, Long>, our UserRepository gains access to standard CRUD operations provided by Spring Data JPA out-of-the-box.

Additionally, we can define custom query methods within this interface to suit specific data access retrieval needs, such as findByUsername():

public interface UserRepository extends JpaRepository<User, Long> {
    // Custom query method to find a user by username
    User findByUsername(String username);
}

6. Implementing Repository Tests

To test the repository layer of our application, we’ll utilize the @DataJpaTest annotation. By using this annotation, an in-memory H2 database will be set up, and Spring Data JPA will be configured. This allows us to write tests that interact with our repository classes.

6.1. Setting up the Test Class

To begin, let’s set up the test class by annotating it with @DataJpaTest. This annotation scans for entity classes annotated with @Entity and Spring Data JPA repositories interfaces. This ensures that only relevant components are loaded for testing, improving test focus and performance:

@DataJpaTest
public class UserRepositoryTest {
    // Add test methods here
}

To create a repository test case, we first need to inject the repository that we want to test into our test class. This can be done using the @Autowired annotation:

@Autowired
private UserRepository userRepository;

6.2. Test Lifecycle Management

In the context of test lifecycle management, @BeforeEach and @AfterEach annotations are used to perform setup and teardown operations before and after each test method, respectively. This ensures that each test method runs in a clean and isolated environment, with consistent initial conditions and cleanup procedures.

Here’s how we can incorporate test lifecycle management into our test class:

@BeforeEach
public void setUp() {
    // Initialize test data before each test method
    testUser = new User();
    testUser.setUsername("testuser");
    testUser.setPassword("password");
    userRepository.save(testUser);
}
@AfterEach
public void tearDown() {
    // Release test data after each test method
    userRepository.delete(testUser);
}

In the setUp() method annotated with @BeforeEach, we can perform any necessary setup operations required before each test method execution. This might include initializing test data, setting up mock objects, or preparing resources needed for the test.

Conversely, in the tearDown() method annotated with @AfterEach, we can perform cleanup operations after each test method execution. This might involve resetting any changes made during the test, releasing resources, or performing any necessary cleanup tasks to restore the test environment to its original state.

6.3. Testing the Insertion Operation

Now, we can write test methods that interact with the JPA repository. For example, we might want to test that we can save a new user to the database. Since a user is automatically saved before each test, we can directly focus on testing interactions with the JPA repository:

@Test
void givenUser_whenSaved_thenCanBeFoundById() {
    User savedUser = userRepository.findById(testUser.getId()).orElse(null);
    assertNotNull(savedUser);
    assertEquals(testUser.getUsername(), savedUser.getUsername());
    assertEquals(testUser.getPassword(), savedUser.getPassword());
}

If we observe the console log for the test case, we’ll notice the following logs:

Began transaction (1) for test context  
.....
Rolled back transaction for test:  

These logs indicate that the @BeforeEach and @AfterEach methods are functioning as expected.

6.4. Testing the Update Operation

In addition, we can create a test case for testing the update operation:

@Test
void givenUser_whenUpdated_thenCanBeFoundByIdWithUpdatedData() {
    testUser.setUsername("updatedUsername");
    userRepository.save(testUser);
    User updatedUser = userRepository.findById(testUser.getId()).orElse(null);
    assertNotNull(updatedUser);
    assertEquals("updatedUsername", updatedUser.getUsername());
}

6.5. Testing the findByUsername() Method

Now, let’s test the findByUsername() custom query method we created:

@Test
void givenUser_whenFindByUsernameCalled_thenUserIsFound() {
    User foundUser = userRepository.findByUsername("testuser");
    assertNotNull(foundUser);
    assertEquals("testuser", foundUser.getUsername());
}

7. Transactional Behavior

By default, all tests annotated with @DataJpaTest are executed within a transaction. This means that any changes made to the database during the test are rolled back at the end of the test, ensuring that the database is left in its original state. This default behavior simplifies testing by preventing interference between tests and data corruption.

However, there may be cases where we need to disable transactional behavior to test certain scenarios. For instance, testing results may need to persist beyond the test.

In such a case, we can disable transactions for a specific test class using the @Transactional annotation with propagation = propagation.NOT_SUPPORTED:

@DataJpaTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
public class UserRepositoryIntegrationTest {
    // ... test methods
}

Or we can disable transactions for an individual test method:

@Test
@Transactional(propagation = Propagation.NOT_SUPPORTED)
public void testMyMethodWithoutTransactions() {
    // ... code that modifies the database
}

8. Conclusion

In this article, we learned how to use @DataJpaTest to test our JPA repository in JUnit. Overall, @DataJpaTest is a powerful annotation for testing JPA repositories in Spring Boot applications. It provides a focused testing environment and pre-configured tools for testing persistence layers. By using @DataJpaTest, we can ensure that our JPA repositories are functioning correctly without having to start up the entire Spring context.

As always, the source code for the examples is available over on GitHub.

       

1. Overview

In this tutorial, we’ll explore the Testcontainers Desktop application, a simple yet powerful tool for running Testcontainers. We’ll learn how to use it to configure our Docker environment, manage the container lifecycle, and get insights about our development and testing patterns.

2. Testcontainers Desktop

Testcontainers Desktop offers a minimal UI designed to simplify the Testcontainer configuration and debugging. We can download Testcontainers Desktop for free from the official website. To start using it, we’ll sign up by creating an account or via a third party like Google, GitHub, or Docker.

That’s all! Once we install the application and sign in, we can start using Testcontainers Desktop in our development workflow:

We should see the Testcontainers logo in the taskbar. If we right-click on it, we’ll see some of the key features we’ll be exploring today:

• Use Testcontainers Cloud
• Freeze containers shutdown
• Define fixed ports
• Interact with the containers
• See Testcontainers dashboard
• Perform advanced customizations

3. Testcontainers Execution Modes

Testcontainers Desktop offers developers two main ways to run tests: locally or in the cloud. Notably, local execution is the default behavior.

3.1. Local Execution

Local execution leverages our local Docker environment. For instance, let’s run a JUnit test that uses Testcontainers to spin up a MongoDB Docker container:

@Testcontainers
@SpringBootTest
class DynamicPropertiesLiveTest {
    @Container
    static MongoDBContainer mongoDBContainer = new MongoDBContainer(DockerImageName.parse("mongo:4.0.10"));
    @DynamicPropertySource
    static void setProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.data.mongodb.uri", mongoDBContainer::getReplicaSetUrl);
    }
   
    @Test
    void whenRequestingHobbits_thenReturnFrodoAndSam() {
        // ...
    }
}

If we don’t already have the Docker image locally, we’ll see Docker pulling it in the logs. After that, the MongoDB container starts:

org.testcontainers.dockerclient.DockerClientProviderStrategy - Found Docker environment with local Npipe socket (npipe:////./pipe/docker_engine)
org.testcontainers.DockerClientFactory - Docker host IP address is localhost
org.testcontainers.DockerClientFactory - Connected to docker:
    Server Version: 4.8.3
    API Version: 1.41
    Operating System: fedora
    Total Memory: 7871 MB
org.testcontainers.DockerClientFactory - Checking the system...
org.testcontainers.DockerClientFactory - ✔︎ Docker server version should be at least 1.6.0
tc.mongo:4.0.10 - Pulling docker image: mongo:4.0.10. Please be patient; this may take some time but only needs to be done once.
tc.mongo:4.0.10 - Starting to pull image
tc.mongo:4.0.10 - Pulling image layers:  1 pending,  1 downloaded,  0 extracted, (0 bytes/? MB)
tc.mongo:4.0.10 - Pulling image layers:  0 pending,  2 downloaded,  0 extracted, (0 bytes/0 bytes)
[ ... ]
tc.mongo:4.0.10 - Pull complete. 14 layers, pulled in 17s (downloaded 129 MB at 7 MB/s)
tc.mongo:4.0.10 - Creating container for image: mongo:4.0.10
tc.mongo:4.0.10 - Container mongo:4.0.10 is starting: 3d74c3a...
tc.mongo:4.0.10 - Container mongo:4.0.10 started in PT21.0624015S

Furthermore, we can manually check if the container is created by running the “docker ps” command in the terminal.

3.2. Testcontainers Cloud Execution

Testcontainers Cloud provides a scalable platform for running tests in cloud environments. This is ideal if we don’t want to run the containers locally or if we don’t have access to a running Docker environment.

TestContainer Cloud is a paid feature of Testcontainers, but we can use it for free for up to 300 minutes per month.

From the small UI, let’s switch to “Run with Testcontainers Cloud”:

Let’s re-run the test using this option, and read through the logs again:

org.testcontainers.dockerclient.DockerClientProviderStrategy - Found Docker environment with Testcontainers Host with tc.host=tcp://127.0.0.1:65497
org.testcontainers.DockerClientFactory - Docker host IP address is 127.0.0.1
org.testcontainers.DockerClientFactory - Connected to docker:
    Server Version: 78+testcontainerscloud (via Testcontainers Desktop 1.7.0)
    API Version: 1.43
    Operating System: Ubuntu 20.04 LTS
    Total Memory: 7407 MB
org.testcontainers.DockerClientFactory - Checking the system...
org.testcontainers.DockerClientFactory - ✔︎ Docker server version should be at least 1.6.0
tc.mongo:4.0.10 - Pulling docker image: mongo:4.0.10. Please be patient; this may take some time but only needs to be done once.
tc.mongo:4.0.10 - Starting to pull image
tc.mongo:4.0.10 - Pulling image layers:  0 pending,  0 downloaded,  0 extracted, (0 bytes/0 bytes)
tc.mongo:4.0.10 - Pulling image layers: 12 pending,  1 downloaded,  0 extracted, (0 bytes/? MB)
[ ... ]

As expected, a different environment was used and the Docker images are no longer downloaded locally. Needless to say, if we run the command “docker ps“, we won’t see any container running locally.

4. Debugging Testcontainers

Testcontainers Desktop facilitates a smooth debugging experience, through features such as preventing container shutdowns, defining fixed ports, customizing configurations to suit our needs, and directly engaging with containers.

4.1. Freeze Container Shutdown

We can use the Desktop application to manually control the container’s lifecycle. For instance, we can use the option “Freeze container shutdown” to allow a running container to keep running even after the test that started it has terminated:

If we enable this feature and re-run the tests, we’ll receive a notification confirming that the container has been frozen.

Next, we’ll identify the port on our local machine that corresponds to the exposed port of the Docker container. MongoDB conventionally operates on port 27017. Let’s open a terminal and run the command “docker ps” to see this mapping:

As we can see, Docker is mapping the container’s port 27017 to port 64215 from our machine. Consequently, we can use this port to connect to the database through our preferred MongoDB client application.

Studio3T is a graphical user interface for MongoDB, facilitating database management, querying, and visualization. Let’s use it to configure and test the connection to our Mongo Testcontainer:

Our test inserted some records into the “characters” collection from the “test” database. Let’s run a simple query to list all the records from the collection:

As we can see, all records are present in the database.

4.2. Define Fixed Ports

Normally, Testcontainers starts on random ports. However, if we often need to find the exposed port for debugging purposes, we can define fixed ports instead. To achieve this, we first need to navigate to Services > Open config location. This opens a folder containing configuration examples for a few of the more popular Testconatiners modules:

Let’s stick to our use case and inspect the “mongodb.toml.example” file. First, we’ll rename it to “mongodb.toml“, removing the “.example” extension.

Now, let’s examine the file’s content. The comments explain step by step, how to customize this file to allow Testcontainers Desktop to properly proxy the service’s ports. Let’s focus on the “ports” variable, we can use it to define the mapping between the local port and the container port:

# `local-port` configures on which port on your machine the service is exposed.
# `container-port` indicates which port inside the container to proxy.
ports = [
  {local-port = 27017, container-port = 27017},
]

As a result, just by renaming the file and enabling this configuration, we’ll be able to connect to the MongoDB database using the fixed port 27017.

In other words, we no longer need to manually check the port mapping each time we re-run the test, and we can rely on Mongo’s default port instead.

4.3. Interact With the Containers

Sometimes, even connecting to the database isn’t sufficient, for example when we require more detailed debugging. In this case, we can directly access the Docker container itself. For example, we can open a terminal that is attached to the container and interact with it.

To do this, we navigate to Containers and then we select the container we want to debug. After that, we’ll be prompted with three actions to choose from: “Open terminal“, “Tail logs“, or “Terminate“:

The “Open terminal” action allows us to access a terminal attached to the container. For instance, we can use this terminal to start the MongoDB shell and query data without needing to install any MongoDB client application on our local system.

Let’s start by opening a terminal (Containers > mongo:4.0.10 > Open terminal):

From this point forward, the instructions depend on the container we use and the use case we want to debug. In our case, let’s execute the following commands:

• “mongo” – opens the MongoDB shell prompt
• “show dbs” – lists the databases present on the server
• “use test” – switches to the “test” database, the one created by our application
•  “db.getCollection(“characters”).find({“race”:”hobbit”})” – queries the “characters” collection and filters by the “race” attribute

As expected, we can see the commands being executed using the MongoDB shell. The last query, db.getCollection(…), retrieves a list of records from the “characters” collection of the “test” database.

5. Testcontainers Dashboard

Testcontainers Desktop provides a user-friendly dashboard with a summary of the Testcontainers we used. We can access this webpage by selecting the “Open Dashboard…” option from the menu:

The dashboard offers an overview of the Testcontainers and images used, as well as useful links to resources and account settings. At the bottom of the page, we can see the recent activity and the environment used for execution.

This collaborative tool aggregates test data across desktop and CI environments, offering insights into development and testing patterns. Widgets on the dashboard help answer questions about testing consistency, release impact, popular container images, and outdated dependencies.

6. Conclusion

In this article, we discovered the diverse features of the Testcontainers Desktop application, which help us run and debug Testcontainers. We explored freezing container shutdowns, employing fixed ports, and accessing a terminal attached to the container. Additionally, we looked at the Testcontainers Dashboard, a tool that enhances visibility and insights into testing activities.

As always, the code examples used in this article are available over on GitHub.

       

1. Introduction

In this tutorial, we’ll clarify the difference between GroupId and ConsumerId in Apache Kafka, which is important in understanding how to set up consumers correctly. In addition, we’ll touch on the difference between ClientId and ConsumerId and see how they are related to each other.

2. Consumer Groups

Before exploring the differences between identifier types in Apache Kafka, let’s understand Consumer Groups.

Consumer Groups consist of multiple consumers who work together to consume messages from one or more topics, accomplishing parallel message processing. They enable scalability, fault tolerance, and efficient parallel processing of messages in a distributed Kafka environment.

Crucially, each consumer within the group is responsible for processing only a subset of its topic, known as a partition.

3. Understanding Identifiers

Next, let’s define at a high level all of the identifiers we’re considering in this tutorial:

• GroupId uniquely identifies a Consumer Group.
• ClientId uniquely identifies a request that is passed to the server.
• ConsumerId is assigned to individual consumers within a Consumer Group and is a combination of the client.id consumer property and the consumer’s unique identifier.

4. Purpose of Identifiers

Next, let’s understand the purpose of each identifier.

GroupId is central to the load-balancing mechanism, enabling the distribution of partitions among consumers. Consumer Groups manage the coordination, load balancing, and partition assignment among consumers within the same group. Kafka ensures that only one consumer has access to each partition at any given time. If a consumer within the group fails, Kafka seamlessly reassigns the partition to other consumers to maintain continuity of message processing.

Kafka uses ConsumerIds to ensure that each consumer within the group is uniquely identifiable when interacting with the Kafka broker. This identifier, fully managed by Kafka, is used for managing consumer offsets and tracking the progress in processing messages from partitions.

Lastly, ClientId tracks the source of requests, beyond just IP/port, by allowing the developer to configure a logical application name that will be included in server-side request logging. Because we have control over this value, we could create two separate clients with the same ClientId. However, in this case, the ConsumerId generated by Kafka will be different.

5. Configuring GroupId and ConsumerId

5.1. Using Spring Kafka

Let’s define GroupId and ConsumerId for our consumers in Spring Kafka. We’ll achieve this by leveraging the @KafkaListener annotation:

@KafkaListener(topics = "${kafka.topic.name:test-topic}", clientIdPrefix = "neo", groupId = "${kafka.consumer.groupId:test-consumer-group}", concurrency = "4")
public void receive(@Payload String payload, Consumer<String, String> consumer) {
    LOGGER.info("Consumer='{}' received payload='{}'", consumer.groupMetadata()
      .memberId(), payload);
    this.payload = payload;
  
    latch.countDown();
}

Notice how we specified the groupId property to an arbitrary value of our choice.

Additionally, we’ve set the clientIdPrefix property to contain a custom prefix. Let’s inspect application logs to verify that the ConsumerId contains this prefix:

c.b.s.kafka.groupId.MyKafkaConsumer      : Consumer='neo-1-bae916e4-eacb-485a-9c58-bc22a0eb6187' received payload='Test 123...'

The value of consumerId, also known as memberId, follows a specific pattern. It starts with the clientIdPrefix, followed by a counter based on the number of consumers in the group, and finally, a UUID.

5.2. Using Kafka CLI

We can also configure the GroupId and ConsumerId via CLI. We’ll work with the kafka-console-consumer.sh script. Let’s start a console consumer with group.id set to test-consumer-group and client.id property set to neo-<sequence_number>:

$ kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic Test --group test-consumer-group --consumer-property "client.id=neo-1"

In this case, we must ensure that each client is assigned a unique client.id. This behavior is different from Spring Kafka, where we set the clientIdPrefix and the framework adds a sequence number to it. If we describe the consumer group, we’ll see the ConsumerId generated by Kafka for each consumer:

kafka-consumer-groups.sh --bootstrap-server localhost:9092 --group test-consumer-group --describe

GROUP               TOPIC           PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG             CONSUMER-ID                                HOST            CLIENT-ID
test-consumer-group Test            0          0               0               0               neo-1-975feb3f-9e5a-424b-9da3-c2ec3bc475d6 /127.0.0.1      neo-1
test-consumer-group Test            1          0               0               0               neo-1-975feb3f-9e5a-424b-9da3-c2ec3bc475d6 /127.0.0.1      neo-1
test-consumer-group Test            2          0               0               0               neo-1-975feb3f-9e5a-424b-9da3-c2ec3bc475d6 /127.0.0.1      neo-1
test-consumer-group Test            3          0               0               0               neo-1-975feb3f-9e5a-424b-9da3-c2ec3bc475d6 /127.0.0.1      neo-1
test-consumer-group Test            7          0               0               0               neo-3-09b8d4ee-5f03-4386-94b1-e068320b5e6a /127.0.0.1      neo-3
test-consumer-group Test            8          0               0               0               neo-3-09b8d4ee-5f03-4386-94b1-e068320b5e6a /127.0.0.1      neo-3
test-consumer-group Test            9          0               0               0               neo-3-09b8d4ee-5f03-4386-94b1-e068320b5e6a /127.0.0.1      neo-3
test-consumer-group Test            4          0               0               0               neo-2-6a39714e-4bdd-4ab8-bc8c-5463d78032ec /127.0.0.1      neo-2
test-consumer-group Test            5          0               0               0               neo-2-6a39714e-4bdd-4ab8-bc8c-5463d78032ec /127.0.0.1      neo-2
test-consumer-group Test            6          0               0               0               neo-2-6a39714e-4bdd-4ab8-bc8c-5463d78032ec /127.0.0.1      neo-2

6. Summary

Let’s summarize the key differences between the three identifiers we’ve discussed:

7. Conclusion

In this article, we’ve looked at some of the key identifiers associated with Kafka consumers: GroupId, ClientId, and ConsumerId. We now understand their purpose and how to configure them.

As always, the complete source code is available over on GitHub.

       

1. Overview

In this short tutorial, we’ll explore different ways of getting the first n characters of a string in Java.

First, we’ll learn how to do this using core JDK methods and classes. Then, we’ll see how to achieve the same outcome using external libraries such as Apache Commons Lang and Guava.

2. Using Core JDK

JDK provides several methods that we can use to get the first n characters of a given string. So, let’s take a close look at each option.

2.1. Using String#substring Method

The substring() method belongs to the String class and offers the easiest solution to answer our central question. As the name implies, this method returns as a new string a subset of the given string.

So, let’s see it in action:

@Test
void givenString_whenUsingSubstringMethod_thenGetFirstChars() {
    String givenInput = "Hello Baeldung Readers";
    assertEquals("He", givenInput.substring(0, 2));
}

The method accepts two arguments, beginIndex and endIndex. beginIndex denotes the index of the first character and endIndex represents the last index which is exclusive.

With that being said, the returned substring starts at the specified endIndex and extends to the character at the index endIndex – 1.

2.2. Using String#subSequence Method

Another solution would be to use the subSequence() method. It returns a CharSequence object that holds a portion of the specified string.

The invocation of subSequence(start, end) behaves exactly like the invocation of the substring(start, end) method. So, let’s see it in action:

@Test
void givenString_whenUsingSubSequenceMethod_thenGetFirstChars() {
    String givenInput = "Welcome";
    assertEquals("Wel", givenInput.subSequence(0, 3));
}

Similarly, the method returns the first three characters “Wel” of the string “Welcome”. We should remember that this method throws IndexOutOfBoundsException if beginIndex or endIndex is negative, or if endIndex is greater than the string length, or when beginIndex is greater than endIndex.

2.3. Using String#chars Method

The String class provides the chars() as another option to retrieve the first n characters. This new method is introduced in Java 9 to manipulate a given string as a Stream.

So, let’s exemplify the use of the chars() method using another test case:

@Test
void givenString_whenUsingStreamApi_thenGetFirstChars() {
    String givenInput = "The world is beautiful";
    String result = givenInput.chars()
      .limit(3)
      .collect(StringBuilder::new, StringBuilder::appendCodePoint, StringBuilder::append)
      .toString();
    assertEquals("The", result);
}

In a nutshell, chars() returns an IntStream holding the char values of the string input. Furthermore, we used the limit(3) method to retrieve the first three values. Then, we used collect() with StringBuilder to build a string from the returned values.

3. Using Apache Commons Lang

Alternatively, we can use the Apache Commons Lang library to tackle our challenge. It comes with a set of utility classes, such as StringUtils, that we can use to perform string operations.

First, let’s add its dependency to the pom.xml file:

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.14.0</version>
</dependency>

3.1. Using StringUtils#substring Method

Typically, StringUtils provides its version of the substring() method. The particularity of this method is that it’s null-safe compared to String#substring:

@Test
void givenString_whenUsingStringUtilsSubstringMethod_thenGetFirstChars() {
    String givenInput = "Baeldung";
    assertEquals("Baeld", StringUtils.substring(givenInput, 0, 5));
}

As shown above, the returned substring “Baeld” starts with the character in the position zero and ends before the  position 5.

3.2. Using StringUtils#left Method

Similarly, we can use the left() method to accomplish the same outcome. This method returns the leftmost n characters of the given string.

So, let’s illustrate how to use StringUtils#left using a practical example:

@Test
void givenString_whenUsingStringUtilsLeftMethod_thenGetFirstChars() {
    String givenInput = "kindness always wins";
    assertEquals("kind", StringUtils.left(givenInput, 4));
}

The good thing about this method is that it’s null-safe as it returns null if the specified string input is null.

4. Using Guava

Another solution would be using the Guava. As usual, before starting to work with this library, we need to add its dependency to pom.xml:

<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>33.0.0-jre</version>
</dependency>

Guava provides the Ascii#truncate method that we can use as a workaround to get the first characters of a string:

@Test
void givenString_whenUsingGuavaTruncateMethod_thenGetFirstChars() {
    String givenInput = "Tamassint";
    assertEquals("Tama", Ascii.truncate(givenInput, 4, ""));
}

In short, this method truncates the given string to the specified maximum length of 4 in our case.

5. Conclusion

In this short article, we explored various ways of getting the first n characters of a given string in Java.

Along the way, we saw how to use JDK methods and classes. Then, we learned how to achieve the same objective using external libraries such as Apache Commons Lang and Guava.

As always, the code used in this article can be found over on GitHub.

       

1. Spring and Java

>> How to use Java Records with Spring Data JPA [vladmihalcea.com]

Records meet JPA: a practical guide on how to use Java Records with Spring Data JPA Repositories.

>> How Netflix Really Uses Java [infoq.com]

Exploring the dynamic world of Java at Netflix: enhancing streaming services with cutting-edge Java technologies. Always good stuff out of Netflix.

Also worth reading:

• >> Cloud Cost Optimization Is Hard, Java Can Help [foojay.io]
• >> ClassNotFoundException: java.util.SequencedCollection [aphyr.com]
• >> The road to generated SDKs with Kiota using Quarkus [quarkus.io]
• >> Periodic Face-to-Face [martinfowler.com]
• >> Microservices Modernization Missteps: Four Anti-Patterns of Rebuilding Apps [tanzu.vmware.com]
• >> Thanks FedEx, This is Why we Keep Getting Phished [troyhunt.com]
• >> Should you always keep streams short in Event Sourcing? [event-driven.io]
• >> The road to generated SDKs with Kiota using Quarkus [quarkus.io]

Webinars and presentations:

• >> A Bootiful Podcast: Timefold Solver AI lead Geoffrey De Smet [spring.io]
• >> The State of OpenJDK [inside.java]
• >> Java’s Custom Runtime Builder – jlink [inside.java]
• >> Foojay Podcast #43: Modern Java Testing [foojay.io]

Time to upgrade:

• >> Spring Boot 3.1.9, 3.2.3, and 3.3.0-M2 available now [spring.io]
• >> Spring Authorization Server 1.2.2, 1.1.5, and 1.3.0-M2 available now [spring.io]
• >> Spring for GraphQL 1.2.5 and 1.3 M1 released [spring.io]
• >> Spring for Apache Kafka 3.0.14, 3.1.2 and 3.2.0-M1 Available Now [spring.io]
• >> This Week in Spring – February 20th, 2024 [spring.io]
• >> Spring Batch 5.0.5 and 5.1.1 available now [spring.io]
• >> Spring Security 6.2.2, 6.1.7, and 5.8.10 are now available [spring.io]
• >> Spring LDAP 3.1.4 and 3.2.2 are available [spring.io]
• >> The arrival of the Java Card Development Kit 24.0 [oracle.com]
• >> Spring AI 0.8.0 Released [spring.io]
• >> Spring Modulith 1.0.6, 1.1.3 and 1.2 M2 released [spring.io]

2. Technical & Musings

>> Periodic Face-to-Face [martinfowler.com]

The value of periodic face-to-face meetings – nurturing effective communication in distributed teams.

>> Secure your API with these 16 Practices with Apache APISIX – part 2 [frankel.ch]

And plenty of best practices to follow to have a secured and well-protected API configuration.

Also worth reading:

• >> Microservices Modernization Missteps: Four Anti-Patterns of Rebuilding Apps [tanzu.vmware.com]
• >> Should you always keep streams short in Event Sourcing? [event-driven.io]
• >> 12 Lessons Learned From Doing The One Billion Row Challenge [foojay.io]
• >> Thanks FedEx, This is Why we Keep Getting Phished [troyhunt.com]
• >> Hello eBPF: Tail calls and your first eBPF application (4) [foojay.io]
• >> Should you always keep streams short? [event-driven.io]

3. Pick of the Week

>> Falsehoods Junior Developers believe about becoming Senior [vadimkravcenko.com]

       

1. Overview

String manipulation is a common task in Java programming. Sometimes, trailing whitespace can lead to inconsistencies, increase storage sizes, and even cause unintended bugs.

In this quick tutorial, we’ll explore effective techniques to remove only trailing spaces or whitespace characters from a given String in Java.

2. Introduction to the Problem

Let’s first create an input String as our example:

final static String INPUT = "  a b c d e \t  ";

When we talk about removing the trailing whitespace characters, the trim() method may come up as the first idea. However, the trim() method removes both leading and trailing whitespace characters:

String result = INPUT.trim();
assertEquals("a b c d e", result);

We must keep the leading whitespace characters in the original input. Therefore, trim() doesn’t solve our problem.

Depending on the requirement, we might need to eliminate all trailing whitespace or exclusively trailing space characters. It’s important to recognize that whitespace includes space and other characters such as TAB (‘\t’).

For instance, considering INPUT as an example, removing its trailing whitespace would yield ” a b c d e”. Conversely, if we intend to remove only trailing space characters from INPUT, we would expect to obtain ” a b c d e \t”. As we can see, the TAB character remains intact.

In this tutorial, we’ll cover these two scenarios and address different solutions to remove trailing spaces or whitespace.

Next, let’s dive into coding.

3. Using Regex and the replaceAll() Method

Regex proves to be a powerful utility for manipulating Strings in Java. By crafting a Regex pattern to match trailing spaces or whitespace, we can effectively utilize the replaceAll() method to address the issue.

For example, since the pattern ” +$” matches trailing consecutive space characters, we can pass this Regex pattern to replaceAll() to remove trailing spaces:

String result1 = INPUT.replaceAll(" +$", "");
assertEquals("  a b c d e \t", result1);

As we can see, the TAB character and the spaces before it remain intact.

Similarly, “\\s+$” is a pattern that removes all trailing whitespace:

String result2 = INPUT.replaceAll("\\s+$", "");
assertEquals("  a b c d e", result2); 

4. Using the stripTrailing() Method

In Java 11, the stripTrailing() method was introduced as a new addition to the String class. As its name implies, stripTrailing() allows us to remove trailing whitespace conveniently:

String result = INPUT.stripTrailing();
assertEquals("  a b c d e", result);

5. Using Apache Commons Lang 3’s stripEnd()

Apache Commons Lang 3 is a widely used library. Its StringUtils class provides a rich set of handy utilities for String manipulations. For example, the stripEnd() method eliminates specified trailing characters from the input String. Therefore, we can use it to remove trailing spaces:

String result = StringUtils.stripEnd(INPUT, " ");
assertEquals("  a b c d e \t", result);

It’s worth mentioning that since stripEnd() only takes a predefined String as the stripChars parameter, we cannot use this method to remove trailing whitespace characters.

6. Conclusion

In this article, we explored different approaches to remove trailing spaces or whitespace. These solutions encompass both the Java standard library and an external library, Apache Commons Lang 3.

As always, the complete source code for the examples is available over on GitHub.

       

1. Overview

A database view is a table-like structure in a relational database system in which the data source is from one or more tables joined together.

While Spring Data repositories are commonly used for database tables, they can be effectively applied to database views as well. In this tutorial, we’ll explore adopting Spring Data repositories for database views.

2. Database Table Setup

In this tutorial, we’ll adopt the H2 database system for data definition and demonstrate the database view concept using two example tables — SHOP and SHOP_TRANSACTION.

The SHOP table stores the shop information:

CREATE TABLE SHOP
(
    shop_id             int             AUTO_INCREMENT,
    shop_location       varchar(100)    NOT NULL UNIQUE,
    PRIMARY KEY(shop_id)
);

And the SHOP_TRANSACTION table stores transaction records associated with shops and references to the SHOP table via the shop_id:

CREATE TABLE SHOP_TRANSACTION
(
    transaction_id      bigint          AUTO_INCREMENT,
    transaction_date    date            NOT NULL,
    shop_id             int             NOT NULL,
    amount              decimal(8,2)    NOT NULL,
    PRIMARY KEY(transaction_id),
    FOREIGN KEY(shop_id) REFERENCES SHOP(shop_id)
);

In the Entity-Relationship (ER) model, we can illustrate it as a one-to-many relationship where one shop can have multiple transactions. Still, each transaction is associated with one shop only. We can represent this visually using an ER diagram:

3. Database View

A database view provides a virtual table that gathers data from the result of a predefined query. There are advantages to using a database view instead of using a join query:

• Simplicity – Views encapsulate complex joins, eliminating the need to rewrite the same join query repeatedly
• Security – Views may only include a subset of data from the base tables, reducing the risk of exposing sensitive information from base tables
• Maintainability – Updating view definitions when the base table structure changes prevents the need to modify queries referencing the altered base table in our application

3.1. Standard View and Materialized View

There are two common types of database views, and they serve different purposes:

• Standard Views – These are generated by executing a predefined SQL query when queried. They do not store data themselves. All data is stored in the underlying base tables.
• Materialized Views – These are similar to standard views, which are also generated from a predefined SQL query. In contrast, they copy the query result to a physical table in the database. Subsequent queries retrieve data from this table rather than generating it dynamically.

The following comparison table highlights the varying characteristics of standard and materialized views, aiding in selecting the appropriate view type based on specific requirements:

3.2. Standard View Example

In our example, we would like to define a view that concludes the total sales amount of shops for each calendar month. The materialized view proves suitable since past sales amounts from previous months remain unchanged. Real-time data is unnecessary for calculating total sales unless the current month’s data is required.

However, the H2 database does not support materialized views. We’ll create a standard view instead:

CREATE VIEW SHOP_SALE_VIEW AS
SELECT ROW_NUMBER() OVER () AS id, shop_id, shop_location, transaction_year, transaction_month, SUM(amount) AS total_amount
FROM (
    SELECT 
        shop.shop_id, shop.shop_location, trans.amount, 
        YEAR(transaction_date) AS transaction_year, MONTH(transaction_date) AS transaction_month
    FROM SHOP shop, SHOP_TRANSACTION trans
    WHERE shop.shop_id = trans.shop_id
) SHOP_MONTH_TRANSACTION
GROUP BY shop_id, transaction_year, transaction_month;

Upon querying the view, we should obtain data like the following:

4. Entity Bean Definition

We can now define the entity bean for our database view SHOP_SALE_VIEW. Indeed, the definition is almost the same as defining an entity bean for a normal database table.

In JPA, an entity bean has a requirement that it must have the primary key. There are two strategies that we can consider to define a primary key in a database view.

4.1. Physical Primary Key

In most scenarios, we can pick one or multiple columns in the view to identify the uniqueness of a row in the database view. In our scenario, the shop ID, year, and month can uniquely identify each row in the view.

Hence, we can derive the composite primary key by columns shop_id, transaction_year, and transaction_month. In JPA, we have to first define a separate class to represent the composite primary key:

public class ShopSaleCompositeId {
    private int shopId;
    private int year;
    private int month;
    // constructors, getters, setters
}

Subsequently, we embed this composite ID class into the entity class with @EmbeddedId and define the column mappings by annotating the composite ID by @AttributeOverrides:

@Entity
@Table(name = "SHOP_SALE_VIEW")
public class ShopSale {
    @EmbeddedId
    @AttributeOverrides({
      @AttributeOverride( name = "shopId", column = @Column(name = "shop_id")),
      @AttributeOverride( name = "year", column = @Column(name = "transaction_year")),
      @AttributeOverride( name = "month", column = @Column(name = "transaction_month"))
    })
    private ShopSaleCompositeId id;
    @Column(name = "shop_location", length = 100)
    private String shopLocation;
    @Column(name = "total_amount")
    private BigDecimal totalAmount;
    // constructor, getters and setters
}

4.2. Virtual Primary Key

In certain scenarios, defining a physical primary key is not feasible due to the absence of column combinations that can ensure the uniqueness of each row within the database view. We can generate a virtual primary key to emulate row uniqueness as a workaround.

In our database view definition, we have an additional column id that utilized ROW_NUMBER() OVER () to generate row numbers as identifiers. This is the entity class definition when we adopt a virtual primary key strategy:

@Entity
@Table(name = "SHOP_SALE_VIEW")
public class ShopSale {
    @Id
    @Column(name = "id")
    private Long id;
    @Column(name = "shop_id")
    private int shopId;
    @Column(name = "shop_location", length = 100)
    private String shopLocation;
    @Column(name = "transaction_year")
    private int year;
    @Column(name = "transaction_month")
    private int month;
    @Column(name = "total_amount")
    private BigDecimal totalAmount;
    // constructors, getters and setters
}

It’s crucial to note that these identifiers are specific to the current result set. The row numbers assigned to each row could be different upon re-query. As a result, the same row number in subsequent queries may represent different rows in the database view.

5. View Repository

Depending on the database, systems such as Oracle may support updatable views that allow data updates on them under some conditions. However, database views are mostly read-only.

For read-only database views, it’s unnecessary to expose data modifying methods such as save() or delete() in our repositories. Attempting to call these methods will throw an exception since the database system doesn’t support such operations:

org.springframework.orm.jpa.JpaSystemException: could not execute statement [Feature not supported: "TableView.addRow"; SQL statement:
insert into shop_sale_view (transaction_month,shop_id,shop_location,total_amount,transaction_year,id) values (?,?,?,?,?,?) [50100-224]] [insert into shop_sale_view (transaction_month,shop_id,shop_location,total_amount,transaction_year,id) values (?,?,?,?,?,?)]

In such rationale, we’ll exclude these methods and expose only data retrieval methods when defining our Spring Data JPA Repository.

5.1. Physical Primary Key

For views with a physical primary key, we can define a new base repository interface that only exposes data retrieval methods:

@NoRepositoryBean
public interface ViewRepository<T, K> extends Repository<T, K> {
    long count();
    boolean existsById(K id);
    List<T> findAll();
    List<T> findAllById(Iterable<K> ids);
    Optional<T> findById(K id);
}

The @NoRepositoryBean annotation indicates this interface is a base repository interface and instructs Spring Data JPA not to create an instance of this interface at runtime. In this repository interface, we include all data retrieval methods from ListCrudRepository and exclude all data-changing methods.

For our entity bean with composite ID, we extend ViewRepository and define an additional method for querying the shop sale for the shopId:

public interface ShopSaleRepository extends ViewRepository<ShopSale, ShopSaleCompositeId> {
    List<ShopSale> findByIdShopId(Integer shopId);
}

We’ve defined the query method as findByIdShopId() instead of findByShopId() because it derives from the property id.shopId in the ShopSale entity class.

5.2. Virtual Primary Key

Our approach has a slight difference when we’re dealing with the repository design for database views with a virtual primary key since the virtual primary key is an artificial one that cannot truly identify the uniqueness of data rows.

Due to this nature, we’ll define another base repository interface that excludes the query methods by primary key as well. It’s because we’re using a virtual primary key, and it makes no sense for us to retrieve data using a fake primary key:

public interface ViewNoIdRepository<T, K> extends Repository<T, K> {
    long count();
    List<T> findAll();
}

Subsequently, let’s define our repository by extending it to ViewNoIdRepository:

public interface ShopSaleRepository extends ViewNoIdRepository<ShopSale, Long> {
    List<ShopSale> findByShopId(Integer shopId);
}

Since the ShopSale entity class defines the shopId directly this time, we can use findByShopId() in our repository.

6. Conclusion

This article has provided an introduction to database views, offering a brief comparison between standard views and materialized views.

Furthermore, we’ve described applying different primary key strategies on database views depending on the nature of the data. Finally, we explored the definition of an entity bean and base Repository interfaces based on the key strategies we had chosen.

As usual, the examples discussed are available over on GitHub.

       

1. Overview

In some cases, when we’re saving an entity using a Spring Data JPA Repository, we may encounter an additional SELECT in the logs. This may cause performance issues due to numerous extra calls.

In this tutorial, we’ll explore a few methods to skip SELECT in logs and improve performance.

2. Setup

Before diving into Spring Data JPA and testing it, there are a few preparatory steps we need to take.

2.1. Dependencies

To create our test repositories we’ll use Spring Data JPA dependency:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

As a test database, we’ll use the H2 Database. Let’s add its dependency:

<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
</dependency>

In our integrational tests, we’ll use a test Spring Context. Let’s add the spring-boot-starter-test dependency:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

2.2. Configuration

Here is the JPA configuration we’ll use in our example:

spring.jpa.hibernate.dialect=org.hibernate.dialect.H2Dialect
spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.hibernate.show_sql=true
spring.jpa.hibernate.hbm2ddl.auto=create-drop

According to this configuration, we’ll let Hibernate generate the schema and log all the SQL queries into the log.

3. The Reason for the SELECT Query

First things first, let’s create an entity:

@Entity
public class Task {
    @Id
    private Integer id;
    private String description;
    //getters and setters
}

Now, let’s create a repository for this entity:

@Repository
public interface TaskRepository extends JpaRepository<Task, Integer> {
}

Now, let’s save a new Task specifying the ID:

@Autowired
private TaskRepository taskRepository;
@Test
void givenRepository_whenSaveNewTaskWithPopulatedId_thenExtraSelectIsExpected() {
    Task task = new Task();
    task.setId(1);
    taskRepository.saveAndFlush(task);
}

When we call the saveAndFlush() – the behavior for the save() method will be the same – method of our repository, internally we use this code:

public<S extends T> S save(S entity){
    if(isNew(entity)){
        entityManager.persist(entity);
        return entity;
    } else {
        return entityManager.merge(entity);
    }
}

So, if our entity is considered as not new, we’ll call the merge() method of the entity manager. Inside merge() JPA checks if our entity is present in a cache and persistence context. Since our object is new it’ll not be found there.  Finally, it tries to load the entity from the data source.

This is the point where we come across the SELECT query in the logs. Since we don’t have such an item in the database, we invoke the INSERT query after that:

Hibernate: select task0_.id as id1_1_0_, task0_.description as descript2_1_0_ from task task0_ where task0_.id=?
Hibernate: insert into task (id, description) values (default, ?)

public boolean isNew(T entity) {
    ID id = this.getId(entity);
    return id == null;
}

If we specify the ID on the application side, our entity will be considered new. An extra SELECT query will be sent to the database in that case.

4. Use @GeneratedValue

One of the possible solutions is to not specify the ID on the application side. We can use @GeneratedValue annotation and specify a strategy that’ll be used to generate ID on the database side.

Let’s specify the generation strategy for our TaskWithGeneratedId ID:

@Entity
public class TaskWithGeneratedId {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;
}

Then,  we save an instance of the TaskWithGeneratedId entity, but now we don’t set the ID:

@Autowired
private TaskWithGeneratedIdRepository taskWithGeneratedIdRepository;
@Test
void givenRepository_whenSaveNewTaskWithGeneratedId_thenNoExtraSelectIsExpected() {
    TaskWithGeneratedId task = new TaskWithGeneratedId();
    TaskWithGeneratedId saved = taskWithGeneratedIdRepository.saveAndFlush(task);
    assertNotNull(saved.getId());
}

As we can see in the logs, there are no SELECT queries in the logs and a new ID was generated for the entity.

5. Implement Persistable

Another option we have is to implement the Persistable interface in our entity:

@Entity
public class PersistableTask implements Persistable<Integer> {
    @Id
    private int id;
    @Transient
    private boolean isNew = true;
    @Override
    public Integer getId() {
        return id;
    }
    @Override
    public boolean isNew() {
        return isNew;
    }
    
    //getters and setters
}

Here we’ve added a new field isNew and annotated it as @Transient to not create a column in the base. Using the overridden isNew() method we can consider our entity as new even though we have an ID specified.

Now, under the hood, JPA uses another logic to consider if an entity is new or not:

public class JpaPersistableEntityInformation {
    public boolean isNew(T entity) {
        return entity.isNew();
    }
}

Let’s save our PersistableTask using the PersistableTaskRepository:

@Autowired
private PersistableTaskRepository persistableTaskRepository;
@Test
void givenRepository_whenSaveNewPersistableTask_thenNoExtraSelectIsExpected() {
    PersistableTask persistableTask = new PersistableTask();
    persistableTask.setId(2);
    persistableTask.setNew(true);
    PersistableTask saved = persistableTaskRepository.saveAndFlush(persistableTask);
    assertEquals(2, saved.getId());
}

As we can see, we’ll have only the INSERT log message and the entity contains the ID we specified.

If we try to save a few new entities with the same ID, we encounter an exception:

@Test
void givenRepository_whenSaveNewPersistableTasksWithSameId_thenExceptionIsExpected() {
    PersistableTask persistableTask = new PersistableTask();
    persistableTask.setId(3);
    persistableTask.setNew(true);
    persistableTaskRepository.saveAndFlush(persistableTask);
    PersistableTask duplicateTask = new PersistableTask();
    duplicateTask.setId(3);
    duplicateTask.setNew(true);
    assertThrows(DataIntegrityViolationException.class,
      () -> persistableTaskRepository.saveAndFlush(duplicateTask));
}

So, if we take the responsibility to generate the IDs, we also should take care of their uniqueness.

6. Use persist() Method Directly

As we saw in previous examples, all the actions we did led us to call the persist() method. We also can create an extension for our repository that allows us to call this method directly.

Let’s create an interface with the persist() method:

public interface TaskRepositoryExtension {
    Task persistAndFlush(Task task);
}

Then, let’s make an implementation bean of this interface:

@Component
public class TaskRepositoryExtensionImpl implements TaskRepositoryExtension {
    @PersistenceContext
    private EntityManager entityManager;
    @Override
    public Task persistAndFlush(Task task) {
        entityManager.persist(task);
        entityManager.flush();
        return task;
    }
}

Now, we extend our TaskRepository using a new interface:

@Repository
public interface TaskRepository extends JpaRepository<Task, Integer>, TaskRepositoryExtension {
}

Let’s call our custom persistAndFlush() method to save the Task instance:

@Test
void givenRepository_whenPersistNewTaskUsingCustomPersistMethod_thenNoExtraSelectIsExpected() {
    Task task = new Task();
    task.setId(4);
    Task saved = taskRepository.persistAndFlush(task);
    assertEquals(4, saved.getId());
}

We can see the log message with an INSERT call and no extra SELECT calls.

7. Use BaseJpaRepository From Hypersistence Utils

The idea from the previous section was already implemented in the Hypersistence Utils project. This project provides us a BaseJpaRepository where we have the persistAndFlush()  method implementation as well as its batch analog.

To use it, we have to specify additional dependencies. We should choose a correct Maven artifact based on our Hibernate version:

<dependency>
    <groupId>io.hypersistence</groupId>
    <artifactId>hypersistence-utils-hibernate-55</artifactId>
</dependency>

Let’s implement another repository, that extends both BaseJpaRepository from Hypersistence Utils and JpaRepository from Spring Data JPA:

@Repository
public interface TaskJpaRepository extends JpaRepository<Task, Integer>, BaseJpaRepository<Task, Integer> {
}

Also, we have to enable the implementation of BaseJpaRepository using @EnableJpaRepositories annotation:

@EnableJpaRepositories(
    repositoryBaseClass = BaseJpaRepositoryImpl.class
)

Now, let’s save our Task using our new repository:

@Autowired
private TaskJpaRepository taskJpaRepository;
@Test
void givenRepository_whenPersistNewTaskUsingPersist_thenNoExtraSelectIsExpected() {
    Task task = new Task();
    task.setId(5);
    Task saved = taskJpaRepository.persistAndFlush(task);
    assertEquals(5, saved.getId());
}

We have our Task saved and there are no SELECT queries in the log.

Like in all the examples where we specified ID on the application side, there can be unique constraints violations:

@Test
void givenRepository_whenPersistTaskWithTheSameId_thenExceptionIsExpected() {
    Task task = new Task();
    task.setId(5);
    taskJpaRepository.persistAndFlush(task);
    Task secondTask = new Task();
    secondTask.setId(5);
    assertThrows(DataIntegrityViolationException.class,
      () ->  taskJpaRepository.persistAndFlush(secondTask));
}

8. Use @Query Annotated Method

We also can avoid extra calls using modifying native queries directly. Let’s specify a such method in our TaskRepository:

@Repository
public interface TaskRepository extends JpaRepository<Task, Integer> {
    @Modifying
    @Query(value = "insert into task(id, description) values(:#{#task.id}, :#{#task.description})", 
      nativeQuery = true)
    void insert(@Param("task") Task task);
}

This method calls the INSERT query directly avoiding the work with persistence context. The ID will be taken from the Task object sent in the method parameters.

Now let’s save our Task using this method:

@Test
void givenRepository_whenPersistNewTaskUsingNativeQuery_thenNoExtraSelectIsExpected() {
    Task task = new Task();
    task.setId(6);
    taskRepository.insert(task);
    assertTrue(taskRepository.findById(6).isPresent());
}

The entity was successfully saved using the ID without extra SELECT queries before INSERT.  We should consider, that by using this method we avoid a JPA context and Hibernate cache.

9. Conclusion

When implementing ID generation on the application side using Spring Data JPA, we may encounter occurrences of additional SELECT queries in the logs, leading to performance degradation. In this article, we’ve discussed various strategies to address this issue.

In some cases, it makes sense to move this logic to the database side or fine-tune the persistence logic according to our needs. We should take into account the pros, cons, and potential issues of each strategy before making a decision.

As usual, the full source code can be found over on GitHub.

       

1. Overview

In this tutorial, we’ll discuss converting a JSON array into an equivalent java.util.List object. Gson is a Java library by Google that helps convert JSON strings to Java objects and vice versa.

The Gson class in this library has the method fromJson() that takes in two arguments, the first argument is JSON String and the second argument is of type java.lang.reflect.Type. The method converts the JSON String to an equivalent Java object of type represented by its second argument.

We’ll come up with a generic method, say convertJsonArrayToListOfAnyType(String jsonArray, T elementType), that can convert the JSON array into List<T>, where T is the type of elements in the List.

Let’s understand more about this.

2. Problem Description

Let’s assume we have two JSON arrays, one for Student and one for School:

final String jsonArrayOfStudents =
    "["
      + "{\"name\":\"John\", \"grade\":\"1\"}, "
      + "{\"name\":\"Tom\", \"grade\":\"2\"}, "
      + "{\"name\":\"Ram\", \"grade\":\"3\"}, "
      + "{\"name\":\"Sara\", \"grade\":\"1\"}"
  + "]";
final String jsonArrayOfSchools =
    "["
      + "{\"name\":\"St. John\", \"city\":\"Chicago City\"}, "
      + "{\"name\":\"St. Tom\", \"city\":\"New York City\"}, "
      + "{\"name\":\"St. Ram\", \"city\":\"Mumbai\"}, "
      + "{\"name\":\"St. Sara\", \"city\":\"Budapest\"}"
  + "]";

Normally, we can use the Gson class to convert the arrays into List objects:

@Test
void givenJsonArray_whenListElementTypeDynamic_thenConvertToJavaListUsingTypeToken() {
    Gson gson = new Gson();
    TypeToken<List<Student>> typeTokenForListOfStudents = new TypeToken<List<Student>>(){};
    TypeToken<List<School>> typeTokenForListOfSchools = new TypeToken<List<School>>(){};
    List<Student> studentsLst = gson.fromJson(jsonArrayOfStudents, typeTokenForListOfStudents.getType());
    List<School> schoolLst = gson.fromJson(jsonArrayOfSchools, typeTokenForListOfSchools.getType());
    assertAll(
      () -> studentsLst.forEach(e -> assertTrue(e instanceof Student)),
      () -> schoolLst.forEach(e -> assertTrue(e instanceof School))
    );
}

We created the TypeToken objects for List<Student> and List<School>. Finally, using the TypeToken objects, we got the Type objects and then converted the JSON arrays into List<Student> and List<School>.

To promote reuse, let’s try creating a generic class with a method that can take the element type in the List and return the Type object:

class ListWithDynamicTypeElement<T> {
    Type getType() {
        TypeToken<List<T>> typeToken = new TypeToken<List<T>>(){};
        return typeToken.getType();
    }
}

We’re instantiating a generic TypeToken<List<T>> for a given element type T. Then we’re returning the corresponding Type object. The list element type is available only at runtime.

Let’s see the method in action:

@Test
void givenJsonArray_whenListElementTypeDynamic_thenConvertToJavaListUsingTypeTokenFails() {
    Gson gson = new Gson();
    List<Student> studentsLst = gson.fromJson(jsonArrayOfStudents, new ListWithDynamicTypeElement<Student>().getType());
    assertFalse(studentsLst.get(0) instanceof Student);
    assertThrows(ClassCastException.class, () -> studentsLst.forEach(e -> assertTrue(e instanceof Student)));
}

While the method compiles, it fails in runtime and raises a ClassCastException when we try to iterate over studentLst. Also, we see that the elements in the list are not of type Student.

3. Solution Using getParameterized() in TypeToken

In the Gson 2.10 version, the getParamterized() method was introduced in the class TypeToken. This enabled developers to handle scenarios where the type information of the list elements is not available during the compile time.

Let’s see how this new method helps return the Type information of parameterized classes:

Type getGenericTypeForListFromTypeTokenUsingGetParameterized(Class elementClass) {
    return TypeToken.getParameterized(List.class, elementClass).getType();
}

The method getParamterized(), when called during runtime, would return the actual type of the List object along with its element type. Further, this would help the Gson class to convert the JSON array to the exact List object with the correct type information of its elements.

Let’s see the method in action:

@Test
void givenJsonArray_whenListElementTypeDynamic_thenConvertToJavaListUsingGetParameterized() {
    Gson gson = new Gson();
    List<Student> studentsLst = gson.fromJson(jsonArrayOfStudents, getGenericTypeForListFromTypeTokenUsingGetParameterized(Student.class));
    List<School> schoolLst = gson.fromJson(jsonArrayOfSchools, getGenericTypeForListFromTypeTokenUsingGetParameterized(School.class));
    assertAll(
      () -> studentsLst.forEach(e -> assertTrue(e instanceof Student)),
      () -> schoolLst.forEach(e -> assertTrue(e instanceof School))
    );
}

We used the method getGenericTypeForListFromTypeTokenUsingGetParameterized() to get the Type information of List<Student> and List<School>. Finally, using the method fromJson() we converted the JSON arrays successfully to their respective Java List objects.

4. Solution Using JsonArray

The Gson library has a JsonArray class to represent a JSON array. We’ll use it for converting the JSON array into the List object:

<T> List<T> createListFromJsonArray(String jsonArray, Type elementType) {
    Gson gson = new Gson();
    List<T> list = new ArrayList<>();
    JsonArray array = gson.fromJson(jsonArray, JsonArray.class);
    for(JsonElement element : array) {
        T item = gson.fromJson(element, elementType);
        list.add(item);
    }
    return list;
}

First, we’re converting the JSON array string into the JsonArray object using the usual fromJson() method in the Gson class. Then, we convert each JsonElement element in the JsonArray object to the target Type defined by the second argument elementType in the createListFromJsonArray() method.

Each of these converted elements is put into a List and then finally returned at the end.

Now, let’s see the method in action:

@Test
void givenJsonArray_whenListElementTypeDynamic_thenConvertToJavaListUsingJsonArray() {
    List<Student> studentsLst = createListFromJsonArray(jsonArrayOfStudents, Student.class);
    List<School> schoolLst = createListFromJsonArray(jsonArrayOfSchools, School.class);
    assertAll(
      () -> studentsLst.forEach(e -> assertTrue(e instanceof Student)),
      () -> schoolLst.forEach(e -> assertTrue(e instanceof School))
    );
}

We used the method createListFromJsonArray() to successfully convert both the JSON arrays of students and schools to List<Student> and List<School>.

5. Solution Using TypeToken From Guava

Similar to the TypeToken class in the Gson library, the TypeToken class in Guava also enables capturing generic types at runtime. Otherwise, this is not possible due to type erasure in Java.

Let’s see an implementation using the Guava TypeToken class:

<T> Type getTypeForListUsingTypeTokenFromGuava(Class<T> type) {
    return new com.google.common.reflect.TypeToken<List<T>>() {}
      .where(new TypeParameter<T>() {}, type)
      .getType();
}

The method where() returns a TypeToken object by replacing the type parameter with the class in the variable type.

Finally, we can look at it in action:

@Test
void givenJsonArray_whenListElementTypeDynamic_thenConvertToJavaListUsingTypeTokenFromGuava() {
    Gson gson = new Gson();
    List<Student> studentsLst = gson.fromJson(jsonArrayOfStudents, getTypeForListUsingTypeTokenFromGuava(Student.class));
    List<School> schoolLst = gson.fromJson(jsonArrayOfSchools, getTypeForListUsingTypeTokenFromGuava(School.class));
    assertAll(
      () -> studentsLst.forEach(e -> assertTrue(e instanceof Student)),
      () -> schoolLst.forEach(e -> assertTrue(e instanceof School))
    );
}

Again, we used the method fromJson() to convert the JSON array to the respective List objects. However, we got the Type object with the help of the Guava library in the method getTypeForListUsingTypeTokenFromGuava().

6. Solution Using ParameterizedType of Java Reflection API

ParameterizedType is an interface that is part of the Java reflection API. It helps represent parameterized types such as Collection<String>.

Let’s implement ParamterizedType to represent any class that has parameterized types:

public class ParameterizedTypeImpl implements ParameterizedType {
    private final Class<?> rawType;
    private final Type[] actualTypeArguments;
    private ParameterizedTypeImpl(Class<?> rawType, Type[] actualTypeArguments) {
        this.rawType = rawType;
        this.actualTypeArguments = actualTypeArguments;
    }
    public static ParameterizedType make(Class<?> rawType, Type ... actualTypeArguments) {
        return new ParameterizedTypeImpl(rawType, actualTypeArguments);
    }
    @Override
    public Type[] getActualTypeArguments() {
        return actualTypeArguments;
    }
    @Override
    public Type getRawType() {
        return rawType;
    }
    @Override
    public Type getOwnerType() {
        return null;
    }
}

The variable actualTypeArguments would store the class information of the type argument in the generic class, while rawType represents the generic class. The make() method returns the Type object of the parameterized class.

Finally, let’s see it in action:

@Test
void givenJsonArray_whenListElementTypeDynamic_thenConvertToJavaListUsingParameterizedType() {
    Gson gson = new Gson();
    List<Student> studentsLst = gson.fromJson(jsonArrayOfStudents, ParameterizedTypeImpl.make(List.class, Student.class));
    List<School> schoolLst = gson.fromJson(jsonArrayOfSchools, ParameterizedTypeImpl.make(List.class, School.class));
    assertAll(
      () -> studentsLst.forEach(e -> assertTrue(e instanceof Student)),
      () -> schoolLst.forEach(e -> assertTrue(e instanceof School))
    );
}

We used the make() method to get the Type information of the parameterized List class and successfully converted the JSON arrays to their respective List object forms.

7. Conclusion

In this article, we discussed four different ways of getting the Type information of a List<T> object during runtime. Finally, we used the Type object for converting the JSON array to a List object using the fromJson() method in the Gson library.

Since, ultimately, it is the fromJson() method that gets invoked, the performance of all these methods is close to each other. However, the TypeToken.getParamterized() method is the most succinct, so we recommend using it.

As usual, the code used is available over on GitHub.

       

1. Overview

Finding the largest prime less than a given number is a classic problem in computer science and mathematics.

In this short tutorial, we’ll explore two approaches to solve this problem in Java.

2. Use Brute Force

Let’s begin with the most straightforward way. We can find the largest prime under a given number by iterating backward from the given number until we find a prime. For each number, we check if it’s prime by verifying that it’s not divisible by any number less than itself except 1:

public static int findByBruteForce(int n) {
    for (int i = n - 1; i >= 2; i--) {
        if (isPrime(i)) {
            return i;
        }
    }
    return -1; // Return -1 if no prime number is found
}
public static boolean isPrime(int number) {
    for (int i = 2; i <= Math.sqrt(number); i++) {
        if (number % i == 0) {
            return false;
        }
    }
    return true;
}

The time complexity of the isPrime() method is O(√N), and we might need to check up to n numbers. Thus, the time complexity of this solution is O(N √N).

3. Use Sieve of Eratosthenes Algorithm

A more efficient way to find the most significant prime number under a given number is using the Sieve of Eratosthenes algorithm. This algorithm efficiently considers all prime numbers up to a given limit. Once we have all prime numbers, we can easily find the largest prime less than the given number:

public static int findBySieveOfEratosthenes(int n) {
    boolean[] isPrime = new boolean[n];
    Arrays.fill(isPrime, true);
    for (int p = 2; p*p < n; p++) {
        if (isPrime[p]) {
            for (int i = p * p; i < n; i += p) {
                isPrime[i] = false;
            }
        }
    }
    for (int i = n - 1; i >= 2; i--) {
        if (isPrime[i]) {
            return i;
        }
    }
    return -1;
}

This time, we use the same isPrime() method in the first solution. Our code follows three basic steps:

1. Initialize a boolean array isPrime[] to track prime status for numbers up to n, defaulting to true.
2. For each prime p, mark its multiples as non-prime (false) starting from p*p to n. This efficiently filters out non-prime numbers.
3. Iterate backward from n-1 to find the highest index marked true.

The time complexity of the Sieve of Eratosthenes is O(N log (log (N))), which is much more efficient than the brute force approach for large n.

4. Conclusion

In this tutorial, we’ve explored two ways to find the largest prime in Java under the given number. The brute force method is more straightforward but less efficient. The Sieve of Eratosthenes offers a more efficient solution with a time complexity of O(n log log n), making it the preferred choice for more significant numbers.

The example code from this article can be found over on GitHub.

       

1. Introduction

In this tutorial, we’ll use Netty to create a chat room app. In network programming, Netty stands out as a robust framework that simplifies the complexities of asynchronous I/O operations. We’ll explore how to build a basic chat server where multiple clients can connect and engage in real-time conversations.

2. Scenario

Messages sent to the server will be relayed to all connected clients. It’ll also keep a list of the last few messages sent so new clients can have context from the current conversation when they connect. To do this, we’ll only need a couple of event handlers to maintain communication between channels:

In Netty, communication is done through channels, which abstract asynchronous I/O operations over any protocol. That allows us to focus on application logic instead of networking code. Our application will work via the command line. We’ll write a server and a client app.

3. Creating a Custom Event Handler

For communication between channels, we’ll implement a SimpleChannelInboundHandler<String>, a generic implementation of ChannelInboundHandlerAdapter. This adapter allows us to focus on implementing only the events we care about. In this case, it’s channelRead0(), which is called when a message is received from the server. We’ll use this to simplify our use case since we’ll only exchange String messages.

3.1. Client Event Handler

Let’s start with the handler for client messages, which will print anything received by the server to the console, without modifications:

public class ClientEventHandler extends SimpleChannelInboundHandler<String> {
    @Override
    protected void channelRead0(ChannelHandlerContext ctx, String msg) {
        System.out.println(msg);
    }
}

Later, we’ll handle message sending by writing directly to the channel.

3.2. Message Object

Before we move on to server events, let’s write a POJO to represent every message sent to the server. We’ll register the date sent along with a user name and message:

public class Message {
    private final Instant time;
    private final String user;
    private final String message;
    public Message(String user, String message) {
        this.time = Instant.now();
        this.user = user;
        this.message = message;
    }
    // standard getters...
}

Then, we’ll include a few helpers, starting with how the messages will appear on the console when sent by the server:

@Override
public String toString() {
    return time + " - " + user + ": " + message;
}

Then, for parsing messages received by clients, we’ll use a CSV format. We’ll see how the client sends messages in this format when we create our client app:

public static Message parse(String string) {
    String[] arr = string.split(";", 2);
    return new Message(arr[0], arr[1]);
}

Limiting the split to 2 is important because the message part might contain a semicolon.

3.3. Server Event Handler

In our server event handler, we’ll first create a helper method for the other events we’ll override. Also, we’ll need a map of clients connected and a Queue to keep at most MAX_HISTORY elements:

public class ServerEventHandler extends SimpleChannelInboundHandler<String> {
    static final Map<String, Channel> clients = new HashMap<>();
    static final Queue<String> history = new LinkedList<>();
    static final int MAX_HISTORY = 5;
    private void handleBroadcast(Message message, ChannelHandlerContext context) {
        String channelId = context.channel()
          .id()
          .asShortText();
        
        clients.forEach((id, channel) -> {
            if (!id.equals(channelId))
                channel.writeAndFlush(message.toString());
        });
        // history-control code...
    }
    // ...
}

First, we get the channel ID as a key for our map. Then, for the broadcast, for every client connected, excluding the sender, we relay their message.

It’s important to note that writeAndFlush() receives an Object. And, since our handlers can only handle strings, it’s essential to call toString() so the client can correctly receive it.

In the end, we do history control. Every time we add a new message, we remove the oldest one if our list exceeds MAX_HISTORY items:

history.add(message.toString());
if (history.size() > MAX_HISTORY)
    history.poll();

Now, we can override channelRead0() and parse messages received from clients:

@Override
public void channelRead0(ChannelHandlerContext context, String msg) {
    handleBroadcast(Message.parse(msg), context);
}

Then, for every client that comes online, we add it to our clients list, relay old messages for context, and send a system message announcing the new client:

@Override
public void channelActive(final ChannelHandlerContext context) {
    Channel channel = context.channel();
    clients.put(channel.id().asShortText(), channel);
    history.forEach(channel::writeAndFlush);
    handleBroadcast(new Message("system", "client online"), context);
}

Finally, we override channelInactive(), called in the event of a client that went offline. This time, we only need to remove the client from the list and send a system message:

@Override
public void channelInactive(ChannelHandlerContext context) {
    Channel channel = context.channel();
    clients.remove(channel.id().asShortText());
    handleBroadcast(new Message("system", "client offline"), context);
}

4. Server Bootstrap App

Our handler does nothing independently, so we need an application to bootstrap and run it, which is a common template.

4.1. Registering Custom Components in the ChannelPipeline

To prepare the bootstrap, we select a channel implementation and implement a child handler, which serves the requests for the channel:

bootstrap.group(serverGroup, clientGroup)
  .channel(NioServerSocketChannel.class)
  .childHandler(new ChannelInitializer<SocketChannel>() {
      @Override
      public void initChannel(SocketChannel channel) {
          channel.pipeline()
            .addFirst(
              new StringDecoder(),
              new ServerEventHandler()
              new StringEncoder());
      }
  });

In the child handler, we define our processing pipeline. Since we’re only concerned about String messages, we’ll use the built-in String encoder and decoder, saving us some time by not having to encode/decode the exchanged byte buffers ourselves.

Lastly, since the order matters, we add the decoder, our ServerEventHandler, and the encoder. That’s because events flow through the pipeline from inbound to outbound.

We’ll bind our server to a host/port to finish our app, which returns a ChannelFuture. We’ll use this to wait until our async socket is closed with sync():

ChannelFuture future = bootstrap.bind(HOST, PORT).sync();
System.out.println("server started. accepting clients.");
future.channel().closeFuture().sync();

5. Client Bootstrap App

Finally, our client app follows a common client template for bootstrapping. Most importantly, when calling handler(), we’ll use our ClientEventHandler instead:

channel.pipeline().addFirst(
  new StringDecoder(), 
  new ClientEventHandler(), 
  new StringEncoder());

5.1. Handling Message Input

Finally, to handle user input, after connecting to the server, we’ll loop with a Scanner until we receive a user name, and then, until the message equals “exit.” Most importantly, we must use writeAndFlush() to send our message. We send the message in the format expected by Message.parse():

private static void messageLoop(Scanner scanner, Channel channel) {
    while (user.isEmpty()) {
        System.out.print("your name: ");
        user = scanner.nextLine();
    }
    while (scanner.hasNext()) {
        System.out.print("> ");
        String message = scanner.nextLine();
        if (message.equals("exit"))
            break;
        channel.writeAndFlush(user + ";" + message);
    }
}

6. Creating a Custom Event Listener

In Netty, event listeners play a crucial role in handling asynchronous events throughout the lifecycle of channels. An event listener is essentially a callback mechanism that we can use to react to the completion of any operation that returns a ChannelFuture.

We implement the ChannelFutureListener interface for custom behavior upon its completion. A ChannelFuture represents the result of an asynchronous operation, such as a connection attempt or an I/O operation.

ChannelFutureListener is useful because it defines default implementations like CLOSE_ON_FAILURE or FIRE_EXCEPTION_ON_FAILURE. But, since we won’t use these, let’s implement a GenericFutureListener that we’ll use for operation confirmations.

We’ll hold a custom event name for context, and we’ll check if our future is completed successfully. Otherwise, we’ll mark the status as “FAILED” before logging:

public class ChannelInfoListener implements GenericFutureListener<ChannelFuture> {
    private final String event;
    public ChannelInfoListener(String event) {
        this.event = event;
    }
    @Override
    public void operationComplete(ChannelFuture future) throws Exception {
        Channel channel = future.channel();
        String status = "OK";
        if (!future.isSuccess()) {
            status = "FAILED";
            future.cause().printStackTrace();
        }
        System.out.printf(
          "%s - channel#%s %s: %s%n", Instant.now(), channel.id().asShortText(), status, event);
    }
}

6.1. Event Receipts

Let’s return to some parts of our code to include listeners. First, for the client, let’s include a “connected to server” confirmation:

future.addListener(new ChannelInfoListener("connected to server"));

Then, let’s include a “message sent” confirmation in the message loop:

ChannelFuture sent = channel.writeAndFlush(user + ";" + message);
sent.addListener(new ChannelInfoListener("message sent"));

This allows us to ensure we’re still connected to the server when sending messages. Finally, for the server handler, let’s send a “message relayed” confirmation during the broadcast:

clients.forEach((id, channel) -> {
    if (!id.equals(channelId)) {
        ChannelFuture relay = channel.writeAndFlush(message.toString());
        relay.addListener(new ChannelInfoListener("message relayed to " + id));
    }
});

7. Seeing It in Action

Netty allows us to test pipelines with EmbeddedChannel, but for client/server interactions, let’s see what it looks like when running from the terminal. Let’s start the server (we’ll omit package names for readability):

$ mvn exec:java -Dexec.mainClass=ChatServerMain
chat server started. ready to accept clients.

Then, let’s start the first client, input a name, and send two messages:

$ mvn exec:java -Dexec.mainClass=ChatClientMain
2024-01-12 3:47:02 - channel#03c40ad4 OK: connected to server
your name: Bob
> Hello
2024-01-12 3:47:02 - channel#03c40ad4 OK: message sent
> Anyone there?!
2024-01-12 3:47:03 - channel#03c40ad4 OK: message sent

When we connect with a second client, we’ll get the message history before inputting a name:

$ mvn exec:java -Dexec.mainClass=ChatClientMain
2024-01-12 3:49:33 - channel#daa64476 OK: connected to server
2024-01-12 3:46:55 - system: client online: 03c40ad4
2024-01-12 3:47:03 - Bob: Hello
2024-01-12 3:48:40 - Bob: Anyone there?!

Naturally, after choosing a name and sending a message:

your name: Alice
> Hi, Bob!
2024-01-12 3:51:05 - channel#daa64476 OK: message sent

The first client will receive it:

2024-01-12 3:49:33 - system: client online: daa64476
2024-01-12 3:51:05 - Alice: Hi, Bob!

8. Conclusion

In this article, we successfully built a functional chat server using Netty, demonstrating the power and simplicity of this framework in handling asynchronous communication. Through implementing event handlers, we managed to relay messages among connected clients and maintain context history.

As always, the source code is available over on GitHub.