DEV Community: John Mercier

Comparing lombok features with groovy

John Mercier — Tue, 17 Nov 2020 17:21:43 +0000

Lombok

Lombok is a java annotation processor which generates boilerplate code automatically in your classes at compile time. Many of lombok's feature overlap with features in the groovy language and AST Transformations. Let us look at some of those features.

val and var

lombok

val creates a type inferred, final local variable.

the type will be inferred from the initializer expression. The local variable will also be made final.

var creates a type inferred, local variable.

var works exactly like val, except the local variable is not marked as final.

groovy

Groovy has support for def and var. Since groovy is optionally typed these keywords do not normally provide type inference.

def and var act as a type placeholder, i.e. a replacement for the type name, when you do not want to give an explicit type. (see variable definition)

When using @TypeChecked groovy will provide type inference.

When code is annotated with @TypeChecked, the compiler performs type inference. It doesn’t simply rely on static types, but also uses various techniques to infer the types of variables, return types, literals, … so that the code remains as clean as possible even if you activate the type checker.

To get the behavior of val in groovy apply @TypeChecked and declare a variable with def or var and the final keyword.

@TypeChecked
def final variable = '123'

@NonNull

lombok

Lombok will generate null checks for any generate method which involves a field marked with @NonNull.

Lombok has always treated various annotations generally named @NonNull on a field as a signal to generate a null-check if lombok generates an entire method or constructor for you, via for example @Data.

groovy

Groovy has @NullCheck which provides similar capabilities.

Class, method or constructor annotation which indicates that each parameter should be checked to ensure it isn't null. If placed at the class level, all explicit methods and constructors will be checked.

Lombok has several advantages over groovy. With lombok, if a field is marked with @NonNull all generated methods will perform null checks. In groovy this is not the case. includeGenerated must be set to true for groovy to generate null checks in generated code. When this option is applied in groovy code may still not have a null check. This issue appears to be fixed in groovy 4.

Lombok does not support @NonNull at the class level. This may be considered a disadvantage for some. Each parameter for non-generated methods must be explicitly declared as @NonNull. Lombok does guarantee that null checks will be created for all generated code.

@Cleanup

lombok

You can use @Cleanup to ensure a given resource is automatically cleaned up before the code execution path exits your current scope.

groovy

This feature is not supported by groovy although groovy does support additional idioms for automatic resource management with the use of closures.

@Getter and @Setter

lombok

You can annotate any field with @Getter and/or @Setter, to let lombok generate the default getter/setter automatically.

Lombok will generate getters and setters for all fields marked with these annotations. If the class is marked with these annotations all fields will have getters and setters generated. A developer may still supply one of these methods and lombok will keep the original method.

groovy

Getters and setters are automatically generated for properties in a groovy class. The getter and setter can be overridden by writing it in the class. Scope can be changed by overriding the method. Properties marked with final will not generate a setter.

@ToString

lombok

Any class definition may be annotated with @ToString to let lombok generate an implementation of the toString() method. By default, it'll print your class name, along with each field, in order, separated by commas.

groovy

Groovy has its own @ToString annotation. This is an ast which generates the toString() method for a class.

@EqualsAndHashCode

lombok

Any class definition may be annotated with @EqualsAndHashCode to let lombok generate implementations of the equals(Object other) and hashCode() methods.

groovy

Groovy provides a similar @EqualsAndHashCode annotation. This ast creates an equals() and hashCode() method. It has similar options to lombok.

@NoArgsConstructor, @RequiredArgsConstructor, @AllArgsConstructor

lombok

These annotations create constructors for the class. Required args is any final or uninitialized field with the @NonNull annotation.

groovy

Groovy provides @TupleConstructor which is able to create one constructor with a specific configuration.

It is not possible to create multiple constructors on one class with @TupleConstructor. This is the advantage of having multiple annotations in lombok.

@Data

lombok

@Data is a convenient shortcut annotation that bundles the features of @ToString, @EqualsAndHashCode, @Getter / @Setter and @RequiredArgsConstructor together: In other words, @Data generates all the boilerplate that is normally associated with simple POJOs (Plain Old Java Objects) and beans: getters for all fields, setters for all non-final fields, and appropriate toString, equals and hashCode implementations that involve the fields of the class, and a constructor that initializes all final fields, as well as all non-final fields with no initializer that have been marked with @NonNull, in order to ensure the field is never null.

groovy

Groovy has the @Cononical AST which combines @EqualsAndHashCode, @ToString, and @TupleConstructor.

@Value

lombok

@Value is the immutable variant of @Data; all fields are made private and final by default, and setters are not generated. The class itself is also made final by default, because immutability is not something that can be forced onto a subclass.

groovy

Groovy provides the @Immutable annotation.

@Builder

lombok

The @Builder annotation produces complex builder APIs for your classes.

groovy

Groovy provides the @Builder annotation.

@SnekyThrows

lombok

@SneakyThrows can be used to sneakily throw checked exceptions without actually declaring this in your method's throws clause.

groovy

In groovy all exceptions are optional and do not need to be declared.

@Synchronized

lombok

@Synchronized is a safer variant of the synchronized method modifier.

groovy

@Synchronized already exists in groovy and works in exactly the same way.

@With

lombok

The next best alternative to a setter for an immutable property is to construct a clone of the object, but with a new value for this one field. A method to generate this clone is precisely what @With generates: a withFieldName(newValue) method which produces a clone except for the new value for the associated field.

groovy

Similar methods to @With can be created in groovy with @Builder but the object is not immutable.

Groovy provides the @Builder annotation which can be used with a Simple Strategy to create chained setters.

 @Builder(builderStrategy=SimpleStrategy, prefix = 'with')

@Getter(lazy=true)

lombok

The @Getter(lazy=true) annotation creates a cached version of a getter method.

You can let lombok generate a getter which will calculate a value once, the first time this getter is called, and cache it from then on.

groovy

It is possible to use @Memoized.

@log

lombok

You put the variant of @Log on your class (whichever one applies to the logging system you use); you then have a static final log field, initialized as is the commonly prescribed way for the logging framework you use, which you can then use to write log statements.

groovy

Groovy provides @Log, @Log4j, and @Log4j2.

Plain text vs plaintext

John Mercier — Fri, 06 Nov 2020 20:01:59 +0000

Sometimes when we are programming we don't always do the right thing. This can easily be the result of how a requirement is phrased and a lack of context in assigned tasks. Lets take this example.

No password may be stored as plaintext.

If this were presented to a developer implementing a way to store passwords what would happen? Some developers may see this and think they only need to encode the password using Base64. Other developers may see this and think passwords should be encrypted. These are two very different solutions.

The problem is in the way the requirement is presented. If this is presented as a one line task assigned to a developer you may end up with the Base64 encoding solution. The task lacks context. It doesn't provide a reasoned argument for the requirement which may indicate which solution is better. That context may look something like this.

Passwords are a security mechanism meant to prevent access to some part of a system. Passwords should not be stored as plaintext so they cannot be easily exploited to gain access to the system.

No password may be stored as plaintext.

With this context a developer may understand that Base64 encoding is easy to recognize and decode to gain access to the system.

There is also an ambiguity in the requirement that is not being addressed. The ambiguity is in the meaning of plaintext. Plain text has two definitions.

Developers wanting to use Base64 encoding are defining plain text as readable text.

Plain Text

