DEV Community: Anirban

Build REST API with Spring Boot and Kotlin

Anirban — Sat, 20 Mar 2021 03:00:06 +0000

1. Overview

In this article, we're going to build a REST API using Spring Boot 2.x and Kotlin. Meanwhile, dedicated support for Kotlin was introduced since Spring Framework 5.0. We can read about the supported features in the official Spring Framework documentation.

In particular, the application will expose data via a REST API and persist data in an embedded H2 database.

2. Use Case

We'll build Restful APIs for an employee information application. A user can create, retrieve, update and delete an employee using this application. An employee has an id, username, first name, last name, email id, and date of birth. Moreover, the username of an employee must be unique.

We'll use an embedded H2 database as our data source along with JPA and Hibernate to access the data from the database.

3. Setup

We can use the Spring Initializer tool to create a Spring Boot application. Besides, we can read about the other ways that we can create a Spring Boot project in the blog post.

Subsequently, we will add Spring Web, Spring Data JPA, H2 Database, Spring Boot Devtools as the dependencies. So now we have all the basic dependencies in the build.gradle.kts that will allow us to work with Spring Boot and Kotlin:

The Gradle build file also contains some essential plugins:

The kotlin-spring compiler plugin is a wrapper on top of the all-open plugin. The all-open compiler plugin ensures that the Kotlin classes are annotated and their members are open. This makes it convenient to use libraries such as Spring AOP that require classes to be open unlike Kotlin classes and their members which are final by default.
The kotlin-jpa compiler plugin is a wrapper on top of the no-arg plugin. The no-arg compiler plugin generates a no-argument constructor for classes annotated with Entity, MappedSuperclass, and Embeddable. This ensures that JPA (Java Persistence API) can instantiate the class since it expects a no-argument constructor defined for its entities.

3.1. Configure Database

We have to configure the H2 database properties so that Spring Boot can create a data source. To define such properties, we can use an external configuration. Furthermore, we can define such external configuration using properties files, YAML files, environment variables, and command-line arguments.

In general, Spring Boot provides the application.properties file to define such database properties by default. The properties file uses a key-value format.

Alternatively, we can use YAML-based configuration files which use hierarchical data. The YAML files significantly help to avoid repeated prefixes and make is more readable compared to the properties file:

We can also use the application.yml file to define hibernate properties:

We set the ddl-auto property to update. It will update the database schema based on the modifications in the domain model in our application. This default value is create-drop if we use an embedded database without any schema manager. In case we're using a schema manager such as Liquibase or Flyway, we should consider using validate. It tries to validate the database schema according to the entities that we have created in the application and throws an error if the schema doesn’t match the entity specifications.
The show-sql property enables logging of SQL statement.
The generate-ddl property ensures whether to initialize the schema on startup.
The dialect property ensures that Hibernate generates better SQL for the chosen database.

4. Domain Model - Kotlin Data class

The domain model is the core part of the application. We can create a domain model Employee using a data class.

In addition, a data class in Kotlin automatically generates equals/hashCode pair, toString, and copy functions. Besides, We don't need to define getter and setter methods like Java:

The @Entity annotation specifies that the class is an entity and mapped to a database table.
The @Table annotation specifies the name of the database table that is used for mapping. If we use the @Table annotation without a table name, then Spring generates the table name from the class name.
The @Id annotation specifies the property which is the primary key in the entity class.
The @GeneratedValue annotation specifies the generation strategies for the values of the primary keys.
The @Column annotation specifies the mapped column for a persistent property. If we do not use the @Column annotation, then Spring generates the column name from the property name.

5. Repository

We're going to create a repository interface to interact with the database. Moreover, the EmployeeRepository interface will extend from the JpaRepository interface. This ensures that all the CRUD methods on the Employee entity are available:

The @Repository annotation specifies that the class is a repository and represents the data access layer in our application.

6. Service

Now, we're going to create a service class that will provide the business logic. Besides, the service layer can interact with the data access layer using JPA.

We inject an instance of the EmployeeRepository via constructor in EmployeeService:

The @Service annotation specifies that the class is a service.
The getAllEmployees() function can fetch a list of all employees.
The getEmployeesById() function can fetch one employee based on the id. We provide the employee id as a parameter to the function.
The createEmployee() function can create a new employee. We provide the required properties of the new employee as a parameter to the function.
The updateEmployeeById() function can update the employee details based on the id. We provide both the employee id and the properties as parameters to the function.
The deleteEmployeesById() function can delete an employee based on the id. We provide the employee id as a parameter to the function.

