The gem I found is in the java.util.concurrent.Flow package and consists of Producer, Subscriber and a Subscription with an optional Processor.

The end goal

We will make a machine that will find prime numbers for us using the Sieve of Eratosthenes. The method in its simplicity is the fact that once you found a prime number, any multiple of that prime cannot be prime.

This will utilize the above components and I will explain the concepts as I also show the code.

Overview

The root directory structure and files will be as follows:

processors
publishers
subscribers
subscriptions
util
CyclicRingBuffer.java
Main.java

Of course the CyclicRingBuffer stands out, we will get back to that one shortly.

First will be the util ones as they are small and concise and easy to explain.

util

In util there are three files:

• ConcurrentUtil.java
• PrimeUtil.java
• StatisticsUtil.java

ConcurrentUtil.java

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

public class ConcurrentUtil {

    public static ExecutorService executorService =   Executors.newWorkStealingPool();
}

This particular static method will just get us a ExecutorService so we can schedule work to be done in the background. You put tasks on a queue of sorts and the jobs will get executed for you in the background.

PrimeUtil.java

import java.util.List;
import java.util.concurrent.CopyOnWriteArrayList;
import java.util.concurrent.atomic.AtomicInteger;

public class PrimeUtil {

    public static List<Integer> primes = new CopyOnWriteArrayList<>();
    public static AtomicInteger demand = new AtomicInteger(Integer.parseInt(System.getenv().getOrDefault("PRIMEFINDER_DEMAND", "100")));

    static {
        primes.add(2);
    }
}

So this class exists to hold the primes found so far with a concurrent thread safe CopyOnWriteArrayList so that simultaneous operations do not matter. Then we have an AtomicInteger that gets made by an environment variable or a default of 100. This demand is our end goal of how many primes to find.

Then we need to prime, pun intended (always own your puns), the list by putting in 2 as that will make our lives way easier down the line.

StatisticsUtil.java

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

public class StatisticsUtil {

    public static Map<String, Integer> stats = new ConcurrentHashMap<>();
}

So this class is there to keep a simple ConcurrentHashMap filled with the name of the class and how many primes they found.

That is all for the util . Let's dive into the more fun parts.

Subscription

First we will start with the subscription. Inside the subscriptions package there is one file named IntegerSubscription.java . What a subscription is, is a class that produces some output on one of the method calls you have to implement, namely request(long l) and can be cancelled by calling cancel(). This cancelling means no more messages can flow further into the subscribers.

If l is smaller than 0 in the request function then an error needs to be produced.

So the subscription has a method called request and it gets called by a subscriber .

public class IntegerSubscription implements Flow.Subscription  {

    private IntegerPublisher integerPublisher;
    private Iterator<Integer> integerStream;
    private boolean isCanceled = false;

    public IntegerSubscription(IntegerPublisher integerPublisher) {
        this.integerPublisher = integerPublisher;
        this.integerStream = Stream.iterate(2, i -> i + 1).iterator();
    }

    @Override
    public void request(long l) {
        if ( l < 0) {
            integerPublisher.publish(new IllegalArgumentException("Have to request a positive number of elements"));
        }
        for(long i = 0; i < l; i++) {
            if(isCanceled) {
                break;
            }
            executorService.submit(() -> integerPublisher.publish(integerStream.next()));
        }
    }

    @Override
    public void cancel() {
        isCanceled = true;
    }
}

There are a few parts, so first in the constructor we see a Publisher more on that later. Then we see a way to produce an infinite stream of Integers. Then in request we see the actual work by giving the publisher the next integer in the stream to publish. This gets given to the ExecutorService we saw earlier in order to put this on the backlog of things to execute.

Publisher

So the publisher is the part that actually glues the subscriptions and the subscribers. There is a little more logic in here, but not a whole lot more. Inside the publishers package there are two files:

• IntegerPublisher.java
• IntegerPublisherImpl.java

import java.util.concurrent.Flow;

public interface IntegerPublisher extends Flow.Publisher<Integer> {

    void publish(int i);

    void publish(IllegalArgumentException e);
}

This first file is just an interface with two methods that are not needed by the Flow framework but exist for my convenience and to make it easier to follow everything.

import CyclicRingBuffer;
import subscriptions.IntegerSubscription;

import java.util.Objects;
import java.util.concurrent.*;
import static util.ConcurrentUtil.executorService;

public class IntegerPublisherImpl implements IntegerPublisher  {

    private final IntegerSubscription subscription;
    private final CyclicRingBuffer<Flow.Subscriber<? super Integer>> subscribers;

    public IntegerPublisherImpl() {
        this.subscription = new IntegerSubscription(this);
        subscribers = new CyclicRingBuffer<>();
    }

    @Override
    public void subscribe(Flow.Subscriber<? super Integer> subscriber) {
        subscribers.push(subscriber);
        executorService.submit(() -> subscriber.onSubscribe(this.subscription));
    }

    private void shutdown(boolean cancel) {
        if (cancel) {
            this.subscription.cancel();
        } else {
            for (Flow.Subscriber<? super Integer> subscriber : subscribers) {
                subscriber.onComplete();
            }
        }

        executorService.shutdown();

    }

    public void publish(int i) {
        executorService.submit(() -> Objects.requireNonNull(subscribers.poll()).onNext(i));
    }

    public void publish(IllegalArgumentException e) {
        executorService.submit(() -> Objects.requireNonNull(subscribers.poll()).onError(e));
    }

    public void sendShutdown(boolean cancel) {
        this.shutdown(cancel);
    }
}

