5 years

I would say even 5 years ago it was really bad. It was not secure and frameworks were lacking professionalism. To be honest I would say PHP is still bad today.

Criticisms

The criticisms to bad structure, SQL injections and general security related things are all batted away with one statement: use frameworks. Just use a framework and magically all things are fixed. That is a lie. The fundamental nature of PHP will make it be bad, no matter how many cool awesome things you build on top of it.

Also frameworks themselves are also not foolproof and still will suffer from security flaws. Aside from this there are some other problems. Just search for all the CVE's of your favourite framework. They still occur across the board.

Concurrency / parallelism

The main problem with PHP is that it is not async in any way. It does not support threads, multiprocess or other constructs to make it concurrent or scalable in that sense. It just does not utilize the CPU efficiently. This also is combated in the original article by stating just throw more servers at it. Also the database is the bottleneck in all architectures, just scale that first then you can scale the application too.

This is just nonsense. The database is hardly ever the real bottleneck. I made many applications, enterprise and non-enterprise, and I did not once run into the issue the database could not cope with the amount that was requested. Inefficient queries, sure, lots of request to the webserver, sure, but not that the database was struggling and the application was doing just fine.

The fact you should not have to throw more servers at it is what is important. I worked on a simple Java application using Spring Boot and HATEOAS. This application is used by 100s of concurrent users. I only need to run one instance of this application to handle all of that. It is not even one giant instance with lots of resources, it has 2vCPU and 4Gb memory. That is all that is needed to support complex workflows for 100s of concurrent users. The database is a modest t3.small instance.

Code itself

Of course PHP has typehinting these days and namespacing and all good things, but it still suffers from the same problem outlined in this article subtracted with the addendum of this article. The core is trying to get better but it still is weak. I think the author of the article is referring to this ten year opinion.

The tools you get are still slightly different from normal tools. So the things that get built with them are all slightly wonky.

Deployments

To deploy PHP is horrible. Same goes for Python, because it is not a compiled language. So to make artifacts and deploy consistent code is actually quite difficult. Putting them in a container does not help as you always need a webserver to serve the PHP code. Same for Python where you need something like Gunicorn or similar to wrap around the code. Unless you wrote a server yourself.

It also just is not fun to write PHP.

#code #devops

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

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

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

The code I wrote is on this repo here. I chose the name because I liked the autogenerated one GitHub gave me. Also I am not showing this repo because I want you to view some epic god-like tier code that happens to be Scala, no. It is just to show you what you can do with Scala and how it seems to fit these kind of problems really really well.

Perfect fit

When I started the problems are really simplistic, like doing some mathematical operations on a list of numbers or processing matrices. Some of the earlier ones can be solved naively and in a brute-force kind of way. Later on that won't work anymore as the inputs will be too big to compute or hold in memory on most devices.

For these kind of problems where a lot happens on lists of things, that is usually the input, Scala just offers a variety of tools to operate on these lists. For instance the .sliding() or .grouped() operations. What they essentially do is go over a list and per whatever size and step size you choose give you back the elements. For instance the list [1,2,3,4,5] with sliding(3,1) operating on it will give back: [1,2,3],[2,3,4],[3,4,5]

This operation is very useful in these situations as most often you have to compare the neighbouring elements. So you sort a list, do a sliding operation and then some functional mapping and you get the answer.

Nice structures

The structures arising out of Scala code is one I really like. There exist a couple of concepts and I will only talk about the ones I used. The first is a object. It is similar to a Singleton class idea in normal Java. It holds static methods and variables. This is not to say you cannot have a variable in there outside of methods but it is not usual.

Then exists the normal class like everywhere else. However you can combine this class with an object to create a hybrid. You can therefore apply logic in a nice way and keep everything separated. Then exists the case class concept where you have a very minimal class with just property accessors. You can have these properties be immutable (default) or mutable (use the var keyword in front of it). They can be likened to the new Record concept in Java that also exists in other languages. The case class can have one or more methods, but preferably not.