7. Controller

We implement the APIs for all the CRUD operations in the controller layer which invokes the underlying service.

We define a EmployeeController as our controller class. In particular, it's a REST controller that provides endpoints for creating, manipulating, and deleting employees.

The EmployeeService class is wired into the controller to return the values. Also, we reuse the entities as data transfer object for simplicity:

The @RestController annotation specifies that the class is a controller and capable of handling requests. It combines both the @Controller and @ResponseBody annotations.

Spring provides several annotations to handle the different incoming HTTP requests like GET, POST, PUT and DELETE. These annotations are @GetMapping,@PostMapping,@PutMapping, and @DeleteMapping.

8. Running the application

We can run the application using the following command in the terminal:

gradle bootRun

The Spring Boot application will start running at http://localhost:8080.

9. Exploring the APIs

9.1. Create an Employee

We send the following request to create an employee:

We receive the following response in JSON format:

9.2. Get All Employees

We send the following request to fetch all employees:

We receive the following response in JSON format:

9.3. Get an Employee

We send the following request to fetch an employee based on the employee id:

We receive the following response in JSON format:

9.4. Update an Employee

We send the following request to update employee properties based on the employee id:

We receive the following response in JSON format:

9.5. Delete an Employee

We send the following request to delete an employee based on the employee id:

10. Conclusion

In this tutorial, we looked into creating a microservice application and expose REST API using Kotlin and Spring Boot. In the process, I have also used some best practices which we can utilize while building such applications.

The code for these examples is available on GitHub.

To learn more, check out the related articles on Spring Boot.

Originally published on Anirban's Tech Blog.

How To Create a Spring Boot Project

Anirban — Fri, 12 Feb 2021 03:00:06 +0000

1. Overview

In this tutorial, we'll look into the different ways we can create a Spring Boot project.

2. Using Spring Initializer in spring.io

We can create a Spring Boot project by using the Spring Initializer in start.spring.io. This is the quickest way to create an application in Spring Boot which is one of the most popular frameworks for creating web applications.

The Spring Initializer offers different options for choosing the build tools, programming languages, Spring Boot versions, and the related dependencies.

2.1. Build Tools

We have the option to choose between Maven and Gradle as our build tool. In this case, we'll choose Gradle as our build tool for the Spring Boot application.

2.2. Language

Spring Initializer supports multiple JVM languages like Java, Kotlin, and Groovy to build a web application. In this case, we'll choose Kotlin as our programming language.

2.3. Version

We should always aim to choose the latest stable Spring Boot version for building our application. The SNAPSHOT versions are not stable and should be avoided. The versions labeled with M signifies Milestone versions. It refers to a future stable version.

In this case, the latest stable version is 2.4.2 while M1 is supposed to have version 2.5.0 (M1). So, version 2.5.0 (M1) is the future stable release version.

2.4. Project Metadata

We can also define the project metadata which includes the group, artifact, name, description, package name, packaging, and Java version. In this case, we'll choose Jar as the packaging option. The Java version will be 11.

2.5. Dependencies

Finally, we have to define the dependencies by selecting the Add Dependency button. In this case, we can add a Spring Web dependency which should be sufficient to build a simple RESTful web application.

We can select the Generate button and download the ZIP archive locally. After that, we can extract the project and import it into an IDE like IntelliJ IDEA, Spring Tools, Eclipse, etc.

3. Using Spring Initializer in IntelliJ IDEA

We can create a Spring Boot project by using the Spring Initializer plugin in IntelliJ IDEA.

3.1. Create a New Project

Firstly, we select the option Create New Project.

3.2. Use Spring Initializer

After that, we select the Spring Initializer to generate a Spring Boot application. Then we have to download or assign a project SDK and select Next.

3.3. Configure Project Settings

Now we'll configure the project settings as per our requirements. In this case, we choose Gradle as the build tool, Kotlin as the programming language, Jar as the packaging option, and Java version 11.

Select Next to continue.

3.4. Select Dependencies

Also, we need to define the external dependencies of our Spring Boot application. We can choose Spring Web dependency which should be sufficient to build a simple RESTful web application.