In computing, plain text is a loose term for data (e.g. file contents) that represent only characters of readable material but not its graphical representation nor other objects (floating-point numbers, images, etc.).

Developers wanting to use encryption are defining plain text as unencrypted data.

Plaintext

In cryptography, plaintext usually means unencrypted information pending input into cryptographic algorithms, usually encryption algorithms. Cleartext usually refers to data that is transmitted or stored unencrypted ("in clear").

The requirement should clear the ambiguity by addressing what is meant by plain text.

Passwords are a security mechanism meant to prevent access to some part of a system. Passwords should not be stored as plaintext so they cannot be easily exploited to gain access to the system.

No password may be stored as plaintext. Meaning, passwords should not be store as unencrypted data or "in the clear."

When writing tasks for other developers it is important to:

provide clarity by giving the context of a problem
remove any ambiguity that may result in an unintended solution

Converting names in C to Java

John Mercier — Fri, 31 Jul 2020 12:39:37 +0000

The x11 protocol is described in several xml files in the xcb project. These files define structures used in the C client. Each struct contains types and variable names. The variable names have two problems in java.

do not follow the lower camel case convention
start with invalid characters (numbers)

When converting these names to java I wanted to find an existing solution that could do this quickly. One benefit of java is that so many problems have already been solved by one library or another. I came across two projects that helped me solve these issues.

implementation group: 'com.google.guava', name: 'guava', version: '29.0-jre'
implementation 'pl.allegro.finance:tradukisto:1.8.0'

Guava contains the class CaseFormat which is able to convert between java and c style naming conventions. To convert from c to java:

String converted =  CaseFormat.LOWER_UNDERSCORE.to(CaseFormat.LOWER_CAMEL, x11Name)

This works for the majority of names but some of the enum items in the protocol start with a number.

    <enum name="PropertyFormat">
        <item name="8Bits">  <value>8</value> </item>
        <item name="16Bits"> <value>16</value> </item>
        <item name="32Bits"> <value>32</value> </item>
    </enum>

To convert these names tradukisto can be used to first convert the number to words. Then the rest of the name can be appended.

        String startNumbers = x11Name.find('^\\d+')
        if(startNumbers) {
            String remainingString = x11Name.substring(startNumbers.length())
            String numberWords = ValueConverters.ENGLISH_INTEGER.asWords(startNumbers.toInteger())
                .replace('-', ' ')
                .split(' ').collect{ it.capitalize() }.join('')
            return numberWords + remainingString
        }

With Guava and tradukisto I am able to easily convert c variable names to java variable names.

Exception Scenarios for Java's try-with-resources

John Mercier — Tue, 28 Jul 2020 16:35:54 +0000

Have you ever ran into an exception thrown by a try-with-resources block and wondered how it works? This article observes the behavior of try-with-resources under different scenarios and explains what is going on.

Support for try-with-resources was added in java 7 and has been enhanced in java 9. A try-with-resources block is able to automatically close resources when execution of the block completes. There are many different scenarios where try-with-resources will throw exceptions. This article explores those scenarios.

If you are following along with the test examples the TestResource class is attached at the bottom of this article.

TestResource is a mock object used to simulate a resource. It can be configured to fail the work() and close() methods. The createFailure() method simulates a failure to create a resource within a try block.

Creating Resources

Declare and initialize resource

Try-with-resources starts by declaring a resource inside a resource specification.

try(var r = new TestResource()) {
  //work with resource here
}

Resource Specification - "A resource specification uses variables to denote resources for the try statement, either by declaring local variables with initializer expressions or by referring to suitable existing variables. An existing variable is referred to by either an expression name (§6.5.6) or a field access expression (§15.11)." --Java Language Specification

First r is declared and initialized. After the try block executes r is automatically closed and goes out of scope.

creating resource "resource"
closing resource "resource"

declare resource only

In java 7 a resource needed to be declared and initialized in the resource specification. Since java 9 initialized is not required as long as the variables is effectively final. Here is an example:

try(r) {
  //work with resource here
}

multiple resources

Multiple resources can be used in a try-with-resources block.

try(var r1 = new TestResource("r1"); var r2 = new TestResource("r2")) {
    //work with resource here
}

Resources are created in order and closed in reverse order.

creating resource "r1"
creating resource "r2"
closing resource "r2"
closing resource "r1"

when creation fails with one resource

Here is an example of what happens when creation fails.

try(var r1 = createFailure()) {
    //work with resource here
}

An exception is thrown.

create failure
java.io.IOException: create failure
    at com.github.moaxcp.trywithresources.TestResource.createFailure(TestResource.java:12)
    at com.github.moaxcp.trywithresources.TestTryWithResources.creat_fails(TestTryWithResources.java:35)

The exception can be caught with a catch block.

try(var r1 = createFailure()) {
    //work with resource here
} catch (IOException e) {
    System.out.println("caught exception " + e);
}

An exception is thrown and caught.

create failure
caught exception java.io.IOException: create failure

when creation fails with multiple resources

Another scenario is what happens when creation fails with multiple resources.

try(var r1 = new TestResource("r1"); var r2 = createFailure()) {
    //work with resource here
} catch (IOException e) {
    System.out.println("caught exception " + e);
}

r1 is created, r2 fails to create, then r1 is closed, and then the catch block executes.

creating resource "r1"
create failure
closing resource "r1"
caught exception java.io.IOException: create failure

Notice that r1 is closed before the catch block is executed.

Working with resources

Now that we know the mechanics of creating a resoruce in a try-with-resources block lets examine working with resources inside the block.

Working with one resource

try(var r = new TestResource()) {
    r.work();
}

In this case the resource is create, work is performed, and the resource is closed.

creating resource "resource"
performing work with resource "resource"
closing resource "resource"

when the work fails

What happens with the work() method throws an exception? This can be done by setting the workFailure flag to true on the TestResource.

try(var r = new TestResource(true, false)) {
    r.work();
}

When work fails the resource should be close and then the exception can be caught or thrown.

creating resource "resource"
performing work with resource "resource"
work failure with resource "resource"
closing resource "resource"

work failure with resource "resource"
java.io.IOException: work failure with resource "resource"
    at com.github.moaxcp.trywithresources.TestResource.work(TestResource.java:47)
    at com.github.moaxcp.trywithresources.TestTryWithResources.work_with_resource_fails(TestTryWithResources.java:68)

In this case if there was a catch block it would be executed after the resource closes.

when work fails with multiple resources

When work fails with multiple resources the resources are closed in reverse order and the exception is caught or thrown.

try(var r1 = new TestResource("r1", false, false); var r2 = new TestResource("r2", true, false)) {
    r1.work();
    r2.work();
}

Here r2 is setup to fail when the work() method is called.

creating resource "r1"
creating resource "r2"
performing work with resource "r1"
performing work with resource "r2"
work failure with resource "r2"
closing resource "r2"
closing resource "r1"

work failure with resource "r2"
java.io.IOException: work failure with resource "r2"
    at com.github.moaxcp.trywithresources.TestResource.work(TestResource.java:47)
    at com.github.moaxcp.trywithresources.TestTryWithResources.work_with_multiple_resources_fails(TestTryWithResources.java:76)

As you can see, when r2.work() fails the resources are closed in reverse order and the exception is thrown.

Closing resources

As show before, a try-with-resources block will automatically close the resource but what happens when the close fails?

when close fails with one resource