So this class binds Subscriptions and Subscribers together. Well a subscription will produce an output and call the publish function to publish it to the subscribers of this subscription. The CyclicRingBuffer here will be explained later. Furthermore we have an actual method called subscribe that takes in a Subscriber with a certain bounded type, in my case Integer. We give the subscriber in question the subscription to subscribe to and then the circle is complete and things can get moving.

In the publish method the onNext gets called of the subscriber. That will be the actual processing logic of what we want to do with our Integers. So far we only saw who produces them (Subscription) and who syndicates them (Publisher) and now we see who processes them.

Subscriber

The subscriber requests data from the subscription in question. So the onSubscribe initialises the requesting of data from the subscription. Then the onNext will hold the main logic and at the end always call more request of the subscription if you want to keep things in motion. There is also onComplete when all is said and done and onError which should be called anytime an error occurs in the chain and needs to be propagated to the actual subscriber.

import util.StatisticsUtil;
import java.util.UUID;
import java.util.concurrent.Flow;
import java.util.logging.Level;
import java.util.logging.Logger;

import static util.PrimeUtil.demand;
import static util.PrimeUtil.primes;
import static util.ConcurrentUtil.executorService;

public class PrimeFinder implements Flow.Subscriber<Integer> {

    private final String name;
    private Flow.Subscription subscription;
    private static Logger LOGGER;

    public PrimeFinder() {
        this.name = String.format("%s-%s", this.getClass().getName(), UUID.randomUUID());
        LOGGER = Logger.getLogger(this.name);
    }

    @Override
    public void onSubscribe(Flow.Subscription subscription) {
        subscription.request(1);
        this.subscription = subscription;
        StatisticsUtil.stats.putIfAbsent(this.name, 0);
    }

    @Override
    public void onNext(Integer integer) {
        LOGGER.log(Level.FINE, String.format("I'm %s working on %d", name, integer));

        if (primes.parallelStream().noneMatch(p -> integer % p == 0)) {
            if(demand.getAndDecrement() > 0) {
                primes.add(integer);
                LOGGER.log(Level.INFO, String.format("%d found by me: %s", integer, name));
                int newCount = StatisticsUtil.stats.get(this.name) + 1;
                StatisticsUtil.stats.put(this.name, newCount);
            }
        }
        if(demand.get() > 0) {
            executorService.submit(() -> subscription.request(1));
        }
    }

    @Override
    public void onError(Throwable throwable) {
        LOGGER.log(Level.SEVERE, throwable.getMessage());
    }

    @Override
    public void onComplete() {
        LOGGER.log(Level.INFO, name + " is done");
    }
}

So the onError and onComplete methods are just logging methods. The onSubscribe kickstarts the whole operation. The first thing that happens is request from the subscription in question and then setting that subscription locally to this instance so we can request more from it later on. Then finally register this instance in the StatisticsUtil so the score can be kept on who got how many primes.

Then onNext gets an integer, via the subscription through the publisher, and first checks if it does not occur in the Sieve. This line does all the work:

primes.parallelStream().noneMatch(p -> integer % p == 0)

The explanation is turn the primes list into a parallel stream. Then check if none match the expression given afterwards. The expression will check if the number to be worked on modulo the prime will give 0. This means that the integer given can be divided exactly by the prime and therefore it is not a prime. If the integer cannot be divided by any of the primes found so far then we have a new prime!!

Then it gets and decrements the demand in order to see if we still have to find more primes. If so then add it to the stats and the list of found primes.

Then a new check to demand is made, some other subscriber could have found the last one in the mean time, and then requests more from the subscription if more need to be found.

CyclicRingBuffer

The CyclicRingBuffer is a data structure that lets you cycle through a list endlessly and so it makes perfect sense in this case as I want to infinitely round robin the subscribers to publish the new data to them. How to implement it is by extending a well known class in Java and then overriding a few key methods.

import java.util.concurrent.ConcurrentLinkedDeque;

public class CyclicRingBuffer<E> extends ConcurrentLinkedDeque<E> {

    public E poll() {
        E e = super.pollFirst();

        assert e != null;

        this.offerLast(e);
        return e;
    }

    public E pollFirst() {
        E e = super.pollFirst();

        assert e != null;

        this.offerLast(e);
        return e;
    }

    public E pollLast() {
        E e = super.pollLast();

        assert e != null;

        this.offerFirst(e);
        return e;
    }

}

So the Deque is a queue where you can add both at the front and the back and take from both sides. It is a Double Ended Queue (Deque). So these three methods just implement that logic. If you take from the front you add the element to the back again and also if you take from the rear add it to the front.

Main

The main file puts everything together by hooking up all the necessary parts. Just remember, the flow is Subscriber requests data from a Subscription that should ask the Publisher to publish to all who are subscribed to that particular Subscription.

import publishers.IntegerPublisherImpl;
import subscribers.PrimeFinder;
import util.PrimeUtil;
import util.StatisticsUtil;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.Flow;
import java.util.concurrent.TimeUnit;
import java.util.logging.Level;
import java.util.logging.Logger;


public class Main {
    final static int totalSubscribers = Runtime.getRuntime().availableProcessors();
    private static final Logger LOGGER = Logger.getAnonymousLogger();