Select Next to continue.

3.5. Project Name and Location

Finally, we can define a name for the Spring Boot project and the directory in the local machine. In this case, we continue with the default values.

Select Finish and the Spring Boot project is created.

4. Conclusion

In this tutorial, we discussed the different ways to create a Spring Boot project.

Originally published on Anirban's Tech Blog.

Null Safety in Kotlin

Anirban — Tue, 30 Jun 2020 03:00:06 +0000

1. Overview

In this article, we’ll look into the handling of null references in Kotlin.

Any programming language which has the concept of null reference throws a NullPointerException. It has been referred to as a billion-dollar mistake. Wiki

2. Nullable and Non-Nullable Type

Kotlin aims at eliminating the risk of NullPointerException. It distinguishes between nullable and non-nullable references as a part of its type system. In Kotlin, all variables are non-nullable by default. So, we cannot assign a null value to a variable because it’ll throw a compilation error:

var country: String = "India"
country = null //compilation error

To define a nullable variable, we must append a question mark(?) to the type declaration:

var city: String? = "Kolkata"
city = null

We can call a method or access a property on a non-nullable variable. However, in the case of nullable variables, we need to handle the null case explicitly. Otherwise, it will throw a compilation error since Kotlin knows that the variable contains null references:

val a : String = country.length
val b : String = city.length //compilation error

Let’s look at the different ways how we can handle null references safely in Kotlin.

3. Working With Nullable Types

3.1. Null Check

We can use the if-else expression to explicitly check for nullable variables. However, this option works only where the variable is immutable. Depending on the complexity of the conditions, this can also lead to nested expressions.

Let’s look at an example:

val city: String? = "Kolkata"
return if (city != null) {
    city.length
} else {
    null
}

3.2. Safe Call Operator (?.)

Kotlin has a safe call operator (?.) to handle null references. This operator executes any action only when the reference has a non-null value. Otherwise, it returns a null value. The safe call operator combines a null check along with a method call in a single expression.

Let’s see how to use a safe call operator :

val country: String? = "India"
assertEquals(5, country?.length)
val city: String? = null

assertNull(city?.length)

In addition, we can also use the safe call operator for multiple chain calls :

val country: Country? = Country(City("Kolkata", "003"))
val code: String? = country?.city?.code
assertEquals("003", code)

However, the chain calls return null if any of the properties are null:

val country: Country? = Country(null)
val code: String? = country?.city?.code

assertNull(code)

3.3. Using let() Method

We can use the let() method along with the safe call operator to act on a non-nullable variable:

val cities: List<String?> = listOf("Kolkata", null, "Mumbai")
var name: List<String?> = emptyList()
for (city in cities) {
    city?.let { name = name.plus(it) }
}
return name

assertEquals(2, name.size)

3.4. Using also() Method

We can use the also() method to execute additional operations like logging and printing of the non-nullable variables. Furthermore, this method can be used in a chain with let() or run() method.

Here's how we can use also() method along with let() method:

val cities: List<String?> = listOf("Kolkata", null, "Mumbai")
var name: List<String?> = emptyList()
for (city in cities) {
    city?.let {
        name = name.plus(it)
        it
    }?.also { println("Logging the value: $it") }
}
return name

assertEquals(2, name.size)

3.5. Using run() Method

We can use the run() method to execute some operations on a non-nullable reference. This method operates using this reference and returns the value of the lambda result :

val countries: List<String?> = listOf("India", null, "Germany")
var name: List<String?> = emptyList()
for (country in countries) {
    country?.run {
        name = name.plus(this)
        this
    }?.also { println("Logging the value: $it") }
}
return name

assertEquals(2, name.size)

3.6. Elvis Operator (?:)

We can use the Elvis operator (?:) to return a default value only if the original variable has a null value. If the left-side expression of the Elvis operator has a non-nullable value, then it is returned. Otherwise, the right-side expression is returned.

Let’s take a look at how the Elvis operator works:

val country: Country? = Country(City("New Delhi", null))
val result = country?.city?.code ?: "Not available"

assertEquals("Not available", result)

We can use the Elvis operator with a safe call operator to invoke a method or property of the variable :

val country: Country? = Country(City("Mumbai", "002"))
val result = country?.city?.code ?: "Not available"

assertEquals("002", result)

