Intro to Derive4J

1. Introduction

Derive4J is an annotation processor that enables various functional concepts in Java 8.

In this tutorial, we’ll introduce Derive4J and the most important concepts enabled by the framework:

• Algebraic data types
• Structural pattern matching
• First class laziness

2. Maven Dependency

To use Derive4J, we need to include the dependency to our project:

<dependency>
    <groupId>org.derive4j</groupId>
    <artifactId>derive4j</artifactId>
    <version>1.1.0</version>
    <optional>true</optional>
</dependency>

3. Algebraic Data Types

3.1. Description

Algebraic data types (ADTs) are a kind of composite type – they are combinations of other types or generics.

ADTs generally fall into two main categories:

• sum
• product

Algebraic data types are present by default in many languages like Haskell and Scala.

3.2. Sum Type

Sum is the data type representing the logical OR operation. This means it can be one thing or another but not both of them. Simply speaking, sum type is a set of different cases. The name “sum” comes from the fact that the total number of distinct values is the total number of cases.

Enum is the closest thing in Java to the sum type. Enum has a set of possible values but can have only one of them at a time. However, we can’t associate any additional data with Enum in Java, which is the main advantage of algebraic data types over Enum.

3.3. Product Type

Product is the data type representing the logical AND operation. It’s the combination of several values.

Class in Java can be considered as a product type. Product types are defined by the combination of their fields altogether.

We can find more information on ADTs in this Wikipedia article.

3.4. Usage

One of the commonly used algebraic data types is Either. We can think of Either as a more sophisticated Optional that can be used when there is a possibility of missing values or the operation can result in an exception.

We need to annotate an abstract class or interface with at least one abstract method that will be used by Derive4J to generate the structure of our ADT.

To create the Either data type in Derive4J we need to create an interface:

@Data
interface Either<A, B> {
    <X> X match(Function<A, X> left, Function<B, X> right);
}

Our interface is annotated with @Data, which will allow Derive4J to generate the proper code for us. The generated code contains factory methods, lazy constructors, and various other methods.

By default, the generated code gets the name of the annotated class, but in plural form. But, there is a possibility to configure that via the inClass parameter.

Now, we can use the generated code to create the Either ADT and verify that it’s working properly:

public void testEitherIsCreatedFromRight() {
    Either<Exception, String> either = Eithers.right("Okay");
    Optional<Exception> leftOptional = Eithers.getLeft(either);
    Optional<String> rightOptional = Eithers.getRight(either);
    Assertions.assertThat(leftOptional).isEmpty();
    Assertions.assertThat(rightOptional).hasValue("Okay");
}

We can also use the generated match() method to execute a function depending on which side of Either is present:

public void testEitherIsMatchedWithRight() {
    Either<Exception, String> either = Eithers.right("Okay");
    Function<Exception, String> leftFunction = Mockito.mock(Function.class);
    Function<String, String> rightFunction = Mockito.mock(Function.class);
    either.match(leftFunction, rightFunction);
    Mockito.verify(rightFunction, Mockito.times(1)).apply("Okay");
    Mockito.verify(leftFunction, Mockito.times(0)).apply(Mockito.any(Exception.class));
}

4. Pattern Matching

One of the features enabled by the use of algebraic data types is pattern matching.

Pattern matching is the mechanism for checking a value against a pattern. Basically, pattern matching is a more powerful switch statement, but without limitations on the matching type or the requirement for patterns to be constant. For more information, we can check this Wikipedia article on pattern matching.

To use pattern matching, we’ll create a class that will model the HTTP request. The users will be able to use one of the given HTTP methods:

• GET
• POST
• DELETE
• PUT

Let’s model our request class as an ADT in Derive4J, starting with the HTTPRequest interface:

@Data
interface HTTPRequest {
    interface Cases<R>{
        R GET(String path);
        R POST(String path);
        R PUT(String path);
        R DELETE(String path);
    }

    <R> R match(Cases<R> method);
}

The generated class, HttpRequests (note the plural form), will now allow us to perform pattern matching based on the type of request.

For this purpose, we’ll create a very simple HTTPServer class that will respond with different Status depending on the type of request.

First, let’s create a simple HTTPResponse class that will serve as a response from our server to our client:

public class HTTPResponse {
    int statusCode;
    String responseBody;

    public HTTPResponse(int statusCode, String responseBody) {
        this.statusCode = statusCode;
        this.responseBody = responseBody;
    }
}

Then we can create the server that will use pattern matching to send the proper response:

public class HTTPServer {
    public static String GET_RESPONSE_BODY = "Success!";
    public static String PUT_RESPONSE_BODY = "Resource Created!";
    public static String POST_RESPONSE_BODY = "Resource Updated!";
    public static String DELETE_RESPONSE_BODY = "Resource Deleted!";

    public HTTPResponse acceptRequest(HTTPRequest request) {
        return HTTPRequests.caseOf(request)
          .GET((path) -> new HTTPResponse(200, GET_RESPONSE_BODY))
          .POST((path,body) -> new HTTPResponse(201, POST_RESPONSE_BODY))
          .PUT((path,body) -> new HTTPResponse(200, PUT_RESPONSE_BODY))
          .DELETE(path -> new HTTPResponse(200, DELETE_RESPONSE_BODY));
    }
}

The acceptRequest() method of our class uses pattern matching on the type of the request and will return different responses based on the type of request:

@Test
public void whenRequestReachesServer_thenProperResponseIsReturned() {
    HTTPServer server = new HTTPServer();
    HTTPRequest postRequest = HTTPRequests.POST("http://test.com/post", "Resource");
    HTTPResponse response = server.acceptRequest(postRequest);
    Assert.assertEquals(201, response.getStatusCode());
    Assert.assertEquals(HTTPServer.POST_RESPONSE_BODY, response.getResponseBody());
}

5. First Class Laziness

Derive4J allows us to introduce the concept of laziness, meaning that our objects will not be initialized until we perform an operation on them. Let’s declare the interface as LazyRequest and configure the generated class to be named LazyRequestImpl:

@Data(value = @Derive(
  inClass = "{ClassName}Impl",
  make = {Make.lazyConstructor, Make.constructors}
))
public interface LazyRequest {
    interface Cases<R>{
        R GET(String path);
        R POST(String path, String body);
        R PUT(String path, String body);
        R DELETE(String path);
    }

    <R> R match(LazyRequest.Cases<R> method);
}

We can now verify that the generated lazy constructor is working as it should:

@Test
public void whenRequestIsReferenced_thenRequestIsLazilyContructed() {
    LazyRequestSupplier mockSupplier = Mockito.spy(new LazyRequestSupplier());
    LazyRequest request = LazyRequestImpl.lazy(() -> mockSupplier.get());
    Mockito.verify(mockSupplier, Mockito.times(0)).get();
    Assert.assertEquals(LazyRequestImpl.getPath(request), "http://test.com/get");
    Mockito.verify(mockSupplier, Mockito.times(1)).get();
}

class LazyRequestSupplier implements Supplier<LazyRequest> {
    @Override
    public LazyRequest get() {
        return LazyRequestImpl.GET("http://test.com/get");
    }
}

We can find more information about first class laziness and examples in the Scala documentation.

6. Conclusion

In this tutorial, we introduced the Derive4J library and used it to implement some functional concepts, like Algebraic Data Types and pattern matching, which are normally not available in Java.

We can find more information about the library can be found in the official Derive4J documentation.