    public static void main(String[] args) throws InterruptedException {
        IntegerPublisherImpl integerPublisher = new IntegerPublisherImpl();
        List<Flow.Subscriber<Integer>> subscribers = new ArrayList<>();

        for (int i = 0; i < totalSubscribers; i++) {
            subscribers.add(new PrimeFinder());
        }
        subscribers.forEach(integerPublisher::subscribe);

        while (PrimeUtil.demand.get() > 0 ) {
            TimeUnit.MILLISECONDS.sleep(100);
        }
        integerPublisher.sendShutdown(false);
        StatisticsUtil.stats.forEach((name, count) -> LOGGER.log(Level.INFO, String.format("%s found %d", name, count)));
        LOGGER.log(Level.INFO, PrimeUtil.primes.toString());
    }
}

This code gets the available processors and creates that many subscribers. Then each of those subscribers get the same subscription to the Integer stream. Then there is a sleep moment until all is found and they are then being nicely shutdown and the statistics of who found what is then printed out.

Why not both

So in order to chain things you can create Processors. They are subscribers and publishers at the same time, but of potential different types. For example a Publisher of Strings but a Subscriber of Integers. In other words you put String things in and out should come Integers to the next Subscriber or Processor .

The main benefit is you can transmute things but also have one Processor start off many other chains with the same data. For example one word can be counted for in length, how many vowels, what kind of word it is, what language and so on. As this processor is just a hub to kick off many other flows, it makes more sense maybe to think of our Prime finder example and then just extend it by operating on the primes found.

Seeing if we found sexy primes or cousin primes for example.

#code #java

Oracles

Why do objects need to be immutable and what does it even mean? Well to be immutable mean you are not allowed to change a property of the object but you are allowed to assign a whole new reference to the variable for example. Like with String in Java, and with strings in most other languages. You cannot change a part of the String in the middle but you are allowed to assign a new String to a variable declared.

String s = "StealthyCoder";
s = "Coding Ninjas"; 

What you want is the fact that s, in this case, will hold a truth and that truth will not easily be changed halfway true except very explicitly.

In this case you want s to be a so called oracle. It needs to be able to tell you what the source of truth is at this specific moment in time.

DTOs

In the REST API world, there is a pattern that consists of DTOs, Entities, Services and Controllers. In which a Controller is responsible for making sure a route has a method associated with it. The Entities are responsible for modeling the Database tables. The Services are responsible for handling Entities and making business logic decisions. The DTOs are responsible for being the truthful state of the world.

This leads to stating that DTOs, and also to an extent Entities, should be immutable as it was just stated that oracles are there to provide truths. In the REST API we will be making, the fact is that whatever the frontend will be sending as an input should be immutable once it is in the backend as we do not want any code to be able to accidentally change something. Also the generation of a response should be once only.

The following project outline and code will provide some examples on how to achieve this using the Quarkus framework.

Outline

├── build.gradle
├── docker-compose.yml
├── Dockerfile
├── gradle.properties
├── settings.gradle
└── src
    └── main
        ├── java
        │   └── com
        │       └── stealthycoder
        │           └── dto
        │               ├── models
        │               │   ├── dto
        │               │   │   ├── GiftRequestDTO.java
        │               │   │   └── GiftResponseDTO.java
        │               │   └── entity
        │               │       └── Gift.java
        │               ├── routes
        │               │   └── gifts
        │               │       └── GiftResource.java
        │               └── services
        │                   └── SantaClausService.java
        └── resources
            └── application.properties

build.gradle

The contents of the build.gradle file are as follows:

plugins {
    id 'java'
    id 'io.quarkus' version "${quarkusVersion}"
}

repositories {
     mavenCentral()
}

test {
  useJUnitPlatform()
}

dependencies {
    implementation 'io.quarkus:quarkus-resteasy-jackson'
    implementation 'io.quarkus:quarkus-hibernate-orm'
    implementation 'io.quarkus:quarkus-jdbc-postgresql'
    implementation enforcedPlatform("io.quarkus:quarkus-bom:${quarkusVersion}")

    testImplementation 'io.quarkus:quarkus-junit5'
    testImplementation 'io.rest-assured:rest-assured'
}
group 'com.stealthycoder'
version '0.0.1-SNAPSHOT'

sourceCompatibility = 14

This just sets up the necessary dependencies for our project and the extensions for Quarkus in order to handle JSON serialization (quarkus-resteasy-jackson) and connect to Postgres (quarkus-jdbc-postgresql) for example.

docker-compose.yml

The contents of the docker-compose.yml file are as follows:

version: '3.6'

networks:
  quarkus:
    name: quarkus

services:
  api:
    container_name: api.dto.local
    build:
      context: .
      dockerfile: 'Dockerfile'
    environment:
      PG_HOST: database
      PG_USER: dto
      PG_PASS: dto
      PG_DATABASE: dto
    ports:
      - "8080:8080"
    networks:
      - quarkus
  database:
    image: postgres:13-alpine
    container_name: db.dto.local
    environment:
      POSTGRES_PASSWORD: dto
      POSTGRES_USER: dto
      POSTGRES_DB: dto
    stdin_open: true
    tty: true
    networks:
      - quarkus

This sets us up so we have a running container and database we can use locally for our development purposes. I chose to build the image for the API because I was reluctant this time to install Gradle on the docker image or indeed use a ready made Gradle image to run the tooling in there.

Dockerfile

The contents of the Dockerfile are as follows:

FROM adoptopenjdk/openjdk14:alpine-slim

COPY build/com.stealthycoder.dto-0.0.1-SNAPSHOT-runner.jar /srv/http/quarkus.jar
COPY build/lib /srv/http/lib

CMD ["/opt/java/openjdk/bin/java", "-jar", "/srv/http/quarkus.jar" ]

Very straightforward, copy a jar into a named other jar and copy the lib folder as well as it needs that to be able to load the dependencies and start it. The name of the jar depends on the group name and the structure of the package and of a setting in the settings.gradle file.