We can also use throw and return expression in the right-side expression of the Elvis operator. So instead of default values, we can throw specific exceptions in the right-side expressions of the Elvis operator:

val country: Country? = Country(City("Chennai", null))
val result = country?.city?.code ?: throw IllegalArgumentException("Not a valid code")

assertThrows<IllegalArgumentException> { result }

3.7. Not Null Assertion Operator (!!)

We can use the not-null assertion operator (!!) to explicitly throw a NullPointerException. This operator converts any reference to its non-nullable type and throws an exception if the reference has a null value. Let’s have a look into how we can throw NullPointerException using not-null assertion operator(!!):

val country: String? = null
val result : Int = country!!.length
assertThrows<NullPointerException> { result }

However, if the reference has a non-nullable value, then it is executed successfully:

val country: String? = "India"
val result : Int = country!!.length
assertEquals(5, result)

The not-null assertion operator should be used carefully since it’s a potential sign of a NullPointerException. We should avoid using multiple non-null assertions like the following since it makes it harder to debug which property is null:

country!!.city!!.code

Additionally, We should always try to use safe call operator in such cases to ensure NullPointerException doesn’t occur :

country?.city?.code

4. Nullability in Collections

Kotlin collections are non-nullable by default. So, in order to define a collection of nullable types in Kotlin, we have to append the question mark (?) to the type declaration:

val countries: List<String?> = listOf("India", null, "Germany", "Russia", null)

We can use the following way to define a nullable collection in Kotlin:

var countries: List<String>? = listOf("India", "Germany", "Russia")
countries = null

4.1. Filtering Nullable Types

We can filter a list that contains nullable values to return only the non-nullable values using the filterNotNull() method. Let’s have a look at an example:

val countries: List<String?> = listOf("India", null, "Germany", "Russia", null)
val result: List<String> = countries.filterNotNull()
assertEquals(3, result.size)
assertEquals("Russia", result[2])

5. Conclusion

In this article, we look into the various ways to handle nullable references in Kotlin.

The code for these examples is available on GitHub.

Originally published on Anirban's Tech Blog.

Hexagonal Architecture in Java

Anirban — Sat, 23 May 2020 03:00:06 +0000

1. Overview

In this tutorial, we'll take a look into the hexagonal architecture in Java. To illustrate this further, we'll create a Spring Boot application.

2. Hexagonal Architecture

The hexagonal architecture describes a pattern for designing software applications around the domain logic. The hexagon describes the core of the application consisting of the domain object and the use cases of the application. The edges of the hexagon provide the inbound and outbound ports to the outside parts of the hexagon such as web interface, databases, etc.

So, in this kind of software architecture, all the dependencies between the components point towards the domain object. Therefore, the communication between the core application and the outside part is only possible using ports and adapters. In the following sections, we can have a deep dive into the different layers of hexagonal architecture.

3. Domain Object

The domain object is the core part of the application. It can have both state and behaviour. However, it doesn’t have any outward dependency. So any change in the other layers has no impact on the domain object.

The domain object changes only if there is a change in the business requirement. Hence, this is an example of the Single Responsibility Principle among the SOLID principles of software design.

First, let’s create a domain object Product that forms the core of the application. It contains product-related information and business validations:

public class Product {

    private Integer productId;
    private String type;
    private String description;

    public Product() {
        super();
    }

    public Product(Integer productId, String type, String description) {
        this.productId = productId;
        this.type = type;
        this.description = description;
    }

    //getters
}

4. Ports

The ports are interfaces that allow inbound and outbound flow. Therefore, the core part of the application communicates with the outside part using the dedicated ports.

4.1. Inbound Port

The inbound port exposes the core application to the outside. It is an interface that can be called by the outside components. These outside components calling an inbound port are called primary or input adapters.

Let's define a ProductService interface which is the inbound port:

public interface ProductService {

    List<Product> getProducts();

    Product getProductById(Integer productId);

    Product addProduct(Product product);

    Product removeProduct(Integer productId);
}

4.2. Outbound Port

The outbound port allows outside functionality to the core application. It is an interface that enables the use case of the core application to communicate with the outside such as database access. Hence, the outbound port is implemented by the outside components which are called secondary or output adapters.

Let's define a ProductRepository interface which is an outbound port:

public interface ProductRepository {

    List<Product> getProducts();

