JVM

Validation – Operation – Notification

Daniel, 2 Comments

Given When Then – short intro

Have You ever heard about Given-When-Then approach to create tests? It’s an approach to separate tests structure into three parts:

  • Given – Test preparation. We should ask ourselves a few questions here (depending on approach):
    • What I need to execute before tested operation?
    • Do I need some specific beans?
    • Do I need to mock something?
    • Do I need some particular data?
  • When – this is our operation under test.
  • Then – this are our expectations. Basically – test assertions.

Of course not every code can have such structure, but as an ideal approach it can increase overall readability of our source code.

Example:

This test checks if newly created issue will invoke some sort of notification. We can read this test like this:

  • With given title  and description
  • When I create new issue
  • Then one notification has been published.

Of course sometimes, some parts can not be that obvious. Take a look:

Now you can see that given part is hidden. But it’s still there!

There are a lot of good articles about this topic. Some of them:

Validation – Operation – Notification approach

I would like to propose similar approach, but for production source code. Let’s call it VON (Validation – Operation – Notification).

  • Validation – all prerequisites which need to be checked or done before you can do particular command. Such as validations, security check rules etc.
  • Operation – our business command. The heart of the method. We start writing our method because of this. This is our main purpose.
  • Notification – what happens after successful operation. Often it will be just some return statement, but it could be more. It’s a part of business method that did not exist to do primary operation, but invoke some other command (which very often can be done asynchronously. For example using CompletableFuture).

Let’s see a basic example:

Now, look at this method using 3 steps defined above:

  • Validate – if title and description is not null,
  • Create issue (our operation),
  • Notify about newly created issue and return it.

Of course sometimes it will not be such straightforward. Above method in real world can look more like this (using lombok):

Still – you can see all 3 parts of VON approach.

Error handling

Depending on step, we should think about errors and problems differently. Lets try to check possible scenarios when we use VON code structure.

Imagine that something happen on validation step – the only thing you have to do is to throw an exception, return specific error message or maybe send error information to some notification queue… You didn’t start any operation- so you have no problem (within this method).

When something happen during operation part- then you have a problem. If your validation was well prepared then any error within this step will be related to technical or network issues (database downtime, no network connection, etc.).

Finally when something happen during notification phase then you should know two things- operation went well, so main purpose of this method was finished without problems. The only problem you have now is that some notification was not published. Question is what can you do about this? Maybe you should not do anything, maybe you should send information to technical error queue that some message was not sent. Maybe just log this situation? It depends.

As you can see separating your method to VON structure helps you identifying error type that can occurred. It’s one of the advantages of this approach.

To “Enter” or not to “Enter”

As you can see in above examples “enter key” change step in VON approach. In general “new line” in source code should inform us about context change. This principle goes well with whole VON approach as every step is different context. We can look at source code and with a single glance focus on most important part for us at the moment. If every team member use the same approach, then source code starts to look more clear and well structured. The faster you can focus on important things, the faster you can solve the problem you are currently working on.

Of course this doesn’t mean that we should create long methods 🙂 Ideally our methods will have 2-3 lines- each line for single step. Then we can omit all enters.

Lets start some cleaning!

Caution - Wet floor

Refactor to VON – example

Imagine a method that delete contract from some old system. Contract can be deleted when it’s not started and any of its conditions are not started yet as well (for example, there can be specific condition which will limit that resignation from contract can be made two or more months before contract is started). Delete operation is made using SoftDelete (BTW. I hate soft delete). Of course before we start making any changes we should have proper unit tests!

Our example:

First let’s try to find our steps:

  • validation 
    • our contract and any of its conditions can not be started- this is in the code
    • we don’t have validation that contractId  is null …
    • we don’t have validation that particular contract exists in repository..
  • operation
    • delete all contract conditions
    • set contract as non active (soft-delete)
    • save in repository
  • notifications
    • cancel payment disposition for deleted payment

I would start with preparing above steps. Problematic part is that deleteAllContractConditionsByContract method is at the same time in validation and in operation phase. Let’s split it to two methods (for now).

As we don’t want to change too much outside this method let’s just extract both assertions to particular methods:

Much better 😉 Now lets fill the gap with our validations:

Ok. We should hide this whole optional stuff:

Now some small refactoring with operation part:

Now we need to take a look at the notification part. There are two things possible:

  1. Add a new method to paymentsService  which will cancel payment disposition. Simple and safe operation, however we will still have direct relation between contracts and payments.
  2. Add some queue in the middle between payments and contracts modules/components. We can use queue or just simple implementation of Producer/Consumer pattern. It’s a bit more complicated, but this gives us a more loose connection between the modules.

And basically we can stop now as this finish whole VON approach. Using this approach we did find 2 possible problems with particular method, however- now probably we have redundant checks – in our method we must assert that all contract conditions can be remover, and probably within contractConditionsService  the same check will be made.

Despite this, its look like a good start to further source code refactoring. Finally we can finish with something like this:

Summary

This technique nicely apply mostly to more complicated business methods and for legacy code refactor. Its biggest advantage is shown when every team member use this technique for all business operations. Then these methods starts to look consistent and much more straightforward. Also it helps to look at different parts of method differently (for example in case of potential errors that could happen).