gradle.properties

The contents of the gradle.properties file is as follows:

quarkusVersion=1.8.1.Final

settings.gradle

The contents of the settings.gradle file are as follows:

pluginManagement {
    repositories {
        mavenLocal()
        mavenCentral()
        gradlePluginPortal()
    }
}
rootProject.name = 'com.stealthycoder.dto'

That rootProject.name will mostly determine the naming together with the version of build.gradle.

application.properties

The contents of the application.properties file are as follows:

quarkus.datasource.db-kind = pg
quarkus.datasource.jdbc.url = jdbc:postgresql://${PG_HOST:localhost}/${PG_DATABASE:database}
quarkus.datasource.username=${PG_USER:user}
quarkus.datasource.password=${PG_PASS:password}
quarkus.hibernate-orm.database.generation=${HIBERNATE_GENERATION:drop-and-create}
quarkus.http.access-log.enabled=true
quarkus.http.access-log.pattern="%h "%r" %s"
quarkus.resteasy.gzip.enabled=true
quarkus.resteasy.gzip.max-input=10M

This will set the connection to the database based on Environment variables with some defaults. The HIBERNATE_GENERATION should only be set to drop-and-create the very first time you run the application as it will otherwise consistently delete your previous data.

GiftResource.java

The contents of the GiftResource.java are as follows:

package com.stealthycoder.dto.routes.gifts;

import com.stealthycoder.dto.models.dto.GiftRequestDTO;
import com.stealthycoder.dto.models.dto.GiftResponseDTO;
import com.stealthycoder.dto.services.SantaClausService;

import javax.inject.Inject;
import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.PATCH;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import java.util.Objects;
import java.util.UUID;

@Path("/gift")
public final class GiftResource {

    @Inject
    SantaClausService service;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    @Path("{id}")
    public Response get(@PathParam("id") UUID uuid) {
        GiftResponseDTO gift = service.getGift(uuid);
        if (Objects.isNull(gift)) {
            return Response.status(Response.Status.NOT_FOUND).build();
        }
        return Response.ok(gift).build();
    }

    @POST
    @Produces(MediaType.APPLICATION_JSON)
    @Consumes(MediaType.APPLICATION_JSON)
    public Response add(GiftRequestDTO giftRequestDTO) {
        return Response.ok(service.createGift(giftRequestDTO)).build();
    }

    @PATCH
    @Produces(MediaType.APPLICATION_JSON)
    @Consumes(MediaType.APPLICATION_JSON)
    @Path("{id}")
    public Response update(@PathParam("id") UUID uuid, GiftRequestDTO giftRequestDTO) {
        GiftResponseDTO responseDTO = service.updateGift(uuid, giftRequestDTO);
        if (Objects.isNull(responseDTO)) {
            return Response.status(Response.Status.NOT_FOUND).build();
        }
        return Response.ok(responseDTO).build();
    }

}

This file will create routes for GET, POST and PATCH on the path /gift. From this we can also determine that the service SantaClausService returns DTOs and also accepts DTOs. The Produces and Consumes annotations help with making sure the serialization will work alright. So in this case the fact is the method will get an instance of the GiftRequestDTO class to be able to use for further processing.

GiftRequestDTO.java

The contents of the GiftRequestDTO.java file are as follows:

package com.stealthycoder.dto.models.dto;

import com.fasterxml.jackson.annotation.JsonAutoDetect;

@JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.ANY)
public final class GiftRequestDTO {
    private String name;
    private String wrapper;
    private boolean expensive;
    private boolean fragile;

    public String getName(){
        return name;
    }

    public String getWrapper() {
        return wrapper;
    }

    public boolean isExpensive() {
        return expensive;
    }

    public boolean isFragile() {
        return fragile;
    }
}

The important bits to note are the fields are all private. Another is that there are only so called getters . The thing that ties it all together is to tell Jackson to allow to use reflection on all fields so it can set even private fields to values. This is what will make the DTO immutable for further processing. Of course there are ways around this as it was just stated that even Jackson can do mutations to private fields. Also the class is marked as final meaning you cannot extend it in some way and therefore cast it and still make changes.

GiftResponseDTO.java

The contents of the GiftResponseDTO.java are as follows:

package com.stealthycoder.dto.models.dto;

import com.fasterxml.jackson.annotation.JsonAutoDetect;

import java.util.UUID;

@JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.PROTECTED_AND_PUBLIC)
public final class GiftResponseDTO {
    protected UUID id;
    protected String name;
    protected String wrapper;
    protected boolean expensive;
    protected boolean fragile;

    public final static class Builder {
        private String name;
        private String wrapper;
        private boolean expensive;
        private boolean fragile;
        private UUID id;

        public Builder withName(String name) {
            this.name = name;
            return this;
        }

        public Builder withWrapper(String wrapper) {
            this.wrapper = wrapper;
            return this;
        }

        public Builder isExpensive(boolean expensive) {
            this.expensive = expensive;
            return this;
        }

        public Builder isFragile(boolean fragile) {
            this.fragile = fragile;
            return this;
        }

        public Builder withId(UUID id) {
            this.id = id;
            return this;
        }

        public GiftResponseDTO build() {
            GiftResponseDTO responseDTO = new GiftResponseDTO();
            responseDTO.name = this.name;
            responseDTO.wrapper = this.wrapper;
            responseDTO.expensive = this.expensive;
            responseDTO.fragile = this.fragile;
            responseDTO.id = this.id;
            return responseDTO;
        }
    }
}