Failing close can be achieve by setting the closeFailure flag to true on the TestResource.

try(var r = new TestResource(false, true)) {
    r.work();
}

When close fails the exception is thrown.

creating resource "resource"
performing work with resource "resource"
closing resource "resource"
close failure with resource "resource"

close failure with resource "resource"
java.io.IOException: close failure with resource "resource"
    at com.github.moaxcp.trywithresources.TestResource.close(TestResource.java:56)
    at com.github.moaxcp.trywithresources.TestTryWithResources.close_with_resource_fails(TestTryWithResources.java:84)

When close fails with two resources

Here r1 and r2 will fail to close.

try(var r1 = new TestResource("r1", false, true); var r2 = new TestResource("r2", false, true)) {
    r1.work();
    r2.work();
}

Since resources are closed in reverse order the exception from r2 will suppress the exception from r1.

creating resource "r1"
creating resource "r2"
performing work with resource "r1"
performing work with resource "r2"
closing resource "r2"
close failure with resource "r2"
closing resource "r1"
close failure with resource "r1"

close failure with resource "r2"
java.io.IOException: close failure with resource "r2"
    at com.github.moaxcp.trywithresources.TestResource.close(TestResource.java:56)
    at com.github.moaxcp.trywithresources.TestTryWithResources.close_with_two_resources_fails(TestTryWithResources.java:92)
Suppressed: java.io.IOException: close failure with resource "r1"
        at com.github.moaxcp.trywithresources.TestResource.close(TestResource.java:56)
        at com.github.moaxcp.trywithresources.TestTryWithResources.close_with_two_resources_fails(TestTryWithResources.java:89)

Notice - The exception from closing r1 is suppressed by the exception from r2.

When work and close fails

Now we are getting to the interesting scenario.

try(var r1 = new TestResource("r1", true, true); var r2 = new TestResource("r2", true, true)) {
    r1.work();
}

In this case work will fail but so will closing the two resources.

creating resource "r1"
creating resource "r2"
performing work with resource "r1"
work failure with resource "r1"
closing resource "r2"
close failure with resource "r2"
closing resource "r1"
close failure with resource "r1"

work failure with resource "r1"
java.io.IOException: work failure with resource "r1"
    at com.github.moaxcp.trywithresources.TestResource.work(TestResource.java:47)
    at com.github.moaxcp.trywithresources.TestTryWithResources.work_and_close_with_two_resources_fails(TestTryWithResources.java:98)
...
    Suppressed: java.io.IOException: close failure with resource "r2"
        at com.github.moaxcp.trywithresources.TestResource.close(TestResource.java:56)
        at com.github.moaxcp.trywithresources.TestTryWithResources.work_and_close_with_two_resources_fails(TestTryWithResources.java:97)
        ... 88 more
    Suppressed: java.io.IOException: close failure with resource "r1"
        at com.github.moaxcp.trywithresources.TestResource.close(TestResource.java:56)
        at com.github.moaxcp.trywithresources.TestTryWithResources.work_and_close_with_two_resources_fails(TestTryWithResources.java:97)
        ... 88 more

Here the work failure is thrown and the two close failures are suppressed.

Summary

Try-with-resources is a very helpful tool when dealing with resources. It is especially helpful when dealing with multiple resources. It saves the developer from having to write correct closing code. It also makes suppressed exceptions available so developers know exactly what failures occurred. This article outlines different mechanics of try-with-resources in different scenarios. Can you think of any other scenarios for try-with-resources?

TestResource

Before I start showing examples there is some code for a TestResource and a failing factory method that is needed.

class TestResource implements AutoCloseable {
    private final String name;
    private final boolean workFailure;
    private final boolean closeFailure;

    public static TestResource createFailure() throws IOException {
        System.out.println("create failure");
        throw new IOException("create failure");
    }

    public TestResource() {
        name = "resource";
        System.out.println("creating resource \"" + name + "\"");
        workFailure = false;
        closeFailure = false;
    }

    public TestResource(String name) {
        System.out.println("creating resource \"" + name + "\"");
        this.name = name;
        workFailure = false;
        closeFailure = false;
    }

    public TestResource(boolean workFailure, boolean closeFailure) throws IOException {
        this.name = "resource";
        System.out.println("creating resource \"" + name + "\"");
        this.workFailure = workFailure;
        this.closeFailure = closeFailure;
    }

    public TestResource(String name, boolean workFailure, boolean closeFailure) throws IOException {
        System.out.println("creating resource \"" + name + "\"");
        this.name = name;
        this.workFailure = workFailure;
        this.closeFailure = closeFailure;
    }

    public void work() throws IOException {
        System.out.println("performing work with resource \"" + name + "\"");
        if(workFailure) {
            System.out.println("work failure with resource \"" + name + "\"");
            throw new IOException("work failure with resource \"" + name + "\"");
        }
    }

    @Override
    public void close() throws IOException {
        System.out.println("closing resource \"" + name + "\"");
        if(closeFailure) {
            System.out.println("close failure with resource \"" + name + "\"");
            throw new IOException("close failure with resource \"" + name + "\"");
        }
    }
}

marking parameters and local variables as final

John Mercier — Tue, 07 Jul 2020 20:22:21 +0000

In a few projects at work everything is declared final. Even parameters and local variables. I believe this is done through a setting in intellij.

This seems excessive so I wanted to find a style guide that justifies this style. I couldn't find one. In fact, very few guides mention this style in a positive way. There is a guide for the jdk that describes some rare cases where this style applies.

Method parameters and local variables should not be declared final unless it improves readability or documents an actual design decision. Fields should be declared final unless there is a compelling reason to make them mutable.

Motivation

Writing out modifiers where they are implicit clutters the code and learning which modifiers are implicit where is easy.
Although method parameters should typically not be mutated, consistently marking all parameters in every methods as final is an exaggeration.
Making fields immutable where possible is good programming practice. Refer to Effective Java, Item 15: Minimize Mutability for details.

The google style guide does not mention using final for parameters and local variables.

The twitter styleguide does not directly mention using final for local variables or parameters but the examples only use final for fields.

Oracle's coding conventions does not mention making parameters or local variables final.

After checking several other style guides I have not found anywhere that states parameters and local variables should always be declared final.

Prior to java 8 local variables needed to be declared final when used in an anonymous inner class. This was changed in java 8 with the concept of effectively final variables. Since java 8, effectively final variables do not need to be marked as final. This is explained in the Java Language Specification.

Any local variable, formal parameter, or exception parameter used but not declared in an inner class must either be declared final or be effectively final (§4.12.4), or a compile-time error occurs where the use is attempted.

It also explains that the final modifier can be removed from code that declares parameters and local variables as final.

If a variable is effectively final, adding the final modifier to its declaration will not introduce any compile-time errors. Conversely, a local variable or parameter that is declared final in a valid program becomes effectively final if the final modifier is removed.

I believe this is where the suggestion in the first style guide applies. Parameters and local variables should only be declared final to improve readability or to document a design decision. They should not be declared final to "check a box" in a static code analysis report.

Let's code: graphs in java

John Mercier — Thu, 18 Jun 2020 01:47:45 +0000

I have been obsessed with graphs for a few years now. This obsession has resulted in three projects: graph-dsl, graphs, and graph-wm. Graphs are excellent data structures that have helped me in a few situations at work. In this tutorial we will develop a mutable DirectedGraph class in Java using Test Driven Development (TDD).

