Implement Java’s compareTo() the right way

Mon, 27 Apr 2026 09:33:07 +0000

Java’s Comparable#compareTo() looks simple, but small mistakes can create issues that are difficult to find — especially with sorted collections like TreeSet and TreeMap, which rely on ordering to determine uniqueness.

Why do you need `compareTo()`?

Java’s Comparable interface defines a method for comparing two objects. This can be used to sort your objects in their natural order. Typical examples for natural ordering are

String → alphabetical order
LocalDate → chronological order

In business code, natural ordering should represent the most common and expected meaning of “sorted”. For example, sorting line items by position in an order is usually what humans expect.

How to implement `compareTo()`

A correct compareTo() must follow these rules:

Anti-symmetric: signum(a.compareTo(b)) == -signum(b.compareTo(a))
Transitive: If a > b and b > c, then a > c
Consistent: If a.compareTo(b) == 0, they are considered equal in ordering

Also: it is recommended (but not required) that compareTo() is consistent with equals(). We will see why that is important later.

So let’s take the same domain example as before: an order with multiple items. Imagine a type representing a line item in an order:

id → database identity (unique)
position → business ordering inside the order (1, 2, 3, …)

We want:

Natural ordering: by position (ascending)
Alternative ordering: by id (ascending)

A naive implementation could look like this:

public record LineItem(long id, int position) implements Comparable<LineItem> {
    @Override
    public int compareTo(LineItem o) {
        return Integer.compare(this.position, o.position); // risky: compareTo==0 for different ids
    }
}

Fig. 1: Naive implementation of `compareTo()` for `LineItem`

Looks reasonable — but this innocent one-liner can silently lose data from your collections without a single exception or warning. Can you spot the flaw?

The TreeSet bug: “missing elements”

TreeSet does not use equals() to decide duplicates. It uses ordering: if compareTo() returns 0, the element is treated as a duplicate.

import java.util.Set;
import java.util.TreeSet;

public class Demo {
    public static void main(String[] args) {
        Set<LineItem> set = new TreeSet<>();

        set.add(new LineItem(1001L, 1));
        set.add(new LineItem(1002L, 1)); // same position, different id
        set.add(new LineItem(1003L, 2));

        System.out.println(set);
        System.out.println("size = " + set.size());
    }
}

Fig. 2: TreeSet drops elements when compareTo() returns 0

With the broken compareTo(), the output will effectively be:

One of the position=1 entries is dropped
size becomes 2 instead of 3

This is not a TreeSet bug. It is a compareTo implementation bug.

A correct implementation for natural ordering

If your natural ordering is “position first”, the safe version is:

public record LineItem(long id, int position) implements Comparable<LineItem> {
    @Override
    public int compareTo(LineItem other) {
        int byPosition = Integer.compare(this.position, other.position);
        if (byPosition != 0) return byPosition;

        // Tie-breaker: ensure a total order (important for TreeSet/TreeMap)
        return Long.compare(this.id, other.id);
    }
}

Fig. 3: Correct `compareTo()` with `id` tie-breaker for a total order

Why the tie-breaker matters

This makes ordering:

sort by position
if same position, sort by id

Now:

the ordering is total
TreeSet can safely store multiple items with the same position
you avoid accidental “duplicates”

Bonus: Use `Comparator` for alternative ordering

Natural ordering should reflect the business meaning. For LineItem, sorting by position is usually what humans expect. But you will often also need sorting by id (for stable output, debugging, or database work). That should be done with a Comparator, not by changing compareTo()

import java.util.Comparator;

public class LineItemOrderings {
    public static final Comparator<LineItem> BY_ID =
            Comparator.comparingLong(LineItem::id);

    public static final Comparator<LineItem> BY_POSITION_THEN_ID =
            Comparator.comparingInt(LineItem::position)
                      .thenComparingLong(LineItem::id);
}

Fig. 4: Comparators for alternative orderings

This way you can easily sort by different criteria:

import java.util.ArrayList;
import java.util.List;

public class SortingDemo {
    public static void main(String[] args) {
        List<LineItem> list = new ArrayList<>(List.of(
                new LineItem(2002L, 2),
                new LineItem(2001L, 1),
                new LineItem(2003L, 1)
        ));

        list.sort(null); // natural ordering (position, then id)
        System.out.println("Natural: " + list);

        list.sort(LineItemOrderings.BY_ID); // ordering by id
        System.out.println("By id:   " + list);
    }
}

Fig. 5: Sorting with natural order vs comparator

Common Pitfalls

A common design mistake is to make compareTo() sort by id just because id is unique. That is usually wrong because:

it does not represent business meaning
it surprises readers of the code
it breaks UI expectations (“why is position ignored?”)

Instead:

keep natural ordering for business meaning (position)
use comparators for alternative views (id)

Another common flaw is to make compareTo() inconsistent with equals(). Java recommends consistency:

if a.compareTo(b) == 0, then a.equals(b) should also be true

But it is not required. For records, equals() uses all components (id and position). If your compareTo() only compares position, it becomes inconsistent with equals(). This is often a source of subtle bugs in sorted collections like we explored before with the TreeSet. Adding the id tie-breaker solves that problem in a clean way.

Takeaways

compareTo() defines natural ordering, not “any ordering”.
Never implement comparison using subtraction (a - b): it overflows for large negative values and returns a wrong result silently.
If compareTo() == 0, sorted collections treat elements as duplicates.
For business ordering like position, add a tie-breaker (id) to create a total order.
Use explicit Comparators for alternative sorting (like ordering by id).

If you follow these rules, your ordering logic stays predictable, safe, and easy to maintain.

Using the Web Share API

Sat, 03 Feb 2024 18:40:00 +0000

I recently learned of the existance of the Web Share API: this browser feature provides a mechanism for sharing text, links, files, and other content to an arbitrary share target selected by the user. I have adapted the Share feature here in this blog to use the Web Share API where available. The API is currently supported by Edge, Safari and most mobile browsers.

Leaving Twitter

Tue, 02 Jan 2024 09:00:00 +0000

I’ve been a passive user of Twitter for over two years now. My last tweet dates from 8 August 2021. Since the pandemic began, the number of tweets from conspiracy theorists has risen sharply and finally reached an unbearable level for me. I removed my Twitter client (Fenix) from the home page of my phone and ignored Twitter for months. I never really went back. After a while, I did check my timeline from time to time, but that too ended with the third-party client ban in January 2023.

It's officially over.
No more Fenix on Android, iOS or macOS.

Fenix for iOS was suspended earlier today and I've removed it from sale.

I've had a great time working on these apps for the past 10 years and I'm very greatful for all your messages and support. pic.twitter.com/ibVZng78Ra
— Fenix (@fenix_app) January 20, 2023

A few months later I started using Mastodon. It’s still a very small community, and so far it has none of the toxicity that X has developed. On Mastodon, I also came across a post describing how to host your exported tweets as your own archive. This is even more relevant as X forces users to sign in to browse tweets since June 2023.

Since I'm seeing a new wave of people saying they plan to leave Twitter, you may like my browser tool that takes the zip file of your Twitter export and returns a zip file of a web site that lets people browse and search your tweets. You can just upload the files wherever you normally host html and it'll work just fine.

https://tinysubversions.com/twitter-ar…

Example archive: https://tinysubversions.com/twitter-ar…
— Darius Kazemi (@darius@friend.camp) June 30, 2023

As I did not like the look and feel of the suggested web application I did a little research and found tweetback. I exported my data from X, extracted my tweets, and published my archive at tweets.davidfuhr.de. I also removed the X widgets integration and replaced the links to my X profile with a link to my personal archive. I’d be happy to see more media outlets join the Fediverse to fuel discussions there and make X less relevant.

Automate Dependency Updates with Renovate

Mon, 17 Apr 2023 19:30:00 +0000

Software ages

Renovate Logo

Keeping your dependencies up-to-date is a chore. Updating dependencies often gets neglected while working on new features and busy improving your application. But it is necessary to keep your application safe and secure. Renovate reminds you of new dependency releases and makes upgrading a bliss.

Renovate is a standalone node application. It scans your repositories for dependencies and creates Pull Requests (aka. Merge Requests) for the dependency updates. It supports a wide range of “package managers”, including Maven, Gradle, and npm, but also Dockerfile and bitbucket-pipelines.yml. Each update is proposed in a separate Pull Request containing information like Changelogs of the dependency and Renovate’s instructions on how to work with the PR. Your build pipeline with your automated tests will automatically verify if your application still works with the updated dependency. If you have enough confidence in your build pipeline, you can configure Renovate to auto-merge the PRs. Otherwise, you can merge the PRs yourself.

Renovate has tons of configuration options allowing to define version ranges for certain dependencies, grouping of dependencies, or telling Renovate to ignore the dependency altogether. It supports private package registries, schedules, and limits for the number of PR it creates. These configurations can be shared via repositories and nested and combined as you like. Additionally, it provides a Dependency Dashboard that shows an overview of the state of your repositories’ dependencies.

Getting started

The easiest way to get started is to use the Renovate Docker Container. But installing it as node package gives you more control over the Renovate version used. So let’s start in an empty folder and install Renovate (Fig. 1). I assume you have a current version of node and npm installed.

mkdir renovate-runner
cd renovate-runner
npm i -S renovate

Fig. 1: Install Renovate node package

This will generate a package.json and a package-lock.json file. Now you can proceed to create the config.js configuration file (Fig. 2).