Here there is a bit more going on. First off Jackson is instructed to allow protected fields as well. This time there are no getters or so called setters. There is a Builder class in there though. This is the so named Builder pattern. The gist is to have a static Builder class that you instantiate and all methods except build() will return the instance itself. This causes a Fluent API to emerge where you can in a declarative way set the properties that you need and then even pass around the Builder instance if you wanted to produce carbon copies but separate instances each time by subsequently calling the build() method. The reason for the protected one is because then the Builder can instantiate a new instance of the class GiftResponseDTO and then be allowed to set the properties.

Gift.java

The contents of the Gift.java file are as follows:

package com.stealthycoder.dto.models.entity;

import org.hibernate.annotations.Type;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import java.util.Objects;
import java.util.UUID;

@Entity
public class Gift {
    private UUID id;
    private String name;
    private String wrappingPaper;
    private Boolean expensive;
    private Boolean fragile;


    @Id
    @GeneratedValue
    @Type(type = "uuid-char")
    public UUID getId() {
        return id;
    }

    public void setId(UUID id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        if (Objects.isNull(this.name) && Objects.nonNull(name)) {
            this.name = name;
        }
    }

    public String getWrappingPaper() {
        return wrappingPaper;
    }

    public void setWrappingPaper(String wrappingPaper) {
        if (Objects.isNull(this.wrappingPaper) && Objects.nonNull(wrappingPaper)) {
            this.wrappingPaper = wrappingPaper;
        }
    }

    public boolean isExpensive() {
        return expensive;
    }

    public void setExpensive(Boolean expensive) {
        if (Objects.isNull(this.expensive) && Objects.nonNull(expensive)) {
            this.expensive = expensive;
        }
    }

    public boolean isFragile() {
        return fragile;
    }

    public void setFragile(Boolean fragile) {
        if (Objects.isNull(this.fragile) && Objects.nonNull(fragile)) {
            this.fragile = fragile;
        }
    }
}

So this class has the Entity annotation to mark it as an entity for the Hibernate framework to do it's magic. There is a novel approach here by having a sort of immutability by allowing the properties to be only set once. This is because the Entity should reflect the database values and it should be explicit when you want to do updates, not just willy-nilly throughout the services. This is the reason for the usage of the Boolean boxing instead of using boolean. A primitive like boolean will automatically become false in the checking for isNull.

SantaClausService.java

The contents of the SantaClausService.java are as follows:

package com.stealthycoder.dto.services;

import com.stealthycoder.dto.models.dto.GiftRequestDTO;
import com.stealthycoder.dto.models.dto.GiftResponseDTO;
import com.stealthycoder.dto.models.entity.Gift;

import javax.enterprise.context.ApplicationScoped;
import javax.inject.Inject;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import javax.transaction.Transactional;
import java.util.Objects;
import java.util.UUID;

@ApplicationScoped
public final class SantaClausService {

    @PersistenceContext
    EntityManager em;

    @Transactional
    public GiftResponseDTO createGift(GiftRequestDTO newGift){
        Gift gift = fromDTO(newGift);
        em.persist(gift);
        return toDTO(gift);
    }

    @Transactional
    public GiftResponseDTO updateGift(UUID uuid, GiftRequestDTO updatedGiftDto) {
        Gift originalGift = em.find(Gift.class, uuid);
        if (Objects.isNull(originalGift)) {
            return null;
        }

        Gift updatedGift = fromDTO(updatedGiftDto);
        updatedGift.setId(uuid);
        updatedGift.setWrappingPaper(originalGift.getWrappingPaper());
        updatedGift.setFragile(originalGift.isFragile());
        updatedGift.setExpensive(originalGift.isExpensive());
        updatedGift.setName(originalGift.getName());

        updatedGift = em.merge(updatedGift);
        em.flush();

        return toDTO(updatedGift);
    }

    public GiftResponseDTO getGift(UUID uuid) {
        return toDTO(em.find(Gift.class, uuid));
    }

    private GiftResponseDTO toDTO(Gift gift) {
        if (Objects.isNull(gift)) {
            return null;
        }
        return new GiftResponseDTO.Builder()
                .withName(gift.getName())
                .withWrapper(gift.getWrappingPaper())
                .isExpensive(gift.isExpensive())
                .isFragile(gift.isFragile())
                .withId(gift.getId())
                .build();
    }

    private Gift fromDTO(GiftRequestDTO requestDTO) {
        Gift gift = new Gift();
        gift.setName(requestDTO.getName());
        gift.setExpensive(requestDTO.isExpensive());
        gift.setFragile(requestDTO.isFragile());
        gift.setWrappingPaper(requestDTO.getWrapper());
        return gift;
    }
}

So here is the meat of the whole application basically. There are two helper methods that either take in an Entity and transmogrify it into a DTO or the other way around. Here is where we use the Builder to build the DTO. There is only one place now in the application where GiftResponseDTO classes can be instantiated and therefore after this service nobody can change it. The Gift that comes back from the helper method fromDTO might have properties that still can be set. Namely they can be still null.

The create and get methods are quite self explanatory. The update one might require some more explanation. So we get a DTO and we turn it into a Gift entity. Then we get the one that is currently in the database. That will set the Persistence Context to that object. Then we update the Gift from the DTO to set the properties that were not set yet (i.e. are still null), meaning the properties that were set override the ones in the database. Then the em.merge happens which will give back the representation in the database of the newly updated Gift with the correct properties. Then the em.flush call will make sure this is actually persisted/synchronised with the database.

The Transactional annotations make sure the methods will be transactional and that means if something fails at all, it will not be persisted and rolled back.

