DEV Community: pazvanti

Phoenix - a modern template engine for Spring

pazvanti — Mon, 08 Jan 2024 13:29:03 +0000

After several months of work, it's time for me to present my most ambitious open-source project. It's not finalized yet; there are still bugs and features that need to be added, but it's stable enough for you to "play" with and give your feedback.

What is Phoenix?

Phoenix is a modern template engine for Spring and Spring Boot aiming to facilitate the development of complex web applications by providing a way to create complex and modular templates benefiting from server-side rendering for better integration between the frontend and backend.

Phoenix vs Thymeleaf or Freemarker

Phoenix offers several advantages compared to other existing template engines at the moment:

The ability to integrate Java code directly into HTML templates without needing to learn a new syntax or special utilities.
An easier-to-understand syntax that only requires a special character "@" to integrate Java code into HTML code.
Fragments or components that can be combined and reused, making the code easier to maintain.
Speed, speed, speed - Phoenix templates are compiled, offering rendering speeds up to 10x faster compared to Thymeleaf.
A single PhoenixController that easily allows the return of both HTML pages and JSON responses.
Reverse routing - a completely new feature for Spring. URLs are written at runtime in templates, eliminating the need for manual writing. You only mention the controller and method, and Phoenix calculates the correct URL. This way, you can change the URL in the controller without having to modify the template.
Pages dynamically modified by calling from JS to the backend to obtain a ready-to-add fragment/module to the DOM.
Easy to configure* (Work in Progress to reduce necessary dependencies).

Why Phoenix and not React/Angular/Vue?

Phoenix is not intended to be a replacement for JS frameworks. Instead, Phoenix aims to utilize existing JS frameworks to add SSR, thereby enhancing page rendering speed and FE-BE integration. You no longer need to always return complex JSON; you can directly provide an HTML page with everything needed and nothing more. There can be a whole debate about SSR vs non-SSR, so Phoenix tries to combine the advantages of both.

Open Source

Phoenix is open source, and everyone is encouraged to download the code, contribute improvements, or suggest features.

Source code: https://gitlab.com/ppopescu/phoenix-template-engine

Wiki: https://gitlab.com/ppopescu/phoenix-template-engine/-/wikis/home

Build jar: https://gitlab.com/ppopescu/phoenix-template-engine/-/jobs/5879024082/artifacts/download?file_type=archive

My blog: https://petrepopescu.tech

An argument for using Optional as input parameters

pazvanti — Thu, 22 Dec 2022 17:51:49 +0000

This article may be the hardest I wrote so far here. Not because it is really technical nor because it required a lot of research prior, but because it is controversial and I had to be sure that the arguments I will present here are good. Still, I know that some will not agree with me. So let’s get down to business.

Article originally posted on my personal website under Should we use Optional as input parameters in Java?

There is an ongoing debate in the Java community regarding Optional and if it should be used as input parameters for methods or only as return values. Most people, including big names from the Java ecosystem, advocate for using Optional only as output. Even Sonar has a rule that grants a “Major” severity for Optional as parameter. So, to say that my statement here is controversial may be an understatement.

And in most cases, I agree. The presence of an Optional parameter usually can be attributed to a lack of knowledge or to a faulty design. However, I am not as strict nor one-sided. Things are not black and white only. That is why I think that there are a limited number of scenarios where not only having an Optional input parameter is ok, but recommended.

Our scenario

Let’s assume that you have a Datasource class that holds a list of Students. How this list is obtained is not important right now. This Student class has multiple fields, as shown in the code below.

public class Student {
    private String firstName;
    private String lastName;
    private String middleName;
    private int yearOfBirth;
    private int studyYear;
}

It is a simple data class, nothing too fancy. For simplicity, I did not write any getters or setters, but they are there. Now, we will need to have a way to retrieve these students, so our Datasource class has a method ‘getStudentsFitleredBy()’. However, we don’t need ALL the students, only a subset: the ones that match certain criteria.

We can filter them by firstName, by lastName, by studyYear or ANY combination of these three. So, we will need to pass the needed parameters in our getStudents() method.

This is where I believe that having these parameters as Optional (in the way shown below) adds value. Let’s look at the code that returns the filtered list of students.

public List<Student> getStudentsFitleredBy(Optional<String> firstName, Optional<String> lastName, Optional<Integer> studyYear) {
    Stream<Student> studentsStream = this.students.stream();
    if (firstName.isPresent()) {
        studentsStream = studentsStream.filter(student -> student.getFirstName().equals(firstName.get()));
    }
    if (lastName.isPresent()) {
        studentsStream = studentsStream.filter(student -> student.getLastName().equals(lastName.get()));
    }
    if (studyYear.isPresent()) {
        studentsStream = studentsStream.filter(student -> student.getStudyYear() == studyYear.get().intValue());
    }

    return studentsStream.collect(Collectors.toList());
}

The advantage that Optional introduces in this case is three-fold. First of all, you don’t have to write overloaded methods for each combination of desired filtering parameters. Second, if you don’t want filtering by one of the parameters, just send Optional.empty(). Third, and the most important one, you can clearly see from the method’s signature that any of the parameters can be omitted and the method will still work as intended.

Optional was introduced so that you can clearly see that “this method may or may not return something”. The same logic is here, it is just that we say “this method will returne students filtered by any of the optional parameters”. And I know what you are thinking now. Why not use them without an optional and do null check instead of isPresent()? And yes, this is a valid question and writing the method in that way will work. However, you will be losing clarity. As an outsider or a different developer than the one that actually implemented the method, you won’t know if all parameters are required without looking over the documentation or the code.

As for doing null checks for the Optional inside the method, I don’t think that they are needed here. If someone sends null, he is clearly using the API wrong.

If right now you are thinking that nobody writes methods like this to filter lists, you are wrong. But even so, let’s change things a bit. Instead of having a list that is being filtered, consider that this datasource class is a DAO that uses CriteriaBuilder to construct a JPA query that retrieves the information from the database. Things don’t looks as silly now, do they?

Others that may agree with me

I could not find any example of Optional being used as input parameter in the standard Java library. Maybe there is somewhere, but for now it remains hidden to me. But I can provide one example from a well-known framework that uses it: Spring.

For Spring controllers, if you have request parameters (the ones that come after ? in the URL), you can specify them in the controller’s method handler as Optional. This way, the honest that are received in the URL will be mapped, while the others will be Optional.empty()

@GetMapping("/students")
public List<Student> getStudents(@RequestParam Optional<String> firstName,
                                 @RequestParam Optional<String> lastName,
                                 @RequestParam Optional<Integer> studyYear) {
    ...
}

You can have a request like this: /students?firstName=Petre&studyYear=2

For that request, the lastName parameter will be mapped to Optional.empty()

LogMasker - OpenSource masking library for Java

pazvanti — Mon, 07 Mar 2022 19:55:17 +0000

I am happy to share with you my first open-source project: LogMasker

LogMasker is a log masking library that makes it easy to mask confidential information directly in the logs. This is done by intercepting the log event and masking it even before it has a chance to be written. It is easy to integrate, works with both Log4j2 and Logback and is highly efficient. The log masking library can be easily added to your existing project and is highly configurable.

Check out the project at LogMasker - Log Masking library

What sensitive data can be masked

Currently, LogMasker can mask the following sensitive information:

[x] Email addresses
[x] IPv4 addresses
[x] IBANs
[x] Card numbers (PANs)
[x] Passwords (if marked accordingly)

The maskers that are being used are easily configurable and the library allows you to write your own masker and include it in the masking process. By default, all maskers from above are used.

Performance

Each masker ads an additional layer of processing, so it is recommended that you only use the maskers that are needed for your business needs, especially if you have high throughput and write a lot of logs. There are performance tests for each masker as well as for integration directly with Log4j. Results on my machine are as follows:

Masker	Number of lines masked	Average time in ms (for all lines)
Email masker	100000	30ms
Password masker	100000	163ms
IP masker	100000	33ms
Card number masker	100000	127ms
IBAN masker (all countries)	100000	450ms
Masking Converter (all maskers)	100000	713ms
Masking Converter Exclusive (all masker)	100000	356ms
Log4j Integrated	1000 (one log event)	390ms

Integration with Log4j

The library can be easily added and integrated with Log4J 2. Once imported into your project, it will provide a custom message converter (LogEventPatternConverter) which when used will mask all incoming data. To do this, replace the %m inside your message pattern with %msk or %mask.

Integration with Logback

The library can be easily added and integrated with Logback. Once imported into your project, it will provide a custom message converter (MessageConverter) which can be used for all messages. To do this, include the following line in your configuration file:

<conversionRule conversionWord="mask" converterClass="com.ppopescu.logging.LogbackMaskingConverter" />

Download

You can view the source code and download the jar files from the projects repository over at LogMasker - Log Masking library

The library is under Apache 2.0 license, so you can use it with commercial projects as well.

Crawling and Parsing a Website in Java using JSoup

pazvanti — Tue, 12 Oct 2021 07:17:07 +0000

There are many scenarios where you would need to parse the contents of a website to extract data. Search engines do this, certain applications require this functionality in order to extract information, there are integration tests that need this and even some tools must have this functionality. In this article, I will be showing how to build a website crawler in Java and how to parse the website’s content and extract information from it.

Article originally posted on my personal website under How to parse a website in Java

Building the entire parser is quite complicated, but luckily, there already exists a library that does the complicated parts for us: JSoup. It provides all the needed tools and APIs for parsing and extracting website data. It is quite easy to use and learn as well, making it ideal for most such applications.

Establishing a connection using JSoup

For the examples, I will be using my own website. So, let’s get started. First, we must establish a connection to the website and retrieve the HTML document. This is how we connect to a site and parse the DOM using JSoup.

Connection connection = Jsoup.connect("https://petrepopescu.tech");
Document document = connection.execute().parse();