This tutorial starts each step with a goal. The goal is to either write a failing test, refactor existing code, or write production code. With each step you will get closer to representing a directed graph with a full suite of tests proving it works. These steps will help you practice TDD and provide insight into how TDD can help you write better code. Before we start coding here is an introduction to graphs and the definitions used to design the code.

Graph

Graph is not always well defined in programming languages. There are different implementations in java used for different situations. It is difficult for me to start coding a graph without some plan. First we need to put some concepts in place.

A graph encapsulates vertices and edges. A vertex is a value stored in the graph while an edge is a connection between those values. This implementation will contain a set of vertices and a set of edges.

Using a Set implies uniqueness. Only unique vertices and edges are allowed in the graph. These objects must correctly implement equals and hashCode.

Identity for edges can be tricky. It depends on if the graph is directed or undirected. In an undirected graph only one edge can be between any two vertices. In a directed graph one or two edges can be between any two vertices. If there are two edges between two vertices those edges must be in opposite directions. These properties will affect the implementation of equals and hashCode for edges.

At this point we have enough information to start coding but I want to explain TDD.

TDD

Here are the three laws of TDD (from Clean Coder by Robert C. Martin):

You are not allowed to write any production code until you have first written a failing unit test.

You are not allowed to write more of a unit test than is sufficient to fail -- and not compiling is failing.

You are not allowed to write more production code that is sufficient to pass the currently failing unit test.

These laws imply a workflow which consists of:

write a test that fails
write small production changes until all tests pass
refactor production code
refactor test code

refactor 🔄 change code in a way that does not fail tests and does not change the api or functionality.

To help facilitate TDD test status will be shown as a ❌ when failing and a ✔️ when passing.

The TDD workflow quickly switches between writing tests to writing production code. In These steps there very little refactoring but a future tutorial may introduce refactoring.

Lets get started.

Step 1

Like many tutorials this one is broken down into steps. Steps can be linked to using the form "step-1" for example.

[step-1](#step-1)

The goal in using steps is to help discussion in the comments.

The DirectedGraph class is production code. The class should not be written until there is a failing test according to law #1. Here is that test.

public class DirectedGraphTest {
  @Test
  void constructor() {
    DirectedGraph graph = new DirectedGraph();
  }
}

Test Satus: ❌ failing, write production code

Step 2

Workflow: The criteria in law #1 is met and now the workflow changes to add production code. A failure to compile is considered a test failure according to law #2 and so no more unit test code should be written.

Action: Create the DirectedGraph class. Most IDEs are helpful in situations where a class, method, or variable is missing. I am using intellij to create the class.

public class DirectedGraph {

}

Test Satus: ✔️ passing, write failing test

Step 3

Workflow: According to law #3 we should not write more production code. The only valid option is to follow law #1 and write a failing unit test.

Test Design: Back to the first test, it is obviously incomplete. The purpose of a constructor is to initialize the object. We have already discussed that DirectedGraph will have two Sets. This test should show that the graph is initialized by checking that these two Sets are empty.

Action: Add failing check for vertices.

@Test
void constructor() {
  DirectedGraph graph = new DirectedGraph();
  assertThat(graph.getVertices()).isEmpty();
}

Test Status: ❌ failing, write production code

Step 4

Workflow: The getVertices() method does not compile and now the test is failing (law #2) and production code can be added (law #1).

Action: The method can be added using the IDE but intellij does not know the return type to use. Here is the code.

public Set<T> getVertices() {
}

Production Design: In this case the IDE does not know how to design this method and I added the return value as a generic. The test is driving that these design decisions need to be made now. I am deciding that vertices must be a member variable and returned by getVertices(). I am also deciding that vertices are generic. Making vertices generic also implies that DirectedGraph is now generic.

public class DirectedGraph<T> {
  public Set<T> getVertices() {
    return null;
  }
}

Test Status: ❌ failing, write production code

Step 5

Action: The test will still fail but it does compile. At this point we need to return an empty Set for the test to pass.

public Set<String> getVertices() {
  return HashSet<>();
}

Test Satus: ✔️ passing, write failing test

Returning a new Set seems like an odd thing to do but I believe it is in line with the laws of TDD. Vertices will likely not become a member variable until a failing test shows it is needed.

Step 6

Refactor Test: 🔄 The test shows some warnings about the use of raw types. This can be fixed by adding a type parameter.

@Test
void constructor() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  assertThat(graph.getVertices()).isEmpty();
}

Test Satus: ✔️ passing, write failing test

Step 7

Workflow: Now the test is passing and another failing unit test is needed (law #2). Remember the current goal is to check the constructor. There is a test that checks vertices but what about edges.

I want to add an assertion that looks something like this:

assertThat(graph.getEdges()).isEmpty()

Design: But what is an edge? I have not decided how edges are represented in a graph. At this point I need a failing test but it doesn't have to be the constructor test. The context needs to switch to a focus on designing an edge.

DirectedEdge class

A DirectedEdge class should contain the source vertex and the target vertex of the edge. These are the endpoints of the edge. DirectedEdge must also use a generic type so the graph can specify different vertex types when creating an edge. Since edges will be in a Set they must implement equals and hashCode. I am also deciding that DirectedEdge should be an immutable value class which means source and target will be required constructor parameters and the class is final. This is enough information to create tests.

public class DirectedEdgeTest {
  @Test
  void constructor() {
    DirectedEdge<String> edge = new DirectedEdge<>();
  }
}

Test Status: ❌ failing, write production code

Step 8

As was in the case of DirectedGraphTest the DirectedEdge class may be generated in an IDE.

public final class DirectedEdge<T> {
}

Test Satus: ✔️ passing, write failing test

Step 9

Action: The test now passes but is the constructor correct? Lets add verification of the source vertex.

@Test
void constructor() {
  DirectedEdge<String> edge = new DirectedEdge<>();
  assertThat(edge.getSource()).isEqualTo("A");
}

Test Status: ❌ failing, write production code

Step 10

The method getSource() does not exist but also notice that the test is expecting it to be equal to "A". First getSource() can be added to DirectedEdge.

public T getSource() {
  return null;
}

The test will compile but still fail expecting the source to be "A".

public T getSource() {
  return (T) "A";
}

Test Satus: ✔️ passing, write failing test

Step 11

Action: Add verification for target vertex.

@Test
void constructor() {
  DirectedEdge<String> edge = new DirectedEdge<>();
  assertThat(edge.getSource()).isEqualTo("A");
  assertThat(edge.getTarget()).isEqualTo("B");
}

Test Status: ❌ failing, write production code

Step 12

Action: Add getTarget() method to DirectedEdge.

public T getTarget() {
  return (T) "B";
}

Test Satus: ✔️ passing, write failing test

Step 13

Action: replace default constructor with required args constructor.

@Test
void constructor() {
  DirectedEdge<String> edge = new DirectedEdge<>("A", "B");
  assertThat(edge.getSource()).isEqualTo("A");
  assertThat(edge.getTarget()).isEqualTo("B");
}

Test Status: ❌ failing, write production code

Step 14

Action: Add required args constructor (removing default constructor).

public final class DirectedEdge<T> {

  public DirectedEdge(T source, T target) {

  }

  public T getSource() {
    return (T) "A";
  }

  public T getTarget() {
    return (T) "B";
  }
}

Test Satus: ✔️ passing, write failing test

Step 15

Action: Add new constructor test with different source and target.

@Test
void constructor_AB() {
  DirectedEdge<String> edge = new DirectedEdge<>("A", "B");
  assertThat(edge.getSource()).isEqualTo("A");
  assertThat(edge.getTarget()).isEqualTo("B");
}

@Test
void constructor_XY() {
  DirectedEdge<String> edge = new DirectedEdge<>("X", "Y");
  assertThat(edge.getSource()).isEqualTo("X");
  assertThat(edge.getTarget()).isEqualTo("Y");
}

Test Status: ❌ failing, write production code

Step 16

Action: Add member variables and assign in constructor.

public final class DirectedEdge<T> {
  private final T source;
  private final T target;

  public DirectedEdge(T source, T target) {
    this.source = source;
    this.target = target;
  }

  public T getSource() {
    return "A";
  }

  public T getTarget() {
    return "B";
  }
}

Test Status: ❌ failing, write production code

Step 17

Action: Return member variables from getters.

public T getSource() {
  return source;
}

public T getTarget() {
  return target;
}

Test Satus: ✔️ passing, write failing test

Step 18

Action: Add null checks

It doesn't make sense to allow a null source or target. These parameters should be checked in the constructor. A nice way to do this is with Objects.requireNonNull.

@Test
void constructor_fails_on_null_source() {
  assertThatNullPointerException().isThrownBy(() -> new DirectedEdge<>(null, "B"));
}

Test Status: ❌ failing, write production code

Step 19

Action: write null checks

public DirectedEdge(T source, T target) {
  this.source = requireNonNull(source);
  this.target = target;
}

Test Satus: ✔️ passing, write failing test

Step 20

Action: Add check for exception message

Checking for the exception is ok but there is not real way to prove that the exception is caused by a null source. One way to show this is to check the message for the NullPointerException.

assertThatNullPointerException()
  .isThrownBy(() -> new DirectedEdge<>(null, "B"))
  .withMessage("source must not be null");

Test Status: ❌ failing, write production code

Step 21

Action: Add message to NPE

requireNonNull has another form that allows a message to be passed to the NPE.

this.source = requireNonNull(source, "source must not be null");

Test Satus: ✔️ passing, write failing test

Step 22

Action: Perform same test for target

@Test
void constructor_fails_on_null_target() {
  assertThatNullPointerException()
    .isThrownBy(() -> new DirectedEdge<>("A", null))
    .withMessage("target must not be null");
}

Test Status: ❌ failing, write production code

Step 23

Action: Add check for target in constructor

public DirectedEdge(T source, T target) {
  this.source = requireNonNull(source, "source must not be null");
  this.target = requireNonNull(target, "target must not be null");
}

Test Satus: ✔️ passing, write failing test

Step 24

Action: Test equals and hashCode.

Since edges are stored in a HashSet it makes sense to implement equals and hashCode.

Testing the equals and hashCode contract is difficult even in this simple case. There are two member variables source and target. Instead of writing all of these tests there is a tool available which can do these tests for us. This will be done using equals-verifier.

@Test
void equalsContract() {
    EqualsVerifier.forClass(DirectedEdge.class).verify();
}

Test Status: ❌ failing, write production code

Step 25

Action: Write equals and hashCode methods using IDE.

To generate this code in intellij I used the java 7+ format and source and target are non null.

@Override
public boolean equals(Object o) {
  if (this == o) return true;
  if (o == null || getClass() != o.getClass()) return false;
  DirectedEdge<?> that = (DirectedEdge<?>) o;
  return source.equals(that.source) &&
    target.equals(that.target);
}

@Override
public int hashCode() {
  return Objects.hash(source, target);
}

Test Status: ❌ failing, write production code

The equalsContract test will still fail since source and target are non-null.

Action: Suppress these warnings.

EqualsVerifier.forClass(DirectedEdge.class).suppress(Warning.NULL_FIELDS).verify();

Test Satus: ✔️ passing, write failing test

Step 26

Action: Add check for edges in DirectedGraph constructor

Now that there is a DirectedEdge class edges in the DirectedGraph constructor class can be checked.

@Test
void constructor() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  assertThat(graph.getVertices()).isEmpty();
  assertThat(graph.getEdges()).isEmpty();
}

Test Status: ❌ failing, write production code

Step 27

Action: Add getEdges method

public Set<DirectedEdge<T>> getEdges() {
  return new HashSet<>();
}

Test Satus: ✔️ passing, write failing test

Step 28

In this step we are testing that vertices can be added to the graph.

Action: Make test for adding vertices

@Test
void vertex_adds_new_vertex() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  graph.vertex("A");
}