Getting started

After you copied all the content and setup the project exactly as is and have Gradle installed, run the following command in the root of the project: gradle quarkusBuild . Then run docker-compose up . Next use your favourite API exploration tool to POST something to http://localhost:8080/gift and see what happens.

Conclusion

I hope that the patterns above can be useful for you when you want to have immutability in Java and in general. I think this pattern is quite powerful as it also makes you think about what you are doing and what you want to change and where and why. This makes it transparent who generates the instances, who mutates them and what is being changed. Also I quite like the novel approach of only allowing to set the properties once.

Also I really like Quarkus. It gives you enough control but still allows for very fast development. It has some cool patterns like Event driven design out of the box as well as Reactive programming. Check out their guides.

#code #java

import java.util.function.Supplier;
import java.util.UUID;


public class Quirky {
  private Supplier<UUID> id;
  private Supplier<String> name;


  public Supplier<UUID> getId() {
    return this.id;
  }

  public Supplier<String> getName() {
    return this.name;
  }

  public void setId(UUID id) {
    this.id = () -> { return id; };
  }

  public void setId(Supplier<UUID> id) {
    this.id = id;
  }

  public void setName(String name) {
    this.name = () -> { return name; };
  }

  public void setName(Supplier<String> name) {
    this.name = name;
  }

}

The idea was to turn the properties into Suppliers and therefore you would get to do some functional style flows. I am not sure yet how it will fit in with other patterns. For example to set the id you would do :

Quirky q = new Quirky();
q.setId(UUID.randomUUID());

Then to retrieve the id you would do :

q.getId().get();

There is the fact you have to do double gets that feel weird. If you wanted to make a random Quirky you could do the following:

Quirky q = new Quirky();
q.setId(() -> { return UUID.randomUUID();});

Then every following call to getId().get() will return a new UUID.

One thing I did want to implement were the double setters . One will wrap a value into a simple supplier but you could also augment that.

public void setName(String name) {
    this.name = () -> { return name.toUpperCase(); };
  }

Now the normal method will always return all caps. There can also be logging and other side effects.

Hopefully you will read this and think of something somewhere to use it. Also I have the feeling somewhere functional programmers woke up and are going to bombard me with Monads, Functors and similar corrigenda.

#code #java

var greetings = {
 hello: function() { console.info("Hello"); }
};
greetings.hello();
greetings["hello"]();

This is how functions could be shipped around. So the idea is simple, especially the second one. I started to wonder if we can have a Map of String -> Function in other languages like Java, Python, PHP and more?

Java

We sure can. I was working on a JSON-RPC project where you don't send entity bodies but you send what method to invoke and with what arguments. In the backend we made it so internally a consistent object was shipped around (RPCServiceResult) and we had Enum for the methods that were allowed. So I set up an EnumMap of Enum -> Function. This made it so the entrypoint of each service was the same. See if the method key exists, if so execute the corresponding function with the given input otherwise throw a MethodNotFound error. This meant we could extend the Enum and EnumMap and the Function mapping but never had to change how the services called each other.

Python

In Python I was working on a silly hacking simulation game in the Console. I wanted to have a list of commands and execute the corresponding function that was that command in game terms. At this point I just came from PHP and there it is completely normal to execute the string itself. I will come back to this in a bit. This is more difficult to do in Python and so I came up with a dict where command name was the key and function references were the values. This made it super simple to maintain.

PHP

So in PHP this is normal:

function a(){ echo "A"; };
$a = "a";
$a();

However it is really difficult to maintain and see what is going on, let alone insecure to do this if the input to $a is user input. The following makes more sense and is easier to maintain.

function a() { echo "A"; };
$commands = ["a" => function() { call_user_func("a"); }];
if ( array_key_exists("a", $commands) ) { $commands["a"](); }

Granted this is a contrived example but I hope it gets the point across.

Scala

I was working on the Advent of Code 2020 and one of the puzzles had a lot of validation rules. Immediately the structure came to mind of having a Map of Functions, for each field to validate the corresponding function. This worked like a charm and it is very easy to see what each rule does.

Java

Another example was that in a particular flow there was a need to either create a User of type A or type B and then continue the flow. It was first like the following:

if ( type == "UserA" ) {
    return new UserA();
} else {
    return new UserB();
}

Now never mind the bug of always returning type B, I suggested the following:

Map<String, Supplier<User>> userSupplier = new HashMap<>(){{ put("UserA", UserA::new); put("UserB", UserB::new); }};

Now you could replace it with one entrypoint:

return userSupplier.getOrDefault(type, UserB::new).get();

You still have the bug, but it became a feature. So we leave it in. The colleague immediately said, this happens in way more places in the code and I can change all of them.

The nice thing again is, we can extend the map to support more types but it does not change the logic of calling the service.

Conclusion

I hope this concept proves useful to you, I find it quite powerful and easy to construct and it gives lots of nice patterns.

#code #javascript #java #python

Let's say you are building an object, you have the materials ready to build it and at some step you have to ask another party for some information. Based on that information you will either add a piece or not to your build.

This means you have to also know the domain knowledge of what that third party knows and also how to attach it to your build. For every one of these kind of steps.

Would it not be nicer to just hand off the build sign an agreement that party is responsible the time it is in their care and have them give it back with or without modifications depending on the same information you had before.

Of course it would be nice to understand what is going on at the party in order to maintain it yourself, but let us just say that it is free forever to have the party maintain your build.

Now in code

Now in code we can do the same, even in Java where everything is passed by value. Just make sure to wrap it in something, a POJO for example or basically anything that is a class instance.