module.exports = {
  // see https://docs.renovatebot.com/self-hosted-configuration/#platform
  platform: `${process.env.RENOVATE_PLATFORM}`,
  repositories: [
    "davidfuhr/davidfuhr-jekyll", // <-- Add your repositories here
  ],
  timezone: "Europe/Berlin",
  onboardingConfig: {
    $schema: "https://docs.renovatebot.com/renovate-schema.json",
    extends: ["config:base"],
  },
};

Fig. 2: config.js

For the following steps I will assume your repositories are hosted on Bitbucket Cloud. For other platforms, see the Renovate Platforms Documentation.

Next, you need to create an app password for your Bitbucket account. It is ok to use your personal account for testing purposes, but I recommend creating a dedicated user for the bot later when you automate things. Now all left to do is to export your credentials as environment variables and are ready to run Renovate for the first time (Fig. 3).

export RENOVATE_PLATFORM=bitbucket
export RENOVATE_USERNAME=<your_username>
export RENOVATE_PASSWORD=<your_app_password>

npx renovate

Fig. 3: Run Renovate for the first time

If everything works, then Renovate should have created a Pull Request titled “Configure Renovate” in the configured repositories. The PR’s description contains the packages Renovate discovered, which Update-PRs it will create, and on what configuration it is running. After you merged this PR and run renovate again, it will create the first Update-PRs.

Set up on Bitbucket Pipelines

The next step is to automate Renovate and run it on a reliable environment, and not your local machine. An easy way to automate Renovate is to run it in Bitbucket Pipeline. A good starting configuration can you see in figure 4.

---
image: node:18

pipelines:
  default:
    - step:
      name: "Lint"
      caches:
        - node
      script:
        - npm ci
        - npx renovate-config-validator
custom:
  renovate:
    - step:
      name: Renovate
      caches:
        - node
      script:
        # See https://stackoverflow.com/a/74528937/501248
        - 'echo "deb http://deb.debian.org/debian bullseye-backports main" >/etc/apt/sources.list.d/bullseye-backports.list'
        - apt-get update && apt -t bullseye-backports install -y git
        - npm ci
        - npx renovate

Fig. 4: bitbucket-pipelines.yml

Next, you should add the three environment variables we used before (RENOVATE_PLATFORM, RENOVATE_USERNAME, RENOVATE_PASSWORD) to the Repository Variables in your Repository settings. After that, you can try to run the pipeline manually (Fig. 5).

Fig. 5: Bitbucket Pipelines: Run Pipeline

If everything works as expected, you can proceed to create a schedule (Fig. 6).

Fig. 6: Bitbucket Pipelines: Create a schedule

Congratulations! You’re done! Now Renovate will run periodically and help you keep your dependencies up-to-date!

Further Improvements

GitHub Token for Release Notes

To further improve the description of the PRs, you can enable Renovate to pull in public Release Notes from GitHub. To that, you need to create a public API Token and add it as GITHUB_COM_TOKEN to your Repository variables.

Autodiscover

Renovate has a powerful feature called “autodiscover”. When you enable autodiscover, by default, Renovate runs on every repository that the bot account can access. You can limit which repositories Renovate can access by using the autodiscoverFilter config option. This releases you from remembering to add every new repository you create to the Renovate configuration.

Other tips and resources

Alternatives

If your code is hosted on GitHub, it is probably easier to just use Dependabot. You can enable Dependabot in your repository settings. According to the Dependabot Documentation, it should be possible to run Dependabot for some other Git providers as well, but I didn’t test it:

However, if you want to run a custom version of Dependabot or run it on another platform, you're not left out in the cold. This repo provides the logic necessary for hosting your own standalone Dependabot, as long as you're not re-selling Dependabot to others. It currently supports opening Pull Requests against repositories hosted on GitHub, Github Enterprise, Azure DevOps, GitLab, BitBucket, and AWS CodeCommit.
– github.com/dependabot/dependabot-core

Other alternatives which I didn’t test are Depfu, or snyk. Are there any other alternatives I missed? What do you do to keep your dependencies up-to-date? Let me know!

Composing Micro Frontends Server-Side

Fri, 12 Jun 2020 07:37:00 +0000

This article was originally published at esentri.com.

Scaling development

Microservices are well-known now for some years and are widely adopted. But the frontend oftentimes is still monolithic. This application structure often reflects on the team structure: there are several independent backend teams and one single frontend team. This also prevents backend development teams from delivering complete usable features - they always lack the frontend. To implement the frontend all changes must be done by the one frontend team. This makes it hard to scale development. By implementing micro frontends we can form full-stack teams that can ship complete features on their own. This is one of the reasons why ThoughtWorks placed micro frontends in the “Adopt” section of their famous Technology Radar for the third time in a row!

Composing Micro Frontends

For our use case, a micro frontend consists of markup (HTML), styles (CSS), scripts (JavaScript), and images. We want to compose the different micro frontends, or “fragments” as they are usually called, in our page. Some fragments are interactive. Some might have dependencies on some fragments. And some might want to interact with other fragments.

