Develop a web app with VertX and Thymeleaf

Standard

What is Vert.X?

Bullet points summary:

  • Vert.X is “a tool-kit for building reactive applications on the JVM”.
  • It is event driven, asynchronous, non blocking- uses Netty behind.
  • It is similar with NodeJS, but it uses multiple event loops.
  • Helps you to scale your app.
  • It’s polyglot: supports Java, JavaScript (through Nashorn), Groovy, Ruby. The API’s are virtually the same.
  • It has many modules for: web, data access, mail, jms, rx java, clustering, cloud, etc.
  • It is not that well documented.
  • It’s harder to test because a lot of things happen asynchronously; nevertheless, Vert.X offers some useful API for testing.

You can find out more at these resources which helped me:
https://www.youtube.com/watch?v=yLg-LPSRjho&t=1893s
https://www.youtube.com/watch?v=8ClYUo_A3h0&t=91s
http://escoffier.me/vertx-hol/

Simple web app with Vert.X

Everything in Vert.X is a verticle. So the http server we’ll create will be also a verticle – by extending the AbstractVerticle class and we override the start() method.

public class HttpServerVerticle extends AbstractVerticle {
    public void start(){
        Router router = Router.router(vertx);
        router.route(HttpMethod.GET, "/").handler(rc -> {
             rc.response().putHeader("Content-type", "text/html").end("Hello, world!");
        });
        vertx.createHttpServer().requestHandler(router::accept).listen("8080");
    }

    public static void main(String args[]) {
        Vertx vertx = Vertx.vertx();
        vertx.deployVerticle(new HttpServerVerticle());
    }
}

Now you can run this class and open in your browser http://localhost:8080.

Adding Thymeleaf and Bootstap template

Now we will bring a html file to the table. I took the “One page wonder” bootstrap template from here: https://startbootstrap.com/template-overviews/one-page-wonder/

I put the html file in the mvn project under: src/main/resources/webapp/html

The css and js folders go under: src/main/resources/webapp/static

Now, let’s modify the HttpServerVerticle to render the html page – basically we just modify the start method.

@Override
public void start() throws Exception {
    Router router = Router.router(vertx);
    router.route("/static/*").handler(StaticHandler.create("webapp/static"));
    router.route(HttpMethod.GET, "/").handler(rc -> {
        engine.render(rc, "index", res -> {
            if (res.succeeded()) {
                rc.response().end(res.result());
            } else {
                rc.fail(res.cause());
            }
        });
    });
    vertx.createHttpServer().requestHandler(router::accept).listen(Constants.PORT);
    LOGGER.info("Listening on http://localhost:" + Constants.PORT);
}

The first interesting thing to spot is that the router maps the requests for /static/* (like /static/css and /static/js) to the webapp/static directory. So this will help to resolve the dependencies from the html page.
Then you see the response now is rendered by the engine and the content is “index”.

But we also need to specify a thymeleaf template resolver so that “index” is used to construct the path to the html resource, using the specified prefix and suffix, by the template resolver.

The engine is of type ThymeleafTemplateEngine exposed by the vertx web module and it is the integration with Thymeleaf.

public HttpServerVerticle() {
    this.engine = ThymeleafTemplateEngine.create();
    configureThymeleafEngine(engine);
}

private void configureThymeleafEngine(ThymeleafTemplateEngine engine) {
    ClassLoaderTemplateResolver templateResolver = new ClassLoaderTemplateResolver();
    templateResolver.setPrefix(Constants.TEMPLATE_PREFIX);
    templateResolver.setSuffix(Constants.TEMPLATE_SUFFIX);
    engine.getThymeleafTemplateEngine().setTemplateResolver(templateResolver);
}

We also add another java class as the main one for our application.

public class MainApp {
    public static void main(String[] args) {
        Vertx vertx = Vertx.vertx();
        vertx.deployVerticle(new HttpServerVerticle());
    }
}

Adding i18n and l10n

By default thymeleaf uses the StandardMessageResolver class to resolve resource bundles. This model uses one resource bundle per template; so if you have for example a template called “home” you would need to specify resource bundles (properties files) like: home.properties (default) , home_en_US.properties, home_es_ES.properties and so on, for each locale.

If you want though, you can define your own message resolver – for example if you want one resource bundle per locale, for all the templates. Let’s do that here.

public class CustomMessageResolver extends AbstractMessageResolver {
    private final static Logger LOGGER = LoggerFactory.getLogger(CustomMessageResolver.class);
    private Map<String, Properties> localizedMessages;

    public CustomMessageResolver() {
            super();
        readMessageBundles();
    }

    private void readMessageBundles() {
        localizedMessages = new LinkedHashMap<>();
    //here populate the map from the disk - use whatever convention you like
    }

/**
This method actually resolves the message key
*/
    @Override
public String resolveMessage(ITemplateContext context, Class<?> origin, String key, Object[] messageParameters) {
    Validate.notNull(context, "Context cannot be null");
    Validate.notNull(context.getLocale(), "Locale in context cannot be null");
    Validate.notNull(key, "Message key cannot be null");

    String languageContry = StringUtils.isEmptyOrWhitespace(context.getLocale().getCountry()
    ) ? context.getLocale().getLanguage() : context.getLocale().getLanguage() + "_" + context.getLocale()
            .getCountry();

    //get into account the {language} and {language}_{country} (de and de_DE) type of
    // localized resource bundles
    Properties messages = localizedMessages.entrySet()
            .stream()
            .filter(e -> e.getKey().contains(languageContry))
            .findFirst()
            .map(Map.Entry::getValue)
            .orElseGet(() -> localizedMessages.get(Constants.DEFAULT_BUNDLE_KEY));

    if (messages != null && messages.get(key) != null)
        return messages.get(key).toString();
    return null;
}

