DEV Community: Hamza Belmellouki

Working With Nulls in the Java Ecosystem

Hamza Belmellouki — Sun, 31 Jan 2021 12:32:53 +0000

A null value can appear anywhere in a Java application.
In this post, we'll see how to work with data you control as well as data you don't. We'll also discuss how we can use annotation libraries like JSR 380, Spring annotations, Lombok, and some patterns to handle null values.

Dealing with nulls: Old way

Assertions

Java's built-in assert keyword can be used to check for assumptions. It can be a handy utility to check for nulls:

class Scratch {
    public static void main(String[] args) {
        foo(null);
    }

    public static void foo(List list) {
        assert list != null : "List is null";
        // code
    }
}

The above example checks if the argument of foo is null. If it does, then it will fail by throwing an AssertionError with a message: Exception in thread "main" java.lang.AssertionError: List is null. To enable assertion checks in your code, pass -ea as an option when running your code:

java -ea com.example.MyClass

If you don't, Java will ignore all the assertions in your code. Typically, developers enable assertion checks when they're in development and disable them when deploying to production.

If/Else Statement

Normally we use assertions if there's a programming error. But what if it isn't? An If/Else statement can be leveraged to handle this case:

if (list != null) {
    // do something with the list
} else {
    // list is null
}

java.util.Objects

Introduced in Java 7 along with other static helper methods in Objects class. Object.requirNonNull() checks that the specified object reference is not null:

class Scratch {
    public static void main(String[] args) {
        foo(null);
    }

    static void foo(List list) {
        Objects.requireNonNull(list, "list is null");
    }
}

The above example checks that the specified object is non-null and if it is, It will throw a NullPointerException along with the error message:

Exception in thread "main" java.lang.NullPointerException: list is null

Java 8 added other methods in the Objects class that can check if the object is null and vice-versa. You may prefer to use these method to increase readability and avoid typos:

void foo(List list) {
    if (Objects.isNull(list)) {
        // list is null
    } else {
        // do something with the list object
    }
}

void foo(List list) {
    if (Objects.nonNull(list)) {
        // do something with the list object
    } else {
        // list is null
    }
}

Data outside of your control

We can classify data in our application into two types; Data that we can control(Internal Data) and data that is outside of our control(External Data). This section and the following one shows you the best practices you can do when dealing with these kinds of data.

Typically the presentation layer(controller) is the one responsible for getting data from the client. Therefore the data we're getting is outside of our control. In there, the controller has the responsibility for checking for null values. Follow these practices when dealing with external data:

Document your public API
Check for nulls only in the upper layers
Validate method contract by adopting a fail-fast strategy
Use exceptions (NullPointerException & IllegalArgumentException) to indicate that an invalid value had been received
Replace the null value with some default value if it makes sense

Data that you control

For the data that you control, remember that you shouldn't try to pass a null value to a method. For example, the method bar accepts two arguments. The first one is mandatory, and the second one is optional. Instead of passing a null value into the second parameter, overload the method bar to two methods. One that takes a single parameter, and the other takes both of the parameters(mandatory and the optional). That way, you won't need to worry about passing null values to method arguments:

void bar(List list) {

}

void bar(List list, String msg) {

}

Another thing to remember is never to return a null value in a method. For that, you can use the null object pattern. For example, if your method returns a Collection. Instead of returning null, you would return an empty collection. Or you can use the Optional type as it provides a clear and explicit way to communicate the message that there may NOT be a value without using null.

Finally, having a good suite of tests will definitely help you detect programming bugs caused by nulls.

Checking for Null Using Annotations

There are third party annotations that will help you handle null values. However, in Java, there are no standard annotations to handle nulls.
Static analysis tools can leverage annotations to analyze your code at compile-time to detect a null violation error. Other annotations may throw an exception at runtime if the null condition is violated. In this section, we'll be looking at how to handle nulls using different libraries.

Spring

Numerous null safety annotations were introduced in Spring 5.0. They are located in org.springframework.lang package. They can be used by static analysis tools and IntelliJ inspection tools to inspect code and generate errors and warnings at compile-time.

Spring's @NonNull annotation is used to check that the value passed to the parameter cannot be null. It can be leveraged at parameter, return value, and field level. To get null violation compile-time errors/warnings in IntelliJ, you'll need to add the annotation to IntelliJ's inspection tools. To do that go to Preferences | Editor | Inspections and search for @NonNull/@Nullable problems and in the options section click Configure Annotations and then add Spring's @NotNull annotation from org.springframework.lang package.
Now, whenever you set null in name's setter method. IntelliJ will generate a warning telling you that the specified setter should not accept null in its parameter. This example demonstrates how the use of such annotation:


class Person {
    @NonNull
    private String name;
    private int age;

    public Person(@NonNull String name, int age) {
        this.name = name;
        this.age = age;
    }

    public Person() {
    }

    @NonNull
    public String getName() {
        return name;
    }