Test Status: ❌ failing, write production code

Step 29

Action: Add vertex method

  public void vertex(T vertex) {

  }

Test Satus: ✔️ passing, write failing test

Step 30

Action: Add check for added vertex

@Test
void vertex_adds_new_vertex() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  graph.vertex("A");
  assertThat(graph.getVertices()).containsExactly("A");
}

Test Status: ❌ failing, write production code

Step 31

This test proves that DirectedGraph needs to store vertices.

Action: Add vertices member and change vertex method to add the vertex. Change getVertices() to return vertices.

public class DirectedGraph<T> {
  private final Set<T> vertices;

  public DirectedGraph() {
    vertices = new HashSet<>();
  }

  public Set<T> getVertices() {
    return vertices;
  }

  public Set<DirectedEdge<T>> getEdges() {
    return new HashSet<>();
  }

  public void vertex(T vertex) {
    vertices.add(vertex);
  }
}

Test Satus: ✔️ passing, write failing test

Step 32

The set returned by getVertices() should be unmodifiable.

Action: Add test ensuring vertices are unmodifiable.

@Test
void vertices_are_unmodifiable() {
  DirectedGraph<Integer> graph = new DirectedGraph<>();
  Set<Integer> vertices = graph.getVertices();
  assertThatThrownBy(() -> vertices.add(10))
    .isInstanceOf(UnsupportedOperationException.class);
}

Test Status: ❌ failing, write production code

Step 33

Action: return unmodifiable set in getVertices().

public Set<T> getVertices() {
  return unmodifiableSet(vertices);
}

Test Satus: ✔️ passing, write failing test

Step 34

The same can be done for getEdges().

*Action: * Add test for getEdges() ensuring set is unmodifiable.

@Test
void edges_are_unmodifiable() {
  DirectedGraph<Integer> graph = new DirectedGraph<>();
  Set<DirectedEdge<Integer>> edges = graph.getEdges();
  assertThatThrownBy(() -> edges.add(new DirectedEdge<>(1, 2)))
    .isInstanceOf(UnsupportedOperationException.class);
}

Test Status: ❌ failing, write production code

Step 35

Action: return unmodifiable set in getEdges().

public Set<DirectedEdge<T>> getEdges() {
  return unmodifiableSet(new HashSet<>());
}

Test Satus: ✔️ passing, write failing test

Step 36

null vertices should not be allowed.

Action: vertex fails on on null parameter.

@Test
void vertex_fails_on_null_vertex() {
  DirectedGraph<Integer> graph = new DirectedGraph<>();
  assertThatNullPointerException()
    .isThrownBy(() -> graph.vertex(null))
    .withMessage("vertex must not be null");
}

Test Status: ❌ failing, write production code

Step 37

Action: check for null vertices.