Then there also exists the concept of a case object. This is super minimal one that does not even take in parameters and holds anything. So why would you use this? Well for example in enumeration it is really helpful or when passing messages. When you want to easily pass around an object that conveys what needs to be done. I used this to represent the cardinal directions. Then I could easily pass around these and use them to implement some logic.

Concurrent programming

This is by far the easiest to do in Scala than compared to Java. You just wrap it in a Future and have an implicit executor. What does it look like? Like this:

def line_of_sight(layout: Array[Array[Seat]]): Unit = {
    var futures : List[Future[Unit]] = List.empty

    futures +:= Future { north(layout) }
    futures +:= Future { north_east(layout) }
    futures +:= Future { east(layout) }
    futures +:= Future { south_east(layout) }
    futures +:= Future { south(layout) }
    futures +:= Future { south_west(layout) }
    futures +:= Future { west(layout) }
    futures +:= Future { north_west(layout) }

    ConcurrencyUtil.awaitAll(futures)

  }

This is taken from day 11. That is it. Now all those functions will be concurrent.

I hope I will find a project soon where I can use this language to its full potential.

#code #scala

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

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

Catalyst is something released by GitHub that is their vanilla JavaScript library of good patterns to make web components more easily. They themselves use it to make the UI of GitHub. This got me thinking on Web Components again and recently I took the journey to whatever happened to the rel=import in HTML <link> tag.

Web Components

This idea started a while back already, maybe around six years ago or so. The idea that you would be able to create custom elements (tags) in HTML with their own scoped CSS and JavaScript in so called Shadow DOM so you could better create reusable components and complex UIs with modern paradigms. Also making HTML carry more of the load and since it should be responsible for structure this is a good move to make.

This all sounds great, we currently have a bunch of them; Shadow DOM, Custom Elements and templates and slots. I won't go into too much detail concerning these but one thing is missing from this and Google thought of it.

Imports

Being able to import HTML files into your current web page that holds all those custom elements code would be amazing. Google thought of this, and implemented it. It even made a framework around it, Polymer. It moved too fast though. Other vendors, at the time Microsoft and Mozilla did not want to implement it. Seemingly it was because Microsoft could not implement it for Internet Explorer and Edge was quite a long ways away. Mozilla just did not want to because it found that imports were already solved by ES modules that you could import. You can read about that here. Note that Google abandoned it in version 73 that is from 2019-03-12. So not that long ago.

Modules

These days you can make so called modules and they can relatively import each other. The caveat is that is done with JavaScript only. It is true that part of making it work with custom elements is JavaScript but the main part are the <template> and <slot> tags that make them work. So this would mean you can currently put the code in modules and still have to have the HTML strewn about.

Broken ideas

So currently we have a broken idea, that will never be implemented because Mozilla is too egotistical. The idea is a good idea, even though it came from your competitor does not make the idea any less viable. I am with Mozilla, I do not like Google on the whole either and I am very happy Mozilla stays in the browser war fight. I use Firefox to type this article currently, and it is my preferred browser by far for a long time already. Still this idea looked so cool and still looks like such a boon to Web development on the whole. The source of an idea does not affect the idea. It does affect how it will be received, conveyed and communicated though.

New Framework

I also followed this CommitStrip comic, I have a cool idea for a framework though.

First let me say this problem can be fixed server side for sure. Just like HTML templates exist there for MVC frameworks you can include and load and do things there that will substitute the need for the rel=import, however that implies you need an application server again to support this. I think it is stronger to have the browser be able to do this. Therefore, I propose the following.

Have an entrypoint in a normal <script> tag that sets some data. Or load it in an index.mjs, just one entrypoint. The entrypoint will use a single method of the framework feeding a config object that will download the html files and inject them into the page. Setting up all the Custom Elements for you, bringing the rel=import back into the browser.

In all seriousness, I wish Mozilla and Google would reconcile and implement this.

#devlife #code

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

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