@Override
public String createAbsentMessageRepresentation(ITemplateContext context, Class<?> origin, String key, Object[] messageParameters) {
    Validate.notNull(key, "Message key cannot be null");
    if (context.getLocale() != null) {
        return "??" + key + "_" + context.getLocale().toString() + "??";
    }
    return "??" + key + "_" + "??";
}

Now, in the html file we can write:

<header class="header-image">
    <div class="headline">
        <div class="container">
            <h1 th:text="#{index.h1}">One Page Wonder</h1>
            <h2 th:text="#{index.h2}">Will Knock Your Socks Off</h2>
        </div>
    </div>
</header>

And in the properties file we have for en_US:

index.h1=One Page Wonder
index.h2=Hello! Vertx is here!

and for de_DE:

index.h1=Eine Seite Wunder
index.h2=Hello! Vertx is here!

Additionally, you can format numbers and dates. Let’s add this to the response renderer:

router.route(HttpMethod.GET, "/").handler(rc -> {
    rc.put("today", Calendar.getInstance());
    rc.put("number", 212.42);
    engine.render(rc, "index", res -> {
        if (res.succeeded()) {
            rc.response().end(res.result());
        } else {
            rc.fail(res.cause());
        }
    });
});

And in the html file we add the following:

Current date(locale example):
<span th:with="df=#{date.format}"
      th:text="${#calendars.format(today,df)}">13 February 2011</span>