There are two ways to integrate the fragments from your micro frontends: client-side and server-side. Both have their pros and cons. We are comparing different ways of server-side composing because we focus on search engine optimization. Google supports lots of JavaScript nowadays but takes longer to index which is bad for a frequently changing site and some other crawlers don’t support JavaScript at all.

Also, the support for slow mobile clients, like smartphones, is better with server-side composition. Mobile clients usually have a slower internet connection so they benefit from the smaller payload to download. They also have less computing power so they profit from the pre-rendered HTML.

Server Side Includes (SSI)

SSI is a simple server-side scripting language that allows conditional statements and the inclusion of other fragments from files and URLs.

To include another fragment in your page add the and SSI tag like . The web server fetches the fragment and replaces the SSI tag with the fragment’s content. The combined output is returned to the client.

For a more in-depth explanation about composition with SSI take a look at this presentation by my colleague Artun Subasi from the duesentrieb Camp last year.

Pros

Proven and well-tested
Well supported in Nginx, Apache, and other web servers
Support for timeouts and fallback content

Cons

Fragments are fetched in parallel but delivered only after the last fragment is fetched (Nginx)
No built-in support for asset handling. Apache PageSpeed (formerly known as modpagespeed by Google) can do some CSS processing and combine the CSS from the fragments, but did not receive any updates since early 2018 and seems to be dead

Edge Side Includes (ESI)

ESI is a simple markup language that allows the inclusion of fragments from other URLs.

ESI works very similar to SSI. ESI is more focussed on the reverse proxy or CDN layer, while SSI targets the web server itself. Of course, these boundaries are somewhat blurry because Nginx is often used as a reverse proxy as well. ESI has no conditional logic itself. But Varnish, for example, allows conditional logic in its own DSL called “VCL”.

Pros

Proven and well-tested
Well supported in Varnish (parallel fetching requires the commercial edition). Squid (project web site is outdated, but there are new releases) and Mongrel (no new releases since 2010) do support it as well

Cons

No built-in support for a timeout. Proprietary extensions do exist.
Mutual exclusive with use of CDN-based ESI for caching
No built-in support for asset handling

Zalando Tailor

Tailor is a Node.js based fragment service open-sourced by Zalando and runs as stand-alone service. It is part of Project Mosaic - Zalando’s umbrella project their frontend modularization.

Zalando Tailor uses custom markup to compose the page. They define <fragment src="http://www.example.com">-tags to specify the fragments to load. Assets, like styles and scripts, can be populated by the fragment itself via Link header.

Pros

Built-in support for asset handling
Fragments as first-party-concept
Asynchronously fetches multiple fragments and streams immediately

Cons

Proprietary solution, needs custom Link-Headers with styles and AMD JS bundling

Podium

Podium is also implemented in JavaScript and runs on Node.js. It is developed by the norwegian company Finn.no for their classified ads site. Podium is a library to integrate fragments (they call them “podlets”) into the page (they call the page “layout”).

To run podium you need at least two instances: a layout server and at least one podlet server. The podlet server exposes the fragment, the layout server integrates it into the page. Every fragment needs to expose a “Podlet Manifest” which contains JSON data assets and may contain a fallback URL. The layout server initially fetches the fallback content and caches it in case the podlet server becomes unavailable.

Pros

Built-in support for asset handling (fragments need to expose metadata-endpoint)
Fragments as first-party-concept
Built-in proxy-support to hide fragment servers
Fragement servers can define fallback content

Cons

Proprietary solution, tight coupling with library

Final Thoughts and Recommendations

ESI and SSI are well-tested, stable technologies, and are easy to learn. Custom additions like Varnish’s VCL add complexity but introduce lots of new possibilities. In general, these solutions offer no good solution for asset handling and struggle with the requirements of modern web applications.

More modern solutions like Tailor and Zalando solve many problems the old-fashioned tools have. But the introduce their fair share of complexity and have their own learning curve. Both tools are more or less a one-man-show (if you look at the contribution logs). So you should be prepared to step in and continue development or fork if Zalando or Finn.no drop their solutions if you make any of these products a cornerstone of your application.

For a broader overview of composition techniques (includes client-side composition) I can recommend this article about Micro Frontends by bluesoft. If you are interested in micro frontends you should take a look at Micro Frontends in Action by Michael Geers.

Do you have a better of idea how to compose micro frontends server-side? Contact me via Twitter and let me know!

Maintenance Mode for your API

Wed, 05 Jul 2017 12:08:00 +0000

This article was originally published at esentri.com.

I recently implemented a simple maintenance mode for a REST API. Letting the web server return a 503 Service Unavailable sounds easy enough. But there was a catch displaying a maintenance page in our Angular client application.

Our setup is nothing fancy. We have an AngularJS frontend application serviced by a REST API. nginx is used as reverse proxy in front of our backend application servers. It does SSL offloading and simple round-robin load balancing. This makes nginx the central point to toggle the maintenance mode.