    public void setName(@NonNull String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

The above example is a simple Java POJO class. Spring's @NotNull annotation is used to forbid null values in Person's name field. If you got this test method in IntelliJ, it would generate a warning telling you: Passing 'null' argument to parameter annotated as @NotNull:

Likewise, @Nullable can be used to declare that annotated elements can be null under some circumstances.

If you want to specify nullability policy as not null by default in a package level, use @NonNullApi.
For example, if you want to specify that all parameters and return values of com.example.demo package should be non-nullable by default specify that in package-info.java:

@NonNullApi
package com.example.demo;

import org.springframework.lang.NonNullApi;

The above example specifies that all parameters and return values inside com.example.demo package are considered to be non-null by default. Note that you can override this for a specific parameter or return value by annotating them with Spring's @Nullable annotation.

JSR 380

Known as Jakarta Bean Validation 2.0, is a set of constraints as annotations. Besides @NotNull constraint annotation, it provides others as well: @Email, @NotEmpty, @NotBlank, @Positive, @PositiveOrZero, @Negative, @NegativeOrZero, @PastOrPresent etc. You can leverage these annotations at any layer in your application. Typically you would validate your data upon creation/update of a resource in the Front layer of your application. If you're working in Spring, all you have to do is annotate your POJO class with the constraints and annotate the method parameter with @Valid annotation. In case if a constraint is violated, a ConstraintViolationException is thrown.

If your project is based on spring-boot starter validation, it will bring a dependency of Hibernate Validator, which is the reference implementation for this specification.

Lombok

Lombok is a library used to reduce boilerplate code for data objects by generating getters, setters, constructors, hashcode, and toString, among other things.
Lombok works as an annotation post-processor. It generates code and injects it into the application. If Lombok's @NotNull annotation is put on a parameter, Lombok will insert a null-check at the start of the method/constructor's body, throwing a NPE with the parameter's name as a message. If put on a field, any generated method assigning a value to this field will also produce these null-checks.

In Lombok, we can configure which exception to be thrown in case of passing a null value. Also, the flag usage, whether compilation should generate an error or a warning.

Null object pattern

The null object pattern can help us deal with the numerous null checks in our code. Our code may have many if statements checking for an object's nullability; thus, code becomes ugly and hard to read. You may also get various null pointer exceptions by forgetting to add a null check for your objects. The null object pattern can help by encapsulating the object's nullability logic in your object, resulting in a clean, elegant, and safe code.

The null object pattern is a particular case of the strategy design pattern. Using the strategy pattern, you implement a base interface and hide the null handling logic in a unique object called the null object. The following diagram shows the pattern and how does it relate to the strategy pattern:

In this example, InventoryService is the interface that defines the contract for fetching items. Its method returns a collection of items. ConcreteRealObject implements that interface, which does the fetching logic maybe some processing and transformations too. NullObject is also an implementation that may stub fetchItems method by returning an empty list or some other default values.

It is recommended to leverage the null object pattern when a default value can be assigned or a default action can be taken. Please do not use it when you don't know what a default value or behavior might look like. Doing so might introduce subtle bugs in your code. So be careful and use it when appropriate.

Optional instead of null

Typically, when developers cannot return an actual value, we tend to produce a null or throw an exception in that method. Java 8 added the Optional type, which is an immutable container object that may or may not contain a non-null value. An Optional can hold at most one value or none(null). We can leverage its API to handle the presence and emptiness of value.

One thing to note about Optional is that they make clients aware that the API might return a null value, and this is the key difference between returning an Optional or a null value. It's easy to forget or ignore handling an API return value if we were returning null.

In this example I am populating a list of users using a static initializer:

static List<User> users;
static {
    users = new ArrayList<>();
    users.add(new User("Lorem", 20));
    users.add(new User("Epsum", 22));
    users.add(new User("John", 26));
}

Here, I have a method that searches a user by its name. Instead of returning a null, I am returning an Optional so the client code that's calling the method can react to the value's presence or emptiness.

static Optional<User> findUserByName(String userName) {
    final List<User> user = users.stream()
            .filter(u -> u.getName().equals(userName))
            .collect(Collectors.toList());

    if (user.size() == 1) {
        return Optional.of(user.get(0));
    } else {
        return Optional.empty();
    }
}

User class:

class User {
   private String name;
   private int age;
    // constructor, getter, setters & toString
}

Client's code:

public static void main(String[] args) {
    User user = findUserByName("John")
            .orElseThrow(NotFoundException::new);
    System.out.println(user);
}

As you can see, orElseThrow method returns a User if the user's name is "John". Else, a NotFoundException exception is thrown.
There are other numerous handy Optional methods that you'll likely wanna use: isEmpty, ifPresent, map, orElse, etc.
The best way to learn about them is to go and explore the API at the Javadoc.

Wrap up

In this post, we've seen how nulls can make our code unpleasant to work with. Also, we've looked over some modern best practices and patterns you can implement when working with nulls.

If you have any feedback on this post. Please, don't hesitate to reach out to me or just say a "hello" on Twitter.

IntelliJ IDEA: Beyond The Basics

Hamza Belmellouki — Sat, 12 Sep 2020 14:08:27 +0000

IntelliJ IDEA Ultimate is the most powerful IDE for JVM developers in the market by now. It has support for various JVM frameworks, complex refactorings, Integration with VCS, and many more.

Java developers spend a tremendous amount of time in front of their IDEs. Unfortunately, I've noticed that developers don't take advantage of IDEA's powerful features.

In this blog, I'll talk about some tricks that I use my day to day job. And show you some best practices that can boost your productivity 😉.

UI-Less mode

Jetbrains developer advocates recommend working with IntelliJ without using the UI (tool window buttons, toolbar, etc.). Always remember that all shortcuts are configurable. So make sure to take your time to customize the IDE according to your need and preferences.

Up till now, most developers I've met are using IntelliJ with UI enabled.

However, it isn't recommended to do it that way! If you want to take your IDEA's skills to the next level, you have to get rid of those UIs. They represent distraction to the developer, preventing you from focusing on what matters: Your code!

Now you can remove these distractions by going into your Main Menu | View | Appearance and uncheck toolbar, tool window bar, navigation bar. What's left are tabs. Please get rid of them by right-click into the tab and choose Configure Editor Tabs... and on the appearance section, set tab placement to None. The resulting IDEA's UI would be:

Fantastic! I've been working with IDEA for almost two years using this mode. At first, it may sound overwhelming the number of shortcuts/actions you'll have to learn. Learning IDEA's shortcuts is like driving. When you know how to drive a car, you don't think about the process of driving. It comes naturally. But when driving for the first time you do. So be patient on yourself.

Running code

How do you run code in IDEA? Typically, you would go to Edit Configuration in the toolbar and set up your run configuration. Once you do that, you build and run your code by clicking the run button at the toolbar. Using the mouse to run your code isn't professional. Instead, I prefer to do it the following: You can set up multiple run configurations using a keyboard shortcut and run the runnable class directly from IDEA so IDEA can create the run configs using its defaults. Then, whenever you want to run your project. Invoke the run popup (using a shortcut) and choose the appropriate config:

Abbreviate Actions

Sometimes actions can be hard to remember and take more time to type compared to an abbreviation. Fortunately, in IDEA you can set up an abbreviation for an action, and when you invoke Find Action you can just type the name of the abbreviation, and it'll invoke the action that is associated with it. First, you can set an abbreviation like so:

After setting your action abbreviation. Call it using Find by Action. Type your abbreviation and boom your action will appear in two keystrokes:

Navigation

In IntelliJ, you don't need tabs. Tabs are inefficient in navigation. Instead, IDEA provides you powerful ways to navigate in your project. You can navigate using "Recent Files" action. This action shows all the recent files you've visited. A double shortcut would show only recent files that have been changed:

Recent Locations action is also a great way to navigate/search for recent portions of code:

File Preview

What if you want to preview a file without opening it? Quick Definition action can do just that. You invoke it from multiple contexts:

In the editor itself
In the project tool window
In Go To Class action popup
Etc...

This GIF showcase how I use Quick Definition action to preview a specific file:

VCS

I could write a bunch of articles talking about VCS support in IDEA. But in this article, I'd like to highlight on an unknown feature of IntelliJ, which IntelliJ's VCS Shelve. Shelving commits is similar to stashing commits in git, but it's more powerful. I would prefer to shelve changes instead of stashing them if I am not sharing my changes elsewhere.

Stashing is a git feature and doesn't give you the option to select specific files or changes inside a file. Shelving can do that, but this is an IDE-specific feature, not a git feature:

As you can see, I am able to choose to specify which files/lines to include on my shelve. Note that I can't do that with stashing.

Beware using shelves in the IDE may limit the portability of your patches because those changes are not stored in a .git folder. But this isn't important since we use remote branches to showcase work.

Learn More

If you want to measure your productivity and see usage statistics for IntelliJ IDEA features, make sure to check out Productivity Guide by going to the main menu -> help -> Productivity Guide. It should display a popup containing all usage statistics of IDEA's features:

Also, Checkout Key Promoter X plugin if you want to avoid using the mouse.

Finally, the manual guide is the most comprehensive resource you can find online. So, make sure to skim through the manual if you want to know what other things you can do with IDEA.

Wrap Up

In this blog, I've shown you how you can take your IDEA's skills to the next level by using a UI-Less mode as Jetbrains developer advocates recommend. We also saw how to navigate and work with VCS in IDEA.

If you have any feedback about my blogs. Please, don't hesitate to reach out to me or just say a "hello" on twitter: @HamzaLovesJava.

Top 5 things I've Learned During my Internship

Hamza Belmellouki — Sat, 12 Sep 2020 14:08:09 +0000

A good internship can provide you with practical work experience and an opportunity to grow and learn before fully entering the working world. This is especially true for us student developers since we're stuck with the "hello world" based learning. An internship can help with that!

After finishing my software development studies at home by being a self-taught dev, I was contacted by a recruiter for an internship. Last week I had completed my three-month internship period and got hired as a Junior Backend Developer! In this post, I'd like to share my internship experience at xHub and things I've learned during this period.

Professional Communication

Excellent communication is the most crucial characteristic for success as a software developer. For most people, this may appear counterintuitive. Now you may ask: Don't developers spend all day coding? In fact, A large part of the day-to-day job of a software developer is not spent in code but instead working with a variety of people across the company.

I think we can all agree that a large part of professional software development is about writing documentation, doing code reviews, sending emails, and Slack messages, attending meetings. My genuine advice to you is to work on your communication skills. That will definitely benefit you in your career!

Constructive Criticism

Always ASK and ASK and ASK for feedback! As an intern, you'll make tons of mistakes. Consequently, you should have the courage to accept and ask for constructive criticism from your experienced colleagues. Don't take criticism personally. Adopting a humble mindset will encourage your mentors to give you more feedback about your work.

I can remember how much I failed my first pull requests. But luckily, I've asked my colleagues for a code review and they were kind and humble enough to help me with that.

Moral of the story: Have the courage to make mistakes and ask for feedback from your coworkers.

Adaptability

Internships can have a steep learning curve during the first couple of weeks. During this period, you'll be working with industry best practices, which require you to learn about a new set of skills. Be patient and take it easy; after all, it's not simple to adapt, especially when you want to go outside your comfort zone.

Teamwork

Teamwork is an important skill you should concentrate on most during your internship since it's not learnable in college or by studying alone at home. Ideally, an IT company works with different methodologies and frameworks like DevOps, Agile, Scrum, XP, ... As an intern, you'll have the opportunity to hone your skills in these methodologies.

You'll also learn how to collaborate with multiple people with diverse skills. This is very important since you'll be part of a cross-functional team.

Problem Solving

Developing an adequate problem-solving approach can drive you onto the fastest path to success. An internship introduces you to real-world work problems and thus develops your problem-solving skills.
Now you've got your first stories assigned to you in your company's issue tracker. Great! How do you approach these issues? The first step is to understand the problem and then breaking it into manageable pieces that you can solve.

Make sure to verify how you plan to break down the implementation with your mentor. They might be able to aid you identify other components or dependencies you hadn't thought of.

Wrap up

Intern life can be challenging, and you only get a short time to make a lasting impression. Though it is an excellent opportunity to gain experience, form friendships, and ultimately learn. So work hard and appreciate your internship!

If you have any feedback about my writings. Please, don't hesitate to reach out to me or just say a "hello" on twitter: @HamzaLovesJava

Intro to OAuth and OpenID Connect - Part 1

Hamza Belmellouki — Sat, 12 Sep 2020 14:07:58 +0000

OAuth 2.0 and OpenID Connect are becoming the de-facto standard for handling authentication and authorization in modern applications.

This post is the starting point of a series of posts covering OAuth 2.0 and OpenID Connect (OIDC). It introduces you to OAuth and OIDC and tells you why you'll want to leverage these mechanisms when dealing with authentication and authorization. We'll also take a look at OAuth tokens and the most widely used OAuth extensions.

Beware that I use the terms OAuth and OAuth 2.0 interchangeably. So when I say OAuth I mean OAuth 2.0 not the 1.0 version.

What Is OAuth?

Before defining what OAuth is I'd like to make a clear distinction between Authentication(AuthN) and Authorization(AuthZ): AuthN defines who you are. On the other hand, AuthZ specifies what you can do.

To save you the time from looking up to Wikipedia here is the definition:

OAuth is an open standard for access delegation, commonly used as a way for Internet users to grant websites or applications access to their information on other websites but without giving them the passwords

Keep in mind that OAuth 2.0 is an authorization framework. Like most frameworks, it does left many things undefined and it's up to the specific OAuth implementation to define the missing parts.

Here I am describing some of the most widely used oAuth 2.0 extensions:

JWT

JSON Web Token, short for JWT defined by RFC 7519 as a way to repensent claims to be exchanged between two parties. Note that OAuth doesn't require JWTs, but it's common to use it along with it. JWTs are encoded, there're not encrypted; so make sure to not put sensitive information into JWT. It's not secure! If you want to share sensitive data you could leverage an opaque token or JSON Web Encryption (JWE).

A JWT contains fields like:

iss (issuer): Specifies issuing auth server
iat (issued at): Issued at time
sub (subject): Identifies the principal that is the subject of the JWT(the user)
aud (audience): Represents who should use it
exp (expiration): Specifies the expiration date

Token revocation

The token revocation spec defined by RFC 7009 as a way to revoke(cancel) a token via API. Note that implementing this spec is optional, and it shouldn't be because if your tokens were leaked to malicious actors, you'd need a way to make the access token invalid without needing to wait for the expiration date of the token.

Token introspect

The token introspection spec RFC 7662 examines a token to describe its contents, this is useful if you want to know the content of an opaque token. Also, it is used to determine the validity of a token. Finally, With introspection your client applications can query the authorization server to know if the token is revoked.

Dynamic Client Registration

The Dynamic Client Registraction spec RFC 7591 let systems to register themselves with the auth server for reqesting tokens and It is done programmatically. Once registered you could leverage Dynamic Client Management spec RFC 7592 to manage and maintain registered oAuth clients.

Authorization Server Metadata Discovery

All the above specifications are optional. Not to mention that not all auth servers will support all the above oAuth 2.0 extensions. This is where Authorization Server Metadata Discovery spec REF 8414 known as oAuth Discovery Document comes in handy. It allows us to query the auth server to learn about its capabilities. Also, the server will tell us what endpoints are available.

Why OAuth?

OAuth was created to solve authentication issues. Previously, third-party apps using HTTP Basic users were prompted for username/password so the app can make authorized requests on their behalf. So you have to trust the app because if you give your email/password to a third-party app, it will store your credentials in their datastore. Using HTTP Basic decentralizes password management to third-party apps. Many of these apps will have to store your credentials in their datastores; therefore, third-party apps will be required to do their best to secure their datastores, which isn't an easy thing to do. Security leaks in those third-party apps could emerge, and boom! Users are doomed!

With OAuth, instead of sending username/password to the API every time you make a request, you'll register your application to the OAuth server and then send a client_id(provided by the OAuth server) and a secret to getting a signed access token which will authorize future requests. The diagram bellow illustrates the basic process for getting an access token:

OAuth Tokens

RFC 6749 defines an OAuth access token as:

Access tokens are credentials used to access protected resources. An access token is a string representing an authorization issued to the client. The string is usually opaque to the client. Tokens represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization server.

I found this to be a vague definition, so let's try to demystify it.

As we've learned previously, OAuth 2.0 is a framework or a loose agreement that leaves many things undefined. The tokens are among the many things. Note that it gets pretty clean when working with an OAuth implementation. Typically an Opaque or JSON Web Tokens are the most common approaches to OAuth:

An opaque token is a unique string that acts as a database key to retrieve relevant information, only the issuer(auth server) knows the format; there's nothing to decode or decrypt in this token.
JWT has readable content. If you go to https://jwt.io/, anyone can validate and decode the content of that JWT.

Validating a JWT

Validating the JWT is a crucial step in establishing trust between the auth server and the app. If we validate a token correctly, we can trust it.

These are typically the steps to validate an access or ID token:

You have to retrieve your signing keys. Often, these keys are available in the keys document via URL from your auth server.
The JWT contains three components: the header, payload, and signature separated by a dot. Decode these components using Base64
After decoding the JWT header, grab the kid(Key ID) claim, which should be precise as the key from the original document you retrieved a couple of steps ago. If they don't match either the document is out of date, or the token is not for you, and you should decline it immediately.
Next, use the referenced key to sign the payload and compare it against the original signature. If they don't match, then the token is not for you, and you should decline it immediately.
After knowing that the token is for us and untouched, we'll examine four claims from the payload. First, the ISS(issuer) claim should match our auth server, so we know where it originated from. Next, the AUD(Audience) claim should match the values set in our auth server, so we know who the token is intended for. Next, CID(Client ID) claim should match the Client ID of our app that requested the token. And finally, EXP(Expiration Time) should be in the future; If our EXP is in the past, it means that the token is no longer valid, and we can't trust it.

If our token failed in any of the above checks, we shouldn't use that token because we can't trust it. But once you've made it through all the above steps, your token should be valid and verified.

PS: Implementing these steps yourself is error-prone and a daunting task. Luckily there are various libraries in every programming language that handles most of this work for you.

Refresh Token

Because refresh token is an opaque token, it means that it can't be decoded and verified; thus, it can only be used in the token endpoint authorization server. Now the auth server grabs the refresh token, make sure it's still active, and then dispense a new access token and refresh token. Note that the revocation endpoint must be secured, for example, if someone gets a refresh token, they can each time(as long as refresh token not expired) generate new access and refresh token. We don't want this!

What Is OpenID Connect?

OpenID Connect (OIDC) is an authentication layer on top of OAuth 2.0. It provides the structure to a user profile, and allows you to selectively share it. So OIDC is just a special case of OAuth, and It's designed for Single Sign On(SSO) and sharing profile information. Like so GitHub, Twitter and many others use OIDC to share user profile information to clients.

On top of OAuth 2.0, OIDC adds another type of token: the ID Token. This token is highly defined and structured; it is mandated to be a JWT. Most of the times it contains the user profile information.

OIDC exposes user info endpoint to retreive user info. In general, this will retreive the exact user info which was available in the ID token itself. Thus, if you app trust the auth server that issued the token, we know who signed in and can use that to create a profile on our end. Note that OIDC supports only a subset of the OAuth grant types(we'll cover them in the next blog).

The great thing about OIDC is that the structure and names of token claims are entirely defined by the specification with isn't the case when using jusr the regular OAuth.

Wrap Up

In this blog, I've introduced you to the world of OAuth and OIDC. In the next part, we'll cover OAuth Grant Types.

If you have any feedback about my blogs. Please, don't hesitate to reach out to me or just say a "hello" on twitter: @HamzaLovesJava

Test Slices in Spring-Boot

Hamza Belmellouki — Sat, 12 Sep 2020 14:07:40 +0000

One of the early mistakes that I've done in my first professional Spring-Boot based project was writing integration tests that load the entire ApplicationContext using @SpringBootTest annotation when there's no need. Thankfully, one of my colleagues was kind enough to help me understand that there is a better way to do things :) Writting tests like that will definitely slow down your continuous integration pipeline.

Before talking about test slices I want to make a clear distinction between a unit test and an integration test in Spring: Unit testing doesn't involve loading the application context. On the other hand, integration testing is more involed with loading the application context.

Test Slices

Test Slices are a cool Spring-Boot feature introduced in 1.4. The idea is that Spring-Boot will bootstrap only the configuration meta-data that's appropriate for the component that's under test. Using this feature will result in a much lightweight ApplicationContext. Thus, the execution of our integration tests will be faster compared to loading the entire context. Now let's see some of these test slices in action.

@WebMvcTest

Integration tests is about mocking the minimum amount of dependencies to test if the integration of your components and modules works fine. But, ofentimes your components depend on external web services and that web service isn't up in your build/dev environment. In such situation we can go ahead with the integration test and mock that dependency. In this example, I want to test EmployeeResource endpoints:

@RestController
class EmployeeResource {

    @Autowired
    EmployeeService employeeService;

    @GetMapping("/employees")
    public ResponseEntity<List<Employee>> getAllEmployees() {
        return ResponseEntity.ok(employeeService.getAllEmployees());
    }
}

Now @WebMvcTest will disable full auto-configuration(done by @SpringBootTest) and instead apply only configuration relevant to MVC tests(i.e. @Controller, @ControllerAdvice, @JsonComponent, Converter/GenericConverter, Filter, WebMvcConfigurer). Suppose that employeeService.getAllEmployees() routine perform an HTTP call to another external web service and the service isn't available in my local dev environment so I'll decide to mock it using @MockBean. Now I can perform request and test the results:

@RunWith(SpringRunner.class)
@WebMvcTest
public class EmployeeResourceTest {

    @Autowired
    MockMvc mockMvc;

    @MockBean
    EmployeeService employeeService;

    List<Employee> employees = new ArrayList<>();

    @Before
    public void setUp() throws Exception {
        Employee employee = new Employee();
        employee.setId(1);
        employee.setFirstName("a first name");
        employee.setLastName("a last name");
        employees.add(employee);
    }

    @Test
    public void shouldReturnOkayAndPayloadWhenRequestingEmployeeResource() throws Exception {
        doReturn(employees).when(employeeService).getAllEmployees();
        mockMvc.perform(MockMvcRequestBuilders.get("/employees"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$[0].id").value(1))
                .andExpect(jsonPath("$[0]firstName").value("a first name"))
                .andExpect(jsonPath("$[0]lastName").value("a last name"));

        verify(employeeService).getAllEmployees();
    }
}

@DataJpaTest

We can leverage @DataJpaTest annotation to disable full auto-configuration and instead apply only configuration relevant to JPA tests. This will not only load repository components but also utility classes like DataSource and TestEntityManager which can be used to save/find data in the DB.

Note that by default, tests annotated with @DataJpaTest will auto-configure an in-memory h2 database (can be overridden) for testing purposes. Also, tests are transactional and rolled back at the end of each test. In this example, I'd like to test EmployeeRepository:

@Repository
public interface EmployeeRepository extends JpaRepository<Employee, Long> {

}

This simple test tests that the repository can save and retrieve the data in the in-memory h2 database:

@RunWith(SpringRunner.class)
@DataJpaTest
public class EmployeeRepositoryTest {

    @Autowired
    EmployeeRepository employeeRepository;

    @Autowired
    TestEntityManager entityManager;

    Employee employee;

    @Before
    public void setUp() throws Exception {
        employee = new Employee();
        employee.setId(1);
        employee.setFirstName("a first name");
        employee.setLastName("a last name");
    }

    @Test
    public void shouldSaveEmployee() {
        entityManager.persist(employee);
        Employee result = employeeRepository.findAll().get(0);
        assertThat(result.getId()).isEqualTo(1);
        assertThat(result.getFirstName()).isEqualTo("a first name");
        assertThat(result.getLastName()).isEqualTo("a last name");
    }
}

@RestClientTest

Use @RestClientTest to speed up the testing of REST clients. this annotation will disable full auto-configuration and instead apply only configuration relevant to rest client tests (i.e. Jackson or GSON auto-configuration and @JsonComponent beans, but not regular @Component beans). It also auto-configure some essential beans like RestTemplateBuilder and MockRestServiceServer and load them into the context. Now we'll test EmployeeDetailsService which perform an HTTP request to http://localhost:8081/{id}/details endpoint to retrieve an EmployeeDetails object:

@Service
public class EmployeeDetailsService {

    private final RestTemplate restTemplate;

    public EmployeeDetailsService(RestTemplateBuilder restTemplateBuilder) {
        this.restTemplate = restTemplateBuilder.build();
    }

    public EmployeeDetails getEmployeeDetails(int id) {
        return restTemplate.getForObject("http://localhost:8081/{id}/details", EmployeeDetails.class, id);
    }
}

@Data
class EmployeeDetails {
    private String address;
    private int salary;
}

@RestClientTest annotation's value attribute specify which service is under test. Doing so will speed up our test since only EmployeeDetailsService is loaded in the context along with other beans provided from the auto-configuration. This example demonstrates how to test EmployeeDetailsService:

@RunWith(SpringRunner.class)
@RestClientTest(EmployeeDetailsService.class)
public class EmployeeDetailsServiceTest {

    @Autowired
    private EmployeeDetailsService employeeDetailsService;

    @Autowired
    private MockRestServiceServer mockRestServiceServer;

    @Test
    public void shouldReturnEmployeeDetailsFromHttpRequest() {
        mockRestServiceServer.expect(requestTo("http://localhost:8081/1/details")).andRespond(
                withSuccess(new ClassPathResource("employeeDetails.json"), MediaType.APPLICATION_JSON));

        EmployeeDetails employeeDetails = employeeDetailsService.getEmployeeDetails(1);

        assertThat(employeeDetails.getAddress()).isEqualTo("Morocco, Casablanca, Maarif");
        assertThat(employeeDetails.getSalary()).isEqualTo(100_000);
    }
}

MockRestServiceServer mocks the expected behavior of the intended HTTP request made by a RestTemplate inside EmployeeDetailsService. Note that ClassPathResource picks employeeDetails.json from the root of the test classpath.

Wrap Up

In this blog, I've discussed the most widely-used test slices. Note that I didn't cover them all. If you want to check others checkout this link. And as usual you can find these code snippets the github repo.

If you have any feedback about my blogs. Please, don't hesitate to reach out to me or just say a "hello" on twitter: @HamzaLovesJava

Twelve-Factor Application: Configuration in Spring

Hamza Belmellouki — Sat, 12 Sep 2020 14:07:05 +0000

The Twelve-Factor application methodology is a collection of best practices that are designed to enable applications to be developed with portability and resilience when deployed. In this post, we’ll cover the third factor, Config. We’ll also see how the spring ecosystem contributes to helping developers achieve this factor.

The Twelve-Factor application manifesto advocates on externalizing configs(passwords, hostnames…) as environment variables:

The twelve-factor app stores config in environment variables (often shortened to env vars or env). Env vars are easy to change between deploys without changing any code

Open-sourcing your codebase without compromising any credentials is the test that your app needs when you want to check if you’ve honored the factor.

Using @Value

This example demonstrates a quite simple example on how to load up properties from sample.properties file using regular spring:

message="Blogging is cool"

Here I am creating a command-line runner to print the value that is loaded from the sample.properties. Note that this file exists in the classpath, meaning in target/classes directory:

@SpringBootApplication
@Slf4j
@PropertySource("classpath:sample.properties")
public class ConfigsApplication implements CommandLineRunner {
    @Value("${message}")
    private String msg;

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

    @Override
    public void run(String... args) throws Exception {
        log.info(msg);
    }
}

Profiles

If you’re working in the enterprise chances are your projects have to go into many different environments(Dev | Test | Stage |UAT /Pre-Prod | Prod). Each of these environments may have different settings that are specific to them. How can we load the appropriate settings in its appropriate environment? The simplest answer to this question is to work with Spring Profiles. You’ll map each environment to its configuration that’s defined as a properties or yml file.

You can leverage environment variables in your yml/properties files as this factor advocate. In fact, you should do that since you don’t want to check out sensitive info like db credentials into your source control management system.

In this example, we’ll work with two environments: dev and prod. These two environments will differ in the database setup. For the dev environment, we’ll define a file called application-dev.yml. For prod, we’ll define it as application-prod.yml.

application-dev.yml:

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    username: sa
    password: sa
  jpa:
    hibernate:
      ddl-auto: create

The above configuration didn’t use environment variables because there’s no need, this profile is used solely for a dev environment(Don’t do that in prod).

application-prod.yml:

spring:
  datasource:
    url: ${DB_URL}
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
  jpa:
    hibernate:
      ddl-auto: none

Here I’ve used environment variables to load db credentials to the database. Now if you want you can publish your project to the public without worrying about db credentials being leaked.

You can activate a profile using one of these methods:

JVM system parameter

Passing a JVM system parameter is a way to activate a profile. For example, if you build your project using the spring-boot plugin you can pass the parameter like so:

mvn spring-boot:run -Dspring.profiles.active=prod

Environment Variable

Activate a profile by setting up an environment variable. For example, in Unix environment you would set your env in .bashrc file like so:

export spring_profiles_active=dev

Maven profile

You can leverage Maven profiles to activate Spring Profiles. This is my favorite way to activate a profile. For example, in your profiles section we’ll define two maven profiles dev and prod, each of these profiles will set a JVM system parameter:

<profiles>
    <profile>
        <id>dev</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <spring.profiles.active>dev</spring.profiles.active>
        </properties>
    </profile>
    <profile>
        <id>prod</id>
        <properties>
            <spring.profiles.active>prod</spring.profiles.active>
        </properties>
    </profile>
</profiles>

After setting up your maven profiles. You’ll need to set up resource filtering in your pom.xml to trigger variable resolution.

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>
        </resource>
    </resources>
    ...
</build>
</properties>

All that’s left is to specify which profile will be active by running a maven command with -P option:

mvn spring-boot:run -Pdev

Spring Cloud

If you're using Spring Cloud, we can centralize the configuration in "Spring Cloud Config Server" and consume the configuration that exists in a configuration git repository which stores all the necessary property configuration. The Config Server acts like a proxy between our configuration repository and clients. Note clients will consume the Spring Cloud Config Server via REST API.

Leveraging the above approach if configuration is changed the application will need to restart. Spring Cloud Config Server solves that problem by introducting a new scope: The refresh scope, this will allow us to reconfigure components without a restart. In this example we'll see how to configure a Config Server and how clients can consume it using its REST API.

Build a config server

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-config-server</artifactId>
</dependency>

Our Config Server will load configuration from a git repo hosted on GitHub. The service is a regular Spring Boot application which expose .(properties / yml) configuration as a REST API. Now, all you have to do to add Spring Clould Config Server support is to annotate your Spring Boot app with @EnableConfigServer annotation:

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

This annotation will tell Spring Boot provide all plumbing you app need to configure beans and expose the API.

This is the configuration for the Config Server located in application.yml:

server:
  port: 8181

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/Hamzablm/configuration-demo

The property spring.cloud.config.server.git.uri tells spring to look for configuration files located this git repository. Every Spring Boot application that leverage Spring Cloud should provide a unique name which is defined in bootstrap.yml:

spring:
  application:
    name: config-server

Keep in mind that "Spring Could Config Server" will bring all configuration from configuration-demo repository and expose the appropriate configuration to clients by matching client's spring.application.name to the configuration filename that exists in the git repo.

Note that you can even expose a specific configuration file for a specific profile; say if you run in a dev profile then configuration-client-dev.properties will be leveraged if it exists.

Also, If an application.(properties/yml) file exists in the git repo the config server will expose its properties to all clients, other configuration files will either define new properties or override the ones from application.(properties/yml)

Buid the client

Add Spring Cloud Config Client dependency to connect to Spring Cloud Config Server to fetch the app's configuration. Also, you'll need to bing Spring Actuator to access the refresh endpoint (more on that later) which will enable you to update the configuration on the fly in the client side:

<dependency>
   <groupId>org.springframework.cloud</groupId>
   <artifactId>spring-cloud-starter-config</artifactId>
</dependency>

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

The client which is a Spring Cloud based service will look for bootstrap.yml to bootstrap the service. bootstrap.yml start up before any application.(properties/yml). Here bootstrap.yml defines the name of the service which should match the name of the configuration filename in the git repository so the client know what need to be consumed.

spring:
  application:
    name: configuration-client
  cloud:
    config:
      uri: http://localhost:8181
management:
  endpoints:
    web:
      exposure:
        include: "*"

cloud.config.uri specifies the endpoint where your Config Server is deployed. management.endpoints.web.exposure.include=* is used to tell spring to enable actuator endpoint; we'll need them if we want to make our configuration refreshable.

Here we can access our config properties using traditional approaches like Environment abstraction, @PropertySource, @ConfigurationProperties:

@RestController
@RefreshScope
class MessageRestController {
    @Autowired
    private Environment env;

    @GetMapping("/msg")
    String getMessage() {
        return env.getProperty("project.message");
    }
}

This class is annotated with @RefreshScope therefore any changes in the configuration git repo could take effect without restarting the client app; to refresh your configs all you have to do is to perform a post request to this endpoint:

curl localhost:8080/actuator/refresh -d {} -H "Content-Type: application/json"

PS: Imagine having lots of microservices consuming your Config Server. If you change the configuration repository then everyone of those clients will have to refresh its configuration by performing a post request to the Actuator refresh endpoint and there's no need to tell you that's not a scalable solution. To solve this problem we can leverage Spring Cloud Bus, which links nodes of a distributed system with a lightweight message broker (e.g RabbitMQ) to broadcast state changes. Maybe I'll do a whole blog to talk about Spring Cloud Bus.

Running the code

First run the config server by running mvn spring-boot run and make sure you get the property defined in configuration-client in the json payload by accessing this url: http://localhost:8181/configuration-client/master. You should get something like:

{
   "name":"configuration-client",
   "profiles":[
      "master"
   ],
   "label":null,
   "version":"e467e3598c0509da56a15731a1f01e0851c46307",
   "state":null,
   "propertySources":[
      {
         "name":"https://github.com/Hamzablm/configuration-demo/configuration-client.properties",
         "source":{
            "project.message":"Blogging is awesome"
         }
      }
   ]
}

Notice now I got my property project.message from the git repo into my config server.

Now after running the config server, go ahead and run the config client by running mvn spring-boot run. Then go ahead and access this endpoint which just expose the configuration: http://localhost:8080/msg:

Blogging is awesome

Now that you've saw how to centralize your configuration in the configuration git repo and expose them using Spring Cloud Config Server make sure to clone the repository if you want to run the demo.

Wrap Up

In this post I attempted to show you how to leverage the Spring ecosystem capabilities to honor Config factor in a Twelve-Factor application.

Core Java: Date and Time

Hamza Belmellouki — Sat, 12 Sep 2020 14:06:22 +0000

Since Java 8, Oracle completely rebuilt its Date/Time API. The new API is supposed to replace the old one.

The new API which is located in the java.time package is thread-safe because most of the new classes are immutable, meaning that, after the object is constructed, it cannot be modified. This is especially useful when working in a multi-threaded environment where issues like thread interference and data corruption cannot happen thanks to immutability.

This article shows how to work with the new API.

Creating Dates and Times

Java lets us create dates and times using static factory methods. Note that you cannot create date and time objects using a constructor (you can do so with the old API, but you shouldn’t) because it is made private.

Creating dates and times is straightforward; you’ll notice a pattern for creating dates and times:

LocalDate

You create a LocalDate by using one of its static factory methods:

LocalDate now = LocalDate.now();
System.out.println(now);// 2020-02-21

LocalDate date = LocalDate.of(2020, 1, 23);
System.out.println(date);// 2020-01-23

LocalDate date2 = LocalDate.of(2020, Month.JANUARY, 23);
System.out.println(date2);// 2020-01-23

Note that month indexes are one-based.

LocalTime

Similarly, you create a LocalTime object like so:

LocalTime now = LocalTime.now();
System.out.println(now);// 12:31:56.186

LocalTime midnight = LocalTime.of(23, 0);
System.out.println(midnight); // 23:00

The second line output a toString representation of LocalTime, which represents [hour:minutes:seconds.milliseconds]

LocalDateTime

The LocalDateTime class represents date and time combined. You can create it with:

LocalDateTime now = LocalDateTime.now();
System.out.println(now);// 2020-02-21T12:46:09.950

LocalDateTime newYear = LocalDateTime.of(LocalDate.of(2021, 12, 31), LocalTime.of(11, 59));
System.out.println(newYear);// 2021-12-31T11:59

Note that in the output date and time are separated with a T.

ZonedDateTime

Use this class if you want to express in a date and time in a specific timezone. for example:

ZonedDateTime usPacific = ZonedDateTime.now(ZoneId.of("US/Pacific"));
System.out.println(usPacific);// 2020-02-22T02:53:46.774455-08:00[US/Pacific]

ZonedDateTime now = ZonedDateTime.now();// 2020-02-22T11:53:46.778363+01:00[Africa/Casablanca]
System.out.println(now);

The format of the output consists of LocalDateTime followed by the ZoneOffset.

Manipulating Dates and Times

LocalDate date = LocalDate.of(2020, Month.JANUARY, 20);
System.out.println(date);// 2020–01–20

date = date.plusDays(1);
System.out.println(date);// 2020-01-21

date = date.plusWeeks(3);
System.out.println(date);// 2020-02-11

date = date.plusMonths(4);
System.out.println(date);// 2020-06-11

date = date.plusYears(10);
System.out.println(date);// 2030-06-11

You these methods return a LocalDate object. Therefore, you can chain them:

LocalDate date = LocalDate.of(2020, Month.JANUARY, 20)
        .plusDays(1).plusWeeks(3)
        .plusMonths(4).plusYears(10);
System.out.println(date);// 2030-06-11

Using the same pattern, you can subtract dates/times from LocalDate, LocalDateTime, LocalTime and ZonedDateTime using minus###() method.

Periods and Durations

Periods

You create a period from the Period class. This class represents the amount of time in years, months, and days. These examples demonstrate the typical ways you would create a Period:

Period threeDays = Period.ofDays(3);
System.out.println(threeDays);// P3D

Period threeWeeks = Period.ofWeeks(3);
System.out.println(threeWeeks);// P21D

Period threeMonths = Period.ofMonths(3);
System.out.println(threeMonths);// P3M

Period threeYears = Period.ofYears(3);
System.out.println(threeYears);// P3Y

Period threeYearsAndFourMonthsAndTwoDays = Period.of(3, 4, 2);
System.out.println(threeYearsAndFourMonthsAndTwoDays);// P3Y4M2D

These static factory methods are self-explanatory; they create an immutable Period instance.

In the output, the letter P stands for Period, Y for years, M for months, and D for days.

Note that you cannot chain methods as you’ve seen in the LocalDate example when you create Period because these methods are static, If you chain them you’ll get unexpected behavior:

Period oneWeekAndADay = Period.ofDays(1).ofWeeks(1);
System.out.println(oneWeekAndADay); // unexpected result: P7D

Remember that a Period cannot be be used with some objects. Let’s look at some code:

Period period = Period.ofDays(1);
LocalTime time = LocalTime.of(6, 15);
time.plus(period); // UnsupportedTemporalTypeException

Durations

You create a duration form the Duration class. This class represents the amount of time in seconds and nanoseconds. It can also be expressed using other duration-based units, such as minutes and hours. These examples demonstrate the typical ways you would create a Duration:

Duration oneNano = Duration.ofNanos(1);
System.out.println(oneNano);// PT0.000000001S

Duration oneMilli = Duration.ofMillis(1);
System.out.println(oneMilli);// PT0.001S

Duration oneSeconds = Duration.ofSeconds(1);
System.out.println(oneSeconds);// PT1S

Duration oneMinute = Duration.ofMinutes(1);
System.out.println(oneMinute);// PT1M

Duration oneHour = Duration.ofHours(1);
System.out.println(oneHour);// PT1H

Duration oneDay = Duration.ofDays(1);
System.out.println(oneDay);// PT24H

Alternatively, you can create a Duration using the following method:

Duration fiveHours = Duration.of(5, ChronoUnit.HOURS);
System.out.println(fiveHours);

This method takes 5 as an amount and a unit that the duration is measured in.

Working with Instants

You create an instant from the Instant class. This class represents a single instantaneous point on the time-line in the GMT since January 1, 1970 (1970–01–01T00:00:00Z), a.k.a the EPOCH. It may come in handy when you want to record event timestamps in the program. These examples demonstrate the typical ways you would create an Instant:

Instant now = Instant.now();
System.out.println(now);//2020-02-25T11:14:46.032856Z

ZonedDateTime zonedDateTime = ZonedDateTime.now(ZoneId.of("US/Eastern"));
System.out.println(zonedDateTime);// 2020-02-25T06:27:27.572624-05:00[US/Eastern]
Instant now2 = Instant.from(zonedDateTime);
System.out.println(now2);// 2020-02-25T11:14:46.055857Z

Instant instant = Instant.parse("2010-01-20T11:33:45Z");
System.out.println(instant);// 2010-01-20T11:33:45Z

Instant epoch = Instant.ofEpochMilli(0);
System.out.println(epoch);// 1970-01-01T00:00:00Z

Note that the output of toString follows the ISO-8601 standard.

As you can see, when Java invoked Instant.from(zonedDateTime); it created an Instant object from ZonedDateTime object and converted the time from US/Eastern timezone to GMT.

Likewise, this class provides various ways to operate on instants. For example:

Instant tenMinutesLater = Instant.now().plus(10, ChronoUnit.MINUTES);
System.out.println(tenMinutesLater);// print 10 minutes later from the current time

Parsing and Formatting

Formating

The JDK provides a new API to parse and format Temporal-based objects, using the DateTimeFormatter from the java.time.format package we can parse and format dates and times. Similar to most other new Date/Time API classes, DateTimeFormatter is immutable thus thread-safe.

The format method is provided by those classes for formatting temporal-based objects for display. For example, this snippet of code format date and time using a predefined formatter:

LocalDate date = LocalDate.of(2020, Month.MARCH, 17);
LocalTime time = LocalTime.of(9, 15, 45);
LocalDateTime dateTime = LocalDateTime.of(date, time);

System.out.println(
dateTime.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));// 2020-03-17T09:15:45

System.out.println(
date.format(DateTimeFormatter.ISO_LOCAL_DATE));// 2020-03-17

System.out.println(
time.format(DateTimeFormatter.ISO_LOCAL_TIME));// 09:15:45

DateTimeFormatter shortF = DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT);
System.out.println(shortF.format(dateTime));// 3/17/20, 9:15 AM

DateTimeFormatter mediumF = DateTimeFormatter.ofLocalizedDateTime(FormatStyle.MEDIUM);
System.out.println(mediumF.format(dateTime));// Mar 17, 2020, 9:15:45 AM

We can also define a custom formatter object using DateTimeFormatter.ofPattern method:

LocalDate date = LocalDate.of(2020, Month.MARCH, 17);
LocalTime time = LocalTime.of(9, 15, 45);
LocalDateTime dateTime = LocalDateTime.of(date, time);

DateTimeFormatter f = DateTimeFormatter.ofPattern("dd-MMMM-yyyy | hh:mm");
System.out.println(dateTime.format(f));// 17-March-2020 | 09:15

Make sure to take a look at the reference documentation if you want to know more about the syntax used in the ofPattern method argument.

Parsing

Now you know how to convert Temporal-based classes into strings, let’s see how we can convert into the other direction using the parse method:

DateTimeFormatter f = DateTimeFormatter.ofPattern("dd MM yyyy");
LocalDate date = LocalDate.parse("25 03 2020", f);
LocalTime time = LocalTime.parse("09:30");

System.out.println(date);// 2020-03-25
System.out.println(time);// 09:30

LocalDate.parse(“25 03 2020“, f) returns a LocalDate by parsing the text string using a custom formatter object. While LocalTime.parse(“09:30”) parses the text string and returns a LocalTime using the default formatter (DateTimeFormatter.ISO_LOCAL_TIME)

A Peek on Dates and Times Before Java 8

Before Java 8, developers used the Date class, which represents the date and time altogether. There was no way to get a date or time separately, and it was all bundled in the Date class. Developers should not use this class anymore, as you’ve seen, there is a better way. This class exists to support backward compatibility.

Another disadvantage of the Date class is that it’s mutable. Therefore, you need to synchronize access to instances of this class when they’re accessed from multiple threads to avoid data corruption and unexpected behavior.

You may encounter the old Date API in legacy projects. You create a date by calling its constructor: Date date = new Date() , date refers to the current date/time. You can specify a specific date using the Calendar class:

Calendar cal = Calendar.getInstance();
cal.set(2020, 0, 23);
Date d = cal.getTime();
System.out.println(d);// Wed Jan 01 11:36:37 WET 2020

You can see how much verbose this old API compared to the new one. Beware that Month indexes are zero-based instead of one-based, which is confusing. The new API’s indexes are one-based.

Wrap Up

In this post, I attempted to demonstrate why you should work with the new Date/Time API, how to work with it, how to format and parse dates and times. And, peeked at how dates/times were handled before Java 8.

If you found this post useful, you know what to do now. Hit that clap button and follow me to get more articles and tutorials on your feed.

Java Generics: Type Erasure & Wildcards

Hamza Belmellouki — Sat, 12 Sep 2020 14:05:56 +0000

Specifying the generic type allows Java to perform type checking at compile-time. But when using generics in your code, due to “Type Erasure” that occurs at compile-time, generic type parameters are converted to the Object type. This makes generic type parameters unable to call other methods except for the Object ones.

What if we want to invoke methods other than that those in Object class? This article explains what “Wildcards”, “bounds” and “Type Erasure” are. And how to use Wildcards to increase flexibility when using generics.

Type Erasure

Wikipedia defines Type erasure as:

Type erasure is the load-time process by which explicit type annotations are removed from a program, before it is executed at run-time.

This example uses generics so we can use it with multiple types.

class Container<T> {
    private T contents;

    public Container(T contents) {
        this.contents = contents;
    }

    public T getContents() {
        return contents;
    }

    public static void main(String[] args) {
        Container<String> container = new Container<>("Hello!");
        String contents = container.getContents();
        System.out.println(contents);// Hello!
    }
}

You may think when typing Container<String> container = new Container<>(“Hello!”); you’re replacing the type T with String. But this is not the case, at compile-time, the Java compiler removes the generic type parameter T from the code and replaces it with the Object type:

class Container {
    private Object contents;

    public Container(Object contents) {
        this.contents = contents;
    }

    public Object getContents() {
        return contents;
    }

    public static void main(String[] args) {
        Container container = new Container("Hello!");
        String contents = (String) container.getContents();
        System.out.println(contents);
    }
}

Notice how String contents = container.getContents(); is transformed to String contents = (String) container.getContents(); As you can see the compiler inserted a cast when invoking getContents() method.

Wildcard generic type

A wildcard, represented by ? is useful when you want to define a “whatever type.”

Unbounded wildcard

One of the generics constraints is you cannot, for example, pass List<Integer> argument to List<Object> parameter; doing so would result in a compile-time error. It is actually a good thing because Java is protecting you from you!

public static void processList(List<Object> list) {
    for (Object o : list)
    System.out.print(o);
}

public static void main(String[] args) {
    List<Integer> numbers = List.of(1, 2);
    processList(numbers); // compile-time error
}

This example isn’t functioning because List<Integer> isn’t a subtype of List<Object>. As you might expect the List<Object> type in the processList parameter needs to be replaced with List<?> (read: list of unknown type)

Now I can pass any kind of List to processList method:

public static void processList(List<?> list) {
    for (Object o : list)
        System.out.print(o);
}

public static void main(String[] args) {
    List<Integer> list = List.of(1, 2);
    processList(list);// 12

    System.out.println();
    List<String> strings = List.of("Hello", "World!");
    processList(strings);// HelloWorld!
}

bounded wildcard

Using bounded wildcards allows the compiler to enforce a restriction on the type. This example demonstrates the power and safety benefits of the bounded wildcard:

public static void transformList(List<? extends CharSequence> list) {
    List<Integer> charsCount = list.stream()
            .map(CharSequence::length)
            .collect(Collectors.toList());
    System.out.println(charsCount);
}

public static void main(String[] args) {
    List<String> stringList = List.of("Hello", "World", "!");
    transformList(stringList);// [5, 5, 1]
    List<StringBuilder> stringBuilders = List.of(new StringBuilder("Java"), new StringBuilder("Rocks"));
    transformList(stringBuilders);// [4, 5]
}

What transformList does is it takes a List and transform it into a List<Integer>, expressing each element’s length.

Notice the parameter of transformList is List<? extends CharSequence> which means that this method will accept any list which is upper-bounded to CharSequence like List<String>, List<StringBuilder>, any list that has a subtype of CharSequence can be passed as an argument to this method.

Wrap up

In this post, I attempted to clarify the concept of Type Erasure and introduced you to wildcards and bounds. Still, there is much more to learn from generics. If you’re curious and want to know more, I highly recommend this comprehensive Java Generics FAQ.

If you found this post useful, you know what to do now. Hit that clap button and follow me to get more articles and tutorials on your feed.

Concurrency: Thread Safety In Java

Hamza Belmellouki — Sat, 12 Sep 2020 14:05:36 +0000

What is Thread safety? To save you the time from looking up to Wikipedia here is the definition:

Thread safety is a computer programming concept applicable to multi-threaded code. Thread-safe code only manipulates shared data structures in a manner that ensures that all threads behave properly and fulfill their design specifications without unintended interaction.

What does this definition really mean? How can we correctly write thread-safe code? What are some of the constructs that Java offers to write such code?

Accessing shared data

Access to mutable shared data requires synchronization which can be implemented using one of these approaches:

Java’s built-in synchronized keyword
volatile fields to guarantee that any thread that reads a field will see the most recently written value
Explicit locks
Atomic variables

Producing Thread-safe code is all about managing access to shared mutable states. When mutable states are published or shared between threads, they need to be synchronized to avoid bugs like race conditions and memory consistency errors.

Race condition

Java Concurrency In Practice defines race condition as:

A race condition occurs when the correctness of a computation depends on the relative timing or interleaving of multiple threads by the runtime; in other words, when getting the right answer relies on lucky timing.

To understand what the definition means, let us look at an example:

public class CheckThenActRace { // Risky
    private Connection connection = null;

    public Connection getConnection() {
        if (connection == null)
            connection = new Connection();
        return connection;
    }
}

CheckThenActRace has race conditions that can compromise its correctness. Say that threads A and B execute getConnection simultaneously. A sees that connection is null, and instantiates a new Connection. B also checks if connection is null. Whether connection is null at this point depends unpredictably on CPU scheduler timing. If connection is null when B examines it, the two callers to getConnection may receive two different results, even though getConnection is always supposed to return the same instance.

To resolve such an issue, the operation check-then-act needs to be atomic; meaning it should happen all at once. We can achieve atomicity by making getConnection synchronized:

public synchronized Connection getConnection() {
    if (connection == null)
        connection = new Connection();
    return connection;
}

Now when Thread A calls getConnection; A acquires the intrinsic lock of the object and locks it until getConnection is completely executed, then A releases the lock for Thread B to acquire it.

Memory consistency errors

When reads and writes occur in different threads, issues like memory consistency errors could emerge. In Java, there is no guarantee that the reading thread will see a value written by another thread on a timely basis, or even at all.

To enable visibility of memory writes across threads, you need to rely on synchronization. For example:

class MemoryErrorDemo { // don't do this
    private static boolean flag;
    private static int number;

    private static class ReaderThread extends Thread {
        public void run() {
            while (!flag) {
                // do nothing
            }
            System.out.println(number);
        }
    }

    public static void main(String[] args) {
        new ReaderThread().start();
        number = 5;
        flag = true;
    }
}

MemoryErrorDemo could loop forever because the value of flag might never become visible to the reader thread. Even more weirdly, MemoryErrorDemo could print zero instead of 5 because the write to flag might be made visible to the reader thread before the write to number, a phenomenon known as reordering.

We could use the built-in intrinsic lock or the volatile keyword, a weaker form of synchronization, to ensure that writes to a variable are propagated predictably to other threads. To make the program works as expected, we have to add the volatile keyword to the second and third line:

private volatile static boolean flag;
private volatile static int number;

Atomicity

Atomicity is when a set of actions all execute as a single operation, in an indivisible manner. Thinking that a set of actions in a multi-threaded program will be executed in sequential order might lead to behavior incorrectness. That’s due to thread interference, which means threads may overlap if they execute several steps on the same data. For example:

class AtomicityDemo {

    private static long counter = 0;

    private static class CounterThread extends Thread {
        public void run() {
            for (int i = 0; i < 1000; i++) {
                increment();
            }
        }
    }

    private static void increment() {
        ++counter;
    }

    public static void main(String[] args) throws InterruptedException {
        CounterThread counterThread = new CounterThread();
        counterThread.start();
        for (int i = 0; i < 1000; i++) {
            increment();
        }
        counterThread.join();
        System.out.println("Final number should be: 2000, but it's :" + counter);
    }
}

AtomicityDemo simulates two threads writing to a shared variable. You may get the correct result if you’re lucky but if you run the program multiple times you’ll get different incorrect values. That’s because the operation ++counter isn’t a one-time operation, instead, it is composed of three steps so thread interference happens between these action steps.

To solve this problem we’ll convert the multi-step increment operation into an atomic operation. Fortunately, the Java core API provides Thread-safe objects to perform the operation. In this case, we’ll leverage AtomicLong wich is in java.util.concurrent.atomic package. Java Concurrency In Practice states:

Where practical, use existing thread-safe objects, like AtomicLong, to manage your class’s state. It is simpler to reason about the possible states and state transitions for existing thread-safe objects than it is for arbitrary state variables, and this makes it easier to maintain and verify thread safety.

The resulting code would look like:

import java.util.concurrent.atomic.AtomicLong;

class AtomicityDemo {

    private static AtomicLong counter = new AtomicLong(0);

    private static class CounterThread extends Thread {
        public void run() {
            for (int i = 0; i < 1000; i++) {
                increment();
            }
        }
    }

    private static void increment() {
        counter.incrementAndGet();
    }

    public static void main(String[] args) throws InterruptedException {
        CounterThread counterThread = new CounterThread();
        counterThread.start();
        for (int i = 0; i < 1000; i++) {
            increment();
        }
        counterThread.join();
        System.out.println("Final number should be: 2000, but it's :" + counter.get());
    }
}

Now the increment method atomically increments the current value. The two threads will not interleave when trying to increment counter variable because it happens all in one operation.

Locking

Locking is an interesting topic in concurrency. In Java, you could use either the object’s intrinsic lock or an explicit lock (implementation of the Lock interface). Both of these two locking strategies help us achieve thread-safety by synchronizing access to shared mutable data.

Object’s Intrinsic Lock

Every object has an intrinsic lock associated with it. Any thread that wants access to a shared object has to acquire the intrinsic lock first so no other thread can access that object, and when the thread finishes with the lock it releases it so other threads may acquire it.

When you declare that a method as synchronized, the thread calling that method acquires the intrinsic lock for that method’s object and releases it when the method exits. In CheckThenActRace (see above) we had used the object’s intrinsic lock to synchronize access to shared mutable objects and also we can leverage it to establish happens-before relationships that are essential to visibility.

Explicit Lock

Added in Java 5, the package java.util.concurrent.locks has multiple classes that implement the Lock interface. One of these classes is ReentrantLock which is a reentrant mutual exclusion Lock with the same basic behavior and semantics as the intrinsic lock accessed using synchronized methods and statements. Typical usage of this class:

Lock lock = new ReentrantLock();

lock.lock();
try {
    //do critical section code. May throw exception
} finally {
    lock.unlock();
}

This trick makes sure that the Lock is unlocked in case an exception is thrown from the code in the critical section. if an exception occurred in the critical section and the unlock() wasn’t called from inside a finally block, the lock would remain locked forever, causing all threads trying to acquire the lock to hang indefinitely.

Conclusion

In this article, we saw what is thread-safety is all about, how to write thread-safe code. We also talked about common pitfalls that may occur when developing concurrent programs and how to deal with them.

If you want to know more about the subject, I highly recommend reading “Java Concurrency In Practice” by Brian Goetz.

In the next article, there will be more Core Java. Stay tuned!

Simplify Strategy Using Lambda Expression

Hamza Belmellouki — Sat, 12 Sep 2020 14:05:16 +0000

The strategy design pattern is one of the most widely used patterns in the software development world. In this article, we’re going to learn about the strategy design pattern, when to use it, when not, how we can leverage the pattern to make our design flexible? And we are going to see an example of how to implement it with and without lambdas.

2. Strategy Design Pattern

2.1 Definition

To save you the time spent on searching Wikipedia here is the definition:

The strategy pattern (also known as the policy pattern) is a behavioral software design pattern that enables selecting an algorithm at runtime. Instead of implementing a single algorithm directly, code receives run-time instructions as to which in a family of algorithms to use. Strategy lets the algorithm vary independently from clients that use it.

The idea of the strategy pattern is to define a family of algorithms, encapsulate what varies into separate classes and make their objects interchangeable in the context. Varies here means: may change over time due to the evolving requirements.

2.2 UML Diagram

The Context class does not implement any strategy (algorithm). Instead, it maintains a reference to the Strategy interface. The Context class doesn’t care about the implementation of those algorithms. All it knows is that it can perform those algorithms!

StrategyImpl1 and StrategyImpl2 implement the Strategy interface, meaning, implement and encapsulate an algorithm.

2.3 When to use/avoid strategy pattern

Use the strategy pattern when you want to:

Use different algorithms within an object and be able to switch from one algorithm to another at runtime.
Hide irrelevant implementation details of your algorithms from the client. The implementation gets injected to the client at runtime by using a dependency injection mechanism.
Replace massive conditionals with a one-line method call. Note that delegation plays an important role here since that one-line method will call the appropriate implementation at runtime based on the reference type (Dynamic dispatch!).
Substitute inheritance with composition

Avoid using the strategy pattern when your algorithms rarely change, there’s no need to overengineer the program with new classes and interfaces that come along with the pattern

2.4 Classic Strategy in Action

In this example, I’ll show you how to implement the classical strategy pattern in Java. This example simulates a dummy program that sorts and searches a list by using various algorithms (or strategies). To start here is the class diagram of our little demo:

Note that the Client class depends on the Context and also on some of the strategy implementations (I didn’t draw we since we don’t want to have spaghetti here). This is the implementation (dummy) for our demo:

import java.util.List;

interface SortStrategy {
    void sort(List<String> list);
}

class QuickSortStrategyImpl implements SortStrategy {

    @Override
    public void sort(List<String> list) {
        System.out.println("List sorted using Quick sort implementation");
    }
}

class BubbleSortStrategyImpl implements SortStrategy {

    @Override
    public void sort(List<String> list) {
        System.out.println("List sorted using Bubble sort implementation");
    }
}

interface SearchStrategy {
    String search(String s);
}

class BinarySearchStrategyImpl implements SearchStrategy {
    @Override
    public String search(String s) {
        System.out.println("list is binary searched");
        return null;
    }
}

class LinearSearchStrategyImpl implements SearchStrategy {

    @Override
    public String search(String s) {
        System.out.println("list is linearly searched");
        return null;
    }
}

class Context {
    private SortStrategy sortStrategy;

    private SearchStrategy searchStrategy;

    public Context(SortStrategy sortStrategy, SearchStrategy searchStrategy) {
        this.sortStrategy = sortStrategy;
        this.searchStrategy = searchStrategy;
    }

    public void setSortStrategy(SortStrategy sortStrategy) {
        this.sortStrategy = sortStrategy;
    }

    public void setSearchStrategy(SearchStrategy searchStrategy) {
        this.searchStrategy = searchStrategy;
    }

    public void sort(List<String> list) {
        sortStrategy.sort(list);
    }

    public String search(String s) {
        // perform search
        return searchStrategy.search(s);
    }
}

class Client {
    public static void main(String[] args) {
        List<String> list = List.of("b", "a", "c");
        Context context = new Context(new BubbleSortStrategyImpl(), new BinarySearchStrategyImpl());
        context.sort(list);
        String searchedElement1 = context.search("b");

        System.out.println("---------------");

        context.setSortStrategy(new QuickSortStrategyImpl());
        context.setSearchStrategy(new LinearSearchStrategyImpl());
        context.sort(list);
        String searchedElement2 = context.search("a");
    }
}

Output:

List sorted using Bubble sort implementation
list is binary searched
---------------
List sorted using Quick sort implementation
list is linearly searched

The class Context depends only on the interfaces that declare the strategies, SortStrategy and SearchStrategy. It doesn’t care about the implementation of those interfaces. BubbleSortStrategyImpl and BinarySearchStrategyImpl are classes that implement those interfaces, respectively. As we said previously, they implement and encapsulate the strategy (algorithm).

For example, in line 75 those implementations get injected into the Context class by the client. So when we call the context.sort(list) and context.search(“b”) at runtime, the context will know which implementation to execute (polymorphism).

Notice the class Context exposes setters that let clients replace the strategy implementation associated with the context at runtime (Remember: Strategy lets the algorithm vary independently from clients that use it).

Let’s say we have another requirement to add another sorting or searching strategy implementation, we can add it by implementing the appropriate strategy interface without changing any existing code. You can see that the Strategy design pattern promotes the Open/Closed Principle.

3. Lambda Expression And The Strategy Pattern

3.1 Overview

Lambda expressions have changed the world in Java, and we can effectively use lambda expressions to avoid writing a lot of ceremonial code.

As far as the Strategy design pattern is concerned we don’t have to create a hierarchy of classes. Instead, we can directly pass the strategy implementation of the interface as a lambda expression to the context.

3.2 Strategy simplified

The above code is verbose and has a lot of ceremony for a simple algorithm. We can leverage lambda expression to reduce code verbosity. Using lambda we can implement different versions of an algorithm inside a set of function objects without bloating your code with extra classes.

In this demo, we’ll refactor the code to use lambda expressions to avoid creating custom interfaces and classes. This is the refactored implementation (dummy) code:

class Context {
    private Consumer<List<String>> sortStrategy;
    private Function<List<String>, String> searchStrategy;

    void sort(List<String> list) {
        sortStrategy.accept(list);
    }

    public Context(Consumer<List<String>> sortStrategy, Function<List<String>, String> searchStrategy) {
        this.sortStrategy = sortStrategy;
        this.searchStrategy = searchStrategy;
    }

    public void setSortStrategy(Consumer<List<String>> sortStrategy) {
        this.sortStrategy = sortStrategy;
    }

    public void setSearchStrategy(Function<List<String>, String> searchStrategy) {
        this.searchStrategy = searchStrategy;
    }

    public String search(List<String> list) {
        return searchStrategy.apply(list);
    }
}

class Client {
    public static void main(String[] args) {
        List<String> list = List.of("b", "a", "c");
        Consumer<List<String>> bubbleSort = l -> System.out.println("List sorted using Bubble sort implementation");
        Function<List<String>, String> binarySearch = list1 -> {
            System.out.println("list is binary searched");
            return null;
        };
        Context context = new Context(bubbleSort, binarySearch);

        context.sort(list);
        String searchedElement = context.search(list);

        System.out.println("-------------");

        Consumer<List<String>> quickSort = list1 -> System.out.println("List sorted using Quick sort implementation");
        Function<List<String>, String> linearSearch = l -> {
            System.out.println("list is linearly searched");
            return null;
        };
        context.setSortStrategy(quickSort);
        context.setSearchStrategy(linearSearch);
        context.sort(list);
        context.search(list);
    }
}

Notice I didn’t create any interface because I’m using functional interfaces from java.util.function package.

The output is the same as before. But the important thing to note is I’m not creating classes and interfaces to implement the strategy. All I’m using is composing the Context class with the Consumer and Function interfaces and I’ve created setters so I can change the strategy behavior at runtime.

And, on the client-side, I’m passing the implementations (function object) to the Context class.

4. Conclusion

In this article, we saw the definition of the strategy design pattern, how to use it to make the design flexible. And we learned the classical implementation of the strategy pattern, also its implementation using Java 8 features. In the next article, there will be more Core Java. Stay tuned!

Let us know what you think in the comments below and don’t forget to share!

Core Java: Comparator vs. Comparable

Hamza Belmellouki — Sat, 12 Sep 2020 14:04:48 +0000

When working with custom objects, we often want to compare them based on some pre-defined criteria. That’s why we use the Comparable interface to implement a natural ordering for our custom objects.

Also, we often need to specify a total ordering if there is no natural ordering implemented by our custom object or override the natural ordering defined by the object, so we use a Comparator interface to do such a thing.

2. The Example Demo

In the example demo, we’ll show how to compare Person objects using natural ordering implemented by the Comparable interface and also to override that natural ordering by using a new ordering implemented by the Comparator interface.

Assume you have a Person class as demonstrated below:

class Person {
    private int age;
    private String firstName;
    private String lastName;

    public Person(int age, String firstName, String lastName) {
        this.age = age;
        this.firstName = firstName;
        this.lastName = lastName;
    }

    // getters and setters

    @Override
    public String toString() {
        return "Person{" +
                "age=" + age +
                ", firstName='" + firstName + '\'' +
                ", lastName='" + lastName + '\'' +
                '}';
    }
}

3. Comparable Interface

3.1 Definition

You define the natural ordering for your objects by implementing the Comparable’s compareTo(T o) method in your custom objects. For example, if we want to compare the Person object based on the first name we’ll implement the Comparable interface like so:

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

class Person implements Comparable<Person> {
    private int age;
    private String firstName;
    private String lastName;

    public Person(int age, String firstName, String lastName) {
        this.age = age;
        this.firstName = firstName;
        this.lastName = lastName;
    }

    @Override
    public String toString() {
        return "Person{" +
                "age=" + age +
                ", firstName='" + firstName + '\'' +
                ", lastName='" + lastName + '\'' +
                '}';
    }

    @Override
    public int compareTo(Person person) {
        return this.firstName.compareTo(person.firstName);
    }

    public static void main(String[] args) {

        // people to sort
        List<Person> people = new ArrayList<>(List.of(
                new Person(20, "Hamza", "Belmellouki"),
                new Person(60, "Allan", "Truck"),
                new Person(40, "Zidan", "Kemero"),
                new Person(30, "Cindy", "Mahbd")
        ));
        people.forEach(System.out::println); //unsorted

        System.out.println("----------");

        Collections.sort(people);// sorted
        people.forEach(System.out::println);

    }
}

If you run the program the output will be:

Person{age=20, firstName=’Hamza’, lastName=’Belmellouki’}
Person{age=60, firstName=’Allan’, lastName=’Truck’}
Person{age=40, firstName=’Zidan’, lastName=’Kemero’}
Person{age=30, firstName=’Cindy’, lastName=’Mahbd’}
 — — — — — 
Person{age=60, firstName=’Allan’, lastName=’Truck’}
Person{age=30, firstName=’Cindy’, lastName=’Mahbd’}
Person{age=20, firstName=’Hamza’, lastName=’Belmellouki’}
Person{age=40, firstName=’Zidan’, lastName=’Kemero’}

As you can see the compareTo method implements the sorting strategy based on the lexicographic order. It calls the compareTo implementation that is defined in the String class which compares two strings lexicographically.

Our compareTo implementation returns the value 0 if the person.firstName is equal to this.fisrtName, a value less than 0 if this.firstName is lexicographically less than the person.firstName; and a value greater than 0 if this.fisrtName is lexicographically greater than the string argument.

Notice Collections.sort method accepts a list of Person, it sorts the list of Person based on the natural ordering.

If the Person class does not implement Comparable then a compile-time error occurs because the Collections.sort method defines its generic type parameter to extend the Comparable interface (you know generic type safety is here to rescue us from ClassCastException! That’s another subject, maybe for another blog).

3.2 Best practices when using Comparable:

These are some best practices when using a Comparable:

Sometimes you may see compareTo method that relies on the fact that the difference between two values is negative if the first is less than the second, zero if the values are equal, and positive if the first value is greater. For example, this code violates compareTo method contract(transitivity):

@Override
public int compareTo(Person p) {
    return this.age - p.age;
}

Don’t use this technique. It is filled with danger from integer overflow and IEEE 754 floating arithmetic artifacts.

Instead, Always either use the static Integer, Double, Float’s compare method. For example:

@Override
public int compareTo(Person p) {
    return Integer.compare(this.age, p.age);
}

4. Comparator Interface

4.1 Definition

If we want to define a total ordering on an object that has no natural ordering or if we want to override the natural ordering then we leverage the Comparator interface to do so. For example, if we want to override the natural ordering of Person objects and compare the Person object based on the age we’ll implement the Comparator interface like so:

import java.util.ArrayList;
import java.util.Comparator;
import java.util.List;

class Person implements Comparable<Person> {
    private int age;
    private String firstName;
    private String lastName;

    public Person(int age, String firstName, String lastName) {
        this.age = age;
        this.firstName = firstName;
        this.lastName = lastName;
    }

    @Override
    public String toString() {
        return "Person{" +
                "age=" + age +
                ", firstName='" + firstName + '\'' +
                ", lastName='" + lastName + '\'' +
                '}';
    }

    @Override
    public int compareTo(Person person) {
        return this.firstName.compareTo(person.firstName);
    }

    public static void main(String[] args) {

        // people to sort
        List<Person> people = new ArrayList<>(List.of(
                new Person(20, "Hamza", "Belmellouki"),
                new Person(60, "Allan", "Truck"),
                new Person(40, "Zidan", "Kemero"),
                new Person(30, "Cindy", "Mahbd")
        ));
        people.forEach(System.out::println); //unsorted

        System.out.println("----------");

        Comparator<Person> cmp = (o1, o2) -> Integer.compare(o1.age, o2.age);

        people.sort(cmp); // sorted

        people.forEach(System.out::println);
    }
}

If you run this code the output will be:

Person{age=20, firstName=’Hamza’, lastName=’Belmellouki’}
Person{age=60, firstName=’Allan’, lastName=’Truck’}
Person{age=40, firstName=’Zidan’, lastName=’Kemero’}
Person{age=30, firstName=’Cindy’, lastName=’Mahbd’}
 — — — — — 
Person{age=20, firstName=’Hamza’, lastName=’Belmellouki’}
Person{age=30, firstName=’Cindy’, lastName=’Mahbd’}
Person{age=40, firstName=’Zidan’, lastName=’Kemero’}
Person{age=60, firstName=’Allan’, lastName=’Truck’}

Note that the list is sorted by age. In line 43 you can see we have implemented the single abstract compare method on the Comparator interface using a lambda. Our implementation of the Comparator#compare method takes two person objects and returns a negative value if o1.age is less than the o2.age; 0 if they are equal; positive integer in the o1.age is greater than the o2.age.

In line 45 I’ve called List#sort method which sorts the list based on the Comparator implementation that we’ve passed to it.

4.2 Best practices when using Comparator:

These are some best practices when using a Comparator:

The practice from Comparable interface applies here: Don’t use the difference to compare objects, instead always rely on the static Integer, Double, Float’s compare method to compare numeric values:

Comparator<Person> comparator = (p1, p2) -> Integer.compare(p1.getAge(), p2.getAge());

Failing to do so could result in an integer overflow and IEEE 754 floating arithmetic artifacts.

The second best practice that is recommended is to avoid chaining if-else statements that result from additional comparison if objects were equal on the previous comparison(s). To illustrate, in this code snippet we implemented a Comparator that compares the person objects based first on their first name if they were equal then we move to the last name then to age:

public static void main(String[] args) {

        // people to sort
        List<Person> people = new ArrayList<>(List.of(
                new Person(20, "Hamza", "Belmellouki"),
                new Person(50, "Hamza", "Belmellouki"),
                new Person(44, "Hamza", "Belmellouki"),
                new Person(60, "Allan", "Truck"),
                new Person(40, "Zidan", "Kemero"),
                new Person(30, "Cindy", "Mahbd")
        ));
        people.forEach(System.out::println); //unsorted

        System.out.println("----------");

        // Don't do this!
        Comparator<Person> cmp = (p1, p2) -> {
          int result = p1.firstName.compareTo(p2.firstName);
            if (result == 0) {
                result = p1.lastName.compareTo(p2.lastName);
                if (result == 0) {
                    return Integer.compare(p1.age, p2.age);
                } else {
                    return result;
                }
            } else {
                return result;
            }
        };

        people.sort(cmp); // sorted

        people.forEach(System.out::println);

    }
}

Output:

Person{age=20, firstName='Hamza', lastName='Belmellouki'}
Person{age=50, firstName='Hamza', lastName='Belmellouki'}
Person{age=44, firstName='Hamza', lastName='Belmellouki'}
Person{age=60, firstName='Allan', lastName='Truck'}
Person{age=40, firstName='Zidan', lastName='Kemero'}
Person{age=30, firstName='Cindy', lastName='Mahbd'}
----------
Person{age=60, firstName='Allan', lastName='Truck'}
Person{age=30, firstName='Cindy', lastName='Mahbd'}
Person{age=20, firstName='Hamza', lastName='Belmellouki'}
Person{age=44, firstName='Hamza', lastName='Belmellouki'}
Person{age=50, firstName='Hamza', lastName='Belmellouki'}
Person{age=40, firstName='Zidan', lastName='Kemero'}

You don’t have to use this old pattern when you want to do such a comparison because it is hard to read, error-prone code and lacks robustness. Instead, you would use Java 8 Comparator’s comparing and thenComparingXXX methods:

public static void main(String[] args) {

        // people to sort
        List<Person> people = new ArrayList<>(List.of(
                new Person(20, "Hamza", "Belmellouki"),
                new Person(50, "Hamza", "Belmellouki"),
                new Person(44, "Hamza", "Belmellouki"),
                new Person(60, "Allan", "Truck"),
                new Person(40, "Zidan", "Kemero"),
                new Person(30, "Cindy", "Mahbd")
        ));
        people.forEach(System.out::println); //unsorted

        System.out.println("----------");

        Comparator<Person> cmp = Comparator.comparing(Person::getFirstName)
                .thenComparing(Person::getLastName)
                .thenComparingInt(Person::getAge);

        people.sort(cmp); // sorted

        people.forEach(System.out::println);

}

This code does that same thing but it is much more readable and less error-prone. Here on line 16, the static Comparator’s comparing method takes a key extractor which is a Function object implementation used to extract the Comparable sort key.

Notice on line 18 I used thenComparingInt instead of thenComparing because the former takes a ToIntFunction object, thus there will be no boxing involved because its abstract method returns an int primitive, not a boxed int.

5. Comparable vs. Comparator

You'll want to use the Comparable interface when we want a default order. When using a Comparable interface we don’t need to make any code changes at the client-side. For example, Collections#sort method automatically uses the compareTo() method of the class. For Comparator, the client needs to provide the Comparator class to use in compare() method.

Both of these interfaces are part of the Java Collection framework.

There are several reasons to use a Comparator even if we already have a Comparable implemented:

Specify different comparison strategies which aren’t possible when using Comparable
To avoid changing/adding code to our custom classes
Often, it is impossible to modify the source code of the class whose objects we want to sort, thus it is impossible to use Comparable in such circumstances.

7. Conclusion

In this article, we saw how to use Comparable to implement the natural ordering and how to override it using a Comparator. We saw well-known best practices to use when implementing them. In the next article, there will be more Core Java. Stay tuned!

Let us know what you think in the comments below and don’t forget to share!

Apache Maven: Working With Build Profiles

Hamza Belmellouki — Sat, 12 Sep 2020 14:04:18 +0000

In this article, we’re going to take a peek at Maven Build Profiles. Build profiles are often underestimated yet they have a lot of capabilities, and we are going to explore some of its capabilities. How we can use it? how we can leverage build profiles to make our build flexible?

2. Overview of Maven Build Profiles

The power of a profile comes from its ability to modify the basic POM only under certain circumstances. A profile is an alternative set of values that set or override default values.

2.1 Why Use Profiles?

Profiles allow you to customize a particular build for a particular environment (development, testing, and production).
Profiles facilitate portability between different build environments.
It may also be used in a situation where you need a different build based on the OS, JDK.
To activate specific plugins
To provide alternative build-time configuration values

2.2 Declaring Profiles

You can declare build profiles in one of the following ways:

In pom.xml (Use this when you want your build to be portable between different computers)
Declared In <user-home>/.m2/settings.xml (use this when you want the profile to be available to many projects)

3. Simple Example

This example demonstrates how to declare and leverage profiles in your pom.xml file. You declare a profile inside <profile> element like so:

<profiles>