public void vertex(T vertex) {
  requireNonNull(vertex, "vertex must not be null");
  vertices.add(vertex);
}

Test Satus: ✔️ passing, write failing test

Step 38

Now that vertices can be added to the graph, edges should be added to the graph. This method should ensure that the vertices are added if not present in the graph. This time the tests start by checking for error conditions. The idea is to test for errors before writing the happy path code.

*Action: * Add check for null source parameter to edge method.

@Test
void edge_fails_on_null_source() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  assertThatNullPointerException()
    .isThrownBy(() -> graph.edge(null, "B"))
    .withMessage("source must not be null");
}

Test Status: ❌ failing, write production code

Step 39

The edge method does not exist and needs to be added.

public void edge(T source, T target) {
}

Test Status: ❌ failing, write production code

Step 40

Now the edge method needs to throw the exception.

*Action: * Add NPE to edge method.

public void edge(T source, T target) {
  throw new NullPointerException("source must not be null");
}

Test Satus: ✔️ passing, write failing test

Step 41

The edge method should also check target for null.

*Action: * Add test for null target parameter in edge method.

@Test
void edge_fails_on_null_target() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  assertThatNullPointerException()
    .isThrownBy(() -> graph.edge("A", null))
    .withMessage("target must not be null");
}

Test Status: ❌ failing, write production code

Step 42

The edge method now needs to actually check source for a null value.

*Action: * Add null checks for source and target in edge method.

public void edge(T source, T target) {
  requireNonNull(source, "source must not be null");
  requireNonNull(target, "target must not be null");
}

Test Satus: ✔️ passing, write failing test

Step 43

The edge method should add the source vertex if it is not already in the graph.

*Action: * Add test for source vertex in graph after calling edge.

@Test
void edge_adds_source_vertex() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  graph.edge("A", "B");
  assertThat(graph.getVertices()).contains("A");
}

Test Status: ❌ failing, write production code

Step 44

*Action: * Add source vertex to graph in edge method.

public void edge(T source, T target) {
  requireNonNull(source, "source must not be null");
  requireNonNull(target, "target must not be null");
  vertex(source);
}

Test Satus: ✔️ passing, write failing test

Step 45

The target vertex should also be added to the graph.

*Action: * Add test for target vertex in graph after calling edge.

@Test
void edge_adds_target_vertex() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  graph.edge("A", "B");
  assertThat(graph.getVertices()).contains("B");
}

Test Status: ❌ failing, write production code

Step 46

*Action: * Add source vertex to graph in edge method.

public void edge(T source, T target) {
  requireNonNull(source, "source must not be null");
  requireNonNull(target, "target must not be null");
  vertex(source);
  vertex(target);
}

Test Satus: ✔️ passing, write failing test

Step 47

The actual edge should be added as well.

*Action: * Add test checking if edge is added to the graph.

@Test
void edge_adds_an_edge() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  graph.edge("A", "B");
  assertThat(graph.getEdges()).containsExactly(new DirectedEdge<>("A", "B"));
}

Test Status: ❌ failing, write production code

Step 48

The test proves that edges needs to be a member variable which requires changes to the constructor getEdges() and the edge method.

*Action: * Add edges member variable, use member in getEdges and edges method.

public class DirectedGraph<T> {
  private final Set<T> vertices;
  private final Set<DirectedEdge<T>> edges;

  public DirectedGraph() {
    vertices = new HashSet<>();
    edges = new HashSet<>();
  }

  public Set<T> getVertices() {...}

  public Set<DirectedEdge<T>> getEdges() {
    return unmodifiableSet(edges);
  }

  public void vertex(T vertex) {...}

  public void edge(T source, T target) {
    requireNonNull(source, "source must not be null");
    requireNonNull(target, "target must not be null");
    vertex(source);
    vertex(target);
    edges.add(new DirectedEdge<>(source, target));
  }
}

Test Satus: ✔️ passing, write failing test

Step 49

At this point a method can be added to remove edges.

*Action: * Add test for removeEdge.

@Test
void removeEdge_fails_on_null_source() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  assertThatNullPointerException()
    .isThrownBy(() -> graph.removeEdge(null, "A"))
    .withMessage("source must not be null");
}

Test Status: ❌ failing, write production code

Step 50

*Action: * removeEdge needs to be added in order to compile.

public void removeEdge(T source, T target) {
}

Test Status: ❌ failing, write production code

Step 51

*Action: * Add check for a null source.

public void removeEdge(T source, T target) {
  requireNonNull(source, "source must not be null");
}

Test Satus: ✔️ passing, write failing test

Step 52

*Action: * Write a failing test checking for null target.

@Test
void removeEdge_fails_on_null_target() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  assertThatNullPointerException()
    .isThrownBy(() -> graph.removeEdge("A", null))
    .withMessage("target must not be null");
}

Test Status: ❌ failing, write production code

Step 53

*Action: * Add check in removeEdge for null target.

public void removeEdge(T source, T target) {
  requireNonNull(source, "source must not be null");
  requireNonNull(target, "target must not be null");
}

Test Satus: ✔️ passing, write failing test

Step 54

removeEdge should fail if the edge is not found.

*Action: * Add test expecting exception when edge does not exist.

@Test
void removeEdge_fails_on_missing_edge() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  assertThatIllegalArgumentException()
    .isThrownBy(() -> graph.removeEdge("A", "B"))
    .withMessage("edge with source \"A\" and target \"B\" does not exist");
}

Test Status: ❌ failing, write production code

Step 55

*Action: * Add check to see if edges contains the edge and throw exception if it is missing.

public void removeEdge(T source, T target) {
  requireNonNull(source, "source must not be null");
  requireNonNull(target, "target must not be null");
  if(!edges.contains(new DirectedEdge<>(source, target))) {
    throw new IllegalArgumentException(String.format("edge with source \"%s\" and target \"%s\" does not exist", source, target));
  }
}

Test Satus: ✔️ passing, write failing test

Step 56

*Action: * Add test for removing and edge from the graph.

@Test
void removeEdge_removes_edge() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  graph.edge("A", "B");
  graph.removeEdge("A", "B");
  assertThat(graph.getEdges()).isEmpty();
}

Test Status: ❌ failing, write production code

Step 57

Instead of calling contains the code can call remove. This will remove the edge and still throw an exception when the edge does not exist in the graph.

*Action: * Use remove instead of contains.

public void removeEdge(T source, T target) {
  requireNonNull(source, "source must not be null");
  requireNonNull(target, "target must not be null");
  if(!edges.remove(new DirectedEdge<>(source, target))) {
    throw new IllegalArgumentException(String.format("edge with source \"%s\" and target \"%s\" does not exist", source, target));
  }
}

Test Satus: ✔️ passing, write failing test

Step 58

Now a method is needed to remove vertices. Lets write a test for it.

*Action: * Add test for removing vertices.

@Test
void removeVertex_removes_vertex() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  graph.vertex("A");
  graph.removeVertex("A");
  assertThat(graph.getVertices()).isEmpty();
}

The test will fail to compile.

Test Status: ❌ failing, write production code

Step 59

*Action: * Add removeVertex method.

public void removeVertex(T vertex) {
}

Test Status: ❌ failing, write production code

Step 60

*Action: * remove vertex.

public void removeVertex(T vertex) {
  vertices.remove(vertex);
}

Test Satus: ✔️ passing, write failing test

Step 61