<br/>
Decimal number(thymeleaf format example):
<span th:with="delimiter=#{decimal.delimiter}"
      th:text=${#numbers.formatDecimal(number,1,3,delimiter)}></span>

Now you can test again in the browser.

Testing

Let’s add some testing for the HttpServerVerticle to test that it runs and listens on the specified port.

For this we create the test class and annotate it to run with the Vertx context. We also instantiate a RunTestOnContext rule object to have access to vertx.

@RunWith(VertxUnitRunner.class)
public class HttpServerVerticleTest {

@Rule
public RunTestOnContext rule = new RunTestOnContext();

}

and now we deploy the verticle and write the test which makes an http response and expects to get a 200 ok response.

@Before
    public void setUp(TestContext context) throws InterruptedException {
        Vertx vertx = rule.vertx();
        vertx.deployVerticle(new HttpServerVerticle(), context.asyncAssertSuccess());
//delay until the http server is listening - context.asyncAssertSuccess() makes sure the start method is called, but not finished
        Thread.sleep(2000);
        httpPort = Constants.PORT;
    }

    @Test
    public void testServerUp(TestContext context) {
        Vertx vertx = rule.vertx();
        final Async async = context.async();
        HttpClient client = vertx.createHttpClient();
        HttpClientRequest req = client.get(httpPort, "localhost", "/", response -> response
                .handler(body -> {
                    //dummy assertion to test the http server responds
                    context.assertEquals(HttpResponseStatus.OK.code(), response.statusCode());
                    context.assertNotNull(body.toString());
                    async.complete();
                }));
        req.putHeader("Accept-Language", "en-US");
        req.end();
    }

That’s it.

Conclusion

You saw how you can get started with a simple Vert.X web application and how you can integrate Thymeleaf as a templating engine. Also you saw how you can implement and customize a message resolve for Thymeleaf to use.

The source code for this article can be found at: https://github.com/RemusSino/vertx-web-thymeleaf .

Additional Thymeleaf documentation about localization and number formatting:
http://www.thymeleaf.org/doc/tutorials/2.1/usingthymeleaf.html#a-multi-language-welcome
http://www.thymeleaf.org/doc/tutorials/2.1/usingthymeleaf.html#numbers

Dependency inversion principle

Standard

SOLID is a set of 5 principles for design in object oriented programming, defined by Robert C. Martin.

  • Single-responsibility principle
  • Open-closed principle
  • Liskov substitution principle
  • Interface segregation principle
  • Dependency Inversion principle

Dependency inversion principle – ISP

The official definition:

Depend on abstractions, not on concretions.

The definition is pretty simple and intuitive: depend on interfaces rather than implementations. This limits the amount of impact that introducing a new type of implementation in the application will have.

This applies best when designing of the application when you deal with multiple layers and when using functionalities from one layer to another.

Or what?

If this principle is violated, when introducing new types in our applications, they will induce many more changes to existing code than we would want.

Lets talk code

Violating the DIP

Lets take an example: let’s say we have a web crawler which makes requests to http pages and searches for some information. That information is saved to the disk in a structure of files.

public class WebCrawler {

    private FileWriter fileWriter;

    public WebCrawler(FileWriter fileWriter){
        this.fileWriter = fileWriter;
    }

    public String extractInfoFromHttpPage(String url) {
        //logic to make a GET request to a HTTP Page search for a specific information a search for a specific information
    }

    public void saveInformation(String info) {
        //logic to process the information and save it to a file in a
        fileWriter.saveInformationToFile(info);
    }
}

public class FileWriter {

    private Path file;

    public FileWriter(Path file){
        this.file = file;
    }

    public void saveInformationToFile(String info) {
        //logic to save the information to a file 
    }
}

This design is fine and working very well. But lets say we want to add the functionality to save now in the database. This means we must also change the WebCrawler class.

public class DatabaseWriter {
    // some configuration variables for the DB connection

    public DatabaseWriter(){
        // logic to initiate the connection
    }

    public void writeToDatabase(String info){
        // logiwrite to save the information in the database
    }

}


public class WebCrawler {

    private DatabaseWriter dbWriter;

    public WebCrawler(DatabaseWriter dbWriter){
        this.dbWriter = dbWriter;
    }

    public void setPersistenceProvider(){

    }

    public String extractInfoFromHttpPage(String url) {
        //logic to make a GET request to a HTTP Page search for a specific information a search for a specific information
    }

    public void saveInformation(String info) {
        //logic to process the information and save it to a file in a
        dbWriter.writeToDatabase(info);
    }
}

Of course, in this example we did minor changes, but in a real world application, changes to require time and effort, maybe even conflict with some existing functionalities.

Satisfying the DIP

A better design, which would satisfy the principle would be to make the WebCrawler class depend on an abstraction: an interface named PersistenceProvider. In this way, when we would want to introduce a new persistence provider we would just need to implement the interface and inject it in the WebCrawler class.

With the new design, the classes look like this:

public interface PersistenceProvider {

    public void saveInformation(String information);
}

public class FileWriter implements PersistenceProvider{

    private Path file;

    public FileWriter(Path file){
        this.file = file;
    }

    @Override
    public void saveInformation(String information) {
        //logic to save the information to a file 
    }
}

public class DatabaseWriter implements PersistenceProvider{
    // some configuration variables for the DB connection

    public DatabaseWriter(){
        // logic to initiate the connection
    }

    @Override
    public void saveInformation(String information) {
        // logiwrite to save the information in the database
    }

}


public class WebCrawler {

    PersistenceProvider persistenceProvider;

    public WebCrawler(PersistenceProvider persistenceProvider){
        this.persistenceProvider = persistenceProvider;
    }

    public void setPersistenceProvider(){

    }

    public String extractInfoFromHttpPage(String url) {
        //logic to make a GET request to a HTTP Page search for a specific information a search for a specific information
    }

    public void saveInformation(String info) {
        //logic to process the information and save it to a file in a
        persistenceProvider.saveInformation(info);
    }
} 

Now, this design ensures we don’t have to change the high level class when introducing changes into the low level classes, because the high level class depends on abstractions from the low level ones.

Conclusion

This is a very powerful principle used in many modern applications and frameworks, no matter of the programming language used.

Interface segregation principle

Standard

SOLID is a set of 5 principles for design in object oriented programming, defined by Robert C. Martin.

  • Single-responsibility principle
  • Open-closed principle
  • Liskov substitution principle
  • Interface segregation principle
  • Dependency Inversion principle

Interface segregation principle – ISP

The official definition:

Make fine grained interfaces that are client specific. Clients should not be forced to depend upon interfaces that they do not use.

The principle definition basically says it all: when designing interfaces, they should only do one thing, describe one behavior. As you can see this principles is related with the single responsibility principle.

Or what?

If this principle is violated, the interface we design will provide a lot of functionalities, not just a single one. This way, the implementing classes will be forced to implement all the methods they don’t use. This kind of interfaces are called "fat". The design proposed by this principle is to break fat interfaces into many interfaces, each doing one thing.

Lets talk code

Example of violation of ISP: let’s assume we have a farm with animals; in the beginning we have only pigs and cows. We model the Animal interface and the Pig and Cow classes.

public interface Animal {
    public void walk();
    public void eat();
    public void sleap();
}


public class Cow implements Animal{

    @Override
    public void walk() {
        // implementation
    }

    @Override
    public void eat() {
        // implementation
    }

    @Override
    public void sleap() {
        // implementation
    }

}


public class Pig implements Animal{

    @Override
    public void walk() {
        // implementation
    }

    @Override
    public void eat() {
        // implementation
    }

    @Override
    public void sleap() {
        // implementation
    }
}

After the farm grows, we want to also bring ducks into it; the easy thing to do is, of course, extend the Animal interface with the fly and swim methods and implement the Duck class.

public interface Animal {
    public void walk();
    public void eat();
    public void sleap();
    public void fly();
    public void swim();
}


public class Duck implements Animal{

    @Override
    public void walk() {
        //implementation
    }

    @Override
    public void eat() {
        //implementation
    }

    @Override
    public void sleap() {
        //implementation
    }

    @Override
    public void fly() {
        //implementation
    }

    @Override
    public void swim() {
        //implementation
    }

}

Now, the problem is that we have to also modify the Pig and Cow classes and add stub implementation for fly and swim methods. This leads to unused methods in these classes and forces us to recompile them, which can be tricky in complex systems with many dependencies.

The solution is to use another design to separate the behaviors that the interfaces describe. The Animal interface remains at it was in the beginning and we add two other interfaces.

public interface Animal {
    public void walk();
    public void eat();
    public void sleap();
}


public interface FlyingAnimal extends Animal {

    public void fly();
}


public interface SwimmingAnimal extends Animal {

    public void swim();
}

Now, the Duck class looks like this:

public class Duck implements FlyingAnimal, SwimmingAnimal {

    //implementation for all the methods

}

Conclusion

Interface segregation principle is a very important one, even though it can seem the opposite at the first glance. It goes hand in hand with the other SOLID principles.

Liskov Substitution Principle

Standard

SOLID is a set of 5 principles for design in object oriented programming, defined by Robert C. Martin.

  • Single-responsibility principle
  • Open-closed principle
  • Liskov substitution principle
  • Interface segregation principle
  • Dependency Inversion principle

Liskov substitution principle – LSP

The official definition:

Derived classes must be substitutable for their base classes

When you extend a PARENT class you must make sure not to change it’s functionality in the CHILD class. In this way, in a block of code that uses the PARENT class you can substitute it with the CHILD and it will work the same.

Or what?

If this principle is violated, introducing new classes in existing class hierarchies and replacing a PARENT type with a CHILD type, can introduce unpredictable behaviors/defects. This can lead to OCP violation because you can be forced to change the PARENT class as a consequence.

Lets talk code

The simple and famous example of LSP violation is making the following. We have first a Rectangle class for which we want to calculate the area:

public class Rectangle {
    protected int length;
    protected int width;

    public void setLength(int length){
        this.length = length;
    }

    public void setWidth(int width) {
        this.width = width;
    }

    public int getLength() {
        return length;
    }

    public int getWidth() {
        return width;
    }

    public int calculateArea(){
        return this.length * this.width;
    }
}

And the main method which outputs 6:

public static void main(String args[]) {
    Rectangle s = RectangleFactory.getRectangle();
    s.setLength(3);
    s.setWidht(2);
    System.out.println(s.calculateArea());
}

static class RectangleFactory {

    static Rectangle getRectangle() {
        return new Rectangle();
    }

}

Now, if we want to add also a Square to our program and of course we can be tempted to implement the Square type as a sub-type of the Rectangle class; naturally we think of a Square as a particular type of Rectangle.

public class Square extends Rectangle {

    public void setLength(int length) {
        this.length = length;
        this.width = length;
    }

    public void setWidth(int width) {
        this.width = width;
        this.length = widht;
    }
}

We change the Factory to use the Square type and the area is now 4; this is not what the client expected which is 6. This shows how LSP is violated, because Square and Rectangle types can’t be used interchangeably, with the same results.

public static void main(String args[]) {
    Rectangle s = RectangleFactory.getRectangle();
    s.setLength(3);
    s.setWidht(2);
    System.out.println(s.calculateArea());
}

static class RectangleFactory {

    static Rectangle getRectangle() {
        return new Square();
    }
}

In this example, a better design would be the Square class not to extend the Rectangle class.

Conclusion

Simply put: follow the IS-A principle. If the CHILD type IS-A PARENT, it should act like it. LSP goes hand in hand with OCP.

Open-Closed Principle

Standard

SOLID is a set of 5 principles for design in object oriented programming, defined by Robert C. Martin.

  • Single-responsibility principle
  • Open-closed principle
  • Liskov substitution principle
  • Interface segregation principle
  • Dependency Inversion principle

Open-Closed Principle – OCP

This is the second article in the series which discusses 5 basic object oriented design principles called SOLID. In the last post I presented the first one – SRP. Here I will write about the second one, Open-Closed Principle.

The official definition:

A software entity should be open for extension and closed for modification.

So, the way to enhance software is to extend them, not to change.

Or what?

If this principle is violated software modules can not be enhanced by extending them. Also, if changes introduced can impact the functionality of the current system and also can generate the need for other changes.

This principle is achieved by using abstractions.

It is strongly related with the SRP. If OCP is violated by extending a class through change it means that it will have more than one responsibility and SRP gets violated too.

Lets talk code

Lets say we have a GUI application which must draw circle and square shapes.

public class GUI {

    void drawCircle(Point origin, double radius){
        // draw circle code
    }

    void drawSquare(Point origina, double length){
        // draw square code
    }
}

This design violates the OCP because if we want to extend the application to draw also a triangle, we must change the GUI class.

A better design is to use abstractions and to create a Shape interface which is implemented by Circle and Square.

public interface Shape {

    void draw();
}


public class Circle implements Shape{

    @Override
    public void draw() {
        // draw code
    }

}


public class Square implements Shape{

    @Override
    public void draw() {
        // draw code
    }

}

The GUI class uses the Shape abstraction when drawing:

public class GUI {

    void drawShape(Shape sh) {
        sh.draw();
    }
}

If we want to extend the solution to draw also a triangle, we don’t have to change the GUI class. Just extend the class list by adding Triangle:

public class Triangle implements Shape{

    @Override
    public void draw() {
        // draw code
    }

}

Conclusion

Key point here is to use abstraction to enforce a closed system. The abstraction doesn’t change, just the implementations are extended.

If you want to read more about OCP check out:

Single responsibility principle

Standard

SOLID is a set of 5 principles for design in object oriented programming, defined by Robert C. Martin.

  • Single-responsibility principle
  • Open-closed principle
  • Liskov substitution principle
  • Interface segregation principle
  • Dependency Inversion principle

Single-reponsability principle – SRP

As the name indicates, this principle forces a class to have a single responsibility. The official definition is: A class should have one, and only one, reason to change.
e

Or what?

If this principle is violated and a class has at least two responsibilities, when a change occurs for one of them it is very likely that it will affect the other ones as well. This translates to changing more code than we would need.
Basically, loosely coupled responsibilities are promoted here and putting them into separate classes is the first step in achieving that.

What is a responsibility?

Responsibility = "reason to change" – as simple as that. To check if there are multiple responsibilities in a class, you should think the other way around: "How many motives of change would this class have?" If the answer is > 1 , you should extract responsibilities out of it.

Lets talk code

This Employee class violates SPR because it has business logic that calculates the salary and bonus and also the responsibility to persist the data.

public class Employee {

    private String name;
    private double salary;
    private double bonus;

    double calculateBonus() {
        // formula to calculate bonus
    }

    double calculateSalary() {
        // formula to calculate salary
    }

    void saveEmployee() {
        // create DB connection
        // save in DB
    }
}

Let’s extract the responsibilities in separate classes. The employee can be a POJO.

public class EmployeePojo {
    private String name;
    private double salary;
    private double bonus;
}

The business logic responsibility:

public class BusinessLogic {

    double calculateSalary(EmployeePojo emp){
        //calculate salary for employee
    }

    double calculateBonus(Employee pojo emp){
        //calculate bonus for employee
    }
}

Responsability to persist – manage DB connection and save employee data:

public class DBPersistence {

    Connection createDBConnection(){
        // create DB connection
    }

    void saveEmployee(EmployeePojo emp){
        // save employee
    }
}

The client code where the business logic class calculates salary&bonus and persistence is :

public class MainClass {
    public static void main(String args[]){
        EmployeePojo emp = new EmployeePojo();
        BusinessLogic bl = BusinessLogic.getInstance();
        emp.setBonus(bl.calculateBonus(emp));
        emp.setSalary(bl.calculateSalary(emp));
        DBPersistence p = DBPersistence.getInstance();
        p.saveEmployee(emp);
    }
}

Conclusion

As the author says, this is one of the most simple principles in object oriented design, but one of the hardest to get right. It happens mainly because it’s hard to spot multiple responsibilities. If you want to read more about SPR check out:

Concurrent programming in Java – Synchronizers

Standard

The synchronizers

  • Semaphore controls access to one or more shared resources.
  • Phaser is used to support a synchronization barrier.
  • CountDownLatch allows threads to wait for a countdown to complete.
  • Exchanger supports exchanging data between two threads.
  • CyclicBarrier enables threads to wait at a predefined execution point.

Semaphore

A semaphore is an object used for synchronization over a shared resource : in general to restrict the number of threads that can access a resource.

For accessing the resource threads must first try to acquire a permit from the semaphore. Inside it maintains a counter and if the counter is greater than zero the access is granted and the counter decremented. If the counter is zero, access is not granted until some other thread releases the resource.

The most important methods are:

- void acquire() and void acquire(int permits) - Acquires one/the given number of permit from this semaphore, blocking until one/all are available available.
- void release() and void release(int permits) - Releases a/given number of permits.

Let’s take an example to better understand. In a family with 4 children the kitchen has a table with only 2 seats. This means that they have to eat in 2 rounds.
First let’s create the Person class.

public class Person extends Thread {

    private Semaphore tableSeats;
    private String name;

    public Person(String name, Semaphore tableSeats) {
        this.tableSeats = tableSeats;
        this.name = name;
    }

    public void run() {
        try {
            System.out.println(this.name + " is trying to occupy a place at the table");
            this.tableSeats.acquire();
            System.out.println(this.name + " occupied a place at the table");
            Thread.sleep(2000);
            this.tableSeats.release();
            System.out.println(this.name + " left the table");
        } catch (InterruptedException ex) {
            System.out.println(this.name + " could not aquire a seat on the table");
        }
    }

}

Now let’s create the test class that simulates the table and the people eating.

public class SemaphoreTest {

    public static void main(String args[]) {
// a table with 2 seats
        Semaphore tableSeats = new Semaphore(2);
        Person Mike = new Person("Mike", tableSeats);
        Person John = new Person("John", tableSeats);
        Person Dan = new Person("Dan", tableSeats);
        Person Bill = new Person("Bill", tableSeats);
        Mike.start();
        John.start();
        Dan.start();
        Bill.start();
    }
}

The output of the SemaphoreTest program looks like below. You can see how at first all the threads try to occupy a seat (acquire the semaphore). Only 2 Bill and Mike occupy the seats first. Then Bill leaves and John joins the table. Then Mike leaves and Dan occupies the table.

Mike is trying to occupy a place at the table
Bill is trying to occupy a place at the table
Dan is trying to occupy a place at the table
John is trying to occupy a place at the table
Bill occupied a place at the table
Mike occupied a place at the table
Bill left the table
John occupied a place at the table
Mike left the table
Dan occupied a place at the table
John left the table
Dan left the table

This demonstrates the use and purpose of the semaphore.

Phaser

A phaser is an object used for synchronization when multiple threads have to work together in phases to complete a task. The important methods from the Phaser class are:

- register() - increments the internal counter
- arriveAndAwaitAdvance() - this method decrements the counter and waits for it to arrive to 0 in order to continue processing.
- arriveAndDeregister() - this method decrements the counter and deregisters the phaser. 

Let’s take an example of a Fast Food restaurant that server Burger Menus. Each order is made of a Burger, a Juice and fries. Let’s say we have three orders to make in the order they came.

First we construct the Worker class. This takes the phaser object which is used by the workers for synchronization of the orders to be processed:

class WorkerThread extends Thread {

    private final Phaser phaser;
    private final String name;

    public WorkerThread(Phaser phaser, String name) {
        this.phaser = phaser;
        this.phaser.register();
        this.name = name;
    }

    @Override
    public void run() {
        try {
            for (int i = 1; i <= 3; i++) {
                System.out.println("Worker " + name + " for BurgerMenu number " + i);
                this.phaser.arriveAndAwaitAdvance();
                Thread.sleep(2000);
                if (i == 2) {
                    this.phaser.arriveAndDeregister();
                }
            }
        } catch (InterruptedException ex) {
            Logger.getLogger(WorkerThread.class.getName()).log(Level.SEVERE, null, ex);
        }

    }
}

Now let’s take a look at the BurgerFastFood class. This constructs and starts the worker threads that are responsible to bring the juice, the burger and the fries.

public class BurgerFastFood {

    public static void main(String args[]) {
        Phaser phaser = new Phaser();
        WorkerThread bringsJuice = new WorkerThread(phaser, "brings juice");
        WorkerThread bringsBurger = new WorkerThread(phaser, "brings burger");
        WorkerThread bringsFries = new WorkerThread(phaser, "brings fries");
        bringsJuice.start();
        bringsBurger.start();
        bringsFries.start();
    }
}

The output of the program shows how the threads are working in phases to deliver each order:

Worker brings juice for BurgerMenu number 1
Worker brings burger for BurgerMenu number 1
Worker brings fries for BurgerMenu number 1
Worker brings fries for BurgerMenu number 2
Worker brings juice for BurgerMenu number 2
Worker brings burger for BurgerMenu number 2
Worker brings fries for BurgerMenu number 3
Worker brings burger for BurgerMenu number 3
Worker brings juice for BurgerMenu number 3

CountDownLatch

This class provides "a synchronization aid that allows one or more threads to wait until a set of operations being performed in other threads completes.
A CountDownLatch is initialized with a given count. The await methods block until the current count reaches zero due to invocations of the countDown() method, after which all waiting threads are released and any subsequent invocations of await return immediately.
This is a one-shot phenomenon — the count cannot be reset." – taken from the CountDownLatch javadoc.
The most important methods of the:

- await() - blocks the code execution until the inner counter is 0.
- countDown() - decrements the inner counter by 1.

Let’s take an example to better understand. Let’s say we want to simulate a football game. We have 3 parties that must be ready before the match starts: both the teams and the referee. So, we will start with the FootballTeam class – it takes the countdown latch as a parameter and uses it :

class FootballTeam extends Thread {

    private CountDownLatch referee;
    private String name;

    public FootballTeam(CountDownLatch referee, String name) {
        this.referee = referee;
        this.name = name;
    }

    public void run() {
        try {
            System.out.println(name + " is preparing for the game start");
            this.referee.countDown();
            System.out.println(name + " is READY to start...");
            Thread.sleep(1000);
            this.referee.await();
        } catch (InterruptedException ex) {
            Logger.getLogger(FootballTeam.class.getName()).log(Level.SEVERE, null, ex);
        }

    }
}

Then we have the Football Match class which creates the two teams and the referee (the countdown latch).

public class FootballMatch {

    public static void main(String args[]) {
        try {
            CountDownLatch referee = new CountDownLatch(3);
            FootballTeam redTeam = new FootballTeam(referee, "Red team");
            FootballTeam blueTeam = new FootballTeam(referee, "Blue team");
            redTeam.start();
            blueTeam.start();
            referee.countDown();
            referee.await();
            System.out.println("Referee blows the wistle and game starts");
        } catch (InterruptedException ex) {
            Logger.getLogger(FootballMatch.class.getName()).log(Level.SEVERE, null, ex);
        }
    }
} 

The output created by this program is showing how all the threads advance only after they are all ready:

Blue team is preparing for the game start
Blue team is READY to start...
Red team is preparing for the game start
Red team is READY to start...
Referee blows the wistle and game starts

Exchanger

The exchanger class is used when two threads need to share data between them. It can be seen as a messenger which delivers a package between two people. The most important method of this class is:

V exchange(V object)

It delivers the message object and receives the message object from the other party.
To better understand let’s take an example when we have two people presenting themselves (thus exchanging messages).

public class ExchangerTest {

    public static void main(String args[]) {
        Exchanger<String> ex = new Exchanger<>();
        John john = new John(ex);
        Jane jane = new Jane(ex);
        jane.setPriority(Thread.MAX_PRIORITY);
        john.setPriority(Thread.MIN_PRIORITY);
        jane.start();
        john.start();
    }
}

class John extends Thread {

    private String name = "John";
    private Exchanger<String> exchanger;

    public John(Exchanger<String> exchanger) {
        this.name = name;
        this.exchanger = exchanger;
    }

    public void run() {
        try {
            String message = exchanger.exchange(name + ": Hello. My name is " + name);
            System.out.println(message);
        } catch (InterruptedException ex) {
            // do something
        }
    }
}

class Jane extends Thread {

    private String name = "Jane";
    private Exchanger<String> exchanger;

    public Jane(Exchanger<String> exchanger) {
        this.name = name;
        this.exchanger = exchanger;
    }

    public void run() {
        try {
            String message = exchanger.exchange(name + ": Nice to meet you. My name is " + name);
            System.out.println(message);
        } catch (InterruptedException ex) {
            //do something
        }
    }
}

The result is:

John: Hello. My name is John
Jane: Nice to meet you. My name is Jane

or:

Jane: Nice to meet you. My name is Jane
John: Hello. My name is John

depending on how the JVM allocates the threads to execute.

We have two threads representing John and Jane. Jane is set with higher priority and is started first because it prints the message from John and we want to force the simulation of John starting the conversation and Jane responding.

CyclicBarrier

The CyclicBarrier class is used when two or more parties need to wait for a predefined execution point. When the object is created it registers a number of threads to wait for/to block before releasing the execution again. This number is specified in the constructor.

The important methods are:

- int await() - blocks executions until the specified number of parties have called this method and returns the arrival index of this thread.
- int await(long timeout, TimeUnit unit) - blocks executions until the specified number of parties have called this method or after the time elapses. 

We will take an example similar as we did with the CountDownLatch. We want to simulate a football game, so we have 3 parties that must be ready before the match starts: both the teams and the referee. The match begins after the teams are ready and the referee blows the whistle.

First we have the football team class. Here the teams prepare for the match and when they are ready to start, invoke the await() method on the CyclicBarrier object.

class FootballTeam extends Thread {

    private CyclicBarrier barrier;
    private String name;

    public FootballTeam(CyclicBarrier referee, String name) {
        this.barrier = referee;
        this.name = name;
    }

    public void run() {
        try {
            System.out.println(name + " is preparing for the game start");
            System.out.println(name + " is READY to start...");
            this.barrier.await();
            System.out.println(name + " started to play");
        } catch (BrokenBarrierException | InterruptedException ex) {
            Logger.getLogger(FootballTeam.class.getName()).log(Level.SEVERE, null, ex);
        }

    }
}

Then we have the football match class where the football team threads are created and started and also the referee (current main thread) starts the match.

public class FootballMatch {

    public static void main(String args[]) throws BrokenBarrierException {
        try {
            CyclicBarrier barrier = new CyclicBarrier(3);
            FootballTeam redTeam = new FootballTeam(barrier, "Red team");
            FootballTeam blueTeam = new FootballTeam(barrier, "Blue team");
            redTeam.start();
            blueTeam.start();
            Thread.sleep(2000);
            barrier.await();
            System.out.println("Referee blows the wistle and game starts");
        } catch (InterruptedException ex) {
            Logger.getLogger(FootballMatch.class.getName()).log(Level.SEVERE, null, ex);
        }
    }
}

The output of running this program is:

Red team is preparing for the game start
Blue team is preparing for the game start
Blue team is READY to start...
Red team is READY to start...
Referee blows the wistle and game starts
Blue team started to play
Red team started to play

Concurrent programming in Java – the basics

Standard

Concurrent programming in Java is based on working with Threads – Thread is a class from the java.lang package and it extends the java.lang.Runnable interface.

The interface Runnable declares 1 method:

  • public void run() – the code to be executed when the thread is executed.

The Thread class implements Runnable and has multiple methods, most important would be:

  • void start() – begins execution of this thread’s run method.
  • boolean isAlive() – checks if this thread is alive (has started and has not yet died).
  • void join() – blocking call which waits for the thread to die.
  • void setPriority(int priority)

To create a Thread you can either:

  • extend the Thread class.
  • implement the Runnable interface and then instantiate a new Thread and give the Runnable object as it’s target.

Implementing the Runnable interface – this has an advantage because you can extend another class and implement other interfaces.

    public class RunnableWorker implements Runnable {

        @Override
        public void run() {
            // worker logic
        }

        public static void main(String args[]) {
            // create the Runnable class
            RunnableWorker worker = new RunnableWorker();
            // create the thread object with the Thread target
            Thread thread = new Thread(worker);
            // start the Thread to execute
            thread.start();
        }
    }

Extending the Thread class.

    public class ThreadClass extends Thread {

        public void run() {
            // worker logic
        }

        public static void main(String args[]) {
            // create the thread object
            ThreadClass thread = new ThreadClass();
            // start the thread
            thread.start();
        }
    }

The important states of the Thread:

  • NEW – Thread was created but is not yet started.
  • RUNNABLE – thread is executing.
  • TERMINATED – thread has exited.

Another important thing when working with threads in Java, is to understand the use of wait() and notify() methods. They are defined on the Object class, so every object in Java has them. They are used as a way to communicate between threads and synchronize in situations that demand this.

Concurrent programming problems

Data Race and Thread Synchronization

The situation in which multiple threads are accessing the same resource – a variable, a collection, etc, and are trying to modify it, is known as a data race or race condition. To avoid this situation you have to make sure that only one thread has access to the resource at a given point of time.

Avoiding a data race can be done with thread synchronization by using the synchronized keyword. You can synchronize a whole method or you can just synchronize a block of code. Synchronization is basically done by threads acquiring a lock when entering a block of code and then releasing it. In Java any object has a lock which can be used for synchronization. In general, synchronizing whole methods is not a good approach because it induces performance issues.

Deadlocks

A deadlock is a popular problem which occurs when two threads are waiting for two resources, each waiting for the resource locked by the other. To be more concrete consider this example: one thread T1 acquires a lock on resource R1 and waits to acquire another on resource R2. At the same time, say there is another thread T2 that has already acquired R2 and is waiting to obtain a lock on R1. This is known as a deadlock and it means neither of
the threads can proceed until the other one releases the lock, which never happens and the program execution is locked. Deadlocks are very hard to find in the code either at design time or run time. You can find more information on Wikipedia here: https://en.wikipedia.org/wiki/Deadlock and you can find a Java example of deadlock here https://docs.oracle.com/javase/tutorial/essential/concurrency/deadlock.html .

Livelocks

A livelock is another popular resource starvation problem, similar to a deadlock, the difference being that each process changes it state with respect to the other one. The code execution is unable to make any progress. A very good analogy of livelock with the real world is presented on Oracle’s website here : "…two people attempting to pass each other in a corridor: Alphonse moves to his left to let Gaston pass, while Gaston moves to his right to let Alphonse pass. Seeing that they are still blocking each other, Alphone moves to his right, while Gaston moves to his left. They’re still blocking each other"

Starvation

The starvation problem is somehow self explanatory. A good description is given on the Oracle’s website specified above: "…a situation where a thread is unable to gain regular access to shared resources and is unable to make progress. This happens when shared resources are made unavailable for long periods by "greedy" threads."

Sets in Java

Standard

The Set interface in Java describes a collection of elements with no duplicates.

The most important implementations of the Set interface are:

  • HashSet – maintains no order
  • TreeSet – maintains natural ordering or ordered by a Comparator
  • LinkedHashSet – maintains insertion order

HashSet implementation

The HashSet implementation is backed by a HashMap collection. As HashMap does, it also permits a null element.

An example of use is:

Set<String> s = new HashSet<>();
s.add("Dog");
s.add("Cat");
s.add("Dog");
System.out.println(s);

As the Set contains no duplicates, the code above prints : [Cat, Dog]

Now let’s dig into the HashSet implementation. The class is declared like this:

public class HashSet<E>
extends AbstractSet<E>
implements Set<E>, Cloneable, java.io.Serializable
{
.....
    private transient HashMap<E,Object> map;

    // Dummy value to associate with an Object in the backing Map
    private static final Object PRESENT = new Object();

We see in the code that it implements the Set interface and it uses a HashMap object to hold the elements.

Adding an element is very simple:

public boolean add(E e) {
    return map.put(e, PRESENT)==null;
}

We see that the element is added as the key and the value used is the dummy object.

Simple is also the removal:

public boolean remove(Object o) {
    return map.remove(o)==PRESENT;
}

And the check if element is contained:

public boolean contains(Object o) {
    return map.containsKey(o);
}

Iteration over the collection:

Iterator<String> it = s.iterator();
while(it.hasNext()) {
    System.out.println(it.next());
}

or a simple way of writing:

for(String e : s) {
    System.out.println(e);
}

For a detailed look on the HashMap internals check this article.

TreeSet implementation

The TreeSet implementation is backed by a TreeMap. As the Java docs state "the elements are ordered using their natural ordering, or by a Comparator provided at set creation time, depending on which constructor is used."

The TreeSet class definition looks like this :

public class TreeSet<E> extends AbstractSet<E>
implements NavigableSet<E>, Cloneable, java.io.Serializable
{
/**
 The backing map.
 */
private transient NavigableMap<E,Object> m;

// Dummy value to associate with an Object in the backing Map
private static final Object PRESENT = new Object();

The no-arg constructor constructs the backing TreeMap:

public TreeSet() {
    this(new TreeMap<E,Object>());
}

The other useful constructor is the one that sets the comparator:

public TreeSet(Comparator<? super E> comparator) {
    this(new TreeMap<>(comparator));
}

The addition, removal, contains check and iteration are the same as for the HashSet implementation.

LinkedHashSet implementation

This class extends the HashSet and is backed by a LinkedHashMap. This ensures the order of insertion is maintained, unlike the HashSet which doesn’t maintain any order of the elements.

The LinkedHashSet is defined like this:

public class LinkedHashSet<E>
    extends HashSet<E>
    implements Set<E>, Cloneable, java.io.Serializable {

Since it extends HashSet, the addition, removal, contains check and iteration are the same as for the HashSet implementation.

Collections in Java – the basics

Standard

Collections in Java – basics


Java offers common collection activities include adding objects, removing objects, verifying object inclusion, retrieving objects, and iterating. Generally speaking, collections can hold only objects, but primitives can be auto-boxed.

We have four basic flavors of collections:

  • java.util.List : describes a list of things; is ordered, has an index and allows duplicates
  • java.util.Set : describes a set of things; may be ordered and/or sorted, does not allow duplicates
  • java.util.Map : describes a map of things with keys; may be ordered and/or sorted, does not allow duplicate keys
  • java.util.Queue : describes a queue of things to process; ordered by priority or FIFO

Collections my be:

  • sorted : the elements are kept in a sorted order
  • unsorted
  • ordered : the elements can be iterated in a collection specific, non-random order
  • unordered

Common LIST implementing classes:

  • Vector – implementation of an array with the possibility to re-size automatically. the components are index accessible. all its methods are synchronized
  • ArrayList – similar with Vector but the methods are not synchronized; fast iteration and random access
  • LinkedList – implementation of a doubly linked list; fast to add elements to both ends
  • Stack – basic implementation of a stack (LIFO) ; extends the Vector class.

Common SET implementing classes:

  • HashSet – fast access, no order, no duplicates. the set is backed by a map.
  • LinkedHashSet – keeps insertion order, no duplicates
  • TreeSet – keeps sorted order, no duplicates

Common MAP implementing classes:

  • Hashtable – slow implementation of map because has synchronized methods; no null keys, no null values
  • HashMap – fast retrieve; faster add/remove; allows only one null key
  • LinkedHashMap – keeps insertion order, faster iteration
  • TreeMap – sorted map
  • ConcurentHashMap – "supporting full concurrency of retrievals and adjustable expected concurrency for updates" as the official javadoc states.

Common Queue implementing classes:

  • PriorityQueue – queue ordered by priority

Another important interface to talk about is the Iterator.

java.util.Iterator

Describes an iterator over a collection. The java.util.Collection interface provides a method to retrieve an Iterator. A classic example of using an iterator is:

Collection<String> c = *initialize and populate*
Iterator<String> it = c.iterator();

while( it.hasNext() ) {
    String s = it.next();
// do something with the string
    System.out.println(s);
}

There are two utility classes provided by the JDK, to work with collections: java.util.Collections and java.util.Arrays . These classes frequently use Comparators or the collections/arrays elements must implement Comparable. For using Comparable and Comparators, keep reading this article.

java.util.Collections

Provides the following common methods. This is a top view, so for more details check the javadocs here.

  • addAll(Collection c, T… elements) – useful when having an array to add in a collection
  • binarySearch() – used to search in a sorted collection. check all the binarySearch methods in the javadocs
  • min() and max()
  • replaceAll()
  • reverse()
  • sort()
  • synchronizedCollection() , synchronizedList() , synchronizedMap() , synchronizedSet() – retrieves a thread-safe type of collection backed by the specified one.

java.util.Arrays

Provides the following common methods. This is a top view, so for more details check the javadocs here.

  • asList() – returns a List object backed by the specified array
  • binarySearch() – used to search in a pre-sorted array. check all the methods in the javadoc
  • equals() – used to check two arrays of equality
  • sort() – used to sort the specified array