Communication Diagram

My first approach for returning the maintenance status from nginx looked like this:

if (-f $error_root/maintenance.html) {
  return 503;
}

It checks if the maintenance.html file is present, and if it is there, the server returns 503 Service Unavailable.

I also implemented an HTTP Interceptor for our AngularJS frontend to display a nice maintenance page if any request returns a 503:

$httpProvider.interceptors.push(function ($q) {
  return {
    responseError: function (response) {
      if (response.status === 503) {
        // display maintenance page
      }
      return $q.reject(response);
    },
  };
});

Strangely enough, the maintenance page wasn’t triggered.

After a while of debugging, I found out that it was some kind of CORS issue. Although I added the Access-Control-Allow-Origin: \*-Header to all responses (with and without maintenance mode for debugging purposes) the client interpreted the CORS request with the status code 503 as failed and denied access to all response information to JavaScript. Even to the response status code. JavaScript always reported a status code of 0.

This left me with two options: either display the maintenance page on status code 0 as well or making the CORS request pass. Triggering the maintenance page on every status code 0 could have unwanted side effects, like maintenance page on other failing requests, so I rejected this solution and opted for making the CORS request pass.

I fixed this by adding an extra check in the maintenance switch in the nginx configuration. For the CORS preflight request (which is a OPTIONS request) I always return 200. Even in maintenance mode.

This way the preflight request succeeds and JavaScript has access to the status code of the following request. Now my interceptor was triggered and displayed the maintenance page as expected.

if (-f $error_root/maintenance.html) {
  if ($request_method = OPTIONS) {
    return 200;
  }
  return 503;
}

Did you encounter a similar problem? How did you solve it? Is there a better/cleaner approach to this problem?

Git Workflow: rebase and merge

Fri, 25 Nov 2016 12:06:00 +0000

I am a fan of a clean git history. It should be easy to spot which commits belong to which feature, which feature was merged when, and what changes were made by whom. I’ve seen several git histories that look more like a pile of spaghetti and it takes a lot of effort to understand the history. I will explain how you can keep things neat and clean by using rebase and how to avoid the pitfalls I ran into.

Git History with Pull Merges

If your git history looks like this and this bothers you this article is for you. With a better understanding of git and it’s features you can make your history look like this.

Git History with Rebase

If you want to know how read more!

Understand merging with `--ff` or `--no-ff`

In git there are two strategies to merge branches. Fast-Forward merges and Non-Fast-Forward merges. Let’s take a look at those two strategies, when you can use which strategy and how the result differs.

Fast-forward merges are possible if you have a situation like this:

          D---E---F topic
         /
A---B---C master

The topic branch is ahead of master. But the master branch does not have any additional commits.

If you merge topic with --ff to master…

git checkout master
git merge --ff topic

…you will have the following result:

A---B---C---D---E---F topic/master

Now master and topic are identical. If you delete the topic branch nobody can tell anymore that there was a topic branch once.

Let’s take a look what the result looks like if you merge with the --no-ff strategy:

git checkout master
git merge --no-ff topic

Git will create an extra commit for the merge itself:

          D---E---F topic
         /         \
A---B---C---------- G master

This way it is transparent for everyone what commits belonged to the feature branch and what was merged. It also makes it easier to un-merge the branch. Because you only need to revert the merge commit and you are done.

So my recommendation is if you merge towards the main line use --no-ff. This means merges from topic to develop or develop to master should always be done with --no-ff.

Merges away from the main line could be done using --ff but continue reading to learn about an even cleaner approach.

Understand rebasing

With rebase you can move commits. Strictly speaking you do not move the commits, but you reapply the commits somewhere else. New commits (with new commit ids) are created, your old commits are removed. This can be used to “catch up” on the changes of master or any other branch.

Let’s assume the following situation:

      A---B---C topic
     /
D---E---F---G master

Now you want to update your topic branch to include the latest changes from master. You could merge masterto topic but this would create a useless merge commit (--no-ff is not possible because both branches have additional commits). A cleaner solution is to rebase your topic branch onto the current master.

git checkout topic
git rebase master

The result will be:

              A'--B'--C' topic
             /
D---E---F---G master

Your old commits A, B and C have been reapplied on top of master. They have new commit ids and your topic branch contains now the latest changes from master. If your commits don’t apply cleanly on master you have to resolve your conflicts while rebasing. Afterwards you can merge your rebased topic branch conflict free with --no-ff to master. Your merge will cause no conflicts and you don’t have to fix several errors in a big, complicated, bloated merge commit. This will make the history cleaner and better to read.

My second recommendation is to rebase your topic branches regularly to stay up to date and solve conflicts as soon as possible. The fresher the changes are the more likely it is that you still remember why you introduced a change and this will make resolving rebase conflicts easier.

Working with a shared repository