    Product getProductById(Integer productId);

    Product addProduct(Product product);

    Product removeProduct(Integer productId);
}

5. Adapters

The adapters are the outside part of the hexagonal architecture. So, they interact with the core application only by using the inbound and outbound ports.

5.1. Primary Adapters

The Primary adapters are also known as input or driving adapters. Therefore, they drive the application by invoking the corresponding use case of the core application using the inbound ports. For example, primary adapters are REST APIs or web interfaces.

Let's define a ProductController class as our primary adapter. In particular, it's a REST controller that provides endpoints for creating and accessing products. Subsequently, it uses the inbound port service to interact with the core application:

@RestController
@RequestMapping("/api/v1/product")
public class ProductController {

    private ProductService productService;

    @Autowired
    public ProductController(ProductService productService) {
        this.productService = productService;
    }

    @GetMapping
    public ResponseEntity<List<Product>> getProducts() {
        return new ResponseEntity<List<Product>>(productService.getProducts(), HttpStatus.OK);
    }

    @GetMapping("/{productId}")
    public ResponseEntity<Product> getProductById(@PathVariable Integer productId) {
        return new ResponseEntity<Product>(productService.getProductById(productId), HttpStatus.OK);
    }

    @PostMapping
    public ResponseEntity<Product> addProduct(@RequestBody Product product) {
        return new ResponseEntity<Product>(productService.addProduct(product), HttpStatus.OK);
    }

    @DeleteMapping("/{productId}")
    public ResponseEntity<Product> removeProduct(@PathVariable Integer productId) {
        return new ResponseEntity<Product>(productService.removeProduct(productId), HttpStatus.OK);
    }
}

5.2. Secondary Adapters

The Secondary adapters are also known as output or driven adapters. These are implementations of the outbound port interface. The use case of the core application invokes the secondary adapters using the output port. For instance, secondary adapters are connections to the database and external API calls.

Let's define a ProductRepositoryImplementation class as our secondary adapter. In particular, this class implements the outbound port interface ProductRepository and allows the core application to access the database:

@Repository
public class ProductRepositoryImplementation implements ProductRepository {

    private static final Map<Integer, Product> productMap = new HashMap<Integer, Product>(0);

    @Override
    public List<Product> getProducts() {
        return new ArrayList<Product>(productMap.values());
    }

    @Override
    public Product getProductById(Integer productId) {
        return productMap.get(productId);
    }

    @Override
    public Product addProduct(Product product) {
        productMap.put(product.getProductId(), product);
        return product;
    }

    @Override
    public Product removeProduct(Integer productId) {
        if(productMap.get(productId)!= null){
            Product product = productMap.get(productId);
            productMap.remove(productId);
            return product;
        } else
            return null;

    }
}

The adapters provide flexibility to the application without influencing the core application logic. If the application can be used by a new client in addition to the existing one, we can add the new client to the inbound port.

In addition, if the application requires a different database, we can add a new secondary adapter implementing the same outbound port.

6. Use cases of the core application

The use cases of the core application are the inside part of the hexagonal architecture. They are specific use case implementations of the inbound port. Hence, it contains all the use case-specific business rule validations and logic. The use case has no outside dependency similar to the domain objects.

Let's define a ProductServiceImplementation class that provides the specific use case implementation:

@Service
public class ProductServiceImplementation implements ProductService {

    @Autowired
    private ProductRepository productRepository;

    @Override
    public List<Product> getProducts() {
        return productRepository.getProducts();
    }

    @Override
    public Product getProductById(Integer productId) {
        return productRepository.getProductById(productId);
    }

    @Override
    public Product addProduct(Product product) {
        return productRepository.addProduct(product);
    }

    @Override
    public Product removeProduct(Integer productId) {
        return productRepository.removeProduct(productId);
    }
}

7. Conclusion

The hexagonal architecture offers several benefits compared to a layered architecture:

It simplifies the architecture design by separating the inside and outside parts of the application
The core business logic is isolated from any external dependencies which help to achieve a high degree of decoupling
The ports allow flexibility in connecting to new adapters in the form of new web clients or databases

The hexagonal architecture might be an overhead for designing simple CRUD applications. However, this architecture is useful when we are designing a domain-driven application.

The code for these examples is available over on Github.

Originally published on Anirban's Tech Blog.