We could use a simplified version, with only Jsoup.connect(“https://petrepopescu.tech”).get(), but I chose the more elaborate version to show the steps that the library does. Furthermore, we can easily use additional features, like setting the user agent (Jsoup.connect(url).userAgent(agent)) or a proxy (connection.proxy(host, port)), features that come really handy when doing a complete site parse because it minimizes the chances of your app being blocked by their firewall.

Parsing website elements

Now that we successfully established a connection and JSoup has parsed the page, let us try to identify elements in the page and get their content. For the first example, I will be retrieving the categories and the link to the specific pages. Using the browser inspector, we can see that the categories are as items in a list that are inside the div with the category-3 ID.

The same approach can be done for almost any website and element on the page to discover the needed criteria for identification.

If possible, always use IDs since they are unique in a page, or at least should be unique. If this is not enough, you can do selection by class, type, and simple navigation in the structure of the page so that you get the exact element that you want. This is exactly what we are going to do now in order to discover all the category links and the category names.

First, we will find the element with the id categories-3, and next, we will search for the list items by searching for the elements with the li tag. from those elements, we exact the href attribute and the text. Finally, we print the items.

Element categoriesMenu = document.getElementById("categories-3");
List<Element> categories = categoriesMenu.getElementsByTag("li");

Map<String, String> categoriesLinks = new HashMap<>();
for (Element category:categories) {
    Element link = category.getElementsByTag("a").get(0);
    String url = link.attr("href");
    String categoryName = link.text();

    categoriesLinks.put(categoryName, url);
}

for (Map.Entry<String, String> category:categoriesLinks.entrySet()) {
    System.out.println(category.getKey() + " - " + category.getValue());
}

Using selector in JSoup to retrieve an element

Sometimes it is not that easy to get the exact element you want. It does not have an ID, or multiple elements share the same ID or maybe the ID is dynamic. For example, the articles present on the front page each have a unique ID that is generated for each individual article like this: “post-”. What if you want to get the excerpt for each one? This is where the select method from JSoup comes into play. You can write a complex selector that will help with the identification and retrieval of the exact element you want.

For example, this is one way to retrieve the excerpts from the front page.

Elements contentElements = document.select("article");
Map<String, String> articles = new HashMap<>();
for (Element element:contentElements) {
    Elements postTextElements = element.getElementsByClass("entry excerpt entry-summary");
    if (postTextElements.size() == 1) {
        articles.put(element.attr("id"), postTextElements.get(0).text());
    }
}

for (Map.Entry<String, String> article:articles.entrySet()) {
    System.out.println(article.getKey() + " - " + article.getValue());
}

If we want to be even more specific, we can get all elements of type article with the id as described above using a more complex selector. Since this one takes a bit longer because of the regex, we can optimize it a bit by only searching inside the div with the actual content, and not on the entire page. To do this, we simple replace the first line with this one: Elements contentElements = document.getElementById(“grid-wrapper”).select(“article[id~=post-*]”);

There are even more selectors available in JSoup that should satisfy all your needs. You can read about them at JSoup’s official website. Just be careful when you use them since some are faster than others. Make sure you always try to optimize the search by going as down in the structure as you can and not by searching the entire page.

Conclusions

As we see, JSoup offers all the needed tools to successfully parse a web page and retrieve the data and information from it. With a bit of work and a bit of knowledge, you should be able to extract information from most websites, validate your web page structure in integration tests, or make an awesome tool that tracks the price of an item.

And, as always, you can download the full source code from my website

Article originally posted on my personal website under How to parse a website in Java

5 simple coding tricks to make your application more stable

pazvanti — Fri, 10 Sep 2021 06:18:38 +0000

Article originally posted on my personal website under 5 coding tricks to make your application more stable

The stability of your application or web service is important for both you and the user. Making things resilient is not easy, but there are a few coding tricks that you can use in order to increase stability and help you solve problems easier and faster. Here are 5 simple coding tricks that will make your application more stable, will reduce errors and will make you a better coder.

Comparing with a static String

In many applications you will need at some point to compare a string you hold in your variable to a pre-defined value. This is a common scenario and it is really easy to get it wrong, especially for beginners, and it can generate errors that, if not handled properly, can crash your application. How can you get such a simple thing wrong? Let’s look at the following example:

public void doSomething(String parameter) {
    if (parameter.equals("new")) {
        // do something only in this case
    }
    // do some more stuff
}

Looks correct, right? Well, this approach hides a NullPointerException that can happen quite often. If, for some reason, the “parameter” is uninitialized and remains null, this will trigger a NPE. The fix is quite easy.

First, let’s extract the value we want to check against. Next, when doing our comparison, instead of using the parameter first, we use our extracted value, since we know that this one is ALWAYS initialized. The new, and much better, code looks like this:

private static final String NEW_PARAMETER = "new";

public void doSomething(String parameter) {
    if (NEW_PARAMETER.equals(parameter)) {
        // do something only in this case
    }
    // do some more stuff
}

Use Optional when null can be returned

One of the features that was introduced in Java 8 was the Optional class. Even though it may not seem as much, this wrapper class can be extremely useful in making the code easier to understand, but also in code stability. This is because Optional can represent two distinct reasons.

When as part of a method you have an Optional parameter, it indicates that that method can properly work even if you don’t know or don’t have a value for that parameter. You can just use Optional.empty() and the method will, at least in theory, work well by assigning a default value or ignoring that parameter.

However, if a method returns an Optional it indicates that the method can’t return an answer in some scenarios. Prior to Java 8 this was done by returning a null which can lead to NullPointerExceptions. With optional, it is clearly indicated that an answer is not always provided. Furthermore, it tells anyone that is using that API/method, that the result should be checked with isPresent() and only in this case you should use the result.

Yes, bad programmers can still just call .get() without the check, but this should be easily discovered during code review or by static analysis tools. It does not completely solve the problem, but it should at least make anyone think twice when an optional is returned. The simple fact that you need an extra call to get the value helps with accidentally having null exceptions.

Avoid Exception Swallowing

This is a problem I encountered many times, especially in legacy systems. It is something easy to overlook and, even though it does not cause any problems with the actual processing flow, it makes things extremely difficult to investigate and fix. For those that don’t know, exception swallowing is the act of hiding the occurrence of an exception by not logging it. It is best explained using the example below:

public boolean processData() {
    try {
        ...
        myService.process(); // this will thrown an exception sometime
        ...
    } catch(Exception e) {
        return false;
    }
    return true;
}

In this example, the service can thrown an exception. When this happens, we catch it, so no problem with the processing flow, but we don’t log anything. For someone that is later investigating to see why the processing did not happen, he won’t have any information available. This is even worse if the same result (in this case false) can be returned in the try{} block.

Some try to fix this by just logging an error message, as in the example on the right. This, however, does not really make things better. Yes, you know that there was an error processing the data, but not much else. What did actually happen? what caused the error? How can I reproduce it? Below is how to properly fix this and avoid exception swallowing. That is why all logger methods have a Throwable as a parameter. That way you actually have the stack trace printed in the logs and can know where the problem happened and with a bit of luck, the exact cause.

public boolean processData() {
    try {
        ...
        myService.process(); 
        ...
    } catch(Exception e) {
        LOGGER.error("Error processing data");
        return false;
    }
    return true;
}

public boolean processData() {
    try {
        ...
        myService.process(); // this will thrown an exception sometime
        ...
    } catch(Exception e) {
        LOGGER.error("Error processing data", e);
        return false;
    }
    return true;
}

Have a final catch-all statement

Sometime it may be really hard to see in advance all error and exceptions that can occur. Maybe the API has changed in a library you are using after an update to a newer version, or maybe another team member was lazy and forgot to add a catch somewhere. That is why it is important to have a catch statement that encapsulates all your app or service.

There, you can log the exception that occurred and return a proper response to the client. All major frameworks have a feature where you can define what happens in case of an exception, so make sure you use it. For Play, I wrote a tutorial on how to handle exceptions not too long ago that you can read. If your application is called by a client, you will have the possibility to respond properly and not keep them waiting. If it is an application, it at least won’t crash suddenly and can continue to process requests.

Nevertheless, try to have a catch-all statement where everything that went bad is properly logged and the program finishes in a graceful way.

Don’t reinvent the wheel

Regardless of the programming language that you are using, there is a big chance that you will find libraries for many common tasks and features that you have to build. When possible, use them. Don’t try to reinvent the wheel and write everything yourself. In most cases, the code present in such libraries are more robust, handle errors well and have more functionality than you initially think you need.

Make sure that the library is well maintained and, if you are building a commercial project, check the license. Need to parse JSON text? There is a library for it. Want to test your code? There are frameworks for this as well. As a developer, you do not have to write everything from scratch, but know what resources to use and when in order to build your vision and software.

Article originally posted on my personal website under 5 coding tricks to make your application more stable

Writing unit tests in Java using jUnit and Mockito

pazvanti — Wed, 11 Aug 2021 06:36:35 +0000

Article originally posted on my personal website under Using jUnit and Mockito for unit testing in Java

Testing is important for all software systems and applications. It will help you easily find bugs and it will prevent crashes and downtimes for your application, especially if the system evolves over time. At first it may not seem critical, but as the system grows and becomes more complex, the likelihood of a bug appearing without being noticed grows.

There are multiple testing frameworks available for Java, with jUnit being one of the most widely used. In this article, we will be looking over a few simple APIs that jUnit offers and how to use them for unit testing. In most cases, jUnit won’t be enough and the combo jUnit + Mockito is often found.

For those that don’t know, Mockito is another framework used for testing where you mock certain classes so that you can easily isolate the class you want to test and to control the output of other classes or components that are being used by the class. It also offers the possibility to check if the mock was called, how many times and more other useful features.

Validating the result in jUnit

The simples and most widely used feature in unit testing is checking that the result received is the one expected. This is a basic functionality that you will be using often when writing tests because it is mandatory to check that your method actually returns the correct answer. This is achieved using the


 methods.



```java
@Test
public void aSimpleTest() {
    int aNumber = 5;
    String str = "A test string";
    double aDouble = 4.67;

    Assert.assertEquals(5, aNumber);
    Assert.assertEquals("A test string", str);
    Assert.assertEquals(4.67004, aDouble, 0.001);
}

A note for the assertion of the double variable. Even though the numbers are not truly equal, the test still passes. This is because the last parameter in the method represents the accuracy. This is the deviation that we allow in the result and still consider it valid. If you want better accuracy, just make the delta smaller.

Custom error message for a test

Sometimes it is important to show a custom message in case the test fails. This feature saves a lot of time during automatic builds where access to the full stack trace is hard to get. Using a custom message you can easily print what was wrong, what variable was not correct or any information that will help you (or another engineer) understand what happened. This is done by using the overloaded methods from Assert that have the message parameter first, as seen below.

@Test
public void aSimpleTestWithMessage() {
    String myStr = "This test will fail";
    Assert.assertEquals("The myStr variable is not the expected value", "Nothing", myStr);
}

Validating results with complex objects in jUnit

In most cases, you will have complex objects that have multiple fields. It is as easy to check them as for simple ones. jUnit uses the equals() method to check that the result you received is identical to the expected one. That is why, in this case, it is important to have a properly written equals() method for your object. Let us look at this data class:

public class DataClass {
    private String field1;
    private String field2;
    private int field3;

    public DataClass(String field1, String field2, int field3) {
        this.field1 = field1;
        this.field2 = field2;
        this.field3 = field3;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        DataClass dataClass = (DataClass) o;
        return Objects.equals(field1, dataClass.field1)
                && Objects.equals(field2, dataClass.field2)
                && Objects.equals(field3, dataClass.field3);
    }
}

Now, we can write a test and because the equals() method is properly written, the test will pass even if there are two different objects:

@Test
public void testComplexObject() {
    DataClass obj1 = new DataClass("f1Value", "f2Value", 3);
    DataClass expected = new DataClass("f1Value", "f2Value", 3);

    Assert.assertEquals(expected, obj1);
}

All is fun, however, in certain scenarios you want to make sure that the EXACT same object is returned. This is achieved using the Assert.same() method. It works exactly like Assert.assertEquals(), however, it does not check the equally of the contents, but the actual object reference. Using it, the test will pass if and only if the expected and the result are the same.

Validating an exception is thrown in jUnit

Another useful feature is validating that the method does indeed throw a proper exception when invalid input is received. There are multiple ways of doing this, but the easies is to provide the expected parameter to the @test annotation. This will tell jUnit that the test will throw the provided exception if it is correct.

@Test(expected = NumberFormatException.class)
public void testNumberParse() {
    Integer.parseInt("a");
}

How to mock your response using Mockito

Complex systems have multiple components and classes that interact with one-another. For such systems, it is hard to test everything at once, either because you don’t know how each and every component works, or because it will take too long to properly set up everything and run the tests. That is why the concept of mocks has been introduced. A mock is an object that replicates the API of your class, but does not do any processing. Instead, it simply returns what you tell it to.

This is useful for unit testing because it will allow you to focus on just one class (the one you actually want to test) while ignoring the inner workings of the other objects that are used by your class. As an example, let’s assume that you want to test a service and validate that the aggregation is done correct. The service uses one or multiple DAOs to retrieve the raw data from the database. You don’t want to have data written in the DB, nor you want slower tests by having to hit the DB every time.

What you do in this case is mock the DAOs and tell the mock what to return for each test. This is easily done using Mockito.

private static MyDao mockDao;

@BeforeClass
public static void setup() {
    // Initialize the mock of the type MyDao
    mockDao = Mockito.mock(MyDao.class);
}

Now, you can write your test by setting the mocked DAO object to your service (via a setter, or using a dependency-injection mechanism) and specifying what the DAO should return when it is called. Here are our original objects. We will want to test that the service works, even though the DAO is not yet written.

public class MyService {
    private MyDao dao;

    public void setDao(MyDao dao) {
        this.dao = dao;
    }

    public boolean process(String id) {
        if (id == null) return false;

        List<DataClass> all = dao.getAll();
        if (all == null || all.isEmpty()) return false;

        DataClass ofInterest = dao.get(id);
        if (ofInterest == null) return false;

        // do some processing
        return true;
    }
}

public class MyDao {
    public List<DataClass> getAll() {
        return Collections.emptyList();
    }

    public DataClass get(String id) {
        return null;
    }

    public void save() {
        // do nothing
    }
}

We will set the mock DAO as the object for our service and tell it to return proper data when called. This way we speed up development as well as test execution.

@Test
public void testService() {
    MyService service = new MyService();
    service.setDao(mockDao);

    Mockito.when(mockDao.getAll()).thenReturn(Arrays.asList(new DataClass("a", "b", 3)));
    Mockito.when(mockDao.get(Mockito.eq("a"))).thenReturn(new DataClass("a", "b", 4));

    boolean result = service.process("a");
    Assert.assertEquals(true, result);
}

The Mockito.when() method tells the mock what to return when it is being called. Also, you can specify the parameter to expect for the methods that have parameters using the provided helper methods: Mockito.eq, Mockito.any, Mockito.matches, Mockito.same, etc.

Preparing and cleaning up test data

With complex systems, some tests become more complicated and require interaction with other systems or parts of the code to make them work properly. Either some test data needs to be written, some features or functionalities need to be turned on or simply some environment variables must be set. You can do this for each test in a suite or, you can use the Before and After features of jUnit to make sure everything is properly initialized and cleaned up.

jUnit has 4 important annotations that help with this: @Before and @BeforeClass alongside @After and @AfterClass.

The methods that are annotated with @Before are executed before each test in a class. If in a test class you have multiple methods annotated with @test, the @Before will be executed right before each test method is run. Similarly, the @After is executed after each test in a suit.

The other two annotations, @BeforeClass and @AfterClass will be executed only once, exactly before any test is run and right after all tests are finished, regardless of the test results. These methods are very useful for preparing your environment and writing any test data as well as doing the necessary cleanup in order to ensure that the environment is in a clean state with no dangling data.

Conclusions

As can be seen, Java with the help of jUnit and Mockito provides all the needed features and functionalities needed for writing unit tests for your code. Even though it may seem as an inconvenience, having well-written tests will help you identify bugs quicker as well as maintain a robust and stable software system.

As always, you can download the full sample codes on my personal website.

Article originally posted on my personal website under Using jUnit and Mockito for unit testing in Java

Cleaner Data classes with Project Lombok

pazvanti — Thu, 22 Jul 2021 08:37:30 +0000

Article originally posted on my personal website under How to use Lombok in your Java projects

One thing that I like about Java is the vast amount of libraries that are freely available. There is a library or code snippet for almost anything that you could think of or any mundane or repetitive task out there. Data classes are no exception. All applications rely on data and the presence of data classes is widespread, however, they are usually quite simple, but can take up a lot of time, especially if you have many fields. Luckily, there is Project Lombok, which makes things easier to maintain, read and code.

What is Project Lombok

Lombok is a library that will automatically generate getters, setters, constructors, and many more for your data classes. You only need to import the library and use the annotations to achieve the desired effect. The code is added at build-time, so your classes remain small and are easier to read.

It may not seem as much, but for data classes that have many fields, it can save a lot of coding and maintenance time. Furthermore, it can do more, like generating a toString method that includes the values of all the fields, null checks and a builder for your class. These are extremely useful if your data classes evolve over time because the needed functionality is there just by adding or removing the variable of interest.

A quick example in Lombok

Let us look at a quick example that demonstrates the power of Project Lombok. We will be creating a “Student” class that has a few fields: surname, given name, the city where he was born, and a few grades. We will need to have a builder for the student, but also a more traditional way of instantiating it by calling the constructor. Also, since this is a data class, we will need getters and setters for all the fields.

Regardless of the number of fields, Lombok makes this really easy. We just create our class, define the fields and add the needed Annotations.

@Data // generates the getters and setter
@NoArgsConstructor // generates the constructor without any arguments
@AllArgsConstructor // generates the constructor that has all the fields as arguments
@Builder // generates a builder for the class
@ToString // generates a toString() method that has the values of all the fields
public class Student {
    private String surname;
    private String givenName;
    private String city;
    private Double mathGrade;
    private Double computerScienceGrade;
    private List<Double> labGrades;
}

If after that we want to add a new field or remove an existing one, we don’t need to change the builder or the toString method in any way. Everything is done by Lombok. Furthermore, the toString that is being generated makes things really convenient from a logging point of view. It automatically includes all the defined fields and can even print complex fields, like the List of lab grades. Here is an example and the log output below:

public static void main(String[] argv) {
    Student student = Student.builder()
            .surname("Popescu")
            .givenName("Petre")
            .city("Paris")
            .mathGrade(8.25)
            .labGrades(Arrays.asList(9.0, 8.7, 9.4))
            .build();

    LOGGER.info(student);
}

There are more features available and you can read all about them on Project’s Lombok website.

Using Lombok in IntelliJ

Since the code for the additional features is generated during build time, your IDE will probably not recognize the getters, setter and features that are added by the annotations. At least, not out of the box. However, it is fairly easy to fix this. If IntelliJ does not recognize Lombok’s features, you will have to download the Lombok plugin from the IntelliJ market. It is completely free.

After that, you will have to enable Annotation processing. This will tell IntelliJ to pre-process annotations so that the features that they add are available for the IDE and it can offer auto-complete and code analysis for it. To do this, go to Settings -> Build, Execution, Deployment -> Annotation Processor (or simply search for Annotation in the top search box) and enable it

That’s it. You can now use Project Lombok in your code and the IDE will properly recognize its features.

Article originally posted on my personal website under How to use Lombok in your Java projects

[Discussion] Use a template engine with backend integration instead of a fully-JS UI framework like react or angular?

pazvanti — Sat, 12 Jun 2021 05:09:39 +0000

Let me start by saying that I am a back-end developer. I do have some experience with front-end technologies, but I can't say that I am capable of a full-stack dev session. With that being said, let me rant a bit.

I find all the JS UI frameworks confusing. There are so many of them, each has its own syntax and structure, many components, and doesn't use "traditional" JS/TS, but many placeholders that get "replaced" later on. I reached this conclusion recently when I started a new project (with a new company) and the UI part was done purely in Angular and the UI communicated with the BE using REST calls. The project had less than a month since it started, so I wasn't quite from the start so I could not impose my view :D

This brings me to my next rant. The UI does soo many calls to the backend all the time. The project has a complex data structure so there are many back-and-forth messages from UI to BE to get certain data elements, save them, updated them, and so on. At one point, for one screen, I counted almost 60 calls from the UI just to populate the needed data.

There HAS to be a better way!

Let the backend do the job
I've been using template engines for as long as I can remember. It offers so many advantages (at least for me) and I honestly can't see a reason why NOT to use one. FTL templates are well integrated with most BE Java frameworks (cough Spring cough) and it gives BE control over the data that is being shown and returned.

Need to show a certain page, let the BE do all the DB queries, filtering and only display the resulting data in one go. One call to the BE to get everything you need. Also, the risk of accidentally returning MORE data than needed is reduced, since everything that is returned is displayed on-screen (with a few exceptions). Instead, if UI communicates with the BE using REST calls only, you get a complex JSON structure back but maybe only a small portion is needed.

Back-end guys can work on the UI as well when a template engine is used. Let the FE team deal with actual styling, element positioning, design... you know, the actual template. The UI should not do business logic, so there is less work for them. You would say that there is more work for BE, but that is not totally true since a good back-end always validates data received, so we are already doing most of the work anyway.

Next, there is the security component. If only REST calls with JSON IN/OUT is done by the FE, you need to validate the request origin, maybe keep an updated table with all FE servers (in case of a distributed system with many instances), use a JWT maybe... all on top of the normal session-based validations. Just using a CSRF token becomes harder when the FE is so isolated from the BE.

Using a template engine is not perfect either

I am not saying that all the problems go away when using a template engine that is controlled by the BE. There still needs to be a lot of work on the UI side and you can't truly make "intelligent" FE that actually do (well) some of the business logic.

Also, I find it REALLY HARD to find a modern UI framework that works well with this. I've been using Bootstrap, but most others (like Vue, React, Angular and Flutter) don't work with a backend-driven template engine. If you do know any good and modern ones, please let me know cause I am really struggling to find something.

Discussions and Conclusions

So what is your take on this? I know I may get a lot of hate since there are soo many FE devs focused on react/angular, but I am sure that any BE dev feels, at least partially, what I feel.

Do you use or know any UI framework that works well with FTL? I really want to stop using jQuery as much as possible for my JS needs and maybe switch Bootstrap as well with something better.

How to invalidate a compromised JWT

pazvanti — Wed, 09 Jun 2021 07:23:41 +0000

In a past article, I wrote about JWTs, how to generate one and how to use them for authorization. JSON Web Tokens, however, have one major drawback. Once it is generated and submitted to the client, it can’t be easily made invalid. This is a big problem if the JWT got leaked and it did not expire (or worse, it does NOT have an expiration date). That is why it is important to make sure that your JWT can be invalidated at the server-side and I will show you two methods to do this.

Method 1: Blacklisting

The easiest way, at least at first glance, is to have a way of blacklisting a JWT once it is compromised. You can store all compromised JWTs in the database and when an authorization request is received, you check that the JWT used is not part of this list. This approach has one big disadvantage though: the DB can become a bottleneck due to the amount of data that you need to retrieve.

For small systems, this is not a major problem, but when you have thousands of requests per second, retrieving a full list of JWTs or going to the database to do a search for the one received can really slow down processing. This can be partially mitigated by using in-memory lists and caching the blacklisted JWTs, but this can also pose a problem because you don’t know if the cache is up-to-date. For example, if your cache refreshes at 15 minutes intervals, there still is that 15 minute window when a compromised JWT can still be used.

To mitigate this you can make a method for invalidating the cache once a new blacklisted JWT is added. Also, what do you do for distributed systems that have multiple instances of the same service? Another problem is that the database has to be cleaned to remove JWTs that have expired and will fail validation even if not black-listed. All these will definitely add to the complexity of the system, will make it more error-prone, and can slow down overall processing, if not done correctly. So, here is a better way!

Method 2: Versioning the JWT

The JWT can hold as much data as we need to validate it. The claims we insert during the build can be used for many purposes. So, let’s use one of the claims to also validate that the JWT is not blacklisted. I am not talking about an expiration date, this is something completely different, but of some information that we can easily correlate with the server and see if it was not marked as being invalid.

I am thinking of using a “version” for the JWT. When we build the JWT for the first time for an entity (a user, a functionality, or some other category), we also store the version of the JWT for that entity. This can be in the database and it won’t provide a big overhead during processing. I will explain why a bit later.

public class MyServer {
    public String generateJwt(String userId, List<String> , String entityId, String version) {
        Algorithm algorithm = Algorithm.HMAC256("mySecret");
        JWTCreator.Builder jwtBuilder = JWT.create()
                .withIssuer("myServer")
                .withClaim("accessGrantedBy", userId)
                .withClaim("accessArea", accessAreas)
                .withClaim("entityId", entityId)
                .withClaim("version", version);

        return jwtBuilder.sign(algorithm);
    }
}

So, now we have the following additional claims: entityId, version. Keep in mind that the entityId can be the userId if you are generating the access for a specific user. I only used entity to be more generic. When a JWT is received, as part of the validation process, you also check that the version is the same as the one stored on the server. Only then you consider it valid.

public boolean hasAccess(DecodedJWT jwt, String areaToAccess, String entityId) {
    if (jwt == null) return false;

    int version = entityDao.getJwtVersion(entityId);
    int versionInJwt = jwt.getClaim("version");
    String entityIdInJwt = jwt.getClaim("entityId");

    if (!entityId.equals(entityIdInJwt) || version != versionInJwt) return false;

    return jwt.getClaim("accessArea")
            .asList(String.class)
            .contains(areaToAccess);
}

If a JWT is compromised, all you have to do is increment the version on the server by one and the JWT validation will fail.

You will still need access to the database, but with good design, you won’t need any additional queries than what you will be doing anyway. For example, if the JWT is for a user, will most probably need the user information either way later on. If the JWT version is in the same table, you can retrieve it in one go along with the data you already retrieve. Even if there is no way for the JWT version to be in the same table, the access pattern will be really fast since you will do direct search by a primary key (the entityId) and the data received back is really small: a number.

Also, don’t stress too much about big number. You don’t need to increment the version every time you generate a new JWT for the entity. If there was no data compromised when the previous JWT has expired, you can reuse the same version. Only if and when a token gets compromised you need to change the version for that entity.

Advantages of versioning the JWT

No need to keep a big blacklist of compromised JWTs
Easy and direct access to the current version on the server, most probably without any additional DB access
No need to synchronize data between server instances since this is done automatically by the DB
No cleanup needed for expired JWTs
Easy to mass invalidate JWTs in case of a wider system breach

Article originally posted on my personal site under How to invalidate a JWT in Java

Handling Exceptions and Errors in Play Framework

pazvanti — Fri, 07 May 2021 07:27:45 +0000

Article originally posted on my personal blog under How to handle Exception in Play Framework

When programming, it is important to always take into consideration exceptions. No matter how well your code is, there can always be invalid data summited by the user problems in other libraries that can trigger exceptions. Also, using this mechanism is an easy way of terminating invalid flows as soon as possible. Exceptions are normal and should be treated in all services. Even in case of an exception, we must provide a response to the user so that he knows the request was indeed processed but something was not right. In this article, I will present how to handle exceptions in Play Framework and how to respond to the client.

The HttpErrorHandler

Play Framework provides the HttpErrorHandler interface that must be implemented by all exception handlers. This interface has two methods and both of them need to be properly implemented. One deals with errors from the client (like an invalid endpoint is accessed), while the other handles exceptions that happened on the server side.

public class ErrorHandler implements HttpErrorHandler {
    @Override
    public CompletionStage<Result> onClientError(Http.RequestHeader request, int statusCode, String message) {
        // Implementation
    }

    @Override
    public CompletionStage<Result> onServerError(Http.RequestHeader request, Throwable exception) {
        // Implementation
    }
}

For the client error, let’s just return a Json String that holds the status code and the error message. The onClientError method provides all the needed information and we can return a CompletebleFuture as the result.

public class ErrorHandler implements HttpErrorHandler {
    @Override
    public CompletionStage<Result> onClientError(Http.RequestHeader request, int statusCode, String message) {
        Map<String, Object> response = new HashMap<>();
        response.put("status", statusCode);
        response.put("error", message);
        return CompletableFuture.completedFuture(
                Results.status(statusCode, Json.toJson(response))
        );
    }

    @Override
    public CompletionStage<Result> onServerError(Http.RequestHeader request, Throwable exception) {
        return null;
    }
}

The server error is where most of the magic happens. All exceptions that are not caught in our code will eventually reach this method so it is important that we properly handle everything here. We must log the exception and return a proper response back to the client. As in the previous method, we will be returning a Json String. However, how this string is obtained can be a bit more complex.

I usually define one or more custom exceptions that hold the needed information. For this example I will make a PlatformException that I will throw in certain parts of the service to signal that no further processing is needed and to return a response back to the client.

public class PlatformException extends Exception {
    private String message;
    private String errorCode;

    public PlatformException(String message, String errorCode) {
        this.message = message;
        this.errorCode = errorCode;
    }

    public PlatformException(String message, String errorCode, Throwable throwable) {
        super(throwable);
        this.message = message;
        this.errorCode = errorCode;
    }

    // Getters
}

Now, in our error handler, when this exception is encountered, we will return a 500 response with the JSON string obtained from this error. If it is not our custom exception, we build one just to make it easier to return the message in a standard format all the time.

public class ErrorHandler implements HttpErrorHandler {
    private final Logger LOGGER = LoggerFactory.getLogger(this.getClass());

    @Override
    public CompletionStage<Result> onClientError(Http.RequestHeader request, int statusCode, String message) {
        Map<String, Object> response = new HashMap<>();
        response.put("status", statusCode);
        response.put("error", message);
        return CompletableFuture.completedFuture(
                Results.status(statusCode, Json.toJson(response))
        );
    }

    @Override
    public CompletionStage<Result> onServerError(Http.RequestHeader request, Throwable exception) {
        LOGGER.error("Error encountered.", exception);
        Throwable exceptionToReturn = exception;
        if (!(exception instanceof PlatformException)) {
            exceptionToReturn = new PlatformException(exception.getMessage(), "UNKNOWN", exception);
        }
        return CompletableFuture.completedFuture(
                Results.internalServerError(Json.toJson(exceptionToReturn))
        );
    }
}

Last but not least, we need to inform Play about our error handler. To do this we edit the application.conf file and set the play.http.errorHandler configuration variable to our class name:

play.http.errorHandler = "ErrorHandler"

What! Full Stack Trace is returned?

If you were to run this code you would see that the JSON includes the full stack trace. This is not desirable since it can provide too much information. We don’t need the client to know all this, so let’s improve our code. First, we don’t make the JSON out of the exception itself. Instead, we make and ErrorDTO that holds the message, the error code and what other information we need. Now, when the exception happens, only the minimum needed information is returned.

public class ErrorHandler implements HttpErrorHandler {
    private final Logger LOGGER = LoggerFactory.getLogger(this.getClass());

    @Override
    public CompletionStage<Result> onClientError(Http.RequestHeader request, int statusCode, String message) {
        Map<String, Object> response = new HashMap<>();
        response.put("status", statusCode);
        response.put("error", message);
        return CompletableFuture.completedFuture(
                Results.status(statusCode, Json.toJson(response))
        );
    }

    @Override
    public CompletionStage<Result> onServerError(Http.RequestHeader request, Throwable exception) {
        LOGGER.error("Error encountered.", exception);
        ErrorDTO error;
        if (exception instanceof PlatformException) {
           errorDTO = new ErrorDTO(exception.getMessage(), ((PlatformException) exception).getErrorCode());
        } else {
            errorDTO = new ErrorDTO(exception.getMessage(), "UNKNOWN");
        }
        return CompletableFuture.completedFuture(
                Results.internalServerError(Json.toJson(errorDTO))
        );
    }
}

Article originally posted on my personal blog under (How to handle Exception in Play Framework)[https://petrepopescu.tech/2021/03/handling-exceptions-and-errors-in-play-framework/]

How to make a custom message converter for Log4J2

pazvanti — Thu, 29 Apr 2021 06:08:56 +0000

Article originally posted on my personal website under Building a custom converter in Log4j2

I’ve been using Log4J for many years. It is a powerful logging library that is efficient and highly customizable. You can extend the functionality with ease and do custom actions on the message prior to it being logged. Without too much chit-chat, in this article I will be showing you how to implement a custom converter for Log4J2.

What is a converter?

Log4J2 has multiple components that are called when a message is logged. You have the actual logger, which you call with the raw message. This is where the .info or .warn calls happen. The logger has one or more appenders. These appenders are called with the log event and are useful because you can log the same message in multiple locations if you want. For example, you can have an appender for the console and another one for writing to a file. If you configure the logger to use both appenders, you only need one call at .info() and it will delegate the logging to both appenders.

Next comes the layout. There are multiple layouts available and they specify the actual format of the logged message. Here you define multiple “converters” and the layout will call each one to format part of the message and append the needed data. There is a converter for the date, one for exception, one for the message and many more. Here we will be inserting our code so that we can format the logged message in our own way.

How to print colored text in Log4J2

For this article we will be making a converter that will highlight different words in the logged message. We will make the list of words configurable directly from the log4j configuration file. Keep in mind that this is just a simple example and that converters can be used for much more powerful features, like masking sensitive elements in the logs or formatting code lines in a certain way.

But, to keep it simple, we will be changing the color of certain words to cyan. To do this, we need a custom converter. It will extend the LogEventPatternConverter class. Furthermore, it needs to be marked as a plugin using the @plugin annotation (we also give a name and category to it) and we need to define converter keys. These will be used in the PatternLayout to identify our converter. When the pattern is parsed and our converter key is identified, it will delegate the log event to our converter. And yes, you can have multiple keys if you want.



@Plugin(name = "highlight", category = PatternConverter.CATEGORY)
@ConverterKeys({"color", "colormsg"})
public class HighlightConverter extends LogEventPatternConverter {

}

Now, we need to provide a constructor. The constructor will get the list of words that we want to highlight in the logs. To make sure we don’t have duplicates, we can make it a set. We also call super() to make sure everything is properly initialized further down the chain. Looking over the documentation for Log4j2 we learn that the converter actually needs a newInstance() method and it takes an array of Strings as the parameter, which represents the options for the converter. In this case, the option is our list of words, but it can be anything that we need to properly initialize our converter.



@Plugin(name = "highlight", category = PatternConverter.CATEGORY)
@ConverterKeys({"color", "colormsg"})
public class HighlightConverter extends LogEventPatternConverter {
    private static final String NO_COLOR = "\u001B[0m"; // No color for Windows
    private static final String HIGHLIGHT_COLOR = "\u001B[96m"; // Cyan for Windows

    private Set<String> words;

    private HighlightConverter(Set<String> words) {
        super("HighlightConverter", null);

        this.words = words;
    }

    public static HighlightConverter newInstance(String[] options) {
        return new HighlightConverter(new HashSet<>(Arrays.asList(options)));
    }
}

Now that we defined our constructor and we prepared the set of words that we want to highlight, we need to alter the message. All Log4j2 converters must implement the append() method. This method takes in a LogEvent and the String Builder where the message must be appended. The LogEvent contains the logged message and we can retrieve it and replace our keywords with the highlighted version. The final version looks something like this:



@Plugin(name = "highlight", category = PatternConverter.CATEGORY)
@ConverterKeys({"color", "colormsg"})
public class HighlightConverter extends LogEventPatternConverter {
    private static final String NO_COLOR = "\u001B[0m";
    private static final String HIGHLIGHT_COLOR = "\u001B[96m";

    private Set<String> words;

    private HighlightConverter(Set<String> words) {
        super("HighlightConverter", null);

        this.words = words;
    }

    public static HighlightConverter newInstance(String[] options) {
        return new HighlightConverter(new HashSet<>(Arrays.asList(options)));
    }



    @Override
    public void format(LogEvent event, StringBuilder toAppendTo) {
        String logMessage = event.getMessage().getFormattedMessage();
        for (String word:words) {
            logMessage = logMessage.replaceAll(word, HIGHLIGHT_COLOR + word + NO_COLOR);
        }

        toAppendTo.append(logMessage);
    }
}

Using a custom converter in Log4J2

We prepared our converter, but how do we tell Log4j2 to use it? We need two things. First, we need to tell Log4J to include our converter class. This is done by adding the package in which the converter resides in our configuration:



<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" packages="com.ppopescu">

</Configuration>

Next, we define our appender (in this case a Console Appender) that has a Pattern Layout. For the message, instead of using %m (the standard converter key for the logged message), we use our defined converter key: %color or %colormsg. Just adding this won’t do any good since we did not specify what words to highlight. We need to add parameters to the converter. This is done using {param} syntax and we can have as many as we need. Here is a sample configuration that highlights the words “custom”, “highlight” and “words”:



<?xml version="1.0" encoding="UTF-8"?>

<Configuration status="WARN" packages="com.ppopescu">

    <Appenders>

        <Console name="Console" target="SYSTEM_OUT">

            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level - %color{custom}{highlight}{words}%n"/>

        </Console>

    </Appenders>

    <Loggers>

        <Root level="info">

            <AppenderRef ref="Console"/>

        </Root>

    </Loggers>

</Configuration>

Conclusions

It is easy to define a custom message converter that fill in any logging needs. Using it to highlight words is easy, but the converter itself can be much more complex and fulfill more advanced needs like masking, code formatting or anything else you can think of. A similar approach can also be taken for building a custom appender or a custom layout.

Full source and original article on my personal website at Building a custom converter in Log4j2

Building a REST API in Play Framework

pazvanti — Wed, 21 Apr 2021 07:02:42 +0000

Article originally posted on my personal website under Building a REST API in Play Framework. Sample requests can also be found there

When building web applications, REST has become the most widely used approach because it is easy to use and easy to implement. In this tutorial I will be showing how to build a simple REST API in Play Framework and will cover the 4 basic functionalities:

Create – POST
Update – PUT
Retrieve – GET
Remove – DELETE

We will be creating a simple API for a student’s management software where we can manipulate the students and retrieve the stored ones. It won’t be anything too fancy, but an introduction to Play Framework and how a REST API can be build.

Setting up our Entities and DB

First, let’s create our database. We will store the student’s name, year in the university and the department he is currently studying in. It is a simple structure with only 4 columns (there is also an ID) and nothing more.

Our entity class looks like this. This will tie the database table to our application model and will allow us to easily map from the DB to a Java class and vice-versa.

package data.domain;

import javax.persistence.*;

@Entity
@Table(name = "students")
public class StudentDO {
    @Id
    @Column
    @GeneratedValue(strategy=GenerationType.IDENTITY)
    private Integer id;

    @Column
    private String name;

    @Column
    private Integer year;

    @Column
    private String department;
}

Building our DAO

Now that we have the Entity, we need to be able to actually store the data in the database and retrieve it when needed. This is done by the JPA Api and Play makes it easy to use it. We will be creating our DAO class that will provide the needed methods for the CRUD operations. CRUD stands for Create, Read, Update and Delete, so these are the methods that we will be implementing.

import com.google.inject.Inject;
import data.domain.StudentDO;
import play.db.jpa.JPAApi;

import javax.persistence.EntityManager;
import javax.persistence.criteria.CriteriaBuilder;
import javax.persistence.criteria.CriteriaQuery;
import javax.persistence.criteria.Root;
import java.util.List;

public class StudentDao {
    private static final String ENTITY_MANAGER_NAME = "default";

    @Inject
    protected JPAApi jpaApi;

    public StudentDO create(StudentDO studentDO) {
        jpaApi.withTransaction(entityManager -> { entityManager.persist(studentDO); });
        return studentDO;
    }

    public StudentDO find(Integer id) {
        return jpaApi.em(ENTITY_MANAGER_NAME).find(StudentDO.class, id);
    }

    public List<StudentDO> find() {
        EntityManager entityManager = jpaApi.em(ENTITY_MANAGER_NAME);

        CriteriaBuilder criteriaBuilder = entityManager.getCriteriaBuilder();
        CriteriaQuery<StudentDO> criteriaQuery = criteriaBuilder.createQuery(StudentDO.class);
        Root<StudentDO> root = criteriaQuery.from(StudentDO.class);
        criteriaQuery.select(root);
        return entityManager.createQuery(criteriaQuery).getResultList();
    }

    public void delete(int id) {
        jpaApi.withTransaction(entityManager -> {
            StudentDO studentDO = entityManager.find(StudentDO.class, id);
            if (studentDO != null) {
                entityManager.remove(studentDO);
            }
        });
    }

    public StudentDO update(StudentDO studentDO) {
        jpaApi.withTransaction(entityManager -> {entityManager.merge(studentDO);});
        return studentDO;
    }
}

We also implemented a method for retrieving all the students that are saved. A more advanced system will also provide filtering options, pagination and other features that are mandatory for an advanced web app, but this will do for our simple REST API tutorial.

The Service and transfer objects

The controller should not communicate directly with the DAO. We should have separation of functionality and each layer has it’s own role. The DAO communicates with the database, the Service has the business logic and the Controller is for external access. I won’t go into details on this topic, but I usually structure my code like this and it is easier to maintain when you know who is responsible for what.

Also, for more advanced systems you should not return directly the DO to the outside. Instead, we should have a mapping between the Domain object and an externally-used Transfer object. This DTO (Data Transfer Object) is the external representation, while the DO is the internal one. For this simple system, there are no differences (so I won’t include the DTO class), but more complex ones usually do have, with the DTO being composed of the data from multiple DOs and with new fields that are processing results.

First, let’s create a utility class that maps between Transfer and Domain objects. Nothing to fancy and if you desire you can use BeanUtils to achieve this.

import data.domain.StudentDO;
import data.dto.StudentDTO;

public class StudentMapper {
    public static StudentDTO toTransfer(StudentDO domain) {
        StudentDTO dto = new StudentDTO();
        dto.setId(domain.getId());
        dto.setName(domain.getName());
        dto.setYear(domain.getYear());
        dto.setDepartment(domain.getDepartment());

        return dto;
    }

    public static StudentDO fromTransfer(StudentDTO dto) {
        StudentDO domain = new StudentDO();
        domain.setId(dto.getId());
        domain.setName(dto.getName());
        domain.setYear(dto.getYear());
        domain.setDepartment(dto.getDepartment());

        return domain;
    }
}

Next, our service that handles all the business logic. Again, there is nothing fancy going on in this simple example. We get the DTO, map it to a DO, call the DAO and return the result.

import com.google.inject.Inject;
import data.dao.StudentDao;
import data.domain.StudentDO;
import data.dto.StudentDTO;

import java.util.List;
import java.util.Optional;
import java.util.stream.Collectors;

public class StudentService {
    @Inject
    private StudentDao studentDao;

    public List<StudentDTO> getAll() {
        List<StudentDO> studentDOList = studentDao.find();
        return studentDOList.stream().map(domain -> StudentMapper.toTransfer(domain)).collect(Collectors.toList());
    }

    public Optional<StudentDTO> getById(int id) {
        StudentDO studentDO = studentDao.find(id);
        if (studentDO == null) {
            return Optional.empty();
        }

        return Optional.of(StudentMapper.toTransfer(studentDO));
    }

    public StudentDTO create(StudentDTO studentDTO) {
        StudentDO studentDO = StudentMapper.fromTransfer(studentDTO);
        studentDO = studentDao.create(studentDO);
        return StudentMapper.toTransfer(studentDO);
    }

    public Optional<StudentDTO> update(StudentDTO studentDTO, int id) {
        StudentDO fromDb = studentDao.find(id);
        if (fromDb == null) {
            return Optional.empty();
        }

        fromDb.setName(studentDTO.getName());
        fromDb.setYear(studentDTO.getYear());
        fromDb.setDepartment(studentDTO.getDepartment());
        fromDb = studentDao.update(fromDb);

        return Optional.of(StudentMapper.toTransfer(fromDb));
    }

    public void delete(int id) {
        studentDao.delete(id);
    }
}

The Controller and endpoint mappings

The controller is the main entry point, so we need to get the information from the HTTP request, map it into our internal data structure and call the service to do the business logic. In case anything goes wrong we return an HTTP status that correctly reflects what happened. I saw many services that always return 200, even if there was an error or the resource was not found, and provide the error only as a JSON response. This is incorrect and the status should reflect the actual state, with the JSON response needed only for additional information.

import com.fasterxml.jackson.databind.JsonNode;
import com.google.inject.Inject;
import data.dto.StudentDTO;
import play.libs.Json;
import play.mvc.Controller;
import play.mvc.Http;
import play.mvc.Result;
import services.StudentService;

import java.util.Optional;

public class StudentsController extends Controller {
    @Inject
    private StudentService studentService;

    public Result get(Integer id) {
        Optional<StudentDTO> student = studentService.getById(id);
        if (student.isPresent()) {
            return ok(Json.toJson(student.get()));
        }

        return notFound();
    }

    public Result getAll() {
        return ok(Json.toJson(studentService.getAll()));
    }

    public Result create(Http.Request request) {
        JsonNode jsonData = request.body().asJson();
        try {
            StudentDTO studentDTO = Json.fromJson(jsonData, StudentDTO.class);
            studentDTO = studentService.create(studentDTO);
            return ok(Json.toJson(studentDTO));
        } catch (RuntimeException e) {
            // Most probably invalid student data
            return badRequest(request.body().asJson());
        }
    }

    public Result update(Http.Request request, Integer id) {
        JsonNode jsonData = request.body().asJson();
        try {
            StudentDTO studentDTO = Json.fromJson(jsonData, StudentDTO.class);
            Optional<StudentDTO> student = studentService.update(studentDTO, id);
            if (student.isPresent()) {
                return ok(Json.toJson(student.get()));
            }
            return notFound();
        } catch (RuntimeException e) {
            return badRequest(request.body().asJson());
        }
    }

    public Result delete(Integer id) {
        studentService.delete(id);
        return ok();
    }
}

And now, we map our endpoints to the Controller methods.

GET     /student                    controllers.StudentsController.getAll
GET     /student/:id                controllers.StudentsController.get(id: Integer)

+ nocsrf
POST    /student                    controllers.StudentsController.create(request: Request)

+ nocsrf
PUT     /student/:id                controllers.StudentsController.update(request: Request, id: Integer)

+ nocsrf
DELETE  /student/:id                controllers.StudentsController.delete(id: Integer)

Some explanations

First thing you may notice is that the DAO uses jpaApi.withTransction(). This is to ensure we have a transaction when doing any write operation on the database. Otherwise, we won’t be able to do any changes and we will get an error: java.lang.IllegalArgumentException: Removing a detached instance.

Second, the fact that the controller catches a RuntimeException. This is because the JSON parser can throw this when an invalid JSON is provided. We will return a badRequest() with the provided input. A more advanced system may detect what is wrong and provide a more explicit message.

Last, but not least, the + nocsrf in the routing file. This is to allow the request even if no CSRF token is provided. Normally we do not allow this, but since this is a RESTful service that is not tied to an HTML, we allow it. For a production-ready service, we do need to add a way of authenticating and authorizing the requests, but that is a discussion for another article.

Article originally posted on my personal website under Building a REST API in Play Framework. Sample requests can also be found there