When you work with a shared repository and you start to rebase branches you need to communicate some extra knowledge to your team. Otherwise you clutter you git history with a lot of useless merge commits and it will blow up in your face. That’s basically the reason why people tell you “don’t rebase pushed branches”. Let’s narrow this principle down to the first rule: “don’t rebase your pushed main branches”. It depends on your branching model what your main branches are called but commonly these are master and develop.

By default, when pulling from a remote branch and both, your local and remote branch have additional commits, git performs a --no-ff- merge. This creates an additional merge commit as you learned earlier. To avoid this you can use rebasing while pulling:

git checkout topic
git pull --rebase origin topic

Remembering to add --rebase for every pull is annoying so you can set the default strategy for the topic branch to rebase:

git config branch.topic.rebase true

You can even tell git to set this automatically for every new branch you create:

git config --global branch.autosetuprebase = always

After rebasing your branch locally you need to push it back to the remote repository. By default git will reject the push as “diverged”. But you can force the push with --force-with-lease¹:

git push --force-with-lease origin topic

This is a potentially destructive operation because it will overwrite the remote branch and you will loose any changes not included in your local copy of the branch. So always be careful which branch you push.

Common Pitfalls

Make sure you do not rebase your main branches. If you do this it will almost certainly cause unwanted results. Like inlined merges (like with --ff). So make sure rebase is disabled for your main branches:

git config branch.master.rebase false
git config branch.develop.rebase false

If you rebase on master (or any other main branch) make sure your master is up to date. So usually you run the following command sequence:

git checkout master
git pull origin master
git checkout topic
git rebase master

TL;DR

Merge topic branches with git merge --no-ff topic towards the mainline.
Use git rebase master topic to catch up with the latest changes from master.
Update your topic branch from remote with git pull --rebase origin topic.
Push your topic branches with git push --force-with-lease origin topic.

Read the TL;DR version of this post at http://stevenharman.net/git-pull-with-automatic-rebase

Provide Feedback!

This workflow is what works well for me and my teams and after some initial explaining is well accepted. What is your workflow? How do you deal with feature branches and master diverging? Do you care about the transparency of your git history?

Learn more about --force-with-lease, how it works, and why you should use it at https://developer.atlassian.com/blog/2015/04/force-with-lease/ ↩

Implement a DateTimeInterface Handler for JMSSerializer

Wed, 28 Sep 2016 15:18:00 +0000

While working on an API today I realized the JMSSerializer does not support neither DateTimeInteface nor DateTimeImmutable. I am going to walk you through the necessary steps to serialize DateTimeImmutable objects using JMSSerializer.

Wow... #jmsserializer does not support DateTimeImmutable (https://t.co/cbkWc3MdqY)... Looks like I have to build my own handler... #symfony
— David Fuhr (@DavidFuhr) September 28, 2016

Building an own handler requires not much code. The only problem is that documentation is scattered to many places and sometimes hard to find. I’m working on a full-stack Symfony 2.8 with JMSSerializerBundle installed. So make sure you are on the same page before starting.

The first step is to create a Handler:

<?php

namespace AppBundle\JmsSerializer;

use DateTimeInterface;
use JMS\Serializer\VisitorInterface;

class DateTimeInterfaceHandler
{
public function serializeToJson(VisitorInterface $visitor, DateTimeInterface $dateTime, array $type)
{
return $dateTime->format(DATE_ATOM);
}
}

DateTimeInterfaceHandler.php

You could also create a Subscriber, but I think the Handler is more straight forward. Read the JMSSerializer Documentation on Handlers to learn more.

Next we have to register our Handler as a service:

# services.yml
services:
  app.jmsserializer.datetimeinterface_handler:
    class: AppBundle\JmsSerializer\DateTimeInterfaceHandler
    tags:
      - {
          name: jms_serializer.handler,
          type: DateTimeImmutable,
          direction: serialization,
          format: json,
          method: serializeToJson,
        }

services.yml

This is documented in the JMSSerializerBundle Documentation, but setting my Service to private did not work (learn more about Private Services in Symfony), and setting the type to DateTimeInterface did not work either.

So if you use want to format DateTime as well you have to adjust the config value in the Bundle’s configuration:

# config.yml
jms_serializer:
  handlers:
    datetime:
      default_format: "c" # ISO8601

config.yml

That’s it. Now your DateTime and DateTimeImmutable objects should be serialized to string similar to 2016-09-28T12:54:07+00:00. If you encounter problems or have further questions find me on Twitter.

Documentation Driven API Development with Swagger 2.0

Tue, 12 Jul 2016 21:05:31 +0000

Good documentation is the key to utilize an API. But it is difficult to keep documentation and development of you API in sync. Differences between implementation and documentation are often hard to spot. Learn how you can use Swagger to document you API first and profit by testing your implementation against your documentation and vice versa. No duplication needed!

Swagger Logo

