java: Add comparators for comparable objects (#312)

Duration, Location and timestamp are comparable. To help sorting these
messages a comparator is needed. The alternative would be implementing
the `Comparable` interface, but with generated code that is quite
tricky.

Author: mpkorstanje

CHANGELOG.md

@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
+### Added
+- [java] Add comparators for comparable objects ([#312](https://github.com/cucumber/messages/pull/312))
 
 ## [28.0.0] - 2025-07-07
 ### Changed

java/pom.xml

@@ -42,6 +42,13 @@
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
+            <dependency>
+                <groupId>org.assertj</groupId>
+                <artifactId>assertj-bom</artifactId>
+                <version>3.27.3</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
         </dependencies>
     </dependencyManagement>
 
@@ -71,9 +78,8 @@
         </dependency>
 
         <dependency>
-            <groupId>org.hamcrest</groupId>
-            <artifactId>hamcrest-core</artifactId>
-            <version>3.0</version>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
             <scope>test</scope>
         </dependency>
 

java/src/main/java/io/cucumber/messages/DurationComparator.java

@@ -0,0 +1,19 @@
+package io.cucumber.messages;
+
+import io.cucumber.messages.types.Duration;
+
+import java.util.Comparator;
+
+/**
+ * Orders durations by their natural order.
+ */
+public final class DurationComparator implements Comparator<Duration> {
+    @Override
+    public int compare(Duration a, Duration b) {
+        int c = a.getSeconds().compareTo(b.getSeconds());
+        if (c != 0) {
+            return c;
+        }
+        return a.getNanos().compareTo(b.getNanos());
+    }
+}

java/src/main/java/io/cucumber/messages/LocationComparator.java

@@ -0,0 +1,25 @@
+package io.cucumber.messages;
+
+import io.cucumber.messages.types.Location;
+
+import java.util.Comparator;
+
+/**
+ * Orders locations by their natural order. 
+ * <p>
+ * Locations on the same line, but with a missing column come before locations
+ * with a column.
+ */
+public final class LocationComparator implements Comparator<Location> {
+    @Override
+    public int compare(Location a, Location b) {
+        int c = a.getLine().compareTo(b.getLine());
+        if (c != 0) {
+            return c;
+        }
+        Long aColumn = a.getColumn().orElse(null);
+        Long bColumn = b.getColumn().orElse(null);
+        // null first.
+        return aColumn == null ? bColumn == null ? 0 : -1 : bColumn == null ? 1 : aColumn.compareTo(bColumn);
+    }
+}

java/src/main/java/io/cucumber/messages/TestStepResultStatusComparator.java

@@ -0,0 +1,15 @@
+package io.cucumber.messages;
+
+import io.cucumber.messages.types.TestStepResultStatus;
+
+import java.util.Comparator;
+
+/**
+ * Orders test step results from least to most severe.
+ */
+public final class TestStepResultStatusComparator implements Comparator<TestStepResultStatus> {
+    @Override
+    public int compare(TestStepResultStatus a, TestStepResultStatus b) {
+        return Integer.compare(a.ordinal(), b.ordinal());
+    }
+}

java/src/main/java/io/cucumber/messages/TimestampComparator.java

@@ -0,0 +1,19 @@
+package io.cucumber.messages;
+
+import io.cucumber.messages.types.Timestamp;
+
+import java.util.Comparator;
+
+/**
+ * Orders timestamps by their natural order.
+ */
+public final class TimestampComparator implements Comparator<Timestamp> {
+    @Override
+    public int compare(Timestamp a, Timestamp b) {
+        int c = a.getSeconds().compareTo(b.getSeconds());
+        if (c != 0) {
+            return c;
+        }
+        return a.getNanos().compareTo(b.getNanos());
+    }
+}

java/src/test/java/io/cucumber/messages/DurationComparatorTest.java

@@ -0,0 +1,46 @@
+package io.cucumber.messages;
+
+import io.cucumber.messages.types.Duration;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class DurationComparatorTest {
+    
+    final DurationComparator comparator = new DurationComparator();
+    
+    @Test
+    void isEqual(){
+        Duration a = new Duration(3L, 14L);
+        Duration b = new Duration(3L, 14L);
+        assertThat(comparator.compare(a, b)).isZero();
+    }
+    
+    @Test
+    void isSmallerOnSeconds(){
+        Duration a = new Duration(2L, 14L);
+        Duration b = new Duration(3L, 14L);
+        assertThat(comparator.compare(a, b)).isNegative();
+    }
+    
+    @Test
+    void isSmallerOnNanos(){
+        Duration a = new Duration(3L, 13L);
+        Duration b = new Duration(3L, 14L);
+        assertThat(comparator.compare(a, b)).isNegative();
+    }
+    
+    @Test
+    void isLargerOnSeconds(){
+        Duration a = new Duration(4L, 14L);
+        Duration b = new Duration(3L, 14L);
+        assertThat(comparator.compare(a, b)).isPositive();
+    }
+    
+    @Test
+    void isLargerOnNanos(){
+        Duration a = new Duration(3L, 15L);
+        Duration b = new Duration(3L, 14L);
+        assertThat(comparator.compare(a, b)).isPositive();
+    }
+}

java/src/test/java/io/cucumber/messages/LocationComparatorTest.java

@@ -0,0 +1,59 @@
+package io.cucumber.messages;
+
+import io.cucumber.messages.types.Location;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class LocationComparatorTest {
+    
+    final LocationComparator comparator = new LocationComparator();
+    
+    @Test
+    void isEqual(){
+        Location a = new Location(3L, 14L);
+        Location b = new Location(3L, 14L);
+        assertThat(comparator.compare(a, b)).isZero();
+    }
+    
+    @Test
+    void isSmallerOnLine(){
+        Location a = new Location(2L, 14L);
+        Location b = new Location(3L, 14L);
+        assertThat(comparator.compare(a, b)).isNegative();
+    }
+    
+    @Test
+    void isSmallerOnColum(){
+        Location a = new Location(3L, 13L);
+        Location b = new Location(3L, 14L);
+        assertThat(comparator.compare(a, b)).isNegative();
+    }
+    @Test
+    void isSmallerAbsentColumn(){
+        Location a = new Location(3L, null);
+        Location b = new Location(3L, 14L);
+        assertThat(comparator.compare(a, b)).isNegative();
+    }
+    
+    @Test
+    void isLargerOnLine(){
+        Location a = new Location(4L, 14L);
+        Location b = new Location(3L, 14L);
+        assertThat(comparator.compare(a, b)).isPositive();
+    }
+    
+    @Test
+    void isLargerOnColumn(){
+        Location a = new Location(3L, 15L);
+        Location b = new Location(3L, 14L);
+        assertThat(comparator.compare(a, b)).isPositive();
+    }
+    
+    @Test
+    void isLargerAbsentColumn(){
+        Location a = new Location(3L, 15L);
+        Location b = new Location(3L, null);
+        assertThat(comparator.compare(a, b)).isPositive();
+    }
+}

java/src/test/java/io/cucumber/messages/ProtocolVersionTest.java

@@ -1,16 +1,16 @@
 package io.cucumber.messages;
 
-import org.hamcrest.Matchers;
 import org.junit.jupiter.api.Test;
 
-import static org.hamcrest.MatcherAssert.assertThat;
+import static org.assertj.core.api.Assertions.assertThat;
+
 
 class ProtocolVersionTest {
 
     @Test
     void should_have_a_resource_bundle_version() {
         String version = ProtocolVersion.getVersion();
-        assertThat(version, Matchers.matchesPattern("\\d+\\.\\d+\\.\\d+(-SNAPSHOT)?"));
+        assertThat(version).matches("\\d+\\.\\d+\\.\\d+(-SNAPSHOT)?");
     }
 
 }

java/src/test/java/io/cucumber/messages/TestStepResultStatusComparatorTest.java

@@ -0,0 +1,38 @@
+package io.cucumber.messages;
+
+import io.cucumber.messages.types.TestStepResultStatus;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+import static io.cucumber.messages.types.TestStepResultStatus.AMBIGUOUS;
+import static io.cucumber.messages.types.TestStepResultStatus.FAILED;
+import static io.cucumber.messages.types.TestStepResultStatus.PASSED;
+import static io.cucumber.messages.types.TestStepResultStatus.PENDING;
+import static io.cucumber.messages.types.TestStepResultStatus.SKIPPED;
+import static io.cucumber.messages.types.TestStepResultStatus.UNDEFINED;
+import static io.cucumber.messages.types.TestStepResultStatus.UNKNOWN;
+import static org.assertj.core.api.Assertions.assertThat;
+
+class TestStepResultStatusComparatorTest {
+
+    final TestStepResultStatusComparator comparator = new TestStepResultStatusComparator();
+    
+    @Test
+    void test(){
+        List<TestStepResultStatus> values = Arrays.asList(TestStepResultStatus.values());
+        Collections.shuffle(values);
+        values.sort(comparator);
+        assertThat(values).containsExactly(
+                UNKNOWN,
+                PASSED,
+                SKIPPED,
+                PENDING,
+                UNDEFINED,
+                AMBIGUOUS,
+                FAILED
+        );
+    }
+}