First the normal way of doing things:

var l = new ArrayList<String>();

if (l.isEmpty()) {  
   l.add("s");
}
if (l.contains("s")) {
     l.removeAll("s");
     l.add("x");
}

Is this a contrived example of course it is.

So we ask first if it is empty then add something. Then otherwise we remove and add elements if it does contain something. What if we did something like the following:

var l = new ArrayList<String>();

Consumer<List<String>> ifEmptyAddS = (l) -> { var b = l.isEmpty() && l.add("s"); };
Consumer<List<String>> removeAllSAddX = (l) -> { l.removeAll(l.stream().filter(s -> s.equalsIgnoreCase("s")).collect(Collectors.toList())); l.add("x");};

ifEmptyAddS.andThen(removeAllSAddX).accept(l);

Now we just hand over the whole list over to the party and have them operate on it. The flow is very easily managed and if the naming is chosen a bit nicely you can read it out and just see what is going on. Like for example, why is removeAllSAddX doing it in such a complicated way? You can change that if needed, but it works and it might be better for future proofing the process according to them.

It also makes it so you are responsible for making sure the right persons in the right order get your build but they are all responsible for what they do to it. That is a nice separation of concerns.

#devlife #code #java

Reactive Programming

The concept this framework is based on is reactive programming. This means you effectively set up conveyor belts on which data will sit and be passed around a factory as part of a chain of operations that will make the raw material into the end product you want.

You get the record from the database, pass it along to the service to transform it into a DTO and then pass it to the controller that transforms it into a HTTPResponse for example.

All of this is non blocking I/O. From the database to the response to the user. This means the CPU is always doing something to progress one process or another. I quite liked this feature. The problem is building these conveyor belts.

Data flow

The flow is sometimes difficult to visualise. It does not help that you can only start flows buy so called subscribing. Then sometimes you want to do two things with the data at two different places but you cannot easily do that. In normal non reactive programming you would for example create a variable that holds some data and send that data to two functions. You could do that asynchronous with CompletableFuture or just regular old synchronous.

I had a hard time grasping every thing and sometimes when things did not work it was because of the flow being wrong or incorrect. Especially when handling errors and stopping the flow. I learned you should handle errors and then send along nulls for example as the next one will not get the null. Optionals might also work but provides more work checking it later in the flow, downstream.

Keep it small

If you keep the functions themselves as small as possible and named correctly you can at least read the flow in a understandable way. It is also important to make it simple at the top and more and more complex the deeper you go. This means if you understand abstractly what needs to happen and then it does not happen you go one layer deeper. Usually the lowest level is fine, i.e. getting the data from some resource. The top level is usually also fine, i.e. sending the response to the user.

It is that middle bit where you do the transformations and business logic where it seems to often go awry.

Adding new functionality to an existing flow is simple and complex at the same time. You have to make sure you give back the same output as before or make sure the input of the next step gets adjusted. It makes it quite finicky to correctly in one try insert new steps.

I would recommend it to at least try out. It might not suit your style, but it does give some great concepts in structuring your application and data flows.

#devlife #code #java

Then I sprinkled some log() statements around and it surfaced that the data import/export I was doing had some unfortunate data that Long.parseLong() did not agree with and threw a NumberFormatException. That however was nowhere in my code to catch and so it failed silently.

This meant I could see the job starting and for all intents and purposes see it do nothing afterwards.

Lesson learned, always have a doOnError on each of your flows.

#code #devops #java

Integer Subscription

In the subscription we will use a internal ExecutorService to handle the input.

import publishers.IntegerPublisher;
import java.util.Iterator;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Flow;
import java.util.concurrent.TimeUnit;
import java.util.stream.Stream;

public class IntegerSubscription implements Flow.Subscription  {

    private IntegerPublisher integerPublisher;
    private Iterator<Integer> integerStream;
    private final AtomicBoolean isCanceled = new AtomicBoolean();
    private final ExecutorService executorService = Executors.newFixedThreadPool(Runtime.getRuntime().availableProcessors());

    public IntegerSubscription(IntegerPublisher integerPublisher) {
        this.integerPublisher = integerPublisher;
        this.integerStream = Stream.iterate(2, i -> i + 1).iterator();
    }

    @Override
    public void request(long l) {
        if ( l < 0) {
            integerPublisher.publish(new IllegalArgumentException("Have to request a positive number of elements"));
        }
        executorService.submit(this.handleRequests(l));
        
    }

    private Runnable handleRequests(long l) {
        return () -> {
            for (long i = 0; i < l; i++) {
                if (isCanceled.get()) {
                    break;
                }
                integerPublisher.publish(integerStream.next());
            }
        };
    }

    @Override
    public void cancel() {
        isCanceled.set(true);
        executorService.shutdown();
        try {
            executorService.awaitTermination(5L, TimeUnit.SECONDS);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
    }
}

Publisher

In the publisher take out the executorService parts. One of the major problems was actually that the publisher itself was on the executorService somewhere and so it would never shutdown. Also I did not call the onComplete and therefore the executorService would not shutdown correctly either.

import CyclicRingBuffer;
import subscriptions.IntegerSubscription;

import java.util.Objects;
import java.util.concurrent.*;

public class IntegerPublisherImpl implements IntegerPublisher  {

    private final IntegerSubscription subscription;
    private final CyclicRingBuffer<Flow.Subscriber<? super Integer>> subscribers;

    public IntegerPublisherImpl() {
        this.subscription = new IntegerSubscription(this);
        subscribers = new CyclicRingBuffer<>();
    }