I recently started planning a new RESTful API for my company. After some initial discussion on the scope and which API endpoints are needed I set out to write the specification in Swagger 2.0. This provided for a good starting point to the further refinement discussion. It also proved very useful to exchange information with our frontend developers in charge of implementing the first API consumer.

Swagger Editor

At first we started using Swagger Editor and YAML as format (because it is the lingua franca of Swagger Editor). Swagger Editor is a great tool to get started using Swagger. It runs directly in your browser, validates your YAML input and renders a beautiful interactive web interface. We were sending the swagger.yaml file around and I was maintaining the authoritative version of the file. This worked well for the start but it was obvious to us that we needed a tighter coupling to the application and track the file in sync with the implementation.

I had worked with NelmioApiDocBundle before to integrate Swagger with a Symfony application and it is a wonderful tool to document your existing API code. But as NelmioApiDocBundle generates the Swagger file from the annotated source code the source must exist prior to the documentation. This did not match our desired workflow. What’s more, the future of NelmioApiDocBundle seems to be a bit uncertain as the William Durand, the current maintainer, thinks of deprecating the bundle¹.

I am thinking about slowly deprecating #NelmioApiDocBundle (feature-freeze first, then EOL). Thoughts?
— William Durand (@couac) June 13, 2016

As I only needed a view component for my Swagger file and had no need for the annotation stuff SwaggerUIBundle was good enough for the job. That made it necessary to convert my Swagger file from YAML to JSON, but that’s no big deal as the Swagger Editor has an export option for JSON. For the Bundle configuration take a look at the installation instructions for static JSON files. This is what my routing configuration looked like:

# app/config/routing_dev.yml
al_swagger_ui:
    resource: "@ALSwaggerUIBundle/Resources/config/routing.yml"
    prefix:   /api-docs

app/config/routing_dev.yml

As I started implementing the first endpoints I also created the first Test Cases in parallel with development. And because I am lazy, I did not want to repeat myself and write the same definitions I already had in my Swagger file for my test assertions again. So I was looking for a way to reuse my Swagger specification in my test’s assertion.

Swagger UI

The model definitions of Swagger 2.0 are valid JSON Schema which aims to be similar as XSD or DTD for XML. And fortunately there is already a library for PHPUnit JSON Schema Assertions. The only problem was I had a single huge Swagger file and I found no way to validate my API response only against a part of the big Swagger definition. JSON Schema allows splitting up the definition into multiple files and referencing these files using $ref. For more information about Referencing take a look at the OpenAPI Guidelines for Referencing, How to split a Swagger spec into smaller files and Structuring a complex schema.

After splitting up the file SwaggerUIBundle did not work anymore because it has problems handling and resolving the JSON references correctly. But that’s not a problem a of SwaggerUI, it’s only a problem of the bundle. As workaround I moved my Swagger files to src/AppBundle/Resources/public/swagger so that Symfony takes care of populating my files in the web root and I adjusted the SwaggerUIBundle configuration to just take that static entry point.

# app/config/config_dev.yml
al_swagger_ui:
    resource_list: /bundles/app/swagger/swagger.json

app/config/routing_dev.yml

Now that the UI was working again I could set up my test cases and validate the controller’s response against my Swagger definition.

namespace AppBundle\Tests\Controller;

use EnricoStahn\JsonAssert\Extension\Symfony as JsonAssert;
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class CartsControllerTest extends WebTestCase
{
    use JsonAssert;

    protected function getSwaggerDir()
    {
        return __DIR__ . '/../../Resources/public/swagger';
    }

    public function testPostCartsResponseSchema()
    {
        $client = static::createClient();
        $client->request('POST', '/carts');

        $this->assertJsonResponse($response);
        $this->assertJsonMatchesSchema(
            $this->getSwaggerDir()
                . '/definitions/CartsResponse.json',
            $response
        );
    }
}

One somewhat questionable thing with JSON Schema is, that additional properties on object are allowed by default. You have to explicitly set additionalProperties to false. Your schema should something like that

{
  "type": "object",
  "properties": {
    "cart_id": {
      "type": "number"
    },
    "item_count": {
      "type": "number"
    }
  },
  "additionalProperties": false
}

If your JSON Schema uses several nesting levels you might need to adjust the $maxDepth of the RefResover (the component that resolves your $ref).

JsonSchema\RefResolver::$maxDepth = 10;

This got me what I want. Whenever there is a change either in the documentation or the implementation it will break the tests and the developer has to make sure both align. This ensures that the documentation is updated on code change and is maintained and also provides easy tests for new endpoints as a bonus!

If you are using NelmioApiDocBundle and looking for alternatives, read this insightful article by David Buchman who coverted his NemlioApiDocBundle annotations to swagger-php annotations. ↩

Track Memory Usage and Runtime of Symfony Commands

Fri, 14 Feb 2014 16:28:48 +0000

This article was originally published at flagbit.de.