Please note that this approach should not be used at every cost. It’s a convention that nicely applies to legacy code methods as in our example, but also to shiny newly created operations.

Have fun and comment below what you think about this approach!

Validation – Operation – Notification

Asynchronous call using CompletableFuture

Daniel, , Leave a comment

Intro

Imagine that you have to use external systems to retrieve data or you deal with communication in distributed architecture (communication between modules within application). In this article I would like to tackle one possible problem, but please note that this approach can be used in a many different scenarios.

Please note that I don’t want to provide another “CompletableFuture guide”. If you are interested in specific options and possibilities of CompletableFuture  I recommend you great article by Tomasz Nurkiewicz.

Problem

We would like to write simple application that will provide us best possible exchange rate from public exchange rate systems (let’s assume that bigger exchange rate value is better as we want to sell). What we want is to convert from our “local” currency (in my example it will be PLN) to selected one (using simple rest call). Response should inform us only about highest rate.

So if I run my application on localhost:8080  and I would like to check lowest exchange rate for GBP then it can looks like:

(In example above I used httpie. I also recommend postman if you prefer more GUI-oriented tools :))

Another example (USD):

In our example we will check 3 external services for exchange rates:

Concept

First of all as you can imagine we will make a few external calls to described above systems (every call will take some time). Best option is to call asynchronously to every exchange rate API and after receiving all rates just check which one is the highest and finally make a response.

Asynchronous call to external exchange rate services

We don’t want to make every request synchronously, because we will increase response time from our application.

Solution

Basic solution

Let’s start with some general interface for every API call:

Then let’s provide some implementation for one of calls:

As you can see there, it’s very simple standard code. I use Spring’s RestTemplate  to prepare and make external call. What’s important here – so far we don’t use any CompletableFuture  so we can test this kind of classes as usual.

What I want to show is that you can provide functionality without thinking about async invocations. You can add this after finishing basic implementation.

Lets go async

Let’s look what we can achieve by using CompletableFuture . This class provides you possibility of creating object that will do some operations “in background” (We will talk about executors which do this operations later in this article). This gives you possibility to create non blocking operations (such as external calls) for future usage. Once you want to use information from CompletableFuture  it start blocking until Future  is completed. However, if operation is already completed then it will not block thread at all.

This can help you in a couple of scenarios:

  • You want to do some expensive operation and use it later. Then you can create CompletableFuture  at first, make other required operations and then use completed Future . In case it’s not completed your app will just wait for it
  • You want to do some expensive operations concurrently and then combine them in some way (this is what we want, and this is most popular scenario)

How do you create CompletableFuture ? The easiest way is to use static factory methods provided by this class. For example:  CompletableFuture.supplyAsync(Supplier<u> supplier)</u> . Supplier  class is a @FunctionalInterface  so you can use lambdas 🙂

Lets try then to provide some Factory for creating our asynchronous calls. This is not the best option, however in this case it can be a good starting point:

I also added exceptionally  here for each created CompletableFuture  – this means that in case that some exception will stop completion of particular Future then provided method will return value as a result. Receiving Throwable t  gives you possibility to adjust result to situation. In this simple example it will return 0.

Finally. we are ready to use it!

Completable Futures are being created in lines 12-14, then (lines 16-19) we take nbpRate  as our basic value, combine result with fixerRate  and select better option (higher), then again we combine this result with yahooRate . This will create another CompletableFuture  – let’s call it  best. 

Finally, as we don’t have anything more to do we use get() method on our Future . This method as I wrote before is blocking- so we will wait until our Futures  will complete and we will have our solution. Then we will just return it as a result.

Now you can see why I said that previous fabric its not our best option. If you have to add new service (and its very likely in our problem) then you will have to add here new lines and implementation which breaks Open/Close principle. I use this approach for sake of simplicity of explanation.

Executors

You can run CompletableFuture  by using default Executor  (as in all examples in this article) what can be fine for simple solutions. But for real world complex requirements this probably will be not effective and can lead to serious problems. If you want to learn more about default executors, Oleg Schelajev did great article about choosing right executor for your tasks.

However, if you are using spring you probably should provide TaskExecutor which has similar interface as java.util.concurrent.Executor , but Spring provides a few nice and configurable implementations of it.

Take an example:

This configuration provides ThreadPoolTaskExecutor  which uses  CustomizableThreadFactory . One can set max pool size (max number of threads that will be created), core pool size (base number of thread that should be in use) and of course more options.

Don’t use default executor. If you use spring, just go with your own configured TaskExecutor . If you use JEE or other frameworks pick up one of available executors in java.util.concurrent  package. Concurrent programming is very challenging so if you can keep something under control then definitely you should do it 🙂

To use particular executor just use second implementation of supplyAsync  method:

Afterwords

There are more problems around this topic, for example,  you need to figure out how to deal with situation when external service is down. We also need to consider how to test our solution and how to simplify future maintenance. There is always a need of providing a good balance- we should always provide sufficient, smallest and simplest possible solution- it’s not easy task to do though 🙂

Most important criteria that should be considered before providing final solution:

  1. Reliability
  2. Resilience
  3. Maintainability
  4. Testability
  5. Performance

 

Asynchronous call using CompletableFuture