        <profile>
            <id>prod</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-surefire-plugin</artifactId>
                        <version>2.22.2</version>
                        <configuration>
                            <skipTests>true</skipTests>
                        </configuration>
                    </plugin>
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-compiler-plugin</artifactId>
                        <version>3.8.1</version>
                        <configuration>
                            <debug>false</debug>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        </profile>

        <profile>
            <id>itTest</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-failsafe-plugin</artifactId>
                        <version>2.22.2</version>
                        <executions>
                            <execution>
                                <goals>
                                    <goal>integration-test</goal>
                                    <goal>verify</goal>
                                </goals>
                                <configuration>
                                    <includes>
                                        <include>**/*IT.java</include>
                                    </includes>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
        </profile>

    </profiles>

This block of code declares 2 profiles: prod(production) and itTest(integration testing) and declares and configures plugins for production and integration testing (of course this is just a simple example to demo profiles. Don’t take it as a robust configuration). Now each profile must have an <id> element. By default, prod profile is not active and itTest profile is active.

To view active profiles run this command:

mvn help:active-profiles

You can activate them by using one of the following ways (there is a lot of options):

Using a command-line argument
In settings.xml in <activeProfiles> element
Using <activeByDefault> element inside the <profile> element
Activation based on JDK versions, OS
Present or missing files
Environment variable

3.1 Command-Line

You activate profiles by using the command-line -P option, for example, here I am running default lifecycle until package phase with prod as the active profile.

If you run this command you’ll notice that the tests did not run because we’re skipping them in this build, also we’ve set <debug> element to ‘true’ in the compiler plugin to not include debugging information in the compiled class files:

mvn package -P prod

You can deactivate profiles by using an exclamation mark(!) or a dash(-), for example here I am deactivating itTest profile (Remember itTest is set up active by default):

mvn verify -P -itTest

This command deactivates itTest profile, thus it will not run integration tests.

3.2 settings.xml

You can activate profiles in settings.xml (located under /Users/<user-home>/.m2) by using <activeProfiles\> element. For example, here I am activating prod profile. By activating that profile unit tests will be skipped and there will be no debugging information in the bytecode:

<activeProfiles>
    <activeProfile>prod</activeProfile>
</activeProfiles>

3.3 <activeByDefault> element

Another useful trick to activate profiles is to use <activeByDefault\> element right in the pom.xml. We’ve already used that in itTest profile to activate it by default:

<activation>
    <activeByDefault>true</activeByDefault>
</activation>

3.5 OS settings

Use <os> element if you want the profile build to be activated based on the OS. I’ve never used this feature before, but I think it would be good to know it. This windows profile will trigger when the system is windows XP:

<profile>
    <id>windows</id>
    <activation>
        <os>
            <name>Windows XP</name>
            <family>Windows</family>
            <arch>x86</arch>
            <version>5.1.2600</version>
        </os>
    </activation>
</profile>

3.6 Files

Use <file> element if you want to activate a profile based on the absence or presence of a file. For example, this profile will be active if data.sql exists If not the profile will not activate:

<profile>
    <id>file-present</id>
    <activation>
        <file>
            <exists>target/resources/data.sql</exists>
        </file>
    </activation>
</profile>

3.7 Environment Variable

Use <property> element if you want the profile build to be activated based on environment variables. For example:

<profile>
    <id>test</id>
    <activation>
        <property>
            <name>env.FOO</name>
            <value>test</value>
        </property>
    </activation>
</profile>

The test profile will trigger when the system property “FOO” is specified with the value “test”. Create an environment variable “FOO” and set its value as “test” if you want to trigger the profile.

4. Conclusion

This article was a quick overview of Maven profiles, we talked about why to use them, how to declare them, and how to activate them. In the next article, we’ll step back from Maven and talk about Core Java. Stay tuned!

Let us know what you think in the comments below and don’t forget to share!