*Action: * add test for null vertex parameter in removeVertex.

@Test
void removeVertex_fails_on_null_vertex() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  assertThatNullPointerException()
    .isThrownBy(() ->graph.removeVertex(null))
    .withMessage("vertex must not be null");
}

Test Status: ❌ failing, write production code

Step 62

*Action: * Add null check to method.

public void removeVertex(T vertex) {
  requireNonNull(vertex, "vertex must not be null");
  vertices.remove(vertex);
}

Test Satus: ✔️ passing, write failing test

Step 63

There is one more failure condition when removing vertices. If the vertex being removed has adjacent edges those edges should also be removed.

Action: Add test checking that adjacent edges are removed when vertex is removed.

@Test
void removeVertex_removes_adjacent_edges() {
  DirectedGraph<String> graph = new DirectedGraph<>();
  graph.edge("A", "B");
  graph.removeVertex("A");
  assertThat(graph.getEdges()).isEmpty();
}

Test Status: ❌ failing, write production code

Step 64

Action: Find all adjacent edges and remove them in removeVertex.

public void removeVertex(T vertex) {
  requireNonNull(vertex, "vertex must not be null");
  Iterator<DirectedEdge<T>> i = edges.iterator();
  while(i.hasNext()) {
    DirectedEdge<T> next = i.next();
    if(next.getSource().equals(vertex) || next.getTarget().equals(vertex)) {
      i.remove();
    }
  }
  vertices.remove(vertex);
}

Test Satus: ✔️ passing, refactor 🔄 change code in a way that does not fail tests

Step 65

Now is a time to refactor. The refactor is actually suggested by Intellij. It replaces the iterator with a call to removeIf using a lambda.

Action: Refactor removeVertex to use removeIf when removing adjacent edges.

public void removeVertex(T vertex) {
  requireNonNull(vertex, "vertex must not be null");
  edges.removeIf(next -> next.getSource().equals(vertex) || next.getTarget().equals(vertex));
  vertices.remove(vertex);
}

Test Satus: ✔️ passing, write failing test

Conclusion

The DirecteGraph class is now able to create and remove vertices and edges. This tutorial described a design for graphs and provided a step-by-step guide for building DirectedGraph using TDD.

There are still several problems to solve but this is a good start in representing a graph as code.

emojis for developers

John Mercier — Tue, 12 May 2020 14:38:47 +0000

What emojis do you often use? I just found about these: ❌, ✔️. I would like to find some emojis for testing and refactoring. I think it would be cool to show a developer tdd workflow as emojis.

What is your $PS1?

John Mercier — Thu, 30 Apr 2020 17:14:25 +0000

Everyone has a different preference for $PS1 in bash what is yours?

debugging the micronaut package and code smells in nix

John Mercier — Tue, 28 Apr 2020 02:27:03 +0000

I am the maintainer for NixOS's micronaut package. This package installs the micronaut cli which can be used for creating projects and classes. The package is very simple. Here is the original.

{ stdenv, fetchzip, jdk, makeWrapper, installShellFiles }:

stdenv.mkDerivation rec {
  pname = "micronaut";
  version = "1.3.2";

  src = fetchzip {
    url = "https://github.com/micronaut-projects/micronaut-core/releases/download/v${version}/${pname}-${version}.zip";
    sha256 = "0jwvbymwaz4whw08n9scz6vk57sx7l3qddh4m5dlv2cxishwf7n3";
  };

  nativeBuildInputs = [ makeWrapper installShellFiles ];

  installPhase = ''
    runHook preInstall
    rm bin/mn.bat
    cp -r . $out
    wrapProgram $out/bin/mn \
      --prefix JAVA_HOME : ${jdk} 
    installShellCompletion --bash --name mn.bash bin/mn_completion
    runHook postInstall
  '';

  meta = ...;
}

This package copies the content into $out, wraps the mn command, and installs shell completion.

There are two problems with this script. First, --prefix is used for JAVA_HOME instead of --set. This causes two paths to be in the variable which can cause problems. Second, my user's PATH contains jdk14 but the script should use the default jdk.

{ stdenv, fetchzip, jdk, makeWrapper, installShellFiles }:

stdenv.mkDerivation rec {
  pname = "micronaut";
  version = "1.3.2";

  src = fetchzip {
    url = "https://github.com/micronaut-projects/micronaut-core/releases/download/v${version}/${pname}-${version}.zip";
    sha256 = "0jwvbymwaz4whw08n9scz6vk57sx7l3qddh4m5dlv2cxishwf7n3";
  };

  nativeBuildInputs = [ makeWrapper installShellFiles ];

  installPhase = ''
    runHook preInstall
    rm bin/mn.bat
    cp -r . $out
    wrapProgram $out/bin/mn \
      --prefix PATH : ${jdk}/bin 
    installShellCompletion --bash --name mn.bash bin/mn_completion
    runHook postInstall
  '';

  meta = ...;
}

This still introduces the user's entire path into the script breaking purity of the install. One principle of NixOS is that the environment is pure. Every input for the application is declared and the ouput is deterministic. Even though at this point the package works on my computer it is incorrect. Since PATH can contain anything there could be missing input in the package. The package may work when run locally but it may not always work with every user's PATH variable. Using --prefix for PATH should be considered a code smell in nix. --set should be used instead.

{ stdenv, fetchzip, jdk, makeWrapper, installShellFiles }:

stdenv.mkDerivation rec {
  pname = "micronaut";
  version = "1.3.2";

  src = fetchzip {
    url = "https://github.com/micronaut-projects/micronaut-core/releases/download/v${version}/${pname}-${version}.zip";
    sha256 = "0jwvbymwaz4whw08n9scz6vk57sx7l3qddh4m5dlv2cxishwf7n3";
  };

  nativeBuildInputs = [ makeWrapper installShellFiles ];

  installPhase = ''
    runHook preInstall
    rm bin/mn.bat
    cp -r . $out
    wrapProgram $out/bin/mn \
      --set PATH ${jdk}/bin 
    installShellCompletion --bash --name mn.bash bin/mn_completion
    runHook postInstall
  '';

  meta = ...;
}

This results in an error because there is in fact a missing dependency for micronaut that was not accounted for.

Error: Could not find or load main class io.micronaut.cli.MicronautCli

This is an interesting problem. At this point I almost gave up. The script mn builds a variable CLASSPATH which is used by java to run the application. If the class cannot be found this means the classpath is incorrect. Something I learned about bash is that it can be debugged using set -x. This can be patched into the mn script using nix.

  patchPhase = ''
    sed -i '2iset -x' bin/mn
  '';

Running mn again reveals some missing dependencies that result in classpath not being setup correctly.

...
++ dirname /nix/store/mhdwrfxd9dj0hipzygbdy4h70dhkq3yh-micronaut-1.3.4/bin/.mn-wrapped
/nix/store/mhdwrfxd9dj0hipzygbdy4h70dhkq3yh-micronaut-1.3.4/bin/.mn-wrapped: line 24: dirname: command not found
...
++ basename /nix/store/mhdwrfxd9dj0hipzygbdy4h70dhkq3yh-micronaut-1.3.4/bin/.mn-wrapped
/nix/store/mhdwrfxd9dj0hipzygbdy4h70dhkq3yh-micronaut-1.3.4/bin/.mn-wrapped: line 29: basename: command not found
...
/nix/store/mhdwrfxd9dj0hipzygbdy4h70dhkq3yh-micronaut-1.3.4/bin/.mn-wrapped: line 53: uname: command not found
+ CLASSPATH=//cli-1.3.4.jar
...