    @Override
    public void subscribe(Flow.Subscriber<? super Integer> subscriber) {
        subscribers.push(subscriber);
        subscriber.onSubscribe(this.subscription);
    }

    private void shutdown(boolean cancel) {
        if (cancel) {
            this.subscription.cancel();
        } 
        for (Flow.Subscriber<? super Integer> subscriber : subscribers) {
           subscriber.onComplete();
        }

        executorService.shutdown();

    }

    public void publish(int i) {
        Flow.Subscriber<? super Integer> subscriber = subscribers.poll();
        if (Objects.nonNull(subscriber)) {
            subscriber.onNext(i);
        }
    }

    public void publish(IllegalArgumentException e) {
        Flow.Subscriber<? super Integer> subscriber = subscribers.poll();
        if (Objects.nonNull(subscriber)) {
            subscriber.onError(e);
        }
    }

    public void sendShutdown(boolean cancel) {
        this.shutdown(cancel);
    }
}

I learned that having everything on the ForkJoinPool with work stealing ethics causes a lot, but a lot, context switching and threads. So in my case the CPU just flared 100% on thread switching whilst not much was going on.

Subscriber

The subscriber will ask for Long.MAX_VALUE so it is essentially unbounded. Which is also in the documentation, so I should have just read that more carefully and think about it.

import util.StatisticsUtil;
import java.util.UUID;
import java.util.concurrent.Flow;
import java.util.logging.Level;
import java.util.logging.Logger;

import static util.PrimeUtil.demand;
import static util.PrimeUtil.primes;

public class PrimeFinder implements Flow.Subscriber<Integer> {

    private final String name;
    private static Logger LOGGER;

    public PrimeFinder() {
        this.name = String.format("%s-%s", this.getClass().getName(), UUID.randomUUID());
        LOGGER = Logger.getLogger(this.name);
    }

    @Override
    public void onSubscribe(Flow.Subscription subscription) {
        StatisticsUtil.stats.putIfAbsent(this.name, 0);
        subscription.request(Long.MAX_VALUE);
    }

    @Override
    public void onNext(Integer integer) {
        LOGGER.log(Level.FINE, String.format("I'm %s working on %d", name, integer));

        if (primes.parallelStream().noneMatch(p -> integer % p == 0)) {
            if(demand.getAndDecrement() > 0) {
                primes.add(integer);
                LOGGER.log(Level.INFO, String.format("%d found by me: %s", integer, name));
                int newCount = StatisticsUtil.stats.get(this.name) + 1;
                StatisticsUtil.stats.put(this.name, newCount);
            }
        }
    }

    @Override
    public void onError(Throwable throwable) {
        LOGGER.log(Level.SEVERE, throwable.getMessage());
    }

    @Override
    public void onComplete() {
        LOGGER.log(Level.INFO, name + " is done");
    }
}

Main

In the main not a lot gets changed. Number of totalSubscribers gets doubled and sending a true to sendShutdown to make sure the executorServices in question are shutdown and waited for until done.

import publishers.IntegerPublisherImpl;
import subscribers.PrimeFinder;
import util.PrimeUtil;
import util.StatisticsUtil;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.Flow;
import java.util.concurrent.TimeUnit;
import java.util.logging.Level;
import java.util.logging.Logger;


public class Main {
    final static int totalSubscribers = Runtime.getRuntime().availableProcessors() * 2;
    private static final Logger LOGGER = Logger.getAnonymousLogger();

    public static void main(String[] args) throws InterruptedException {
        IntegerPublisherImpl integerPublisher = new IntegerPublisherImpl();
        List<Flow.Subscriber<Integer>> subscribers = new ArrayList<>();

        for (int i = 0; i < totalSubscribers; i++) {
            subscribers.add(new PrimeFinder());
        }
        subscribers.forEach(integerPublisher::subscribe);

        while (PrimeUtil.demand.get() > 0 ) {
            TimeUnit.MILLISECONDS.sleep(100);
        }
        integerPublisher.sendShutdown(true);
        StatisticsUtil.stats.forEach((name, count) -> LOGGER.log(Level.INFO, String.format("%s found %d", name, count)));
        LOGGER.log(Level.INFO, PrimeUtil.primes.toString());
    }
}

This should flow way nicer and smoother. It should also provide a more even distribution amongst the subscribers. I have 8 subscribers and put in 1000 primes and it did it in close to 1 second. Which I find a nice result. It did not put a strain on my CPU as all other applications happily chugged along.

Final thoughts

I think about extending this into an example that has an error queue and so the publisher can also publish errors and log them. The nice thing is that in this case the publishing will still happen regardless of errors. The previous one would drop the subscriber as it would not request a new one, and therefore it had to wait a whole cycle until it was next to process a request and then it would request a new one. Let's say all errors happen in a row and all subscribers have to handle errors. Could happen, it is not unfathomable to know multiple errors happen in a row. Then the chain would die due to starvation of no new requests being made.

#code #java

It gets really difficult, like impossible, do to things like return a Mono<Void> that actually is returning some object. You cannot return null as that will internally by construed to be an empty Mono and won't trigger downstream. So that goes out the window, how about instantiating one via Void.TYPE.newInstance() ? Well that is not without it's own problems. It is deprecated and most likely can fail in any number of reasons plus make your code really unmanageable.

Never ever ever ever use it ?

Well you can if you know it is the end of the line, but for instance doing a .onErrorResume(Function<Throwable, ? extends Void>) is not a cool thing to do. Even if a Mono.then() will fix the problem it just makes everything so unnecessarily complex.

#java #reactive