1. Introduction

In this tutorial, we’ll explore various approaches to validating geo coordinates and their accuracy in Java.

2. Understand Geo Coordinates

Geo coordinates are typically expressed as latitude and longitude values, pinpointing locations on our spherical Earth. Latitude measures the distance north or south of the equator and ranges from -90° (South Pole) to 90° (North Pole). On the other hand, longitude measures the distance east or west of the prime meridian and spans -180° (International Date Line) to 180°.

3. Understanding Precision and Accuracy

When checking the validity of coordinates, one crucial factor to consider is the precision of the decimal places. The level of detail expressed by a coordinate and associated with a location is indicated by precision, which is represented by the number of decimal places.

Furthermore, rounding coordinates can cause inaccuracies, especially in applications sensitive to proximity. For example, mapping a building might require coordinates accurate to five decimal places (approximately one meter), while city-level mapping might only need two decimal places (approximately one kilometer).

4. Latitude and Longitude Formats

Understanding the various formats is fundamental for both input and validation of coordinates.

4.1. Decimal Degrees (DD)

Geo coordinates are commonly represented in decimal degrees, where both latitude and longitude are expressed as decimal values. In the DD format, valid latitude values typically range from -90 to 90, while valid longitude values range from -180 to 180. For example, the coordinates for the Eiffel Tower in Paris are approximately 48.8588445 (latitude) and 2.2943506 (longitude).

4.2. Degrees, Minutes, and Seconds (DMS)

The DMS format involves degrees, minutes, and seconds, and latitude and longitude are expressed as degrees. Each degree is further divided into 60 minutes, and each minute can optionally be divided into 60 seconds. Symbols such as ° (degree), ‘ (minute), and ” (second) are used to separate these components. For instance, the coordinates for the Statue of Liberty are 40°41’21.7″N (latitude) and 74°02’40.7″W (longitude).

4.3. Military Grid Reference System (MGRS)

MGRS is another coordinate format used to specify locations on the Earth’s surface. It divides the world into grid zones and provides a concise representation of them. Each section is a 6° wide zone, numbered 1 to 60, further divided into 100,000-meter squares identified by two-letter codes. Within each square, precise positions are given by “Easting” and “Northing”, both measured in meters. For example, the Great Wall of China’s Badaling section can be located as 50TMK6356175784.

5. Basic Validation With Regular Expressions

Regular expressions are powerful tools for pattern matching. We can craft a regex pattern to identify valid coordinate formats using Java’s Pattern and Matcher classes.

The first regex is crafted for DD format, where two decimal numbers are separated by a comma, with an optional space:

public static final String DD_COORDINATE_REGEX = "^(-?\\d+\\.\\d+)(\\s*,\\s*)?(-?\\d+\\.\\d+)$";

The second regex is built to handle the DMS format. It checks for two sets of coordinates, including degrees, minutes, seconds, and cardinal directions (N, S, W, or E), allowing for flexibility in symbol usage:

public static final String DMS_COORDINATE_REGEX = 
  "^(\\d{1,3})°(\\d{1,2})\'(\\d{1,2}(\\.\\d+)?)?\"?([NSns])(\\s*,\\s*)?
    (\\d{1,3})°(\\d{1,2})\'(\\d{1,2}(\\.\\d+)?)?\"?([WEwe])$";

The final regex caters to MGRS coordinates. The code validates patterns that consist of a UTM zone represented by two digits, a latitude band using alphabetical characters (excluding I and O), followed by two to ten digits arranged in even pairs:

public static final String MGRS_COORDINATE_REGEX = 
  "^\\d{1,2}[^IO]{3}(\\d{10}|\\d{8}|\\d{6}|\\d{4}|\\d{2})$";

Let’s define utility methods to validate each format:

boolean validateCoordinates(String coordinateString) {
    return isValidDDFormat(coordinateString) || isValidDMSFormat(coordinateString) || isValidMGRSFormat(coordinateString);
}
boolean isValidDDFormat(String coordinateString) {
    return Pattern.compile(DD_COORDINATE_REGEX).matcher(coordinateString).matches();
}
boolean isValidDMSFormat(String coordinateString) {
    return Pattern.compile(DMS_COORDINATE_REGEX).matcher(coordinateString).matches();
}
boolean isValidMGRSFormat(String coordinateString) {
    return Pattern.compile(MGRS_COORDINATE_REGEX).matcher(coordinateString).matches();
}

Regular expressions are useful for basic validation but cannot guarantee the correctness of coordinates. For instance, the DD regex doesn’t validate whether the coordinates fall within Earth’s latitude and longitude ranges.

6. Custom Validation Logic for Complex Scenarios

To handle complex scenarios, let’s break down the validation process into smaller, more explicit steps.

6.1. Decimal Degrees

Let’s improve the isValidDDFormat() method to handle edge cases such as non-numerical inputs and invalid coordinates:

boolean isValidDDFormat(String coordinateString) {
    try {
        String[] parts = coordinateString.split(",");
        if (parts.length != 2) {
            return false;
        }
        double latitude = Double.parseDouble(parts[0].trim());
        double longitude = Double.parseDouble(parts[1].trim());
        if (latitude < -90 || latitude > 90 || longitude < -180 || longitude > 180) {
            return false;
        }
        return true;
    } catch (NumberFormatException e) {
        return false;
    }
}

The String.split() method splits the coordinates using commas and spaces as delimiters to accommodate different input formats. This ensures there are exactly two parts (latitude and longitude). We then validate that the numeric values fall within the specified ranges.

The NumberFormatException is caught to handle cases where parsing to doubles fails.

6.2. Degrees, Minutes, and Seconds

Next, let’s improve the isValidDMSFormat() method to split the coordinate string into degrees, minutes, seconds, and hemisphere parts, and validate each one accordingly:

boolean isInvalidLatitude(int degrees, int minutes, double seconds, String hemisphere) {
    return degrees < 0 || degrees > 90 || minutes < 0 || minutes >= 60 || seconds < 0 || seconds >= 60 || 
	  (!hemisphere.equalsIgnoreCase("N") && !hemisphere.equalsIgnoreCase("S"));
}

The isInvalidLatitude() method checks whether the provided latitude components are outside of the valid ranges. It returns true (invalid) if any of the following invalid conditions are met:

• Latitude degrees are less than 0 or greater than 90
• Latitude minutes are less than 0 or greater than or equal to 60
• Latitude seconds are less than 0 or greater than or equal to 60
• Hemisphere is not “N” (North) or “S” (South)

Similarly, we’ll create the equivalent validation method for longitude:

boolean isInvalidLongitude(int degrees, int minutes, double seconds, String hemisphere) {
    return degrees < 0 || degrees > 180 || minutes < 0 || minutes >= 60 || seconds < 0 || seconds >= 60 ||
      (!hemisphere.equalsIgnoreCase("E") && !hemisphere.equalsIgnoreCase("W"));
}

The isInvalidLongitude() method checks the provided longitude components, returning true (invalid) if any of the following invalid conditions are met:

• Longitude degrees are less than 0 or greater than 180
• Longitude minutes are less than 0 or greater than or equal to 60
• Longitude seconds are less than 0 or greater than or equal to 60
• Hemisphere is not “E” (East) or “W” (West)

Lastly, let’s leverage both validation methods to validate DMS coordinates:

boolean isValidDMSFormatWithCustomValidation(String coordinateString) {
    try {
        String[] dmsParts = coordinateString.split("[°',]");
        if (dmsParts.length > 6) {
            return false;
        }
        int degreesLatitude = Integer.parseInt(dmsParts[0].trim());
        int minutesLatitude = Integer.parseInt(dmsParts[1].trim());
        String[] secondPartsLatitude = dmsParts[2].split("\"");
        double secondsLatitude = secondPartsLatitude.length > 1 ? Double.parseDouble(secondPartsLatitude[0].trim()) : 0.0;
        String hemisphereLatitude = secondPartsLatitude.length > 1 ? secondPartsLatitude[1] : dmsParts[2];
        int degreesLongitude = Integer.parseInt(dmsParts[3].trim());
        int minutesLongitude = Integer.parseInt(dmsParts[4].trim());
        String[] secondPartsLongitude = dmsParts[5].split("\"");
        double secondsLongitude = secondPartsLongitude.length > 1 ? Double.parseDouble(secondPartsLongitude[0].trim()) : 0.0;
        String hemisphereLongitude = secondPartsLongitude.length > 1 ? secondPartsLongitude[1] : dmsParts[5];
        if (isInvalidLatitude(degreesLatitude, minutesLatitude, secondsLatitude, hemisphereLatitude) ||
          isInvalidLongitude(degreesLongitude, minutesLongitude, secondsLongitude, hemisphereLongitude)) {
            return false;
        }
        return true;
    } catch (NumberFormatException e) {
        return false;
    }
}

The isValidDMSFormatWithCustomValidation() method splits the input into its latitudinal and longitudinal components and validates them separately using the helper methods. If all checks pass, the DMS format is considered valid, and the method returns true (valid).

7. Conclusion

In this article, we’ve explored two distinct approaches to validating geo coordinates. Regular expressions offer a quick solution for basic validation, while the custom validation logic offers flexibility and error feedback, making it suitable for complex scenarios.

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

       

1. Overview

Spring Cloud AWS is a project that aims to simplify interacting with AWS services. Simple Queue Service (SQS) is an AWS solution for sending and receiving asynchronous messages in a scalable way.

In this tutorial, we’ll reintroduce the Spring Cloud AWS SQS integration, which has been completely rewritten for Spring Cloud AWS 3.0.

The framework provides familiar Spring abstractions for handling SQS queues, such as SqsTemplate and the @SqsListener annotation.

We’ll walk through an event-driven scenario with examples for sending and receiving messages, and show strategies for setting up integration tests with Testcontainers, a tool for managing disposable docker containers, and LocalStack, which simulates an AWS-like environment locally for testing our logic.

2. Dependencies

The Spring Cloud AWS Bill of Materials (BOM) ensures compatible versions between projects. It declares versions for many dependencies, including Spring Boot, and should be used instead of Spring Boot’s own BOM.

Here’s how to import it in our pom.xml file:

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

The main dependency we’ll need is SQS Starter, which contains all SQS-related classes for the project. The SQS integration has no dependency to Spring Boot and can be used standalone in any standard Java application:

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

For Spring Boot applications such as the one we’re building in this tutorial, we should add the project’s Core Starter, as it allows us to leverage Spring Boot’s auto-configuration for SQS, and AWS configuration such as credentials and region:

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

3. Setting up a Local Test Environment

In this section, we’ll walk through setting up LocalStack environment with Testcontainers to test our code in our local environment. Note that the examples in this tutorial can also be executed targeting AWS directly.

3.1. Dependencies

For running LocalStack and TestContainers with JUnit 5, we’ll need two additional dependencies:

<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>

Let’s also include the awaitility library to help us assert the asynchronous message consumption:

<dependency>
    <groupId>org.awaitility</groupId>
    <artifactId>awaitility</artifactId>
    <scope>test</scope>
</dependency>

3.2. Configuration

We’ll now create a class with the logic for managing our containers, which can be inherited by our test suites. Let’s name it BaseSqsIntegrationTests. For each test suite that extends this class, Testcontainers will create and start a new container, which is essential for isolating each suite’s data from one another.

The @SpringBootTest annotation is necessary for the Spring Context to be initialized, and the @Testcontainers annotation associates our Testcontainers annotations with JUnit’s runtime so that containers start when the test suite runs and stop after tests are complete:

@SpringBootTest
@Testcontainers
public class BaseSqsIntegrationTest {
   // Our test configuration will be added here
}

Let’s now declare the LocalStackContainer. The @Container annotation is also necessary for the framework to automatically manage the container’s lifecycle:

private static final String LOCAL_STACK_VERSION = "localstack/localstack:2.3.2";
@Container
static LocalStackContainer localstack = new LocalStackContainer(DockerImageName.parse(LOCAL_STACK_VERSION));

Finally, we’ll bind the properties the Spring Cloud AWS framework uses for auto-configuration with LocalStack. We’ll fetch the container port and hosts at runtime since Testcontainers will provide us with a random port, which is great for parallel testing. We can use the @DynamicPropertySource annotation for that:

@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());
    // ...other AWS services endpoints can be added here
}

This is all we need to implement a Spring Boot test with LocalStack, Testcontainers, and Spring Cloud AWS. We also need to make sure the Docker engine is running in our local environment before running the tests.

4. Setting up the Queue Names

We can set up the queue names by leveraging Spring Boot’s application.yml property mechanism.

For this tutorial, we’ll create three queues:

events:
  queues:
    user-created-by-name-queue: user_created_by_name_queue
    user-created-record-queue: user_created_record_queue
    user-created-event-type-queue: user_created_event_type_queue

Let’s create a POJO to represent these properties:

@ConfigurationProperties(prefix = "events.queues")
public class EventQueuesProperties {
    private String userCreatedByNameQueue;
    private String userCreatedRecordQueue;
    private String userCreatedEventTypeQueue;
    // getters and setters
}

Finally, we need to use the @EnableConfigurationProperties annotation in a @Configuration annotated class, or the main Spring Application class, to let Spring Boot know we want to populate it with our application.yml properties:

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

Now, we’re ready to inject either the values themselves or the POJO when we need the queue names.

By default, Spring Cloud AWS SQS will create the queues if they’re not found, which helps us quickly set up dev environments. In production, the application should not have permission to create queues, so it will fail to start if a queue is not found. The framework can also be configured to explicitly fail if a queue is not found instead.

5. Sending and Receiving Messages

There are multiple ways of sending and receiving messages to and from SQS using Spring Cloud AWS. Here, we’ll cover the most common ones, using the SqsTemplate for sending messages and the @SqsListener annotation for receiving them.

5.1. Scenario

In our scenario, we’ll simulate an event-driven application that responds to UserCreatedEvent by saving relevant information in its local repository.

Let’s create a User entity:

public record User(String id, String name, String email) {
}

And let’s create a simple in-memory UserRepository:

@Repository
public class UserRepository {
    private final Map<String, User> persistedUsers = new ConcurrentHashMap<>();
    public void save(User userToSave) {
        persistedUsers.put(userToSave.id(), userToSave);
    }
    public Optional<User> findById(String userId) {
        return Optional.ofNullable(persistedUsers.get(userId));
    }
    public Optional<User> findByName(String name) {
        return persistedUsers.values().stream()
          .filter(user -> user.name().equals(name))
          .findFirst();
    }
}

And finally, let’s create a UserCreatedEvent Java Record class:

public record UserCreatedEvent(String id, String username, String email) {
}

5.2. Setup

To test our scenarios, we’ll create a SpringCloudAwsSQSLiveTest class that extends the BaseSqsIntegrationTest file we created earlier. We’ll autowire three dependencies: the SqsTemplate that’s auto-configured by the framework, the UserRepository so we can assert our message processing worked, and our EventQueuesProperties POJO with the queue names:

public class SpringCloudAwsSQSLiveTest extends BaseSqsIntegrationTest {
    private static final Logger logger = LoggerFactory.getLogger(SpringCloudAwsSQSLiveTest.class);
    @Autowired
    private SqsTemplate sqsTemplate;
    @Autowired
    private UserRepository userRepository;
    @Autowired
    private EventQueuesProperties eventQueuesProperties;
   // ...
}

To contain our listeners, let’s create a UserEventListeners class and declare it as a Spring @Component:

@Component
public class UserEventListeners {
    private static final Logger logger = LoggerFactory.getLogger(UserEventListeners.class);
    public static final String EVENT_TYPE_CUSTOM_HEADER = "eventType";
    private final UserRepository userRepository;
    public UserEventListeners(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
    // Our listeners will be added here 
}

5.3. String Payloads

In this first example, we’ll send a message with a String payload, receive it in our listener, and persist it to our repository. We’ll then poll the repository to make sure our application persists the data correctly.

First, let’s create a test for sending the message in our test class:

@Test
void givenAStringPayload_whenSend_shouldReceive() {
    // given
    var userName = "Albert";
    // when
    sqsTemplate.send(to -> to.queue(eventQueuesProperties.getUserCreatedByNameQueue())
      .payload(userName));
    logger.info("Message sent with payload {}", userName);
    // then
    await().atMost(Duration.ofSeconds(3))
      .until(() -> userRepository.findByName(userName)
        .isPresent());
}

We should see a log similar to:

INFO [ main] c.b.s.c.a.sqs.SpringCloudAwsSQSLiveTest : Message sent with payload Albert

And then, note that the test fails because we don’t have the listener for this queue yet.

Let’s set up our listener to consume the message from this queue in our listener class and make the test pass:

@SqsListener("${events.queues.user-created-by-name-queue}")
public void receiveStringMessage(String username) {
    logger.info("Received message: {}", username);
    userRepository.save(new User(UUID.randomUUID()
      .toString(), username, null));
}

Now, when we run the test, we should see the result in the log:

INFO [ntContainer#0-1] c.b.s.cloud.aws.sqs.UserEventListeners : Received message: Albert

And the test passes.

Note that we’re using Spring’s properties-resolving capabilities to fetch the queue name from the application.yml we created earlier.

5.4. POJO and Record Payloads

Now that we’ve sent and received a String payload, let’s set up a scenario with a Java Record, the UserCreatedEvent we created earlier.

First, let’s write our failing test:

@Test
void givenARecordPayload_whenSend_shouldReceive() {
    // given
    String userId = UUID.randomUUID()
      .toString();
    var payload = new UserCreatedEvent(userId, "John", "john@baeldung.com");
    // when
    sqsTemplate.send(to -> to.queue(eventQueuesProperties.getUserCreatedRecordQueue())
      .payload(payload));
    // then
    logger.info("Message sent with payload: {}", payload);
    await().atMost(Duration.ofSeconds(3))
      .until(() -> userRepository.findById(userId)
        .isPresent());
}

We should see a log similar to this before the test fails:

INFO [ main] c.b.s.c.a.sqs.SpringCloudAwsSQSLiveTest : Message sent with payload: UserCreatedEvent[id=67f52cf6-c750-4200-9a02-345bda0516f8, username=John, email=john@baeldung.com]

Now, let’s create the corresponding listener to make the test pass:

@SqsListener("${events.queues.user-created-record-queue}")
public void receiveRecordMessage(UserCreatedEvent event) {
    logger.info("Received message: {}", event);
    userRepository.save(new User(event.id(), event.username(), event.email()));
}

We’ll see the output noting the message was received, and the test passes:

INFO [ntContainer#1-1] c.b.s.cloud.aws.sqs.UserEventListeners   : Received message: UserCreatedEvent[id=2d66df3d-2dbd-4aed-8fc0-ddd08416ed12, username=John, email=john@baeldung.com]

The framework will auto-configure any ObjectMapper bean available in the Spring Context to handle the serialization and deserialization of messages. We can configure our own ObjectMapper and customize serialization in several ways, but that’s beyond the scope of this tutorial.

5.5. Spring Message and Headers

In this last scenario, we’ll send a Record with a custom header and receive the message as a Spring Message instance, as well as both the custom header we added and a standard SQS header in the method signature. The framework automatically converts all SQS message attributes to message headers, including any provided by the user.

Let’s create the failing test first:

@Test
void givenCustomHeaders_whenSend_shouldReceive() {
    // given
    String userId = UUID.randomUUID()
      .toString();
    var payload = new UserCreatedEvent(userId, "John", "john@baeldung.com");
    var headers = Map.<String, Object> of(EVENT_TYPE_CUSTOM_HEADER, "UserCreatedEvent");
    // when
    sqsTemplate.send(to -> to.queue(eventQueuesProperties.getUserCreatedEventTypeQueue())
      .payload(payload)
      .headers(headers));
    // then
    logger.info("Sent message with payload {} and custom headers: {}", payload, headers);
    await().atMost(Duration.ofSeconds(3))
      .until(() -> userRepository.findById(userId)
        .isPresent());
}

The test should generate a log similar to this before failing:

INFO [ main] c.b.s.c.a.sqs.SpringCloudAwsSQSLiveTest  : Sent message with payload UserCreatedEvent[id=575de854-82de-44e4-8dfe-8fdc9f6ae4a1, username=John, email=john@baeldung.com] and custom headers: {eventType=UserCreatedEvent}

Now, let’s add the corresponding listener to make the test pass:

@SqsListener("${events.queues.user-created-event-type-queue}")
public void customHeaderMessage(Message<UserCreatedEvent> message, @Header(EVENT_TYPE_CUSTOM_HEADER) String eventType,
    @Header(SQS_APPROXIMATE_FIRST_RECEIVE_TIMESTAMP) Long firstReceive) {
    logger.info("Received message {} with event type {}. First received at approximately {}.", message, eventType, firstReceive);
    UserCreatedEvent payload = message.getPayload();
    userRepository.save(new User(payload.id(), payload.username(), payload.email()));
}

And we’ll see the output when we re-run our test, indicating success:

INFO [ntContainer#2-1] c.b.s.cloud.aws.sqs.UserEventListeners   : Received message GenericMessage [payload=UserCreatedEvent[id=575de854-82de-44e4-8dfe-8fdc9f6ae4a1, username=John, email=john@baeldung.com], headers=...

In this example, we’re receiving a Message with the deserialized UserCreatedEvent record as the payload and two headers. To ensure consistency throughout the project, we should use the SqsHeader class constants for retrieving SQS standard headers.

6. Conclusion

In this article, we used an event-driven scenario to go through different examples for sending and receiving messages with Spring Cloud AWS SQS 3.0.

We set up a local environment with LocalStack and TestContainers and configured the framework to use the proper local configuration for our integration tests.

As usual, the complete code used in this tutorial is available over on GitHub.

       

1. Overview

Spring WebFlux is a reactive web framework that provides a non-blocking event loop to handle I/O operations asynchronously. Also, it uses Mono and Flux reactive stream publishers to emit data when subscribed to.

This reactive approach helps applications handle large volumes of requests and data without allocating huge resources.

In this tutorial, we’ll learn how to upload multiple files to a directory using Spring WebFlux through a step-by-step guide. Also, we’ll map the filename to an entity class for easy retrieval.

2. Project Setup

Let’s create a simple reactive Spring Boot project that uploads multiple files to a directory. For simplicity, we’ll use the root directory of our project to store the files. In production, we can use a file system like AWS S3, Azure Blob Storage, Oracle Cloud Infrastructure storage, etc.

2.1. Maven Dependencies

To begin with, let’s bootstrap a Spring WebFlux application by adding the spring-boot-starter-webflux dependency to the pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
    <version>3.2.0</version>
</dependency>

This provides the core Spring WebFlux APIs and embedded Netty server to build reactive web applications.

Also, let’s add the spring-boot-starter-data-r2dbc and H2 database dependencies to the pom.xml file:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-r2dbc</artifactId>
    <version>3.2.0</version>
</dependency>
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>2.2.224</version>
</dependency>

Spring WebFlux R2DBC is a reactive database connector and the H2 database is an in-memory database.

Finally, let’s add the R2DBC native driver dependency to the pom.xml:

<dependency>
    <groupId>io.r2dbc</groupId>
    <artifactId>r2dbc-h2</artifactId>
    <version>1.0.0.RELEASE</version>
</dependency>

This native driver is implemented for the H2 database.

2.2. Entity, Repository and Controller

Let’s create an entity class named FileRecord:

class FileRecord {
    @Id
    private int id;
    private List<String> filenames;
    
   // standard getters, setters, constructor  
}

Next, let’s create a repository named FileRecordRepository:

@Repository
interface FileRecordRepository extends R2dbcRepository<FileRecord, Integer> {
}

Finally, let’s create a controller class:

@RestController
class FileRecordController {
}

In the subsequent sections, we’ll map our file name and its extension to the fileName field.

3. Uploading Files to a Directory

Occasionally, we may upload multiple files to a filesystem without mapping the filenames to database entities. In this case, retrieving the files later may be challenging.

Let’s see an example code that uploads multiple files to our root directory without mapping the file name to an entity:

PostMapping("/upload-files")
Mono uploadFileWithoutEntity(@RequestPart("files") Flux<FilePart> filePartFlux) {
    return filePartFlux.flatMap(file -> file.transferTo(Paths.get(file.filename())))
      .then(Mono.just("OK"))
      .onErrorResume(error -> Mono.just("Error uploading files"));
}

First, we create a method named uploadFileWithoutEntity() which accepts Flux of FilePart objects. Then, we invoke the flatMap() method on each FilePart object to transfer the file and return a Mono. This creates a separate Mono for each file transfer operation and flattens the stream of Monos into a single Mono.

Let’s test the endpoint by uploading multiple files through Postman:

In the image above, we upload three files to the project root directory. The endpoint returns OK to show that the operation was completed successfully.

Notably, we use the onErrorResume() method to handle errors related to file upload explicitly. In a case where failure occurs while uploading, the endpoint returns the error message.

However, files uploaded earlier may have been transferred successfully before the failure. In this case, clean-up may be needed to delete partially uploaded files on error. For simplicity, we didn’t cover the clean-up process.

4. Mapping Uploaded Files to Database Entities

Furthermore, we can map the file name to the database entity. This gives us the flexibility to retrieve files by their Id later. This is useful when we want to display an image or perform further computation.

4.1. Database Configuration

First, let’s create a schema.sql file in the resource folder to define the database table structure:

CREATE TABLE IF NOT EXISTS file_record (
    id INT NOT NULL AUTO_INCREMENT,
    filenames VARCHAR(255),
    PRIMARY KEY (id)
);

Here, we create a file record table to store the uploaded file name and its extension. Next, let’s write a configuration to initialize the schema on startup:

@Bean
ConnectionFactoryInitializer initializer(ConnectionFactory connectionFactory) {
    ConnectionFactoryInitializer initializer = new ConnectionFactoryInitializer();
    initializer.setConnectionFactory(connectionFactory);
    initializer.setDatabasePopulator(new ResourceDatabasePopulator(new ClassPathResource("schema.sql")));
    return initializer;
}

Also, let’s define the database URL in the application.properties file:

spring.r2dbc.url=r2dbc:h2:file:///./testdb

Here, we define the R2DBC URL to connect to the H2 database. For simplicity, the database isn’t protected with a password.

4.2. Service Layer

First, let’s create a service class and add the logic to handle data persistence:

@Service
public class FileRecordService {
    private FileRecordRepository fileRecordRepository;
    public FileRecordService(FileRecordRepository fileRecordRepository) {
        this.fileRecordRepository = fileRecordRepository;
    }
    public Mono<FileRecord> save(FileRecord fileRecord) {
        return fileRecordRepository.save(fileRecord);
    }
}

Here, we inject the FileRecordRepository interface in the service class and define the logic to save the file name and its extension in the database.

Next, let’s inject the FileRecordService class into the controller class:

private FileRecordService fileRecordService;
public FileRecordController(FileRecordService fileRecordService) {
    this.fileRecordService = fileRecordService;
}

The code above makes the logic to persist data available in the controller class.

4.3. Upload Endpoint

Finally, let’s write an endpoint that uploads multiple files to the root directory and maps the file names and their extension to an entity class:

@PostMapping("/upload-files-entity")
Mono uploadFileWithEntity(@RequestPart("files") Flux<FilePart> filePartFlux) {
    FileRecord fileRecord = new FileRecord();
    return filePartFlux.flatMap(filePart -> filePart.transferTo(Paths.get(filePart.filename()))
      .then(Mono.just(filePart.filename())))
      .collectList()
      .flatMap(filenames -> {
          fileRecord.setFilenames(filenames);
          return fileRecordService.save(fileRecord);
      })
      .onErrorResume(error -> Mono.error(error));
}

Here, we create an endpoint that emits Mono. It accepts Flux of FilePart and uploads each file. Next, it collects the file name and its extension and maps them to the FileRecord entity.

Let’s test the endpoint with Postman:

Here, we upload two files named spring-config.xml and server_name.png to the server. The POST request emits a Mono showing details of the request.

For simplicity, we didn’t validate the file name, type, and size.

4.4. Retrieve Book by Id

Let’s implement an endpoint to retrieve stored a file record by its Id to view the associated file names.

First, let’s add the logic to retrieve a file record by its Id to the service class:

Mono findById(int id) {
    return fileRecordRepository.findById(id);
}

Here, we invoke the findById() on bookRepository to retrieve the store Book by its id.

Next, let’s write an endpoint to retrieve the file record:

@GetMapping("/files/{id}")
Mono geFilesById(@PathVariable("id") int id) {
    return fileRecordService.findById(id)
      .onErrorResume(error -> Mono.error(error));
}

This endpoint returns a Mono containing the file Id and file name.

Let’s see the endpoint in action using Postman:

The image above shows the return file information. The image file URLs can be returned in the API response. The client can use these URLs to retrieve and display the images. Additional processing and editing of the images can be implemented by passing the files through processing services.

5. Conclusion

In this article, we learned how to upload multiple files to the server file system using Spring WebFlux.  Also, we saw how to upload files with or without mapping the file name and extension to a database entity.

Finally, we saw an approach that uploads the files and persists the file name and its extension to the database.

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

       

1. Overview

In this tutorial, we’ll learn about Apache Calcite. It’s a powerful data management framework that can be used in various use cases concerning data access. Calcite focuses on retrieving data from any source, not on storing it. Additionally, Its query optimization capability enables faster and more efficient data retrieval.

Let’s explore more, starting with the use cases where Apache Calcite is relevant.

2. Apache Calcite Use Cases

Due to its capabilities, Apache Calcite can be leveraged in several use cases:

It takes years to build query engines for new databases. However, Calcite helps get us started immediately with an out-of-the-box extendible SQL parser, validator, and optimizer. Calcite has been used in building databases such as HerdDB, Apache Druid, MapD, and many more.

Because of Calcite’s capability to integrate with multiple databases, it’s widely used in building data warehouses and business intelligence tools such as Apache Kyline, Apache Wayang, Alibaba MaxCompute, and many more.

Calcite is an integral component of streaming platforms such as Apache Kafka, Apache Apex, and Flink, which help build tools that can present and analyze live feeds.

3. Any Data, Anywhere

Apache Calcite provides ready-made adapters to integrate with third-party data sources like Cassandra, Elasticsearch, MongoDB, and many more.

Let’s explore this in detail.

3.1. High-Level Important Classes

Apache Calcite provides a robust framework for retrieving data. This framework is extendable. Hence, custom new adapters can also be created. Let’s take a look at the important Java classes:

The Apache Calcite adapters provide classes such as ElasticsearchSchemaFactory, MongoSchemaFactory, FileSchemaFactory, and more, implementing the interface SchemaFactory. The SchemaFactory helps connect the underlying data sources in a unified manner by creating a virtual Schema defined in a JSON/YAML model file.

3.2. CSV Adapter

Furthermore, let’s see an example where we’ll read the data from a CSV file using SQL query. Let’s begin by importing the necessary Maven dependencies required for using the file adapter in the pom.xml file:

<dependency>
    <groupId>org.apache.calcite</groupId>
    <artifactId>calcite-core</artifactId>
    <version>1.34</version>
</dependency>
<dependency>
    <groupId>org.apache.calcite</groupId>
    <artifactId>calcite-file</artifactId>
    <version>1.34</version>
</dependency>

Next, let’s define the model in the model.json:

{
  "version": "1.0",
  "defaultSchema": "TRADES",
  "schemas": [
    {
      "name": "TRADES",
      "type": "custom",
      "factory": "org.apache.calcite.adapter.file.FileSchemaFactory",
      "operand": {
        "directory": "trades"
      }
    }
  ]
}

The FileSchemaFactory specified in the model.json looks into the trades directory for the CSV files and creates a virtual TRADES schema. Subsequently, the CSV files under the trades directory are treated like tables.

Before we move on to see the file adapter in action, let’s look at the trade.csv file, which we’ll query using the calcite adapter:

tradeid:int,product:string,qty:int
232312123,"RFTXC",100
232312124,"RFUXC",200
232312125,"RFSXC",1000

The CSV file has three columns: tradeid, product, and qty. Additionally, the column headers also specify the data types. In total, there are three trade records in the CSV file.

Finally, let’s take a look at how to fetch the records using the Calcite adapter:

@Test
void whenCsvSchema_thenQuerySuccess() throws SQLException {
    Properties info = new Properties();
    info.put("model", getPath("model.json"));
    try (Connection connection = DriverManager.getConnection("jdbc:calcite:", info);) {
        Statement statement = connection.createStatement();
        ResultSet resultSet = statement.executeQuery("select * from trades.trade");
        assertEquals(3, resultSet.getMetaData().getColumnCount());
        List<Integer> tradeIds = new ArrayList<>();
        while (resultSet.next()) {
            tradeIds.add(resultSet.getInt("tradeid"));
        }
        assertEquals(3, tradeIds.size());
    }
}

The Calcite adapter takes the model property to create a virtual schema mimicking the file system. Then, using the usual JDBC semantics, it fetches the records from the trade.csv file.

The file adapter can read not only CSV files but also HTML and JSON files. Moreover, for handling CSV files, Apache Calcite also provides a special CSV adapter for handling advanced use cases that use CSVSchemaFactory.

3.3. In-Memory SQL Operation on Java Objects

Similar to the CSV adapter example, let’s look at another example where, with the help of Apache Calcite, we’ll run SQL queries on Java objects.

Assume two arrays of Employee and Department classes in the CompanySchema class:

public class CompanySchema {
    public Employee[] employees;
    public Department[] departments;
}

Now, let’s take a look at the Employee class:

public class Employee {
    public String name;
    public String id;
    public String deptId;
    public Employee(String name, String id, String deptId) {
        this.name = name;
        this.id = id;
        this.deptId = deptId;
    }
}

Similar to the Employee class, let’s define the Department class:

public class Department {
    public String deptId;
    public String deptName;
    public Department(String deptId, String deptName) {
        this.deptId = deptId;
        this.deptName = deptName;
    }
}

Assume there are three departments: Finance, Marketing, and Human Resources. We’ll run a query on the CompanySchema object to find the number of employees in each of the departments:

@Test
void whenQueryEmployeesObject_thenSuccess() throws SQLException {
    Properties info = new Properties();
    info.setProperty("lex", "JAVA");
    Connection connection = DriverManager.getConnection("jdbc:calcite:", info);
    CalciteConnection calciteConnection = connection.unwrap(CalciteConnection.class);
    SchemaPlus rootSchema = calciteConnection.getRootSchema();
    Schema schema = new ReflectiveSchema(companySchema);
    rootSchema.add("company", schema);
    Statement statement = calciteConnection.createStatement();
    String query = "select dept.deptName, count(emp.id) "
      + "from company.employees as emp "
      + "join company.departments as dept "
      + "on (emp.deptId = dept.deptId) "
      + "group by dept.deptName";
    assertDoesNotThrow(() -> {
        ResultSet resultSet = statement.executeQuery(query);
        while (resultSet.next()) {
            logger.info("Dept Name:" + resultSet.getString(1)
              + " No. of employees:" + resultSet.getInt(2));
        }
    });
}

Interestingly, the method runs fine and fetches the results as well. In the method, the Apache Calcite class ReflectiveSchema helps create the Schema of the CompanySchema object. Then, it runs the SQL query and fetches the records using the standard JDBC semantics.

Moreover, this example proves that irrespective of the source, Calcite can fetch data from anywhere using SQL statements.

4. Query Processing

Query processing is Apache calcite’s core functionality.

Standard JDBC drivers or SQL clients execute queries on databases. Whereas Apache Calcite, after parsing and validating the query, intelligently optimizes them for efficient execution, saving resources and boosting performance.

4.1. Decoding Query Processing Steps

Calcite offers pretty standard components that help in query processing:

Interestingly, we can also extend these components to meet the specific requirements of any database. Let’s understand more about these steps in detail.

4.2. SQL Parser and Validator

As part of the parsing process, the parser converts the SQL query into a tree-like structure called AST (Abstract Syntax Tree).

Assume a SQL query on two tables, Teacher and Department:

Select Teacher.name, Department.name 
From Teacher join 
Department On (Department.deptid = Teacher.deptid)
Where Department.name = 'Science'

First, the query parser converts the query into an AST and then performs a basic syntactic validation:

Further, the validator validates the nodes semantically, for example:

• validating the functions and operators
• validating the database objects like tables and columns against the database’s catalog

4.3. Relational Expression Builder

Subsequently, after the validation step, the relational expression builder converts the syntax tree using some of the common relational operators:

• LogicalTableScan: Reads data from a table
• LogicalFilter: Selects rows based on a condition
• LogicalProject: Choose specific columns to include
• LogicalJoin: Combines rows from two tables based on matching values

Considering the AST shown earlier, the corresponding logical relational expression derived from it would be:

LogicalProject(
    projects=[
        $0.name AS name0,
        $1.name AS name1
    ],
    input=LogicalFilter(
        condition=[
            ($1.name = 'Science')
        ],
        input=LogicalJoin(
            condition=[
                ($0.deptid = $1.deptid)
            ],
            left=LogicalTableScan(table=[[Teacher]]),
            right=LogicalTableScan(table=[[Department]])
        )
    )
)

In the relational expression, $0 and $1 represent the tables Teacher and Department. Essentially, it’s a mathematical expression that helps understand what operations will be carried out to get the results. However, it has no information related to execution.

4.4. Query Optimizer

Then, the Calcite optimizer applies optimization on the relational expression. Some common optimization include:

• Predicate Pushdown: Pushing filters as close to the data source as possible to reduce the amount of data fetched
• Join Reordering: Rearranging join order to minimize intermediate results and improve efficiency
• Projection Pushdown: Pushing down projections to avoid unnecessary columns from being processed
• Index Usage: Identifying and utilizing indexes to speed up data retrieval

4.5. Query Planner, Generator, and Executor

Following optimization, the Calcite Query Planner creates an execution plan for executing the optimized query. The execution plan specifies the exact steps to be taken by the query engine to fetch and process data. This is also called a physical plan specific to the back-end query engine.

Then, the Calcite Query Generator generates code in a language specific to the chosen execution engine.

Finally, the Executor connects to the database to execute the final query.

5. Conclusion

In this article, we explored the capabilities of Apache Calcite, which rapidly equips databases with standardized SQL parsers, validators, and optimizers. Hence, freeing vendors from developing years-long query engines, Calcite empowers them to prioritize back-end storage. Additionally, Calcite’s ready-made adapters simplify connection to diverse databases, helping to develop a unified integration interface.

Moreover, by leveraging Calcite, database developers can accelerate time-to-market and deliver robust, versatile SQL capabilities.

The code used in this article is available over on GitHub.

       

1. Introduction

One of the most important capabilities of backend HTTP API development is the ability to resolve request query parameters passed by the frontend.

In this tutorial, we’ll introduce several ways to get the query parameters from HttpServletRequest directly, and some concise ways provided by Spring MVC.

2. Methods in HttpServletRequest

First, let’s see the parameter-related methods provided by HttpServletRequest.

2.1. HttpServletRequest#getQueryString()

This example shows what we can get from the URL directly by invoking the method HttpServletRequest#getQueryString():

@GetMapping("/api/byGetQueryString")
public String byGetQueryString(HttpServletRequest request) {
    return request.getQueryString();
}

When we send a GET request using curl with several parameters to this API, the method getQueryString() just returns all the characters after ‘?’:

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byGetQueryString?username=bob&roles=admin&roles=stuff'
username=bob&roles=admin&roles=stuff

Note that if we change @GetMapping to @RequestMapping, it will return the same response when we send the request by POST/PUT/PATCH/DELETE HTTP method. This means HttpServletRequest will always obtain the query string no matter what the HTTP method is. So, we can just focus on the GET request in this tutorial. To simplify our demonstration of the methods provided by HttpServletRequest, we’ll also use the same request parameters in each of the following examples.

2.2. HttpServletRequest#getParameter(String)

To simplify parameter resolution, the HttpServletRequest provides a method getParameter to get the value by parameter name:

@GetMapping("/api/byGetParameter")
public String byGetParameter(HttpServletRequest request) {
    String username = request.getParameter("username");
    return "username:" + username;
}

When we send a GET request with a query string of username=bob, the call getParameter(“username”) returns bob.

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byGetParameter?username=bob&roles=admin&roles=stuff'
username:bob

2.3. HttpServletRequest#getParameterValues(String)

The method getParameterValues acts similar to the getParameter method, but it returns a String[] instead of a String. This is due to the HTTP specification allowing to pass multiple parameters with the same name.

@GetMapping("/api/byGetParameterValues")
public String byGetParameterValues(HttpServletRequest request) {
    String[] roles = request.getParameterValues("roles");
    return "roles:" + Arrays.toString(roles);
}

So when we pass the value with parameter roles twice, we should get two values in the array:

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byGetParameterValues?username=bob&roles=admin&roles=stuff'
roles:[admin, stuff]

2.4. HttpServletRequest#getParameterMap()

Let’s say we have the following UserDto POJO as part of the following JSON API examples:

public class UserDto {
    private String username;
    private List<String> roles;
    // standard getter/setters...
}

As we can see, it is possible to have several different parameter names with one or more values. For these cases, HttpServletRequest provides another method, getParameterMap(), which returns a Map<String, String[]>. This method allows us to get the parameter values using a Map.

@GetMapping("/api/byGetParameterMap")
public UserDto byGetParameterMap(HttpServletRequest request) {
    Map parameterMap = request.getParameterMap();
    String[] usernames = parameterMap.get("username");
    String[] roles = parameterMap.get("roles");
    UserDto userDto = new UserDto();
    userDto.setUsername(usernames[0]);
    userDto.setRoles(Arrays.asList(roles));
    return userDto;
}

We’ll get a JSON response for this example:

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byGetParameterMap?username=bob&roles=admin&roles=stuff'
{"username":"bob","roles":["admin","stuff"]}

3. Get Parameters with Spring MVC

Let’s see how Spring MVC improves the coding experience when resolving the query string.

3.1. Parameter Name

With the Spring MVC framework, we do not have to manually resolve the parameters ourselves using the HttpServletRequest directly. For the first case, we define a method with two parameters with the query parameter names username and roles and remove the usage of HttpServletRequest, which is handled by Spring MVC.

@GetMapping("/api/byParameterName")
public UserDto byParameterName(String username, String[] roles) {
    UserDto userDto = new UserDto();
    userDto.setUsername(username);
    userDto.setRoles(Arrays.asList(roles));
    return userDto;
}

This will return the same result as the last example since we use the same model:

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byParameterName?username=bob&roles=admin&roles=stuff'
{"username":"bob","roles":["admin","stuff"]}

3.2. @RequestParam

If the HTTP query parameter name and Java method parameter name are different, or if the method parameter names won’t be retained in the compiled bytecode, we can configure annotation @RequestParam on the method parameter name for this situation.

In our case, we use @RequestParam(“username”) and @RequestParam(“roles”) as follows:

@GetMapping("/api/byAnnoRequestParam")
public UserDto byAnnoRequestParam(@RequestParam("username") String var1, @RequestParam("roles") List<String> var2) {
    UserDto userDto = new UserDto();
    userDto.setUsername(var1);
    userDto.setRoles(var2);
    return userDto;
}

and test it:

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byAnnoRequestParam?username=bob&roles=admin&roles=stuff'
{"username":"bob","roles":["admin","stuff"]}

3.3. POJO

More simply, we can use a POJO as the parameter type directly:

@GetMapping("/api/byPojo")
public UserDto byPojo(UserDto userDto) {
    return userDto;
}

Spring MVC can resolve the parameters, create the POJO instance, and fill it with the required parameters automatically.

$ curl 'http://127.0.0.1:8080/spring-mvc-basics/api/byPojo?username=bob&roles=admin&roles=stuff'
{"username":"bob","roles":["admin","stuff"]}

Finally, we check with a unit test to make sure that the last four methods provide exactly the same features.

@ParameterizedTest
@CsvSource(textBlock = """
    /api/byGetParameterMap
    /api/byParameterName
    /api/byAnnoRequestParam
    /api/byPojo
    """)
public void whenPassParameters_thenReturnResolvedModel(String path) throws Exception {
    this.mockMvc.perform(get(path + "?username=bob&roles=admin&roles=stuff"))
      .andExpect(status().isOk())
      .andExpect(jsonPath("$.username").value("bob"))
      .andExpect(jsonPath("$.roles").value(containsInRelativeOrder("admin", "stuff")));
}

4. Conclusion

In this article, we have introduced how to get the parameters from a HttpServletRequest using Spring MVC. From these examples, we can see that a lot of code can be reduced when using Spring MVC to parse parameters.

As usual, all code snippets presented in this article are available over on GitHub.

       

1. Introduction

The execution of a Java program starts from the main() method. However, there are some scenarios where we may want to display messages without using the main() method.

In this tutorial, we’ll delve into some approaches to accomplish this task.

2. Using Static Blocks

Static blocks are executed when a class is loaded in the memory, which makes it possible to display messages without the main() method.

Let’s see an example:

public final class PrintMessageWithoutMainMethod {
    static {
        System.out.println("Hello World!!");
        System.exit(0);
    }
}

In this case, the message “Hello World!!” appears during the loading of the class despite whether the main() method is empty or not present. Besides, the System.exit(0) method ends the program right away.

3. Using Nested Classes

To print messages without the main() method, we can use nested classes as well. Let’s see how we can use this approach:

public final class PrintMessageWithoutMainMethod {
    static {
        NestedClass.printMessage();
    }
    static class NestedClass {
        static void printMessage() {
            System.out.println("Message from nested class");
        }
    }
}

In this case, a static block in an outer class invokes the static method from inside of the nested one and outputs a message.

4. Executing Code During Class Initialization

In some cases, it is necessary to execute certain methods during the initialization of a class. Note that this approach can be helpful when configuring or performing initialization tasks that only need to be performed once.

The given code shows the invocation of a method called getStatus() when loading a class:

public final class PrintMessageWithoutMainMethod {
    private static final int STATUS = getStatus();
    private static int getStatus() {
        System.out.println("Hello World!!");
        System.exit(0);
        return 0;
    }
}

In this case, we call the getStatus() method during the class loading process, and it prints “Hello World!!” to the console.

We should be careful when using this method because it terminates the execution of the Java Virtual Machine (JVM) forcefully. So, if a clean shutdown is necessary, look for alternatives.

5. Using JUnit Testing

Besides the above-described methods, we can print our message to the console using the JUnit tests as shown below:

public class PrintMessageWithoutMainUnitTest {
    @Test
    public void givenMessage_whenUsingJunitTest_thenPrintMessage() {
        System.out.println("Hello World!!");
    }
}

In this case, we create a test method as a unit test that prints “Hello World!!” to the console. This isn’t an alternative to the main() method but a different way of implementing it, especially while testing.

6. Conclusion

In conclusion, there are other ways of printing messages without using the main() method in Java. Subsequently, this tutorial gave insights into several approaches to address this issue, such as using static blocks, executing code during class initialization, and making use of nested classes.

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

       

1. Overview

Postman is a popular API development tool that simplifies designing, testing, modifying, and documenting APIs. It provides a user-friendly interface allowing users to send and receive HTTP requests, manage workflows with environments and collections, perform automated testing, create mock servers for testing, and generate API documentation.

Due to its versatility, it’s highly valued by developers, testers, and other IT professionals engaged in API-centric workflows.

In this tutorial, we’ll discuss how to install, setup, and use the most important features of Postman.

2. Installation and Setup

Postman is available for download as a desktop application for Windows, Mac, or Linux operating systems. It’s also available as a web application. However, not all features are available there.

After installation, we have to sign up and create a free account.

3. Sending an HTTP Request

One of the fundamental actions in Postman is sending a request to an API. Postman provides a collection of free public REST APIs that don’t require any authentication, and we’ll utilize those APIs to demonstrate some of Postman’s functionalities.

We’ll use the API to retrieve colleges and universities in a specific country.

Let’s create a workspace named “baeldung-test-workspace”. Once created, we can click the New button and select HTTP.

To test sending a request in Postman, we’ll set the URL to http://universities.hipolabs.com/search?country=Germany and the method to GET:

After sending the request, Postman will display the response data in the sidebar. We can view the status code, headers, and response body here.

If we don’t receive a successful response, the response status and details in the sidebar will help identify the issue.

In this example, we are using the GET method, but depending on the scenario, we can choose other most common methods such as POST, PUT, PATCH, DELETE, or input a new method.

We also used the query parameter for the country name. When using the query parameters, they can be entered either in the request URL or in the dedicated Query params tab, where they can be entered as key-value pairs. Postman naturally supports path parameters, which are also entered as a part of the request URL.

4. Environments

Effectively managing requests across various environments can be complex. However, Postman’s environments allow us to manage variables for different environments, making switching between, for example, development, testing, and production easy.

Let’s create two different environments by clicking the New button and selecting Environment: development and test:

Here, we can enter both initial and current values. The initial value is the default setting for a variable, while the current value is used in the actual requests when the variable is referenced. The initial value is used as the current value in case we leave the current value blank when saving the environment.

We’ll create a variable country in each, assigning the value “Germany” for development and “France” for the test environment:

We selected the Development environment in the upper right corner and clicked the Send button. The country’s value was resolved to “Germany”. The variables are not reserved only for the query parameters – they can be referenced in the request URLs, headers, and body data.

5. Collections

Managing individual requests for various aspects of the API can be a challenge in terms of effective organization. Additionally, APIs with parameters that differ across different environments require executing the same set of requests in different environments without modifications.

This is where collections prove helpful, as they help manage API workflows more efficiently. A collection can be related to a specific environment, allowing us to use environment variables in requests.

In API workflows, executing multiple requests in a specific order is often necessary, and collections can help by executing requests in a particular order.

In general, collections are an effective way to group requests for easier management and collaboration among team members.

5.1. Creating a Collection

Let’s create a new collection by clicking the Create Collection button or saving our existing GET request. We’ll also add a GET request to retrieve all colleges and universities in France and save it to this new collection.

By clicking on the collection’s name in the left sidebar, we’re presented with multiple tabs, each allowing us to customize and configure our collection, such as by adding tests that will be executed with each request in the collection.

5.2. Collection Runner

We’ll now focus on running our collection by utilizing the Collection Runner, where we can run our requests in a specific order, either manually, on a schedule, or by running it from the command line. We can test the functional aspect of our API this way. Still, the Collection Runner also allows us to test the performance of our API by simulating a real-world traffic scenario.

Collection Runner can be further configured in various ways, but we’ll keep things simple for demonstration purposes and only select the manual run option.

Finally, the collection can be run by clicking the Run Test collection button:

Now, we can review the results of our collection run. Postman will display the results of executed requests and eventual test results if any tests were included. Here, we can view helpful information such as environment, duration, average response time, and results for each request.

6. Summary

In this article, we discussed Postman – a powerful tool for working with APIs.

We covered the essentials of how to send an HTTP request, group variables into environments that can be referenced when sending requests, and group requests into collections. However, this only scratches the surface of Postman’s extensive features. Advanced features, such as automated testing through collections and creating mock servers for testing, can significantly enhance our API development process, especially when dealing with complex scenarios.

      

Related Stories

• Send Array as Part of x-www-form-urlencoded Using Postman
• A Guide to Variables in Postman
• Basic Authentication With Postman

 

1. Overview

Converting byte to int is a common operation, especially when dealing with low-level data manipulation, file I/O, or network communication. In this article, we’ll explore various methods through which we can achieve the byte to int conversion.

2. byte and int

In Java, byte and int are fundamental data types that serve distinct purposes in the representation of numerical values. A byte is an 8-bit signed data type with values ranging from -128 to 127. An int data type is a 32-bit signed integer, offering a wider range than byte, from -2³¹ to 2³¹-1 (-2,147,483,648 to 2,147,483,647).

3. Using Type Casting

One of the most straightforward and common approaches to performing the conversion is to simply typecast the byte variable to an int variable:

class ByteToIntConversion {
    static int usingTypeCasting(byte b) {
        int i = b;
        return i;
    }
}

In this example, we’re directly converting a byte to an int variable through assignment. Let’s test it out:

@Test
void givenByte_whenUsingTypeCasting_thenConvertToInt() {
    byte b = -51;
    int result = ByteToIntConversion.usingTypeCasting(b);
    assertEquals(-51, result);
}

4. Using Integer.valueOf()

The Integer class offers convenient methods for converting values from other primitive data types. We can employ its static method Integer.valueOf(), which facilitates the conversion of a byte to an int:

static int usingIntegerValueOf(byte b){ 
    return Integer.valueOf(b);
}

The above code example takes a byte as an input and will return an Integer instance of the specified byte value. The Java Compiler will automatically apply the unboxing since the Integer class serves as a wrapper for the primitive data type int. We can perform a test to verify its expected behavior:

@Test 
void givenByte_whenUsingIntegerValueOf_thenConvertToInt() { 
    byte b = -51; 
    int result = ByteToIntConversion.usingIntegerValueOf(b); 
    assertEquals(-51, result); 
}

5. Using the Byte Class

Byte class is a wrapper class for the primitive data type byte. It provides methods to work with byte values as objects, including conversion methods for handling byte values.

5.1. Using intValue()

The Byte class offers an indirect approach to convert a byte to an int data type through its intValue() method. To make this method effective, we transform the primitive value to its object representation and then proceed with the conversion process:

static int usingByteIntValue(byte b){
    Byte byteObj = new Byte(b);
    return byteObj.intValue();
}

In this example, the intValue() method returns an int value after performing a widening primitive conversion. Let’s test this out:

@Test
void givenByte_whenUsingByteIntValue_thenConvertToInt() { 
    byte b = -51; 
    int result = ByteToIntConversion.usingByteIntValue(b); 
    assertEquals(-51, result); 
}

5.2. Byte.toUnsignedInt()

Beginning with Java 8, the Byte class offers a utility method called toUnsignedInt for converting a byte to an unsigned integer. This method internally performs bitwise AND operation of the byte value with 0xff:

static int usingByteUnsignedInt(byte b){
    return Byte.toUnsignedInt(b);
}

It’s important to observe that by default, byte-to-int conversion retains the sign of the value. However, the above method treats the byte value as if it were an unsigned byte, producing the equivalent unsigned integer representation:

@Test 
void givenByte_whenUsingByteUnsignedInt_thenConvertToInt() { 
    byte b = -51; 
    int result = ByteToIntConversion.usingByteUnsignedInt(b); 
    assertEquals(205, result); 
}

6. Conclusion

In this tutorial, we’ve delved into different approaches for converting a byte to an int data type. Each approach provides a reliable way to perform the conversion. The choice depends on selecting the most suitable method for our specific use case.

When working with negative numbers and aiming for their signed representation, we can consider using typecasting, Integer.valueOf(), or Byte class intValue() method. Alternatively, for unsigned conversion, we can opt for Byte.toUnsignedInt()  approach.

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

       

1. Overview

Morse code encodes text characters using sequences of dots and dashes to represent letters, numbers, and punctuation. Samuel Morse and Alfred Vail developed it in the early 1830s for telegraphy use.

In this tutorial, we’ll write a method that translates from English to Morse code. Then, we’ll write the method which does the opposite.

2. Writing Morse Code

Let’s understand Morse code and its alphabet.

2.1. What Is the Morse Code?

In Morse code, each letter is represented by a unique combination of short signals (dots) and long signals (dashes), allowing for communication through a series of on-off signals. According to the common usage, we’ll represent dots with “.” and dashes with “–“. Those two characters are enough to write the whole Morse alphabet.

However, we’ll need something more to write sentences. As Morse indeed targeted non-written communication, the flow is essential to decrypt a Morse message. For this reason, the operator responsible for transmitting a Morse message would leave a short pause between each letter. Additionally, he would leave a longer pause between each word. As a result, a representation that wouldn’t take those pauses into account wouldn’t allow for decoding.

A common choice is to leave a blank space ” ” to represent the pause between each word. We’ll also use a “/” to codify the space character between two words. As the slash is also a character, blank spaces will surround it like the others.

2.2. Bidirectional Mapping Between English and Morse

To translate easily from English to Morse and reversely, we’d like to have a bidirectional mapping between both alphabets. Thus, we’ll use Apache Commons Collection’s BidiMap data structure. It’s a Map that allows access by key or by value. This way, we’ll use it for both translating methods. However, if we’re interested in translating only one way, we’d directly use a Map.

First, let’s include the latest version of the library in our pom.xml:

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

We can now create our mapping and initialize it in a static block:

public class MorseTranslator {
    
    private static final BidiMap<String, String> morseAlphabet = new DualHashBidiMap<>();
    
    static {
        morseAlphabet.put("A", ".-");
        morseAlphabet.put("B", "-...");
        morseAlphabet.put("C", "-.-.");
        morseAlphabet.put("D", "-..");
        morseAlphabet.put("E", ".");
        morseAlphabet.put("F", "..-.");
        morseAlphabet.put("G", "--.");
        morseAlphabet.put("H", "....");
        morseAlphabet.put("I", "..");
        // etc
        morseAlphabet.put(" ", "/");
    }
    
}

Let’s note that we added the translation for the blank character. Furthermore, we restrict ourselves to letters, numbers, and punctuation characters. If we want to use also accented characters, we’d need to use another data structure or make choices because various accented characters can match the same Morse code. For instance, “à” and “å” both correspond to “.–.-” in Morse.

3. Translating English Into Morse

First, let’s write a method to translate an English sentence into Morse code.

3.1. General Algorithm

Our BidiMap contains only capital letters because capitalization doesn’t change the translation. Thus, we’ll start with capitalizing the word. Then, we’ll iterate over the letters and translate them one by one:

static String englishToMorse(String english) {
    String upperCaseEnglish = english.toUpperCase();
    String[] morse = new String[upperCaseEnglish.length()];
    for (int index = 0; index < upperCaseEnglish.length(); index++) {
        String morseCharacter = morseAlphabet.get(String.valueOf(upperCaseEnglish.charAt(index)));
        morse[index] = morseCharacter;
    }
    return String.join(" ", morse);
}

It’s convenient to store the translations into an array of Morse Strings. This intermediate array has as many values as the number of characters in the input. In the end, we use the String.join() method to concatenate all entries, using a blank space as a delimiter.

We can now test our method. Since we’d like to check that capitalization doesn’t matter, we’ll write a parameterized test with various inputs expecting the same output:

@ParameterizedTest
@ValueSource(strings = {"MORSE CODE!", "morse code!", "mOrSe cOdE!"})
void givenAValidEnglishWordWhateverTheCapitalization_whenEnglishToMorse_thenTranslatedToMorse(String english) {
    assertEquals("-- --- .-. ... . / -.-. --- -.. . -.-.-----.", MorseTranslator.englishToMorse(english));
}

In addition, we can note that the space between the two words translates to “ / ” as expected.

3.2. Edge Cases

For the moment, our program doesn’t take into account potentially malformed inputs. However, we’d like to refuse sentences that contain invalid characters. In such cases, we’ll throw an IllegalArgumentException:

String morseCharacter = morseAlphabet.get(String.valueOf(upperCaseEnglish.charAt(index)));
if (morseCharacter == null) {
    throw new IllegalArgumentException("Character " + upperCaseEnglish.charAt(index) + " can't be translated to morse");
}
morse[index] = morseCharacter;

The modification is pretty straightforward because if a character is invalid, it isn’t present as a key of the bidirectional map. Hence, the get() method returns null. We can also add a null safety check on top of our method. In a nutshell, our final method reads:

static String englishToMorse(String english) {
    if (english == null) {
        return null;
    }
    String upperCaseEnglish = english.toUpperCase();
    String[] morse = new String[upperCaseEnglish.length()];
    for (int index = 0; index < upperCaseEnglish.length(); index++) {
        String morseCharacter = morseAlphabet.get(String.valueOf(upperCaseEnglish.charAt(index)));
        if (morseCharacter == null) {
            throw new IllegalArgumentException("Character " + upperCaseEnglish.charAt(index) + " can't be translated to morse");
        }
        morse[index] = morseCharacter;
    }
    return String.join(" ", morse);
}

Lastly, we can add a unit test with a non-translatable sentence:

@Test
void givenAnEnglishWordWithAnIllegalCharacter_whenEnglishToMorse_thenThrows() {
    String english = "~This sentence starts with an illegal character";
    assertThrows(IllegalArgumentException.class, () -> MorseTranslator.englishToMorse(english));
}

4. Translating Morse Into English

Let’s now write the reverse method. Once again, we’ll focus on the big picture before diving into edge cases.

4.1. General Algorithm

The concept is the same: for each Morse character, we find the English translation in the BidiMap. The getKey() method allows us to do that. Then, we need to iterate over every Morse character:

static String morseToEnglish(String morse) {
    String[] morseUnitCharacters = morse.split(" ");
    StringBuilder stringBuilder = new StringBuilder();
    for (int index = 0; index < morseUnitCharacters.length; index ++) {
        String englishCharacter = morseAlphabet.getKey(morseUnitCharacters[index]);
        stringBuilder.append(englishCharacter);
    }
    return stringBuilder.toString();
}

We isolated every Morse character thanks to the String.split() method. Appending every English translation to a StringBuilder is the most efficient way to concatenate the result.

Let’s now verify that our method returns the correct result:

@Test
void givenAValidMorseWord_whenMorseToEnglish_thenTranslatedToUpperCaseEnglish() {
    assertEquals("MORSE CODE!", MorseTranslator.morseToEnglish("-- --- .-. ... . / -.-. --- -.. . -.-.-----."));
}

Finally, we can recall that the output will always be in capital letters.

4.2. Edge Cases

Additionally, we want to refuse inputs containing invalid Morse characters. Like in englishToMorse(), we’ll throw an IllegalArgumentException in this case. Moreover, we can also handle the specific case of a null input. Here, we also have to deal with an empty input separately because of the internal functioning of the split() method.

To recap, let’s write our final method:

static String morseToEnglish(String morse) {
    if (morse == null) {
        return null;
    }
    if (morse.isEmpty()) {
        return "";
    }
    String[] morseUnitCharacters = morse.split(" ");
    StringBuilder stringBuilder = new StringBuilder();
    for (int index = 0; index < morseUnitCharacters.length; index ++) {
        String englishCharacter = morseAlphabet.getKey(morseUnitCharacters[index]);
        if (englishCharacter == null) {
            throw new IllegalArgumentException("Character " + morseUnitCharacters[index] + " is not a valid morse character");
        }
        stringBuilder.append(englishCharacter);
    }
    return stringBuilder.toString();
}

Dealing with invalid characters was as straightforward as in the previous case because if a Morse code doesn’t match any of the BidiMap‘s values, the getKey() method returns null.

Lastly, we can also test the error case:

@Test
void givenAMorseWordWithAnIllegalCharacter_whenMorseToEnglish_thenThrows() {
    assertThrows(IllegalArgumentException.class, () -> MorseTranslator.morseToEnglish(".!!!!!!!"));
}

5. Conclusion

In this article, we learned about the Morse code and wrote a simple two-way translator between Morse and English. Most considerations aren’t specific to Morse, so we could probably make our code more generic to deal with any language that can define a bidirectional mapping with English.

As always, the code is available over on GitHub.

       

1. Overview

The Spock Framework is a testing and specification framework for Java and Groovy applications. Gradle is a popular build tool and a Maven alternative.

In this tutorial, we’ll show how to set up a project using Gradle and add Spock test dependencies. We’ll also quickly look and move gradually to fully integrating Spock with Spring, still using the Gradle build process.

2. Using Spock With Gradle

We’ll need to create a Gradle project and add Spock dependencies.

2.1. Setup a Gradle Project

First, let’s install Gradle on our system. A Gradle project can then be initialized using the gradle init command. Different options exist for creating, for example, an application or a library using Java or Kotlin.

In any case, a Gradle project will always get the configuration from:

• build.gradle. It contains info about the build process, such as the Java version or the libraries used for implementation or testing. We’ll refer to it as the build file.
• settings.gradle. It adds project-wise info, such as the project name or the submodule structure. We’ll refer to it as the settings file.

Gradle uses JVM plugins for a project’s compilation, testing, and bundling capabilities.

If we go for Java, we’ll keep it simple by using the ‘java‘ plugin because this is what it will eventually be extended.

Let’s check out a simple build skeleton for a Java 17 project:

plugins {
    id 'java'
}
repositories {
    mavenCentral()
}
dependencies {
    // test dependencies
    testImplementation 'org.junit.jupiter:junit-jupiter:5.9.2'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}
test {
    useJUnitPlatform()
    testLogging {
        events "started", "passed", "skipped", "failed"
    }
}

This file is the core component and defines the tasks necessary to build the project.

We added the JUnit5 test dependency:

testImplementation 'org.junit.jupiter:junit-jupiter:5.9.2'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

We’ll need the useJUnitPlatform() specification in the test task to run the tests. We are also adding some properties for test logging so we have an output while the task is running:

test {
    useJUnitPlatform()
    testLogging {
        events "started", "passed", "skipped", "failed"
    }
}

We also see how our project will download the dependencies using, for example, the mavenCentral() repository:

repositories {
    mavenCentral()
}

Notably, some may find that the configuration is more readable than a Maven project with the XML-based pom.xml build configuration.

Finally, let’s also have a look at the settings file:

rootProject.name = 'spring-boot-testing-spock'

This is pretty straightforward and only configures the project name. However, it can contain relevant information, such as sub-module inclusion or plugin definition.

We can check the Gradle DSL reference for more info about the build or settings scripting.

2.2. Add Spock Dependencies

We need two simple steps to add Spock to our Gradle project:

• Add the ‘groovy’ plugin
• Add the Spock to the test dependencies

Let’s look at the build file:

plugins {
    id 'java'
    id 'groovy'
}
repositories {
    mavenCentral()
}
dependencies {
    // Spock test dependencies
    testImplementation 'org.spockframework:spock-core:2.4-M1-groovy-4.0'
    // Junit dependencies
    testImplementation 'org.junit.jupiter:junit-jupiter:5.9.2'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}
test {
    useJUnitPlatform()
    testLogging {
        events "started", "passed", "skipped", "failed"
    }
}

We must update our dependencies by adding the org.spockframework:spock-core test dependency:

testImplementation 'org.spockframework:spock-core:2.4-M1-groovy-4.0'

Notably, we don’t need to configure the GMavenPlus plugin as we would have to for a Maven project.

2.3. Run Tests

There are different types of tests we can do with Spock. Let’s have a look at a simple test case:

class SpockTest extends Specification {
    def "one plus one should equal two"() {
        expect:
        1 + 1 == 2
    }
}

Every test must extend the Specification class. Furthermore, the tests are defined as functions with the Groovy def syntax.

If we are used to programming in Java, we need to remember that Spock tests are, by default, in a different package and have another class extension. We must put our tests in the test/groovy folder if not otherwise specified. Furthermore, the class will have the .groovy extension, for example, SpockTest.groovy.

To run the tests, we need to execute the test task with our IDE or at the command line:

gradle test

Let’s check some example output:

Starting a Gradle Daemon (subsequent builds will be faster)
> Task :test
SpockTest > one plus one should equal two STARTED
SpockTest > one plus one should equal two PASSED
BUILD SUCCESSFUL in 15s
7 actionable tasks: 7 executed

Gradle uses a caching system and will only re-run tests that have changed since the last execution.

3. Using Spock, Gradle, and Spring

We may want to add Spock to a Spring project. Spock has a specific module for that.

Let’s have a look at Spock with a basic Spring configuration. Later on, we’ll also look at a Spring Boot setup. From now on, we are omitting the java and the test sections in the build file for brevity because they won’t change.

3.1. Spock and Spring

Suppose we have a Spring project and want to switch or adopt testing with Spock.

The dependency structure is getting more complex now in the build file, so let’s comment out every part properly:

plugins {
    id 'java'
    id 'groovy'
}
repositories {
    mavenCentral()
}
dependencies {
    // Spring implementation dependencies
    implementation 'org.springframework:spring-web:6.1.0'
    // Spring test dependencies
    testImplementation 'org.springframework:spring-test:6.1.0'
    // Spring Spock test dependencies
    testImplementation 'org.spockframework:spock-spring:2.4-M1-groovy-4.0'
    // Spock Core test dependencies
    testImplementation 'org.spockframework:spock-core:2.4-M1-groovy-4.0'
    // Junit Test dependencies
    testImplementation 'org.junit.jupiter:junit-jupiter:5.9.2'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

We add org.springframework:spring-web to demonstrate a simple Spring dependency. Furthermore, if we want to use the Spring test features, we must add the org.springframework:spring-test test dependency:

// Spring implementation dependencies
implementation 'org.springframework:spring-web:6.1.0'
// Spring test dependencies
testImplementation 'org.springframework:spring-test:6.1.0'

Finally, let’s add the org.spockframework:spock-spring dependency. This is the only dependency we need to integrate Spock and Spring:

// Spring Spock test dependencies
testImplementation 'org.spockframework:spock-spring:2.4-M1-groovy-4.0'

3.2. Spock and Spring Boot

We only need to replace the previous Spring’s basic dependencies with the Spring Boot ones.

Let’s look at the build file:

plugins {
    id 'java'
    id 'groovy'
}
repositories {
    mavenCentral()
}
dependencies {
    // Spring implementation dependencies
    implementation 'org.springframework.boot:spring-boot-starter-web:3.0.0'
    // Spring Test dependencies
    testImplementation 'org.springframework.boot:spring-boot-starter-test:3.0.0'
    // Spring Spock Test dependencies
    testImplementation 'org.spockframework:spock-spring:2.4-M1-groovy-4.0'
    // Spring Core Test dependencies
    testImplementation 'org.spockframework:spock-core:2.4-M1-groovy-4.0'
    // Junit Test dependencies
    testImplementation 'org.junit.jupiter:junit-jupiter:5.9.2'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

Notably, we are adding the Spring Boot dependencies:

// Spring implementation dependencies
implementation 'org.springframework.boot:spring-boot-starter-web:3.0.0'
// Spring Test dependencies
testImplementation 'org.springframework.boot:spring-boot-starter-test:3.0.0'

3.3. Spring and Gradle Dependency Management

Let’s finalize our setup using the Spring dependency management to make our configuration more compact and maintainable. This way, we adopt a BOM or “Bill Of Materials” oriented style similar to the Maven projects and only declare the version in a single place.

There are a couple of ways we can achieve this.

Let’s have a look at the first option:

plugins {
    id 'java'
    id 'groovy'
    id "org.springframework.boot" version "3.0.0"
    id 'io.spring.dependency-management' version '1.0.14.RELEASE'
}
repositories {
    mavenCentral()
}
dependencies {
    // Spring implementation dependencies
    implementation 'org.springframework.boot:spring-boot-starter-web'
    // Spring Test dependencies
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    // Spring Spock Test dependencies
    testImplementation 'org.spockframework:spock-spring:2.4-M1-groovy-4.0'
    // Spring Core Test dependencies
    testImplementation 'org.spockframework:spock-core:2.4-M1-groovy-4.0'
}

In this case, we are just adding the following plugins:

id "org.springframework.boot" version "3.2.1"
id 'io.spring.dependency-management' version '1.0.14.RELEASE'

Notably, JUnit5 dependencies are now pulled by Spring Boot without specifying them.

Finally, If we want to update the Spring Boot version, we only need to replace it in the org.springframework.boot plugin.

Let’s have a look at the second option:

plugins {
    id 'java'
    id 'groovy'
    id 'io.spring.dependency-management' version '1.1.4'
}
repositories {
    mavenCentral()
}
dependencyManagement {
    imports {
        mavenBom 'org.springframework.boot:spring-boot-dependencies:3.2.1'
    }
}
dependencies {
    // Spring implementation dependencies
    implementation 'org.springframework.boot:spring-boot-starter-web'
    // Test implementation
    testImplementation(
        'junit:junit',
        'org.spockframework:spock-core:2.4-M1-groovy-4.0',
        'org.spockframework:spock-spring:2.4-M1-groovy-4.0',
        'org.springframework.boot:spring-boot-starter-test',
    )
}

We have now replaced the org.springframework.boot plugin with the dependecyManagent section as a single entry point of our dependencies:

dependencyManagement {
    imports {
        mavenBom 'org.springframework.boot:spring-boot-dependencies:3.2.1'
    }
}

Notably, we collapse the testImplementation in one input and add the JUnit4 dependency in case our project still uses it or has a mix with JUnit5:

// Test implementation
testImplementation(
    'junit:junit',
    'org.spockframework:spock-core:2.4-M1-groovy-4.0',
    'org.spockframework:spock-spring:2.4-M1-groovy-4.0',
    'org.springframework.boot:spring-boot-starter-test',
)

4. Conclusion

In this tutorial, we have seen how to set up a Java project using Spock and Gradle. We have also seen how to add Spring and Spring Boot dependencies. Gradle offers great build support and less verbosity in our project scripting setup. Likewise, Spock is a great testing tool for its ease of setup and specification oriented to data-driven testing and interaction-based rather than the assertion-like form of JUnit.

      

Related Stories

• Using Groovy in Spring
• How to Remove a Prefix From Strings in Groovy
• Groovy Variable Scope

 

 1. Introduction

In this tutorial, we’ll look at several methods for obtaining the current timestamp value in Java and using it as a filename.

To accomplish our goal, we’ll leverage several classes from the Java DateTime API and third-party libraries such as Joda-Time.

2. Initial Setup

In later sections, we’ll build several test cases showcasing each approach for acquiring the current timestamp and using it as a filename.

However, to convert the timestamp value into a specified string format, we first need to specify the timestamp format and then use it to define the formatter classes:

static final String TIMESTAMP_FORMAT = "yyyyMMddHHmmss";
static final DateTimeFormatter DATETIME_FORMATTER = DateTimeFormatter.ofPattern(TIMESTAMP_FORMAT);
static final SimpleDateFormat SIMPLEDATE_FORMAT = new SimpleDateFormat(TIMESTAMP_FORMAT);

Following that, we’ll write a method that converts the current time value into a valid filename. The sample output of this method will look like “20231209122307.txt“:

String getFileName(String currentTime) {
    return MessageFormat.format("{0}.txt", currentTime);
}

Since we’re writing test cases, we’ll create another method to check whether the output filename contains a timestamp with the correct format:

boolean verifyFileName(String fileName) {
    return Pattern
      .compile("[0-9]{14}+\\.txt", Pattern.CASE_INSENSITIVE)
      .matcher(fileName)
      .matches();
}

In this scenario, our filename is composed of numbers that represent the timestamp. It’s advised to ensure that the filename format avoids using characters that are forbidden in file names, which are specific to the respective operating system.

3. Current Time With Java DateTime API

Java supplies legacy classes such as Calendar and Date to deal with date and time information. However, due to design flaws, new classes were introduced with the Java 8 DateTime API. The Date, Calendar, and SimpleDateFormatter classes are mutable and not thread-safe.

We’ll first take a look at the legacy classes Calendar and Date to generate the timestamp and gain a basic understanding, followed by Java 8 DateTime API classes like Instant, LocalDateTime, ZonedDateTime, and OffsetDateTime.

Notably, using the Java 8 DateTime API classes is recommended over legacy Java date and time classes for newer Java programs.

3.1. Using Calendar

The most basic approach is to use the Calendar.getInstance() method that returns a Calendar instance using the default time zone and locale. Furthermore, the getTime() method gives us the time value in milliseconds:

@Test
public void whenUsingCalender_thenGetCurrentTime() {
    String currentTime = SIMPLEDATE_FORMAT.format(Calendar.getInstance().getTime());
    String fileName = getFileName(currentTime);
  
    assertTrue(verifyFileName(fileName));
}

The SimpleDateFormatter class can transform the time value into the appropriate timestamp format.

3.2. Using Date

Similarly, we may construct an object of the Date class that expresses the object’s creation time in milliseconds. SimpleDateFormatter transforms the millisecond time value to the desired string pattern:

@Test
public void whenUsingDate_thenGetCurrentTime() {
    String currentTime = SIMPLEDATE_FORMAT.format(new Date());
    String fileName = getFileName(currentTime);
  
    assertTrue(verifyFileName(fileName));
}

It’s recommended  to use the new Java 8 classes that we’ll see in the next sections.

3.3. Using Instant

In Java, the Instant class represents a single moment on the UTC timeline:

@Test
public void whenUsingInstant_thenGetCurrentTime() {
    String currentTime = Instant
      .now()
      .truncatedTo(ChronoUnit.SECONDS)
      .toString()
      .replaceAll("[:TZ-]", "");
    String fileName = getFileName(currentTime);
    assertTrue(verifyFileName(fileName));
}

Instant.now() method asks the system clock for the current instant. We can use the truncatedTo() method to round off the value to the nearest second. The second value can then be changed to a string to substitute any undesired characters in the time zone information from the timestamp.

3.4. Using LocalDateTime

LocalDateTime represents the date and time of the day without a time zone in the ISO-8601 calendar system:

@Test
public void whenUsingLocalDateTime_thenGetCurrentTime() {
    String currentTime = LocalDateTime.now().format(DATETIME_FORMATTER);
    String fileName = getFileName(currentTime);
    assertTrue(verifyFileName(fileName));
}

LocalDateTime.now() method queries the default system clock to provide date-time information. We can then pass a DateTimeFormatter to format the timestamp into a string

3.5. Using ZonedDateTime

ZonedDateTime is an immutable representation of a date-time with a time zone:

@Test
public void whenUsingZonedDateTime_thenGetCurrentTime() {
    String currentTime = ZonedDateTime
      .now(ZoneId.of("Europe/Paris"))
      .format(DATETIME_FORMATTER);
    String fileName = getFileName(currentTime);
    assertTrue(verifyFileName(fileName));
}

A time zone identifier is capable of uniquely identifying specific geographical locations on Earth, for example, “Europe/Paris“. Using this identification, we can obtain the ZoneId, which determines the time zone to use for the conversion from Instant to LocalDateTime.

ZonedDateTime automatically handles daylight savings time (DST) adjustments throughout the year.

3.6. Using OffsetDateTime

OffsetDateTime is a simplified version of ZonedDateTime that ignores time zones. Time zone offsets vary between different regions of the world. For example, “+2:00” denotes a time in a time zone two hours after UTC. We can alter the default time in UTC by using the offset value with ZoneOffSet:

@Test
public void whenUsingOffsetDateTime_thenGetCurrentTime() {
    String currentTime = OffsetDateTime
      .of(LocalDateTime.now(), ZoneOffset.of("+02:00"))
      .format(DATETIME_FORMATTER);
    String fileName = getFileName(currentTime);
    assertTrue(verifyFileName(fileName));
}

Both ZonedDateTime and OffsetDateTime store an instant of the timeline up to a precision of nanoseconds. Knowing their differences helps us choose between them.

4. Current Time With Joda-Time

Joda-Time is a well-known library for date and time processing. It’s one of the most popular libraries among developers as a replacement for troublesome legacy Java classes. It handles date and time values using immutable classes.

Let’s add the Joda-Time Maven dependency in pom.xml:

<dependency>
    <groupId>joda-time</groupId>
    <artifactId>joda-time</artifactId>
    <version>2.12.5</version>
</dependency>

4.1. Using Joda DateTime

DateTime.now() method obtains a DateTime set to the current system millisecond time using the default time zone. We can then convert it to a String with a defined timestamp format:

@Test
public void whenUsingJodaTime_thenGetCurrentTime() {
    String currentTime = DateTime.now().toString(TIMESTAMP_FORMAT);
    String fileName = getFileName(currentTime);
    assertTrue(verifyFileName(fileName));
}

4.2. Using Joda Instant

Joda-Time library also provides the Instant class to capture the moment in the current timeline. We can use DateTimeFormat to transform the timestamp into the desired string pattern:

@Test
public void whenUsingJodaTimeInstant_thenGetCurrentTime() {
    String currentTime = DateTimeFormat
      .forPattern(TIMESTAMP_FORMAT)
      .print(org.joda.time.Instant.now().toDateTime());
    String fileName = getFileName(currentTime);
    assertTrue(verifyFileName(fileName));
}

5. Conclusion

In this article, we discovered a variety of methods for obtaining the current timestamp within a Java program and utilized them to generate a filename. We acquired the current timestamp by using various Java DateTime API classes and the Joda-Time library.

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

       

1. Overview

Java Secure Socket Layer (SSL) debugging is crucial for developers and administrators to diagnose and troubleshoot issues related to establishing secure connections in applications. Enabling SSL debugging provides insights into the handshake process, cipher suites negotiation, and other security-related activities. 

In this tutorial, we’ll explore various ways of enabling Java SSL debugging through a series of practical examples.

2. Why Enable SSL Debug Logging?

The SSL/TLS protocols are fundamental for securing data transmission over the internet.

When using these protocols in applications, we can use SSL debugging to enhance both the security and efficiency of SSL-protected communications in our systems. Some of the ways it can help us include:

• Identifying anomalies such as certificate mismatches and connection failures
• Monitoring against malicious activity
• Ensuring we’re using the appropriate implementation of an encryption algorithm
• Optimizing performance

An output snippet might look like this:

%% Initialized: [Session-1, SSL_RSA_WITH_AES_256_CBC_SHA]
Cipher Suite: SSL_RSA_WITH_AES_256_CBC_SHA
ServerKeyExchange: EC Diffie-Hellman Server Params: [...]
*** ServerHelloDone
Cert chain length: 1
*** Certificate chain
[...]
Application data: "Hello, World!"

In this example, the output begins with session initialization, followed by details on the chosen cipher suite, key exchange parameters, and the completion of the handshake. It also includes information about the certificate chain and application data being transferred securely.

3. Using Command-Line Options

One straightforward way to enable SSL debug logging is through the command-line option. Java allows us to configure it via the javax.net.debug system property. This property accepts various debugging options, allowing users to customize the level of detail in the debugging output:

java -Djavax.net.debug=ssl -jar MyApp.jar

This command activates debugging for all SSL-related activities. For more detailed debugging, some other useful options are:

• handshake for detailed information during SSL handshake
• keygen for key generation details
• record for information about record layer processing

The entire list of options is available in the official documentation.

Let’s utilize the handshake option to generate SSL logs that pertain to the handshake process:

java -Djavax.net.debug=ssl:handshake -jar MyApp.jar

When the above command is executed, the output contains details of the handshake. It’s useful when troubleshooting issues during the initial phase that establishes the SSL/TLS connection between a client and a server. Below is a snippet of the log:

Allow unsafe renegotiation: false
Allow legacy hello messages: true
Is initial handshake: true
Is secure renegotiation: false
...
main, READ: TLSv1.2 Handshake, length = 232
...
*** ClientHello, TLSv1.2
...

The output includes information about the negotiation process, the protocol version being used (in this case, TLSv1.2), and details about the initial handshake messages exchanged between the client and the server.

4. Using System Properties

In some scenarios, we may want to enable SSL debug logging dynamically at runtime. We can do this by changing the value of the javax.net.debug system property programmatically:

static void enableSSLDebugUsingSystemProperties() {
    System.setProperty("javax.net.debug", "ssl");
}

Let’s attempt to initiate a dummy HTTPS request to retrieve the logs:

static void makeHttpsRequest() throws Exception {
    String url = "https://github.com/eugenp/tutorials";
    URL httpsUrl = new URL(url);
    HttpsURLConnection connection = (HttpsURLConnection) httpsUrl.openConnection();
    try (BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
        String line;
        logger.info("Response from " + url + ":");
        while ((line = reader.readLine()) != null) {
            logger.info(line);
        }
    }
}

This approach allows us to toggle logging on and off based on specific events or conditions in our application:

@Test
void givenSSLDebuggingEnabled_whenUsingSystemProperties_thenEnableSSLDebugLogging() {
    ByteArrayOutputStream outContent = new ByteArrayOutputStream();
    System.setErr(new PrintStream(outContent));
    SSLDebugLogger.enableSSLDebugUsingSystemProperties();
    assertEquals("ssl", System.getProperty("javax.net.debug"));
    
    SSLDebugLogger.makeHttpsRequest();
    assertTrue(outContent.toString().contains("javax.net.ssl|DEBUG|"));
    outContent.reset();
    System.clearProperty("javax.net.debug");
    assertNull(System.getProperty("javax.net.debug"));
    
    SSLDebugLogger.makeHttpsRequest();
    assertEquals(outContent.toString(),"");
}

Enabling SSL debugging using system properties offers a quick setup that doesn’t require any configuration files and allows for on-the-fly debugging.

5. Using Logging Configuration File

We can also configure Java Logging to capture SSL debugging information. By creating a logging.properties file and placing it in the classpath, we can customize the logging behavior.

Let’s add the following lines to the logging.properties file to enable logging:

java.util.logging.ConsoleHandler.level=ALL
java.net.ssl.handlers=java.util.logging.ConsoleHandler
javax.net.ssl.level=ALL

These properties tell the console handler to capture messages at all levels.

Let’s test the new behavior with a unit test:

@Test
void givenSSLDebuggingEnabled_whenUsingConfigurationFile_thenEnableSSLDebugLogging() throws IOException {
    InputStream configFile = SSLDebugLoggerUnitTest.class.getClassLoader().getResourceAsStream("logging.properties");
    LogManager.getLogManager().readConfiguration(configFile);
    Logger sslLogger = Logger.getLogger("javax.net.ssl");
    ConsoleHandler consoleHandler = (ConsoleHandler) sslLogger.getHandlers()[0];
    Level consoleHandlerLevel = consoleHandler.getLevel();
    assertEquals(Level.ALL, consoleHandlerLevel, "SSL ConsoleHandler level should be ALL");
}

This approach provides granular control over SSL debugging settings, but any changes typically require an application restart.

6. Conclusion

In this article, we saw various ways of enabling SSL debug logging in Java, which can be leveraged to gain valuable insights into the handshake process, certificate validation, and other aspects of secure communication. This facilitates the prevention and resolution of security-related issues.

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

       

1. Overview

When we work with Java, efficiently navigating through collections is a common requirement. When dealing with lists, the ListIterator interface provides a powerful tool for bidirectional traversal. However, there are situations where resetting the ListIterator to the first element becomes necessary.

In this tutorial, we will explore the various ways to reset a ListIterator to the beginning of a list in Java.

2. Introduction to the Problem

As usual, let’s understand the problem through an example.

Let’s say we have a list of strings:

List<String> MY_LIST = List.of("A", "B", "C", "D", "E", "F", "G");

Then, we can obtain a ListIterator on MY_LIST by MY_LIST.listIterator() and iterate through the list by calling ListIterator‘s next() method.

Sometimes, we may want to reset the ListIterator object by asking it to point to the position right before the first element in the list again, as it was newly created.

Next, we’ll look at different approaches to solving this problem. Also, we’ll leverage unit test assertions to verify whether each solution gives the expected result.

3. Creating a New ListIterator

We know that when we create a new ListIterator object, it points to the beginning of the target list. Therefore, the easiest way to reset a ListIterator instance would be to reassign the variable to a new ListIterator.

Let’s create a test and verify if this idea works as expected:

ListIterator<String> lit = MY_LIST.listIterator();
lit.next();
lit.next();
lit.next();
lit.next();
lit = MY_LIST.listIterator();
assertFalse(lit.hasPrevious());
assertEquals("A", lit.next());

As the test above shows, after we created a ListIterator lit, we called the lit.next() method four times. When we would like to reset lit, we created a new ListIterator instance and reassigned it to lit.

Then, we verify if lit is reset successfully by two assertions:

• lit.hasPrevious() returns false
• lit.next() should be the first element in MY_LIST (“A”)

If we give this test a run, it passes. Therefore, creating a new ListIterator solves our problem.

4. Iterating Backward to the Beginning of the List

Creating a new ListIterator can quickly navigate to the beginning of a list. However, we’ll have a new ListIterator object.

Sometimes, we want to keep the original ListIterator object and move its pointer back to the beginning of the target list. If this is the case, we can utilize ListIterator‘s bidirectional iteration feature to iterate backward to the beginning of the list.

Next, let’s create a test to see how to achieve that:

ListIterator<String> lit = MY_LIST.listIterator();
lit.next();
lit.next();
lit.next();
lit.next();
while (lit.hasPrevious()) {
    lit.previous();
}
assertFalse(lit.hasPrevious());
assertEquals("A", lit.next());

As we can see, we apply the backward iteration through a while loop.

If we run the test, it passes. So, it does the job.

It’s worth noting since this approach iterates from the current position backward to the beginning of the list, it can be slow if the number of elements in the list is significant.

5. Conclusion

In this article, we’ve explored two approaches to resetting a ListIterator to the beginning of the list.

If it’s required to keep the original ListIterator instance, we can iterate backward to the head of the list. Otherwise, creating a new ListIterator would be the most straightforward solution.

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

       

1. Introduction

Java Flight Recorder (JFR) is a profiling and diagnostic tool that monitors the JVM and the programs that run on it. It’s a handy profiling tool developers use to monitor the state and performance of their applications.

This tutorial will focus on the new view command introduced in Java 21 for JFR.

2. Java Flight Recorder (JFR)

The Java Flight Recorder (JFR) is a low-overhead application profiling framework introduced in Java 7 as an experimental feature. It allowed us to analyze and understand important metrics about our programs, such as garbage collection patterns, IO operations, memory allocations, and more.

2.1. What Is The Java Flight Recorder?

JFR collects information about the events in the JVM when a Java application runs and we analyze the results with diagnostic tools.

JFR monitors the application and records the analysis in a recording file. There are two ways for us to instruct the JFR to monitor an application:

1. Use the command line to start the application and enable JFR.
2. Use a diagnostic tool such as jcmd on an already running Java application.

The recording is typically generated as a .jfr file, which can then be analyzed by visual tools such as the Java Mission Control (JMC) tool or using the new view command as we’ll see in the upcoming sections.

2.2. Recording From the Command Line

To demonstrate a flight recording, let’s write a small program that inserts an object into an ArrayList until an OutOfMemoryError is thrown:

void insertToList(List<Object> list) {
    try {
        while (true) {
            list.add(new Object());
        }
    } catch (OutOfMemoryError e) {
        System.out.println("Out of Memory. Exiting");
    }
}

Let’s compile the program using the standard javac compiler:

javac -d out -sourcepath JFRExample.java

Once the .class file is generated, we start the flight recorder. We pass some additional arguments to the java command, namely the -XX:+FlightRecorder option, along with some additional parameters to set the recording duration and the output file path where the recording will be stored:

java -XX:StartFlightRecording=duration=200s,filename=flight.jfr -cp ./out/ com.baeldung.jfrview.JFRExample

Our program now runs with JFR enabled to capture the events and other system properties, and JFR writes the results into the flight.jfr file.

2.3. Recording Using the jcmd Tool

The jcmd diagnostic tool provides an alternative way to record and analyze the performance of our applications and JVM. We can register diagnostic events to a running virtual machine using this tool.

To use the jcmd tool, we need our application to be running and we must know the pid:

jcmd <pid|MainClass> <command> [parameters]

Several commands that the jcmd tool recognizes are:

• JFR.start – starts a new JFR recording
• JFR.check – checks running JFR recording(s)
• JFR.stop – stops a specific JFR recording
• JFR.dump – copies contents of a JFR recording to file

Each of these commands requires additional parameters.

Let’s create a recording using the jcmd tool now. We need to start the application and find the pid of the running process. Once we have the pid, we start the recording:

jcmd 128263 JFR.start filename=recording.jfr

We can stop the recording when we’ve captured the relevant events:

jcmd 128263 JFR.stop filename=recording.jfr

3. Viewing the JFR Recording File

To view and understand the results of the jfr file, we can use the Java Mission Control (JMC) tool. The JMC tool comes with numerous functionalities to profile and monitor Java applications, including a diagnostic tool that reads JFR files and shows a visual representation of the result:

4. The jfr Command

The jfr command parses and prints flight recording files (.jfr) to standard output. While we previously used the Mission Control tool for visual representation, the jfr command provides us with a way to filter, summarize, and generate human-readable output from flight recording files in the console.

4.1. Using the jfr Command

The jfr command resides in the bin path of the $JAVA_HOME. Let’s look at its syntax:

$JAVA_HOME/bin/jfr [command] <path>

In the following sections, we’ll be accessing jfr directly.

4.2. jfr Commands

jfr previously had five commands namely print, summary, metadata, assemble, and disassemble. The view command is the sixth jfr command that has been introduced.

The print command is used to print the contents of the flight recording and it takes several parameters including the output format(json/xml etc), a range of filters which might include categories, events, and the stack depth:

jfr print [--xml|--json] [--categories <filters>] [--events <filters>] [--stack-depth <depth>] <file>

The summary command as the name suggests generates a summary of the recording that includes the events that occurred, disk space utility etc:

jfr summary <file>

The metadata command generates detailed information about the events such as their names and categories:

jfr metadata <file>

Finally, the assemble and disassemble commands are for assembling chunk files into a recording file and vice-versa:

jfr assemble <repository> <file>
jfr disassemble [--max-chunks <chunks>] [--output <directory>] <file>

4.3. Example of a jfr Command

Now we’ll look at an example jfr command and generate the summary of our JFR file:

$JAVA_HOME/bin/jfr summary recording.jfr
 Version: 2.1
 Chunks: 1
 Start: 2023-12-25 17:07:08 (UTC)
 Duration: 1 s
 Event Type                              Count  Size (bytes)
=============================================================
 jdk.NativeLibrary                         512         44522
 jdk.SystemProcess                         511         49553
 jdk.ModuleExport                          506          4921
 jdk.BooleanFlag                           495         15060
 jdk.ActiveSetting                         359         10376
 jdk.GCPhaseParallel                       162          4033

5. The view Command in JDK 21

Java 21 introduced the view command to facilitate the analysis of JFR recordings from the command line. This new view command eliminates the use of dumping recording downloads into the JMC tool and comes with more than 70 prebuilt options. These options, which are likely to increase over time, cover almost all important aspects of the application including the JVM, the application itself, and the environment of the application.

5.1. Categories of View Options

We can broadly classify the different view options into three categories which are similar to the ones displayed in the JMC tool:

1. Java Virtual Machine Views
2. Environment Views
3. Application Views

5.2. JVM Views

Java Virtual Machine views give insights into the JVM attributes such as heap space, garbage collection, native memory, and other compiler-related metrics. Some common JVM views include:

• class-modifications
• gc-concurrent-phases
• compiler-configuration
• gc-configuration
• native-memory-committed
• gc-cpu-time
• compiler-statistics
• gc-pause-phases
• heap-configuration

5.3. Environment Views

Environment views show information about the host system where the JVM is running such as CPU information, network utilization, system properties, process, and information. Some common Environment views are:

• cpu-information
• cpu-load
• jvm-flags
• container-configuration
• network-utilization
• system-processes
• system-properties

5.4. Application Views

Application views provide insights into our application code such as information regarding its thread usage, object statistics, and memory utilization. Some common Application views include:

• exception-count
• object-statistics
• allocation-by-thread
• memory-leaks-by-class
• thread-cpu-load
• thread-count
• thread-allocation

5.5. Command Structure of view

The view command expects a view name and the path to the recording file along with relevant parameters. It can be activated using the jfr command and the jcmd command:

jfr view [view] <recording file>

jcmd <pid> JFR.view [view name]

The output is then displayed on the command line, or any standard output. Additionally, the commands provide customization capabilities on the output format, time ranges, and custom views.

6. JFR view Command Usage

In this section, we’ll use the view command with some of the views mentioned in the previous section to analyze the JFR recording file we generated earlier.

6.1. Using the jfr Command

Let’s apply the gc-configuration JVM view on our flight recording using the jfr command and capture the output:

jfr view gc-configuration flight.jfr

GC Configuration
----------------
Young GC: G1New
Old GC: G1Old
Parallel GC Threads: 4
Concurrent GC Threads: 1
Dynamic GC Threads: true
Concurrent Explicit GC: false
Disable Explicit GC: false
Pause Target: N/A
GC Time Ratio: 12

The view, as its name suggests generates information about the GC type being used and other relevant data on garbage collection.

6.2. Using the jcmd Tool

We can use the view command with the jcmd tool as well:

jcmd <pid> JFR.view [view name]

The jcmd tool requires a running pid to diagnose and we’ll request the Environment view system-processes:

jcmd 37417 JFR.view cell-height=3 truncate=beginning width=80 system-processes
                                                    System Processes
First Observed Last Observed PID  Command Line
-------------- ------------- ---- -------------------------------------------------------------------------------------
23:21:26       23:21:26      453  /Applications/Flycut.app/Contents/MacOS/Flycut
23:21:26       23:21:26      780  /Applications/Grammarly Desktop.app/Contents/Library/LaunchAgents/Grammarly Deskto...
23:21:26       23:21:26      455  /Applications/Grammarly Desktop.app/Contents/MacOS/Grammarly Desktop
23:21:26       23:21:26      431  /Applications/JetBrains Toolbox.app/Contents/MacOS/jetbrains-toolbox
23:21:26       23:21:26      624  /Applications/Safari.app/Contents/MacOS/Safari

6.3. Formatting the view Command Output

We can play with the output of the view command and adjust it according to our needs. The view command currently provides several options to format the output, including modifying the number of columns and rows, and other options such as a verbose flag and output truncation:

--width [number-of-columns]
--cell-height [number of rows]
--verbose [the query that makes up the view]
--truncate [--beginning|--end] [truncate content from beginning or end]

As an example, let’s format the output of the system processes view that we generated above in such a way that each row has two lines and also make the response verbose:

jfr view --cell-height 2 --width 100 --truncate beginning --verbose system-processes flight.jfr
                                          System Processes
First Observed Last Observed PID   Command Line
(startTime)    (startTime)   (pid) (commandLine)
-------------- ------------- ----- ----------------------------------------------------------------
23:33:47       23:33:47      453   /Applications/Flycut.app/Contents/MacOS/Flycut
23:33:47       23:33:47      780   ...ions/Grammarly Desktop.app/Contents/Library/LaunchAgents/Gram
                                   marly Desktop Helper.app/Contents/MacOS/Grammarly Desktop Helper
23:33:47       23:33:47      455   /Applications/Grammarly Desktop.app/Contents/MacOS/Grammarly Des
                                   ktop
23:33:47       23:33:47      431   /Applications/JetBrains Toolbox.app/Contents/MacOS/jetbrains-too
                                   lbox
23:33:47       23:33:47      624   /Applications/Safari.app/Contents/MacOS/Safari
COLUMN 'First Observed', 'Last Observed', 'PID', 'Command Line' SELECT FIRST(startTime),
LAST(startTime), FIRST(pid), FIRST(commandLine) FROM SystemProcess GROUP BY pid
Execution: query-validation=10.6 ms, aggregation=241 ms, formatting=121 ms

As we can see, the verbose command generates more information about the system processes including some meta information such as an explanation of the query and execution statistics to see how long it took.

6.4. Comparing the Result With JCM

The JFR view Command is an attempt to make the process of analyzing JFR recordings easier and independent of any additional tool. The JMC visual output and the console-based output of the view command are quite similar. We can compare the result of the system-processes view with that of the visual JMC tool:

7. Conclusion

In this article, we looked at the newly added JFR view command that assists in displaying the results of the Java flight recordings directly in the command line with a set of predefined views. We saw the different categories of views available today and the ways we can generate a view for our flight recordings.

As usual, the source code from this article can be found over on GitHub.

       

1. Introduction

Apache Maven is a powerful build management tool that provides a structured way to manage the build lifecycle of a project. Maven builds are composed of lifecycles, which define clearly how a project is built and distributed.

Two very useful commands that play a key role in the build process are mvn install and mvn verify. In this tutorial, we’ll compare and contrast these two commands, understanding the differences between them.

2. Maven Lifecycles

Maven defines three standard lifecycles — clean, default, and site — where each one has a distinct purpose:

• The clean lifecycle is responsible for cleaning the project.
• The default lifecycle is for building and deploying.
• The site lifecycle is for creating the project’s site documentation.

Each lifecycle consists of phases, and each phase represents a stage in the lifecycle.

2.1. Maven’s default Lifecycle

The default lifecycle handles the build process, starting from project compilation and ending with the deployment of artifacts. It is composed of six phases:

1. validate: The project is validated to ensure that all necessary information is available for the build.
2. compile: The source code is compiled into bytecode.
3. test: Unit tests are executed to ensure the code’s correctness.
4. package: The compiled code is packaged into a JAR or WAR file, depending on the project type.
5. verify: Additional verification checks run, typically integration tests or ones specified by plugins.
6. install: The packaged artifact is installed into the local Maven repository, ~/.m2/repository, making it available for other projects on the same machine.

When running a command, we only need to call the last build phase we want to be executed. For instance, running mvn test will execute, in order, the validate, compile, and test phases.

3. Setup

In our pom.xml, let’s define the maven-surefire-plugin that’s required to run unit tests during the test phase:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.1.2</version>
</plugin>

Let’s also configure the maven-failsafe-plugin to execute integration tests during the verify phase:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-failsafe-plugin</artifactId>
    <version>3.1.2</version>
    <executions>
        <execution>
            <goals>
                <goal>integration-test</goal>
                <goal>verify</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Next, let’s write a simple Java program that returns a String when executed:

class CourseApp {
    String getCourse() {
        return "Baeldung Spring Masterclass";
    }
}

We’ll define a unit test that will be executed as part of the test phase:

@Test
void whenGetCourse_ThenCourseShouldBePresent() {
    CourseApp courseApp = new CourseApp();
    
    assertEquals("Baeldung Spring Masterclass", courseApp.getCourse());
}

Similarly, a simple integration test will be executed as part of the integration-test goal of the verify phase.

@Test
void givenIntegrationTest_whenGetCourse_ThenCourseShouldBePresent() {
    CourseApp courseApp = new CourseApp();
    
    assertEquals("Baeldung Spring Masterclass", courseApp.getCourse());
}

4. Maven Verify Phase

The mvn verify command triggers five phases: validate, compile, test, package, and verify. The verify phase is intended to be used for verifying a project’s integrity and quality.

Since we bound the verify phase to the integration-test goal using the maven-failsafe-plugin, our integration tests will run. Maven considers the project verified only if both unit and integration tests pass:

By executing the verify phase, we can ensure that our project undergoes thorough testing, including integration testing, before being packaged into an artifact and distributed. This phase can help us maintain the reliability and quality of our application.

5. Maven Install Phase

On the other hand, mvn install is responsible for installing the project’s artifacts into the local repository. It triggers the install phase, which comes directly after verify. Thus, it serves the double purpose of verifying our code’s quality and installing our artifact locally.

When we run mvn install, Maven executes the install phase in addition to all the previous steps of the verify phase:

This is particularly useful when working on multiple projects that have dependencies on one another, as it avoids having to copy JAR files between projects manually.

6. Differences Between mvn install and mvn verify

While both mvn install and mvn verify contribute to the default lifecycle and share common phases, they serve slightly different purposes:

• mvn verify focuses on performing quality checks beyond simple unit testing, such as integration tests and custom checks configured through plugins. It is recommended when the objective is to ensure the project meets specific quality criteria.
• mvn install is primarily used for installing the project’s artifacts into the local repository. It’s often used during development to share artifacts between projects on the same machine.

7. Conclusion

Understanding the different Maven lifecycles and phases is essential for effective project management and collaboration in a Maven-powered build environment.

In this article, we discussed how mvn install is the go-to command for local development and dependency management. In contrast, we’ve seen how mvn verify can be used to perform integrity and quality checks against our project.

As always, the code is available over on GitHub.

       

1. Overview

In this article, we’ll learn about Spring-Kafka‘s RecordDeserializationException. After that, we’ll create a custom error handler to catch this exception and skip the invalid message, allowing the consumer to continue processing the next events.

This article relies on Spring Boot’s Kafka modules, which offer convenient tools for interacting with the broker.  For a deeper grasp of Kafka internals, we can revisit the fundamental concepts of the platform.

2. Creating a Kafka Listener

For the code examples in this article, we’ll use a small application that listens to the topic “baeldung.articles.published” and processes the incoming messages. To showcase the custom error handling, our application should continue consuming messages after encountering deserialization exceptions.   

Spring-Kafka’s version will be resolved automatically by the parent Spring Boot pom. Therefore, we simply need to add the module dependency:

<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
</dependency>

This module enables us to use the @KafkaListener annotation, an abstraction over Kafka’s Consumer API. Let’s leverage this annotation to create the ArticlesPublishedListener component. Additionally, we’ll introduce another component, EmailService, that will perform an action for each of the incoming messages:

@Component
class ArticlesPublishedListener {
    private final EmailService emailService;
    // constructor
    @KafkaListener(topics = "baeldung.articles.published")
    public void onArticlePublished(ArticlePublishedEvent event) {
        emailService.sendNewsletter(event.article());
    }
}
record ArticlePublishedEvent(String article) {
}

For the consumer configuration, we’ll focus on defining only the properties crucial to our example. When we’re developing a production application, we can adjust these properties to suit our particular needs or externalize them to a separate configuration file:

@Bean
ConsumerFactory<String, ArticlePublishedEvent> consumerFactory(
  @Value("${spring.kafka.bootstrap-servers}") String bootstrapServers
) {
    Map<String, Object> props = new HashMap<>();
    props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers);
    props.put(ConsumerConfig.GROUP_ID_CONFIG, "baeldung-app-1");
    props.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
    props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
    props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, JsonDeserializer.class);
    return new DefaultKafkaConsumerFactory<>(
      props,
      new StringDeserializer(),
      new JsonDeserializer<>(ArticlePublishedEvent.class)
    );
}
@Bean
KafkaListenerContainerFactory<String, ArticlePublishedEvent> kafkaListenerContainerFactory(
  ConsumerFactory<String, ArticlePublishedEvent> consumerFactory
) {
    var factory = new ConcurrentKafkaListenerContainerFactory<String, ArticlePublishedEvent>();
    factory.setConsumerFactory(consumerFactory);
    return factory;
}

3. Setting up the Test Environment

To set up our testing environment, we can leverage a Kafka Testcontainer that will seamlessly spin up a Kafka Docker container for testing:

@Testcontainers
@SpringBootTest(classes = Application.class)
class DeserializationExceptionLiveTest {
    @Container
    private static KafkaContainer KAFKA = new KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:latest"));
    @DynamicPropertySource
    static void setProps(DynamicPropertyRegistry registry) {
        registry.add("spring.kafka.bootstrap-servers", KAFKA::getBootstrapServers);
    }
    // ...
}

Alongside this, we’ll need a KafkaProducer and an EmailService to validate our listener’s functionality. These components will send messages to our listener and verify their accurate processing. To simplify the tests and avoid mocking, let’s persist all incoming articles in a list, in memory, and later access them using a getter:

@Service
class EmailService { 
    private final List<String> articles = new ArrayList<>();
   
    // logger, getter
    public void sendNewsletter(String article) {
        log.info("Sending newsletter for article: " + article);
        articles.add(article);
    }
}

As a result, we simply need to inject the EmailService into our test class. Let’s continue by creating testKafkaProducer:

@Autowired
EmailService emailService;
static KafkaProducer<String, String> testKafkaProducer;
@BeforeAll
static void beforeAll() {
    Properties props = new Properties();
    props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, KAFKA.getBootstrapServers());
    props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
    props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
    testKafkaProducer = new KafkaProducer<>(props);
}

With this setup, we can already test the happy flow. Let’s publish two articles with a valid JSON and verify that our application successfully called  the emailService for each of them:

@Test
void whenPublishingValidArticleEvent_thenProcessWithoutErrors() {
    publishArticle("{ \"article\": \"Kotlin for Java Developers\" }");
    publishArticle("{ \"article\": \"The S.O.L.I.D. Principles\" }");
    await().untilAsserted(() -> 
      assertThat(emailService.getArticles())
        .containsExactlyInAnyOrder(
          "Kotlin for Java Developers", 
          "The S.O.L.I.D. Principles"
        ));
}

4. Causing a RecordDeserializationException

Kafka throws RecordDeserializationException if the configured deserializer cannot properly parse the key or value of the message. To reproduce this error, we simply need to publish a message containing an invalid JSON body:

@Test
void whenPublishingInvalidArticleEvent_thenCatchExceptionAndContinueProcessing() {
    publishArticle("{ \"article\": \"Introduction to Kafka\" }");
    publishArticle(" !! Invalid JSON !! ");
    publishArticle("{ \"article\": \"Kafka Streams Tutorial\" }");
    await().untilAsserted(() -> 
      assertThat(emailService.getArticles())
        .containsExactlyInAnyOrder(
          "Kotlin for Java Developers",
          "The S.O.L.I.D. Principles"
        ));
}

If we run this test and check the console, we’ll observe a recurring error being logged:

ERROR 7716 --- [ntainer#0-0-C-1] o.s.k.l.KafkaMessageListenerContainer    : Consumer exception
**java.lang.IllegalStateException: This error handler cannot process 'SerializationException's directly; please consider configuring an 'ErrorHandlingDeserializer' in the value and/or key deserializer**
   at org.springframework.kafka.listener.DefaultErrorHandler.handleOtherException(DefaultErrorHandler.java:151) ~[spring-kafka-2.8.11.jar:2.8.11]
   at org.springframework.kafka.listener.KafkaMessageListenerContainer$ListenerConsumer.handleConsumerException(KafkaMessageListenerContainer.java:1815) ~[spring-kafka-2.8.11.jar:2.8.11]
   ...
**Caused by: org.apache.kafka.common.errors.RecordDeserializationException: Error deserializing key/value for partition baeldung.articles.published-0 at offset 1. If needed, please seek past the record to continue consumption.**
   at org.apache.kafka.clients.consumer.internals.Fetcher.parseRecord(Fetcher.java:1448) ~[kafka-clients-3.1.2.jar:na]
   ...
**Caused by: org.apache.kafka.common.errors.SerializationException: Can't deserialize data** [[32, 33, 33, 32, 73, 110, 118, 97, 108, 105, 100, 32, 74, 83, 79, 78, 32, 33, 33, 32]] from topic [baeldung.articles.published]
   at org.springframework.kafka.support.serializer.JsonDeserializer.deserialize(JsonDeserializer.java:588) ~[spring-kafka-2.8.11.jar:2.8.11]
   ...
**Caused by: com.fasterxml.jackson.core.JsonParseException: Unexpected character ('!' (code 33))**: expected a valid value (JSON String, Number, Array, Object or token 'null', 'true' or 'false')
   **at [Source: (byte[])" !! Invalid JSON !! "; line: 1, column: 3]**
   at com.fasterxml.jackson.core.JsonParser._constructError(JsonParser.java:2391) ~[jackson-core-2.13.5.jar:2.13.5]
   ...

Then, the test will eventually time out and fail. If we check the assertion error, we’ll notice that only the first message was successfully processed:

org.awaitility.core.ConditionTimeoutException: Assertion condition 
Expecting actual:
  ["Introduction to Kafka"]
to contain exactly in any order:
  ["Introduction to Kafka", "Kafka Streams Tutorial"]
but could not find the following elements:
  ["Kafka Streams Tutorial"]
 within 5 seconds.

As expected, the deserialization failed for the second message. Consequently, the listener continued attempting to consume the same message, leading to the repeated occurrence of the error.

5. Creating an Error Handler

If we carefully analyze the failure logs, we’ll notice two suggestions:

• consider configuring an ‘ErrorHandlingDeserializer‘;
• if needed, please seek past the record to continue consumption;

In other words, we can create a custom error handler that will handle the deserialization exception and increase the consumer offset. This will allow us to skip the invalid message and proceed with the consumption.

5.1. Implementing CommonErrorHandler

To implement the CommonErrprHandler interface, we’ll have to override two public methods without a default implementation:

• handleRecord() – called to handle a single failed record;
• handleOtherException() – called when an exception is thrown, but not for a particular record;

We can handle both cases using a similar approach. Let’s start by catching the exception and logging an error message:

class KafkaErrorHandler implements CommonErrorHandler {
    @Override
    public void handleRecord(Exception exception, ConsumerRecord<?, ?> record, Consumer<?, ?> consumer, MessageListenerContainer container) {
        handle(exception, consumer);
    }
    @Override
    public void handleOtherException(Exception exception, Consumer<?, ?> consumer, MessageListenerContainer container, boolean batchListener) {
        handle(exception, consumer);
    }
    private void handle(Exception exception, Consumer<?, ?> consumer) {
        log.error("Exception thrown", exception);
        // ...
    }
}

5.2. Kafka Consumer’s seek() and commitSync()

We can use the seek() method from the Consumer interface to manually change the current offset position for a particular partition within a topic. Simply put, we can use it to reprocess or skip messages as needed based on their offsets.

In our case, if the exception is an instance of RecordDeserializationException, we’ll call the seek() method with the topic partition and the next offset:

void handle(Exception exception, Consumer<?, ?> consumer) {
    log.error("Exception thrown", exception);
    if (exception instanceof RecordDeserializationException ex) {
        consumer.seek(ex.topicPartition(), ex.offset() + 1L);
        consumer.commitSync();
    } else {
        log.error("Exception not handled", exception);
    }
}

As we can notice, we need to call the commitSync() from the Consumer interface. This will commit the offset and ensure that the new position is acknowledged and persisted by the Kafka broker. This step is crucial, as it updates the offset committed by the consumer group, indicating that messages up to the adjusted position have been successfully processed.

5.3. Updating the Configuration

Finally, we need to add the custom error handler to our consumer configuration. Let’s start by declaring it as a @Bean:

@Bean
CommonErrorHandler commonErrorHandler() {
    return new KafkaErrorHandler();
}

After that, we’ll add the new bean to the ConcurrentKafkaListenerContainerFactory using its dedicated setter:

@Bean
ConcurrentKafkaListenerContainerFactory<String, ArticlePublishedEvent> kafkaListenerContainerFactory(
  ConsumerFactory<String, ArticlePublishedEvent> consumerFactory,
  CommonErrorHandler commonErrorHandler
) {
    var factory = new ConcurrentKafkaListenerContainerFactory<String, ArticlePublishedEvent>();
    factory.setConsumerFactory(consumerFactory);
    factory.setCommonErrorHandler(commonErrorHandler);
    return factory;
}

That’s it! We can re-run the tests now and expect the listener to skip the invalid message and continue consuming messages.

6. Conclusion

In this article, we discussed Spring Kafka’s RecordDeserializationException and we discovered that, if not handled correctly, it can block the consumer group for the given partition.

Following that, we delved into Kafka’s CommonErrorHandler interface and implemented it to enable our listener to handle deserialization failures while continuing to process messages. We leveraged the Consumer’s API methods, namely seek() and commitSync(), to bypass invalid messages by adjusting the consumer offset accordingly.

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

       

1. Introduction

In this quick tutorial, we’ll explore effective methods for applying a bold font style to entire rows in Excel sheets using the Apache POI library. Through straightforward examples and valuable insights, we’ll navigate the nuances of each method.

2. Dependency

Let’s start with the dependency we need to write and load Excel files, poi:

<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi</artifactId>
    <version>5.2.5</version>
</dependency>

3. Scenario and Helper Methods

Our scenario involves creating a sheet with a header row and a few data rows. Then, we’ll define a bold style for the font used in the header row. Ultimately, we’ll create a few methods to set this bold style. Most importantly, we’ll see why we need more than one to do this, as the obvious choice (setRowStyle()) doesn’t work as expected.

To facilitate sheet creation, we’ll start with a utils class. Let’s write a couple of methods to create cells and rows with cells:

public class PoiUtils {
    private static void newCell(Row row, String value) {
        short cellNum = row.getLastCellNum();
        if (cellNum == -1)
            cellNum = 0;
        Cell cell = row.createCell(cellNum);
        cell.setCellValue(value);
    }
    public static Row newRow(Sheet sheet, String... rowValues) {
        Row row = sheet.createRow(sheet.getLastRowNum() + 1);
        for (String value : rowValues) {
            newCell(row, value);
        }
        return row;
    }
    // ...
}

Then, to create a bold font style, we’ll first create a font from our Workbook, then call setBold(true). Secondly, we’ll create a CellStyle that will use our bold font:

public static CellStyle boldFontStyle(Workbook workbook) {
    Font boldFont = workbook.createFont();
    boldFont.setBold(true);
    CellStyle boldStyle = workbook.createCellStyle();
    boldStyle.setFont(boldFont);
    return boldStyle;
}

Finally, to write our sheet to a file, we need to call write() on our Workbook:

public static void write(Workbook workbook, Path path) 
  throws IOException {
    try (FileOutputStream fileOut = new FileOutputStream(path.toFile())) {
        workbook.write(fileOut);
    }
}

4. Caveats of Using setRowStyle()

When looking at the POI API, the most obvious choice for our task is Row.setRowStyle(). Unfortunately, this method doesn’t work reliably, and a bug is currently open. The problem seems to be that the Microsoft Office render ignores the row style and only cares about cell styles.

On the other hand, it works with OpenOffice, but only if we use the SXSSFWorkbook implementation, which is intended for large files. To test this, we’ll start with a sample sheet method:

private void writeSampleSheet(Path destination, Workbook workbook) 
  throws IOException {
    Sheet sheet = workbook.createSheet();
    CellStyle boldStyle = PoiUtils.boldFontStyle(workbook);
    Row header = PoiUtils.newRow(sheet, "Name", "Value", "Details");
    header.setRowStyle(boldStyle);
    PoiUtils.newRow(sheet, "Albert", "A", "First");
    PoiUtils.newRow(sheet, "Jane", "B", "Second");
    PoiUtils.write(workbook, destination);
}

Then, an assertion method is used to check the styles on the first and second rows. First, we assert the first Row has a bold font style. Then, for each cell in it, we assert the default style isn’t the same as the style we set for the first Row. This asserts our row style has priority. Finally, we assert that the second Row doesn’t contain any style applied:

private void assertRowStyleAppliedAndDefaultCellStylesDontMatch(Path sheetFile) 
  throws IOException, InvalidFormatException {
    try (Workbook workbook = new XSSFWorkbook(sheetFile.toFile())) {
        Sheet sheet = workbook.getSheetAt(0);
        Row row0 = sheet.getRow(0);
        XSSFCellStyle rowStyle = (XSSFCellStyle) row0.getRowStyle();
        assertTrue(rowStyle.getFont().getBold());
        row0.forEach(cell -> {
            XSSFCellStyle style = (XSSFCellStyle) cell.getCellStyle();
            assertNotEquals(rowStyle, style);
        });
        Row row1 = sheet.getRow(1);
        XSSFCellStyle row1Style = (XSSFCellStyle) row1.getRowStyle();
        assertNull(row1Style);
        Files.delete(sheetFile);
    }
}

Ultimately, our test consists of writing the sheet to a temporary file and then reading it back. We ensure our style is applied, test the styles in the first and second rows, and then delete the file:

@Test
void givenXssfWorkbook_whenSetRowStyle1stRow_thenOnly1stRowStyled() 
  throws IOException, InvalidFormatException {
    Path sheetFile = Files.createTempFile("xssf-row-style", ".xlsx");
    try (Workbook workbook = new XSSFWorkbook()) {
        writeSampleSheet(sheetFile, workbook);
    }
    assertRowStyleAppliedAndDefaultCellStylesDontMatch(sheetFile);
}

When running this test, we can now check that we get our bold style only for the first row, which is what we intended.

5. Using setCellStyle() Cells in the Row

Given the problems with setRowStyle(), we’re left with setCellStyle(). We’ll need it to set the style for every cell in the row where we want to apply our bold style. So, let’s modify our original by iterating through each row in our header and calling setCellStyle() with our bold style instead:

@Test
void givenXssfWorkbook_whenSetCellStyleForEachRow_thenAllCellsContainStyle() 
  throws IOException, InvalidFormatException {
    Path sheetFile = Files.createTempFile("xssf-cell-style", ".xlsx");
    try (Workbook workbook = new XSSFWorkbook()) {
        Sheet sheet = workbook.createSheet();
        CellStyle boldStyle = PoiUtils.boldFontStyle(workbook);
        Row header = PoiUtils.newRow(sheet, "Name", "Value", "Details");
        header.forEach(cell -> cell.setCellStyle(boldStyle));
        PoiUtils.newRow(sheet, "Albert", "A", "First");
        PoiUtils.write(workbook, sheetFile);
    }
    // ...
}

This way, we can guarantee our style is applied consistently across formats and platforms. Let’s finish our test by asserting row styles aren’t set and that every cell in the first row contains a bold font style:

try (Workbook workbook = new XSSFWorkbook(sheetFile.toFile())) {
    Sheet sheet = workbook.getSheetAt(0);
    Row row0 = sheet.getRow(0);
    XSSFCellStyle rowStyle = (XSSFCellStyle) row0.getRowStyle();
    assertNull(rowStyle);
    row0.forEach(cell -> {
        XSSFCellStyle style = (XSSFCellStyle) cell.getCellStyle();
        assertTrue(style.getFont().getBold());
    });
    Row row1 = sheet.getRow(1);
    rowStyle = (XSSFCellStyle) row1.getRowStyle();
    assertNull(rowStyle);
    Files.delete(sheetFile);
}

Note that we’re only using XSSFWorkbook here for convenience. This method works consistently across all Workbook implementations.

6. Conclusion

In this article, we learned that while setRowStyle() may not reliably fulfill our goal, we’ve uncovered a robust alternative using setCellStyle(). We can now confidently format rows in Excel sheets, ensuring consistent and visually impactful results across various platforms.

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

       

1. Introduction

In various applications such as appointments, bookings, or project timelines, avoiding scheduling conflicts is paramount. Overlapping dates can lead to inconsistencies and errors. In this tutorial, we’ll explore different scenarios of date range overlap and dive into various approaches and formulas to check for overlaps.

2. Understanding Overlapping Date Ranges

Before we dive into the implementation, let’s ensure a clear understanding of what it means for two date ranges to overlap. Understanding the different scenarios that constitute date range overlap is crucial when implementing an efficient and accurate overlap checker. Let’s break down the various scenarios that need to be considered.

2.1. Partial Overlap

Partial overlap occurs when one date range partially overlaps with another. This happens when two ranges share some portion of their timeframe but don’t entirely encompass each other. For example, if Project A spans from January 1st to February 10th and Project B runs from February 5th to March 1st, they partially overlap:

A                            B
|-----------------------------|
                C                                D
                |--------------------------------|

2.2 Full Overlap

Full overlap happens when one date range entirely encompasses another. This occurs when one date range completely falls within the boundaries of another. For example, if Booking A covers July 1st to July 31st and Booking B covers July 15th to July 25th, Booking B completely overlaps with Booking A:

A                                               B
|------------------------------------------------|
                C                      D
                |----------------------|

2.3 Consecutive Ranges

Two ranges are considered adjacent if one ends immediately before the other begins. This is common in project timelines, where Project X spans from March 1st to March 31st, and Project Y runs from April 1st to April 30th. These ranges are adjacent but not overlapping:

A                    B
|---------------------|
                       C                    D
                       |--------------------|

2.4. Zero-Range Duration and Consecutive Ranges

Zero-range duration refers to a scenario where the start and end dates of a range are the same, resulting in a duration of zero. For example, we may encounter an event scheduled for exactly one day with no duration. Although seemingly a special case, handling this scenario explicitly is essential to ensure the correctness of our date range overlap logic when considering consecutive ranges:

A                    B
|---------------------|
                      CD
                      |

3. Overlapping Formulas

Various mathematical formulas encapsulate the logic for determining date range overlap. Here, we’ll explore three commonly used formulas and explain their underlying principles.

Let’s first define the variables used in the formulas:

• A: Start date of the first date range
• B: End date of the first date range
• C: Start date of the second date range
• D: End date of the second date range

3.1. Calculating the Overlap Duration

This formula calculates the overlap duration by subtracting the earlier ending date from the later starting date:

(min(B, D) - max(A, C)) >= 0

If this duration is negative, there’s no overlap. If it’s zero, the ranges might be touching, or one might be a single point in time. The application should consider whether to treat this scenario as an overlap or not. Moreover, a positive duration tells us there’s an overlap.

3.2. Checking for Non-Overlap Conditions

This formula checks for non-overlapping conditions between two date ranges. If either condition fails, then there’s an overlap:

!(B <= C || A >= D)

Take note that if we change the condition to use strict inequality “<” and “>”, it means the ranges must not touch at all. There should be no common point between the two ranges. Once again, the application should decide whether to treat this scenario as an overlap or not.

3.3. Finding Minimum Overlap

This implementation calculates the overlap duration in days by considering the minimum of the four calculations. If the minimum overlap duration is zero or negative, it implies that there is no overlap, as the ranges do not intersect in a non-zero duration. A positive minimum overlap duration indicates an actual overlap, suggesting that the ranges share a duration greater than zero:

min((B - A), (B - C), (D - A), (D - C)) >= 0

However, if we change it to just greater than zero, the condition becomes stricter. This means there must be more than just a touch at a single point and must be a non-zero duration of overlap.

4. Implementation

Now that we’ve explored the different overlapping scenarios and formulas, let’s dive into implementing code to accurately detect these overlaps using various approaches.

4.1. Using Calendar

We’ll leverage the Calendar class to manage date ranges and check for overlaps. The Calendar class is part of the java.util package and provides a way to work with dates and times. The getTimeInMillis() method is used to obtain the time in milliseconds for each Calendar instance.

In this example, we’ll leverage the Math.min() and Math.max() methods to calculate the overlap duration by subtracting the earlier ending date from the later starting date:

boolean isOverlapUsingCalendarAndDuration(Calendar start1, Calendar end1, Calendar start2, Calendar end2) {
    long overlap = Math.min(end1.getTimeInMillis(), end2.getTimeInMillis()) -
      Math.max(start1.getTimeInMillis(), start2.getTimeInMillis());
    return overlap > 0;
}

To implement the non-overlap conditions checking, we’ll utilize the before() and after() methods provided by the Calendar class. These methods assess the chronological relationship between date instances and are essential for determining overlap. If either condition is true, it indicates an overlap:

boolean isOverlapUsingCalendarAndCondition(Calendar start1, Calendar end1, Calendar start2, Calendar end2) {
    return !(end1.before(start2) || start1.after(end2));
}

Now, let’s implement the logic using the find minimum formula. This method calculates the minimum overlap duration among different scenarios:

boolean isOverlapUsingCalendarAndFindMin(Calendar start1, Calendar end1, Calendar start2, Calendar end2) {
    long overlap1 = Math.min(end1.getTimeInMillis() - start1.getTimeInMillis(), 
      end1.getTimeInMillis() - start2.getTimeInMillis());
    long overlap2 = Math.min(end2.getTimeInMillis() - start2.getTimeInMillis(), 
      end2.getTimeInMillis() - start1.getTimeInMillis());
   return Math.min(overlap1, overlap2) / (24 * 60 * 60 * 1000) >= 0;
}

To ensure the correctness of our implementation, we can set up test data using Calendar instances representing different date ranges.

First, let’s create the start date range:

Calendar start1 = Calendar.getInstance().set(2024, 11, 15); 
Calendar end1 = Calendar.getInstance().set(2024, 11, 20);

Subsequently, we can set the end date range to partially overlap:

Calendar start2 = Calendar.getInstance()set(2024, 11, 18);
Calendar end2 = Calendar.getInstance().set(2024, 11, 22);
assertTrue(isOverlapUsingCalendarAndDuration(start1, end1, start2, end2));
assertTrue(isOverlapUsingCalendarAndCondition(start1, end1, start2, end2));
assertTrue(isOverlapUsingCalendarAndFindMin(start1, end1, start2, end2));

Here’s the corresponding unit test code to see if the test data is fully overlapping:

Calendar start2 = Calendar.getInstance()set(2024, 11, 16);
Calendar end2 = Calendar.getInstance().set(2024, 11, 18);
assertTrue(isOverlapUsingCalendarAndDuration(start1, end1, start2, end2));
assertTrue(isOverlapUsingCalendarAndCondition(start1, end1, start2, end2));
assertTrue(isOverlapUsingCalendarAndFindMin(start1, end1, start2, end2));

Finally, we set the end date range to consecutive ranges, and we should expect no overlapping:

Calendar start2 = Calendar.getInstance()set(2024, 11, 21);
Calendar end2 = Calendar.getInstance().set(2024, 11, 24);
assertFalse(isOverlapUsingCalendarAndDuration(start1, end1, start2, end2)); 
assertFalse(isOverlapUsingCalendarAndCondition(start1, end1, start2, end2)); 
assertFalse(isOverlapUsingCalendarAndFindMin(start1, end1, start2, end2));

4.2. Using Java 8’s LocalDate

Java 8 introduced the java.time.LocalDate class, which provides a more modern and convenient way to handle dates. We can leverage this class to simplify our date range overlap check. In the calculation of the overlap duration, we utilize the toEpochDay() method provided by the LocalDate class. This method is used to obtain the number of days from the epoch day for a given LocalDate:

boolean isOverlapUsingLocalDateAndDuration(LocalDate start1, LocalDate end1, LocalDate start2, LocalDate end2) {
    long overlap = Math.min(end1.toEpochDay(), end2.toEpochDay()) -
      Math.max(start1.toEpochDay(), start2.toEpochDay());
    return overlap >= 0;
}

The LocalDate class provides two essential methods, isBefore() and isAfter(), for assessing the chronological relationship between LocalDate instances. We’ll utilize both methods to determine the non-overlap conditions:

boolean isOverlapUsingLocalDateAndCondition(LocalDate start1, LocalDate end1, LocalDate start2, LocalDate end2) {
    return !(end1.isBefore(start2) || start1.isAfter(end2));
}

Next, we’ll explore the use of LocalDate to find the minimum overlap between two date ranges:

boolean isOverlapUsingLocalDateAndFindMin(LocalDate start1, LocalDate end1, LocalDate start2, LocalDate end2) {
    long overlap1 = Math.min(end1.toEpochDay() - start1.toEpochDay(), 
      end1.toEpochDay() - start2.toEpochDay());
    long overlap2 = Math.min(end2.toEpochDay() - start2.toEpochDay(), 
      end2.toEpochDay() - start1.toEpochDay());
    return Math.min(overlap1, overlap2) >= 0;
}

Now, let’s set up test data using LocaleDate instances representing different date ranges.

First, let’s create the start date range:

LocalDate start1 = LocalDate.of(2024, 11, 15); 
LocalDate end1 = LocalDate.of(2024, 11, 20);

Next, let’s set the end date range to partially overlap:

LocalDate start1 = LocalDate.of(2024, 11, 15); 
LocalDate end1 = LocalDate.of(2024, 11, 20);
assertTrue(isOverlapUsingLocalDateAndDuration(start1, end1, start2, end2));
assertTrue(isOverlapUsingLocalDateAndCondition(start1, end1, start2, end2));
assertTrue(isOverlapUsingLocalDateAndFindMin(start1, end1, start2, end2));

We’ll follow this by setting the end date range to fully overlap:

LocalDate start1 = LocalDate.of(2024, 11, 16); 
LocalDate end1 = LocalDate.of(2024, 11, 18);
assertTrue(isOverlapUsingLocalDateAndDuration(start1, end1, start2, end2));
assertTrue(isOverlapUsingLocalDateAndCondition(start1, end1, start2, end2));
assertTrue(isOverlapUsingLocalDateAndFindMin(start1, end1, start2, end2));

Finally, when we set the end date range to consecutive ranges, we should expect no overlapping:

LocalDate start1 = LocalDate.of(2024, 11, 21); 
LocalDate end1 = LocalDate.of(2024, 11, 24);
assertFalse(isOverlapUsingLocalDateAndDuration(start1, end1, start2, end2)); 
assertFalse(isOverlapUsingLocalDateAndCondition(start1, end1, start2, end2)); 
assertFalse(isOverlapUsingLocalDateAndFindMin(start1, end1, start2, end2));

4.3 Using Joda-Time

Joda-Time, a widely adopted library for date and time operations in Java, simplifies complex temporal calculations and offers a convenient method called overlaps() to determine if two intervals overlap.

The overlaps() method takes two Interval objects as parameters and returns true if there is any intersection between the two intervals. In other words, it identifies whether there is any shared duration between the specified date ranges.

However, it is important to note that Joda-Time considers two intervals with the same start and end points as non-overlapping. This behavior is especially relevant when dealing with scenarios where precise boundaries matter and even a point in time is not considered an overlap.

Let’s see an implementation using Joda-Time:

boolean isOverlapUsingJodaTime(DateTime start1, DateTime end1, DateTime start2, DateTime end2) {
    Interval interval1 = new Interval(start1, end1);
    Interval interval2 = new Interval(start2, end2);
    return interval1.overlaps(interval2);
}

Now, let’s set up test data using Interval instances representing different date ranges. We begin with the partial overlapping:

DateTime startJT1 = new DateTime(2024, 12, 15, 0, 0);
DateTime endJT1 = new DateTime(2024, 12, 20, 0, 0);
DateTime startJT2 = new DateTime(2024, 12, 18, 0, 0);
DateTime endJT2 = new DateTime(2024, 12, 22, 0, 0);
assertTrue(isOverlapUsingJodaTime(startJT1, endJT1, startJT2, endJT2));

Let’s change the end date range to fully overlap:

DateTime startJT2 = new DateTime(2024, 12, 16, 0, 0);
DateTime endJT2 = new DateTime(2024, 12, 18, 0, 0);
assertTrue(isOverlapUsingJodaTime(startJT1, endJT1, startJT2, endJT2));

Finally, we change the end date range to a consecutive range, and again, it should return no overlapping:

DateTime startJT2 = new DateTime(2024, 12, 21, 0, 0);
DateTime endJT2 = new DateTime(2024, 12, 24, 0, 0);
assertFalse(isOverlapUsingJodaTime(startJT1, endJT1, startJT2, endJT2));

5. Conclusion

In this article, we explored various scenarios, mathematical formulas, and approaches to check if two date ranges overlap in Java. Understanding partial overlap, full overlap, consecutive ranges, and zero-range duration gave us a solid foundation for our exploration.

As always, the code is available over on GitHub.

       

1. Overview

While Byte is a wrapper of the primitive byte, and the conversion can be done automatically by autoboxing for individual values, it’s important to note that this automatic conversion doesn’t extend to arrays. In this article, we’ll dive into the different approaches to converting byte arrays to Byte arrays and vice versa in Java.

2. Dependencies

To demonstrate one of the converting approaches, we’ll use the Apache Commons Lang library. Let’s add its dependency to our bytepom.xml:

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

3. Byte.valueOf()  and byteValue() 

The first approach we’ll explore is to use Byte.valueOf() and a byteValue() of a Byte object in a loop.

3.1. Byte.valueOf()

Byte.valueOf(byte b) returns a Byte instance with a byte value sent in the input parameter of this method.

Let’s convert each byte in the array into a wrapper object using Byte.valueOf(byte b) and iterating the array in a loop:

private static final byte[] PRIMITIVE_BYTE_ARRAY = {65, 66, 67, 68};
private static final Byte[] EXPECTED_ARRAY_VALUES = {65, 66, 67, 68};
@Test
void givenPrimitiveByteArray_whenConvertingUsingByteValueOf_thenGiveExpectedResult() {
    Byte[] newByteArray = new Byte[PRIMITIVE_BYTE_ARRAY.length];
    for (int i = 0; i < PRIMITIVE_BYTE_ARRAY.length; i++) {
        newByteArray[i] = Byte.valueOf(PRIMITIVE_BYTE_ARRAY[i]);
    }
    Assertions.assertThat(newByteArray)
      .containsExactly(EXPECTED_ARRAY_VALUES);
}

As we can see, all the bytes were copied into new Byte[], and all the values remain in the same places.

3.2. Byte.byteValue()

The byteValue() of a Byte object returns a primitive byte value inside it. Let’s iterate the Byte[] and call this method for each element:

private static final byte[] EXPECTED_ARRAY_VALUES = {65, 66, 67, 68};
private static final Byte[] BYTE_ARRAY = {65, 66, 67, 68};
@Test
void givenByteArray_whenConvertingUsingByteValue_thenGiveExpectedResult() {
    byte[] newByteArray = new byte[BYTE_ARRAY.length];
    for (int i = 0; i < BYTE_ARRAY.length; i++) {
        newByteArray[i] = BYTE_ARRAY[i].byteValue();
    }
    Assertions.assertThat(newByteArray)
      .containsExactly(EXPECTED_ARRAY_VALUES);
}

As expected, we copied the bytes into the primitive array using unboxing.

4. Autoboxing and Unboxing

We can rewrite the code above in a more straightforward way using autoboxing to convert a byte value into a Byte instance and vice versa, utilizing unboxing.

If we disassemble our next code fragments – we can use the javap tool for this purpose – we’ll see that autoboxing calls the Byte.valueOf() method, while unboxing calls byteValue() of a Byte object under the hood. Therefore, technically, it’s the same logic with less code.

4.1. Autoboxing

Let’s convert each byte in the array into a wrapper object using autoboxing and iterating the array in a loop:

@Test
void givenPrimitiveIntArray_whenConvertingAutoboxing_thenGiveExpectedResult() {
    Byte[] newByteArray = new Byte[PRIMITIVE_BYTE_ARRAY.length];
    for (int i = 0; i < PRIMITIVE_BYTE_ARRAY.length; i++) {
        newByteArray[i] = PRIMITIVE_BYTE_ARRAY[i];
    }
    Assertions.assertThat(newByteArray)
      .containsExactly(EXPECTED_ARRAY_VALUES);
}

As we can see, all the bytes were copied into new Byte[], and all the values remain in the same places.

4.2. Unboxing

Now, we’ll perform the opposite operation and convert Byte[] into its primitive analog:

@Test
void givenByteArray_whenConvertingUsingUnboxing_thenGiveExpectedResult() {
    byte[] newByteArray = new byte[BYTE_ARRAY.length];
    for (int i = 0; i < BYTE_ARRAY.length; i++) {
        newByteArray[i] = BYTE_ARRAY[i];
    }
    Assertions.assertThat(newByteArray)
      .containsExactly(EXPECTED_ARRAY_VALUES);
}

As expected, we copied the bytes into the primitive array using unboxing.

5. Arrays.setAll()

Since Java 8, we can simplify our code using Arrays.setAll(T[] array, IntFunction<? extends T> generator) instead of a loop. In the first parameter, we’ll send our target array, while in the second parameter, we will have a function that sets a new value for each element.

Let’s rewrite our code for converting byte primitives array into Byte objects array using Arrays.setAll():

@Test
void givenPrimitiveByteArray_whenConvertingUsingAutoboxingAndArraysSetAll_thenGiveExpectedResult() {
    Byte[] newByteArray = new Byte[PRIMITIVE_BYTE_ARRAY.length];
    Arrays.setAll(newByteArray, n -> PRIMITIVE_BYTE_ARRAY[n]);
    Assertions.assertThat(newByteArray)
      .containsExactly(EXPECTED_ARRAY_VALUES);
}

As expected, we successfully converted values using even less code than previously.

6. ArrayUtils from Apache Commons Lang Library

ArrayUtils from the Apache Commons Lang library is a utility class that provides a variety of methods for working with arrays. We can use ArrayUtils.toObject(bytes[] bytes) to create an array of Byte objects from primitives, and conversely, we can create a byte array by calling ArrayUtils.toPrimitive(Byte[] byteObjects).

6.1. ArrayUtils.toObject()

Let’s convert our primitive bytes array into Byte[] using ArrayUtils.toObject():

@Test
void givenPrimitiveByteArray_whenConvertingUsingArrayUtils_thenGiveExpectedResult() {
    Byte[] newByteArray = ArrayUtils.toObject(PRIMITIVE_BYTE_ARRAY);
    Assertions.assertThat(newByteArray)
      .containsExactly(EXPECTED_ARRAY_VALUES);
}

We successfully covered items in just one line of code.

6.2. ArrayUtils.toPrimitive()

Now let’s perform the opposite operation using ArrayUtils.toPrimitive():

@Test
void givenByteArray_whenConvertingArrayUtils_thenGiveExpectedResult() {
    byte[] newByteArray = ArrayUtils.toPrimitive(BYTE_ARRAY);
    Assertions.assertThat(newByteArray)
      .containsExactly(EXPECTED_ARRAY_VALUES);
}

We created a primitive bytes array from Byte[].

7. Conclusion

In this article, we investigated multiple ways to convert a Byte to a byte array and vice versa. Which one to choose depends on the particular case. For the projects that already have Apache Commons in their dependencies, it probably makes sense to use ArrayUtils since it’s the shortest way to achieve the same result.

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

       

1. Overview

In this tutorial, we’ll learn about the challenges in implementing the Builder Design Pattern while dealing with hierarchal inheritance. An example of a hierarchical inheritance could be the inheritance between an electric car, a car, and a vehicle.

Builder Pattern is a creational design pattern that helps simplify building complex objects having many attributes in a step-by-step process with the help of method chaining. While inheritance helps simplify design, it also leads to complexity in implementing method chaining to create objects in the Builder Pattern.

Further, we’ll come up with an efficient implementation with the help of Java Generics API.

2. Problem Description

Let’s take an example of applying the Builder Pattern in creating objects of type Vehicle, Car and ElectricCar:

At the top of the object hierarchy, there is the Vehicle class. The class Car extends the Vehicle and then the ElectricCar extends Car. Similar to these objects their builders also have a hierarchical relationship between them.

Let’s instantiate the CarBuilder class, set its attributes with method chaining, and finally call the build() method to get the car object:

CarBuilder carBuilder = new CarBuilder();
Car car = carBuilder.make("Ford")
  .model("F")
  .fuelType("Petrol")
  .colour("red")
  .build();

Let’s try to change the order of the method calls:

CarBuilder carBuilder = new CarBuilder();
Car car = carBuilder.make("Ford")
  .colour("red")
  .fuelType("Petrol")
  .model("F")
  .build();

The methods colour() and fuelType() return VehicleBuilder class. Hence, the subsequent call to model() would cause a compilation error because it’s absent in the VehicleBuilder class. This is inconvenient and a drawback. Similar behaviour is seen when we try to build the ElectricVehicle object with the ElectricVehicleBuilder class.

3. Solution Without Generics

This is a very straightforward implementation where the child builder classes override the chaining methods of all the base builder classes in the hierarchy. Hence, there is no compilation error during method chaining to set the attribute values.

Let’s understand this by first taking a look at the Vehicle class:

public class Vehicle {
    private String fuelType;
    private String colour;
    // Standard Getter methods..
    public Vehicle(VehicleBuilder builder) {
        this.colour = builder.colour;
        this.fuelType = builder.fuelType;
    }
    public static class VehicleBuilder {
        protected String fuelType;
        protected String colour;
        public VehicleBuilder fuelType(String fuelType) {
            this.fuelType = fuelType;
            return this;
        }
        public VehicleBuilder colour(String colour) {
            this.colour = colour;
            return this;
        }
        public Vehicle build() {
            return new Vehicle(this);
        }
    }
}

The Vehicle class has two attributes fuelType and colour. It also has an inner class VehicleBuilder with methods with a name similar to the attributes in the Vehicle class. They return the builder class so that it can support method chaining.

Now, let’s take a look at the Car class:

public class Car extends Vehicle {
    private String make;
    private String model;
    // Standard Getter methods..
    public Car(CarBuilder builder) {
        super(builder);
        this.make = builder.make;
        this.model = builder.model;
    }
    public static class CarBuilder extends VehicleBuilder {
        protected String make;
        protected String model;
        @Override
        public CarBuilder colour(String colour) {
            this.colour = colour;
            return this;
        }
        @Override
        public CarBuilder fuelType(String fuelType) {
            this.fuelType = fuelType;
            return this;
        }
        public CarBuilder make(String make) {
            this.make = make;
            return this;
        }
        public CarBuilder model(String model) {
            this.model = model;
            return this;
        }
        public Car build() {
            return new Car(this);
        }
    }
}

The class Car has inherited from Vehicle and similarly, the CarBuilder class has inherited from VehicleBuilder. Additionally, the CarBuilder class had to override the methods colour() and fuelType().

Let’s build a Car object now:

@Test
void givenNoGenericImpl_whenBuild_thenReturnObject() {
    Car car = new Car.CarBuilder().colour("red")
      .fuelType("Petrol")
      .make("Ford")
      .model("F")
      .build();
    assertEquals("red", car.getColour());
    assertEquals("Ford", car.getMake());
}

We can set the car’s attributes in any order before calling the build() method.

However, for a child class of Car such as ElectricCar, we must override all the methods of CarBuilder and VehicleBuilder in ElectricCarBuilder. Hence, it’s not a very efficient implementation.

4. Solution With Generics

Generics can help overcome the challenges faced in the implementation discussed earlier.

For this let’s modify the inner Builder class in the Vehicle class:

public class Vehicle {
    private String colour;
    private String fuelType;
    public Vehicle(Builder builder) {
        this.colour = builder.colour;
        this.fuelType = builder.fuelType;
    }
    //Standard getter methods..
    public static class Builder<T extends Builder> {
        protected String colour;
        protected String fuelType;
        T self() {
            return (T) this;
        }
        public T colour(String colour) {
            this.colour = colour;
            return self();
        }
        public T fuelType(String fuelType) {
            this.fuelType = fuelType;
            return self();
        }
        public Vehicle build() {
            return new Vehicle(this);
        }
    }
}

Noticeably, the methods fuelType() and colour() in the inner Builder class are returning a generic type. This kind of implementation facilitates fluent style coding or method chaining. This is a design pattern well known by the name Curiously Recurring Template Pattern(CRTP).

Let’s now implement the class Car:

public class Car extends Vehicle {
    private String make;
    private String model;
    //Standard Getters..
    public Car(Builder builder) {
        super(builder);
        this.make = builder.make;
        this.model = builder.model;
    }
    public static class Builder<T extends Builder<T>> extends Vehicle.Builder<T> {
        protected String make;
        protected String model;
        public T make(String make) {
            this.make = make;
            return self();
        }
        public T model(String model) {
            this.model = model;
            return self();
        }
        @Override
        public Car build() {
            return new Car(this);
        }
    }
}

We’ve applied CRTP in the signature of the inner Builder class and made the methods in the inner class return a generic type to support method chaining.

Similarly, let’s implement the child class ElectricCar of Car:

public class ElectricCar extends Car {
    private String batteryType;
    public String getBatteryType() {
        return batteryType;
    }
    public ElectricCar(Builder builder) {
        super(builder);
        this.batteryType = builder.batteryType;
    }
    public static class Builder<T extends Builder<T>> extends Car.Builder<T> {
        protected String batteryType;
        public T batteryType(String batteryType) {
            this.batteryType = batteryType;
            return self();
        }
        @Override
        public ElectricCar build() {
            return new ElectricCar(this);
        }
    }
}

The implementation remains almost the same except for the inner Builder class extending its parent Builder.Car<T>. The same technique must be applied to the subsequent child classes of ElectricCar and so on.

Let’s see the implementation in action:

@Test
void givenGenericImpl_whenBuild_thenReturnObject() {
    Car.Builder<?> carBuilder = new Car.Builder();
    Car car = carBuilder.colour("red")
      .fuelType("Petrol")
      .make("Ford")
      .model("F")
      .build();
    ElectricCar.Builder<?> ElectricCarBuilder = new ElectricCar.Builder();
    ElectricCar eCar = ElectricCarBuilder.make("Mercedes")
      .colour("White")
      .model("G")
      .fuelType("Electric")
      .batteryType("Lithium")
      .build();
    assertEquals("red", car.getColour());
    assertEquals("Ford", car.getMake());
    assertEquals("Electric", eCar.getFuelType());
    assertEquals("Lithium", eCar.getBatteryType());
}

The method successfully builds the objects of type Car and ElectricCar.

Interestingly, we’ve used the raw generic type ? for declaring the inner classes Car.Builder<?> and ElectricCar.Builder<?>. This is because we need to ensure that method calls such as carBuilder.colour() and carBuilder.fuelType() return Car.Builder instead of its parent Vehicle.Builder.

Similarly, the method calls ElectricCarBuilder.make() and ElectricCarBuilder.model() should return ElectricCarBuilder and not CarBuilder class. Without this method chaining won’t be possible.

5. Conclusion

In this article, we discussed the challenges in the Builder Design Pattern while handling inheritance. Java Generics and Curiously Recurring Template Pattern helped us implement a solution. With this, we can use method chaining without worrying about the order of method calls to set the attribute values in the builder class.

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