The missing dependencies are all located in the coreutils package. Its path can be added.

--set PATH ${coreutils}/bin:${jdk}/bin

Now when mn is run java appears to run and start the application but there is an exception.

Exception: java.lang.StackOverflowError thrown from the UncaughtExceptionHandler in thread "main"

The problem here is not obvious at all. It requires debugging the jvm. To do this from a nix expression options need to be added to the start the application with the debugger enabled. The mn script passes these options by setting MN_OPTS.

  installPhase = ''
    runHook preInstall
    rm bin/mn.bat
    cp -r . $out
    wrapProgram $out/bin/mn \
      --set MN_OPTS -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=8000 \
      --set JAVA_HOME ${jdk} \
      --set PATH ${coreutils}/bin:${jdk}/bin
    installShellCompletion --bash --name mn.bash bin/mn_completion
    runHook postInstall
  '';

To debug and set breakpoints I needed to checkout micronaut-core and open it in intellij. After a few hours I was able to narrow the problem down to the jline dependency. This code calls sh which is not on PATH.

The final result:

{ stdenv, coreutils, fetchzip, jdk, makeWrapper, installShellFiles }:

stdenv.mkDerivation rec {
  pname = "micronaut";
  version = "1.3.4";

  src = fetchzip {
    url = "https://github.com/micronaut-projects/micronaut-core/releases/download/v${version}/${pname}-${version}.zip";
    sha256 = "0mddr6jw7bl8k4iqfq3sfpxq8fffm2spi9xwdr4cskkw4qdgrrpz";
  };

  nativeBuildInputs = [ makeWrapper installShellFiles ];

  installPhase = ''
    runHook preInstall
    rm bin/mn.bat
    cp -r . $out
    wrapProgram $out/bin/mn \
      --set JAVA_HOME ${jdk} \
      --set PATH /bin:${coreutils}/bin:${jdk}/bin
    installShellCompletion --bash --name mn.bash bin/mn_completion
    runHook postInstall
  '';

  meta = with stdenv.lib; {
    description = "Modern, JVM-based, full-stack framework for building microservice applications";
    longDescription = ''
      Micronaut is a modern, JVM-based, full stack microservices framework
      designed for building modular, easily testable microservice applications.
      Reflection-based IoC frameworks load and cache reflection data for 
      every single field, method, and constructor in your code, whereas with 
      Micronaut, your application startup time and memory consumption are 
      not bound to the size of your codebase.
    '';
    homepage = "https://micronaut.io/";
    license = licenses.asl20;
    platforms = platforms.all;
    maintainers = with maintainers; [ moaxcp ];
  };
}

To recap the only changes made were to set JAVA_HOME instead of prefix it and to set PATH to all inputs into the application runtime. This problem was very easy to cause and difficult to debug. It is possible that it is in other packages in nix. Especially packages I wrote.

Project Escher

John Mercier — Mon, 13 Apr 2020 10:36:14 +0000

I'm really interested in x11 but I am a java developer. Java covers most desktop application development with swing and javafx. As a result, using x11 directly in java is not very common. While researching my options I started looking into an old project called escher. Escher started on sourceforge but there is a fork on github which is also published to maven central. Over the past few days I have done quite a bit of work on my own fork.

Converted mercurial history

The fork on gihub was based off version 0.3 sources but there were a few years of development after 0.3 in the mercurial repository. I was able to convert the mercurial history to git and start my fork with it. I followed this guide.

Added demo code

The 0.3 sources had demo code that was apparently removed from the mercurial repository. This code is important because there are no tests and the only way to know the library really works is to run the demos. I was able to add the missing demo code and get it to compile after a while of refactoring. At this point I believe I have all the code from the original project.

Fixed major bug from mercurial repository

After getting all of the code together and compiling there was a bug. Every Input event returned from X11 was LAST_EVENT. This is a special code that seems to mean null. I was able to debug this and found it was a simple == that should have been a !=.

Added XephyrRunner

XephyrRunner is a test helper I made which handles starting and stopping an x11 server for integration tests. I am also using it for the "demoTest" which is a way to automate running the demo code.

Added unix socket support

Escher didn't have a way to connect to a unix socket. It appeared to only support tcp connections. Most deployments of X11 never support tcp connections due to security concerns. I found another library called junixsocket and used it to connect escher to x11 through a unix socket.

Added github actions

In all of my other projects I use travis-ci. For escher I used github actions. Github Actions are nicely integrated into github and allow the community to share CI more easily. I still need to figure out how to run x11 tests on it though.

Added project to sonarcube

I added automated static analysis to the project using sonarcloud. As a legacy project without tests there are some bad practices and bugs in escher. Being able to perform static analysis on the whole project enables a more strategic approach to refactoring and testing the code.

Final thoughts

Why would someone go through this trouble to bring a mostly dead project back from its sourceforge grave? Like I said I want to work on X11 in java. I have an idea for a window manager and I think java has a lot to offer in this space.

Legacy code is everywhere. I like to define it as code without tests but this is a simplification. It is very common at work. A trend I have noticed is the pattern of creating legacy code is practiced between different projects. Legacy code is also copied between projects. Sometimes tests are added and code is refactored to better standards but there may be other copies that live on while the "good" code dies. Even new ideas are developed with legacy code. Because of this trend and my desire to "own" the code and have confidence in it, I spend as much time as permitted testing and refactoring code. I like to find better patterns and build nice APIs out of old code.

Escher may still end up as dead code in my github repo but this has been a gread experience so far.

Bye for now!

Mocking private static final log

John Mercier — Fri, 03 Apr 2020 18:25:46 +0000

Tests for logging is something I have tried to avoid in the past. Today I had to write some code which exports TestRail results to splunk and I was determined to test the output.

Instead of searching for how to do this using jmockit or mockito (since this hasn't worked for me in the past) I decided to try using reflection myself. I searched for "java reflection change private static field" and came across this post on stackoverflow. The post shows a way to change the value of a public static final field. There are some caveats but in the case of Logger it works out.

Combining this information with mockito I was able to mock the logger for a class and test logging output. First the test setup (junit 4.13):

@RunWith(MockitoJunitRunner.class)
public class SplunkReporterMethods {
  @Mock private Logger log;
  private SplunkReporter reporter;

  @Test
  public void report() {
    reporter.report(new Car());
    then(log).should().info("{\"name\":\"car\",\"speed\":4}");
  }
}

To setup the SplunkReporter class with a different logger the mock needs to be injected into the private static final field. This can be done in an @Before method.

@Before
void setup() {
  //allow log field to be changed
  Field field = SplunkReporter.class.getDeclaredField("log");
  field.setAccessible(true);

  //remove final modifier
  Field modifiersField = Field.class.getDeclaredField("modifiers");
  modifiersField.setAccessible(true);
  modifiersField.setInt(field, field.getModifiers() & ~Modifier.FINAL);

  //set to mock object
  field.set(null, log);
  reporter = new SplunkReporter();
}

First, the setup method makes log accessible but that is not enough. The modifiers on the field need to be changed so final is removed. The Field class does not have a setter for the modifiers field and so modifiers needs to be set in field using reflection. Finally the static field is set to the mock object.