If you write lots of Console Commands in your Symfony application you sure want to know more about their memory and time consumption. To collect the necessary data you can make use of the Stopwatch Component.

<?php
use Symfony\Component\Stopwatch\Stopwatch;

$stopwatch = Stopwatch();
$stopwatch->start('my event');
// do something important
$stopwatchEvent = $stopwatch->stop('my event');

echo $stopwatchEvent->getDuration();
echo $stopwatchEvent->getMemory();

First we need to define a service for our Stopwatch in our services.yml to have it available where we want it:

services:
    flagbit_core.stopwatch:
        class: Symfony\Component\Stopwatch\Stopwatch

services.yml

You could implement the Stopwatch in each and every command by hand but this is tiresome and error-prone. So we make use of the Console Events and attach to them:

flagbit_core.console_stopwatch.command:
  class: Flagbit\CoreBundle\EventListener\ConsoleStopwatchListener
  arguments: ["@flagbit_core.stopwatch"]
  tags:
    - { name: kernel.event_listener, event: console.command }
flagbit_core.console_stopwatch.terminate:
  class: Flagbit\CoreBundle\EventListener\ConsoleStopwatchListener
  arguments: ["@flagbit_core.stopwatch"]
  tags:
    - { name: kernel.event_listener, event: console.terminate }

Ok, let’s walk through the ConsoleStopwatchListener. First we start with the Constructor to inject the Stopwatch into our Service:

<?php
namespace Quantum\CoreBundle\EventListener;

use Symfony\Component\Console\Event\ConsoleCommandEvent;
use Symfony\Component\Console\Event\ConsoleTerminateEvent;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Stopwatch\Stopwatch;

class ConsoleStopwatchListener
{
    /**
     * @var Stopwatch
     */
    private $stopwatch;

    /**
     * @param Stopwatch $stopwatch
     */
    public function __construct(Stopwatch $stopwatch)
    {
        $this->stopwatch = $stopwatch;
    }

The console.command Event is dispatched just before command execution. So it is the perfect place to start our Stopwatch:

    /**
     * @param ConsoleCommandEvent $event
     */
    public function onConsoleCommand(ConsoleCommandEvent $event)
    {
        $this->stopwatch->start($event->getCommand()->getName());
    }

The second Event we attached to is console.terminate which is triggered after the command has been executed. So we attach our stats to the Output there:

    /**
     * @param ConsoleTerminateEvent $event
     */
    public function onConsoleTerminate(ConsoleTerminateEvent $event)
    {
        $stopwatchEvent = $this->stopwatch->stop($event->getCommand()->getName());

        $output = $event->getOutput();
        if (OutputInterface::VERBOSITY_VERBOSE <= $output->getVerbosity()) {
            $output->writeln(
                '<comment>' . $this->formatDuration($stopwatchEvent->getDuration()) . ' / '
                . $this->formatMemory($stopwatchEvent->getMemory()) . '</comment>'
            );
        }
    }

    /**
     * @param int $bytes Memory in bytes
     * @return string
     */
    private function formatMemory($bytes)
    {
        return round($bytes / 1000 / 1000, 2) . ' MB';
    }

    /**
     * @param int $microseconds Time in microseconds
     * @return string
     */
    private function formatDuration($microseconds)
    {
        return $microseconds / 1000 . ' s';
    }
}

You might also have noticed the Verbosity check which causes our stats only to be printed if the command is run with -v. Symfony >= 2.4 allows to do this a little bit cleaner with $output->isVerbose().

Implement Java’s compareTo() the right way

Why do you need compareTo()?

How to implement compareTo()

The TreeSet bug: “missing elements”

A correct implementation for natural ordering

Why the tie-breaker matters

Bonus: Use Comparator for alternative ordering

Common Pitfalls

Takeaways

Using the Web Share API

Leaving Twitter

Automate Dependency Updates with Renovate

Software ages

Getting started

Set up on Bitbucket Pipelines

Further Improvements

GitHub Token for Release Notes

Autodiscover

Other tips and resources

Alternatives

Composing Micro Frontends Server-Side

Scaling development

Composing Micro Frontends

Server Side Includes (SSI)

Pros

Cons

Edge Side Includes (ESI)

Pros

Cons

Zalando Tailor

Pros

Cons

Podium

Pros

Cons

Final Thoughts and Recommendations

Maintenance Mode for your API

Git Workflow: rebase and merge

Understand merging with --ff or --no-ff

Understand rebasing

Working with a shared repository

Common Pitfalls

TL;DR

Further reading

Provide Feedback!

Implement a DateTimeInterface Handler for JMSSerializer

Documentation Driven API Development with Swagger 2.0

Track Memory Usage and Runtime of Symfony Commands

Why do you need `compareTo()`?

How to implement `compareTo()`

Bonus: Use `Comparator` for alternative ordering

Understand merging with `--ff` or `--no-ff`