Utterlyidle - RESTful Framework for Java Part 1/2

Overview:
This article looks at Utterlyidle, Google Code framework for writing RESTful services in Java. Utterlyidle is written based on totallylazy framework for functional programming. This is a good candidate for writing micro-services in Java.

Here, we will look at a simple example how you could leverage the Utterlyidle as a RESTful framework. The sample will demonstrate two aspects. Firstly, the server API and secondly, the client API usage to access the REST resources. This article will focus on the service API.

You can learn more about this framework here.

A comprehensive sample code for this article can be found here.

Project Structure:

 utterlyidle-sample-rest-app  
 ├── pom.xml  
 └── src  
   ├── main  
   │   ├── java  
   │   │   └── org  
   │   │     └── fazlan  
   │   │       ├── DemoApplication.java  
   │   │       ├── audit  
   │   │       │   ├── AuditHandler.java  
   │   │       │   └── AuditModule.java  
   │   │       ├── common  
   │   │       │   ├── CommonModule.java  
   │   │       │   ├── Json.java  
   │   │       │   ├── JsonResponseRenderer.java  
   │   │       │   └── Repository.java  
   │   │       ├── feed  
   │   │       │   ├── Feed.java  
   │   │       │   ├── FeedActivator.java  
   │   │       │   ├── FeedModule.java  
   │   │       │   ├── FeedRepository.java  
   │   │       │   ├── FeedResource.java  
   │   │       │   ├── Feeds.java  
   │   │       │   └── InMemoryFeedRepository.java  
   │   │       ├── framework  
   │   │       │   ├── CreateResponseFactory.java  
   │   │       │   ├── OkResponseFactory.java  
   │   │       │   └── ResponseFactory.java  
   │   │       └── greet  
   │   │         ├── GreetModule.java  
   │   │         └── GreetResource.java  
   │   └── resources  
   └── test  
     └── java  
       └── org  
         └── fazlan  
           ├── feed  
           │   ├── FeedActivatorTest.java  
           │   ├── FeedRepositoryTest.java  
           │   ├── FeedResourceAcceptanceTests.java  
           │   ├── InMemoryFeedRepositoryTest.java  
           │   └── ObjectMother.java  
           ├── greet  
           │   └── GreetResourceAcceptanceTests.java  
           └── testframework  
             ├── AcceptanceTests.java  
             ├── BDD.java  
             ├── RestClient.java  
             └── utterlyidle  
               ├── Function.java  
               └── UtterlyIdleRestClient.java  

Step 1: Creating the Project

 mvn archetype:generate -DartifactId=utterlyidle-sample-rest-app -DgroupId=org.fazlan -Dversion=1.0-SNAPSHOT -DinteractiveMode=false  

Step 2: Updating the Maven Dependencies

 <?xml version="1.0" encoding="UTF-8"?>  
 <project xmlns="http://maven.apache.org/POM/4.0.0"  
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
      xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">  
   <modelVersion>4.0.0</modelVersion>  
   <groupId>org.fazlan</groupId>  
   <artifactId>utterlyidle-sample-rest-app</artifactId>  
   <version>1.0-SNAPSHOT</version>  
   <repositories>  
     <repository>  
       <id>Utterlyidle - Bodar Repository</id>  
       <url>http://repo.bodar.com/</url>  
     </repository>  
   </repositories>  
   <properties>  
     <mvn.dep.googlecode.utterlyidle.version>742</mvn.dep.googlecode.utterlyidle.version>  
     <mvn.dep.googlecode.gson.version>2.2.4</mvn.dep.googlecode.gson.version>  
     <mvn.dep.testng.version>6.8.8</mvn.dep.testng.version>  
     <mvn.dep.hamcrest-core.version>1.3.RC2</mvn.dep.hamcrest-core.version>  
     <mvn.dep.mockito-all.version>1.9.5</mvn.dep.mockito-all.version>  
     <mvn.plug.failsafe.version>2.17</mvn.plug.failsafe.version>  
   </properties>  
   <dependencies>  
     <dependency>  
       <groupId>com.googlecode.utterlyidle</groupId>  
       <artifactId>utterlyidle</artifactId>  
       <version>${mvn.dep.googlecode.utterlyidle.version}</version>  
     </dependency>  
     <dependency>  
       <groupId>com.google.code.gson</groupId>  
       <artifactId>gson</artifactId>  
       <version>${mvn.dep.googlecode.gson.version}</version>  
     </dependency>  
     <dependency>  
       <groupId>org.testng</groupId>  
       <artifactId>testng</artifactId>  
       <version>${mvn.dep.testng.version}</version>  
       <scope>test</scope>  
     </dependency>  
     <dependency>  
       <groupId>org.hamcrest</groupId>  
       <artifactId>hamcrest-core</artifactId>  
       <version>${mvn.dep.hamcrest-core.version}</version>  
       <scope>test</scope>  
     </dependency>  
     <dependency>  
       <groupId>org.mockito</groupId>  
       <artifactId>mockito-all</artifactId>  
       <version>${mvn.dep.mockito-all.version}</version>  
       <scope>test</scope>  
     </dependency>  
   </dependencies>  
   <build>  
     <plugins>  
       <plugin>  
         <groupId>org.apache.maven.plugins</groupId>  
         <artifactId>maven-failsafe-plugin</artifactId>  
         <version>${mvn.plug.failsafe.version}</version>  
         <executions>  
           <execution>  
             <id>acceptance-test</id>  
             <phase>post-integration-test</phase>  
             <goals>  
               <goal>integration-test</goal>  
               <goal>verify</goal>  
             </goals>  
             <configuration>  
               <includes>  
                 <include>**/*AcceptanceTests.java</include>  
               </includes>  
             </configuration>  
           </execution>  
         </executions>  
       </plugin>  
     </plugins>  
   </build>  
 </project>  

Step 3: Creating the RESTful Endpoint
This is our first service containing a simple endpoint to elaborate the usage of the server API.

 package org.fazlan.greet;  
 
 import com.googlecode.utterlyidle.Response;  
 import com.googlecode.utterlyidle.annotations.GET;  
 import com.googlecode.utterlyidle.annotations.Path;  
 import com.googlecode.utterlyidle.annotations.PathParam;  
 import com.googlecode.utterlyidle.annotations.Produces; 
 
 import static com.googlecode.utterlyidle.MediaType.APPLICATION_JSON;  
 import static java.lang.String.format;  
 import static org.fazlan.framework.OkResponseFactory.ok;
  
 @Path("/greet")  
 @Produces(APPLICATION_JSON)  
 public class GreetResource {  

   @GET  
   @Path("hello/{name}")  
   public Response hello(@PathParam("name") final String name) {  
     return ok(format("Hello %s", name));  
   }  
 }  

Step 4: Creating an Application Module
The above rest service accepts a parameter called name, and returns a greeting message with that name. This service is then wired to the application via a module. Modules are the building blocks of a Utterlyidle application (Modular architecture - vertical silos compared to typical horizontal slices).

 package org.fazlan.greet;  

 import com.googlecode.utterlyidle.Resources;  
 import com.googlecode.utterlyidle.modules.ResourcesModule;  
 import static com.googlecode.utterlyidle.annotations.AnnotatedBindings.annotatedClass;  

 public class GreetModule implements ResourcesModule {  

   @Override  
   public Resources addResources(Resources resources) throws Exception {  
     return resources.add(annotatedClass(GreetResource.class));  
   }  
 }  

We create a module called GreetModule, and wire all the components related to that module.

Step 5: Adding a Module to the Application
Once the modules are created and ready, we can add them as building blocks of our application. One or more modules creates the entire application.

 package org.fazlan; 
 
 import com.googlecode.utterlyidle.Application;  
 import com.googlecode.utterlyidle.RestApplication;  
 import org.fazlan.audit.AuditModule;  
 import org.fazlan.greet.GreetModule;  

 import static com.googlecode.utterlyidle.ApplicationBuilder.application;  
 import static com.googlecode.utterlyidle.BasePath.basePath;  

 public class DemoApplication extends RestApplication {  
   public DemoApplication(String basePath) {  
     super(basePath(basePath));  
     addModules(this);  
   }  

   private void addModules(Application application) {  
     addInfrastructureModule(application);  
     addApplicationModules(application);  
   }  

   private void addInfrastructureModule(Application application) {  
     application.add(new AuditModule());  
   }  

   private void addApplicationModules(Application application) {  
     application.add(new GreetModule());  
   }  

   . . .  
 }  

Step 6: Running the Application
Once all the modules are added to the application, running the application is pretty simple. For this tutorial, we will run the application as a standalone server. This can be achieved as follows,

 package org.fazlan;  

 import static com.googlecode.utterlyidle.ApplicationBuilder.application;  
 import static com.googlecode.utterlyidle.BasePath.basePath;  

 public class DemoApplication extends RestApplication {  
   public DemoApplication(String basePath) {  
     super(basePath(basePath));  
     addModules(this);  
   }  

   . . .  

   public static void main(String[] args) throws Exception {  
     application(new DemoApplication("/")).start(7000);  
   }  
 }  

This would start the server at http://localhost:7000/. Greeting REST endpoint can be accessed at http://localhost:7000/greet/hello/

The endpoint can be accessed either,
http://localhost:7000/greet/hello/FooName or http://localhost:7000/greet/hello?name=FooName

Summary
This article briefly touch based on the capabilities provided by Utterlyidle based on totallylazy in building REST services.

You can learn more about this framework here.

A comprehensive sample code for this article can be found here.

Separating Unit, Integration and Acceptance Tests in Maven

Overview:
This article looks at how to segregate different types of tests in a build using Maven. There are several way in achieving this goal. However, this tutorial looks at a common approach that uses the following two Maven plugins.

maven-failsafe-plugin

build-helper-maven-plugin

Default Project Structure:

project-root
│
├── pom.xml
└── src
    ├── main
    │   ├── java
    │   └── resources
    └── test
        ├── java
        └── resources

Updated Project Structure:

project-root
│
├── pom.xml
 ├── src  
 │   ├── main  
 │   │   ├── java  
 │   │   │   └── Something.java  
 │   │   └── resources  
 │   │     └── prod-resource.txt  
 │   └── test  
 │     ├── acceptance  
 │     │   ├── java  
 │     │   │   └── SomethingAcceptanceTests.java  
 │     │   └── resources  
 │     │     └── acceptance-resource.txt  
 │     ├── integration  
 │     │   ├── java  
 │     │   │   └── SomethingIntegrationTests.java  
 │     │   └── resources  
 │     │     └── integration-resource.txt  
 │     └── unit  
 │       ├── java  
 │       │   └── SomethingTest.java  
 │       └── resources  
 │         └── unit-resource.txt  
 └── target  
   ├── classes  
   │   ├── Something.class  
   │   └── prod-resource.txt  
   ├── failsafe-reports  
   │   ├── SomethingAcceptanceTests.txt  
   │   ├── SomethingIntegrationTests.txt  
   │   ├── TEST-SomethingAcceptanceTests.xml  
   │   ├── TEST-SomethingIntegrationTests.xml  
   │   └── failsafe-summary.xml  
   ├── maven-archiver  
   │   └── pom.properties  
   ├── some.artifact.id-1.0-SNAPSHOT.jar  
   ├── surefire-reports  
   │   ├── SomethingAcceptanceTests.txt  
   │   ├── SomethingIntegrationTests.txt  
   │   ├── SomethingTest.txt  
   │   ├── TEST-SomethingAcceptanceTests.xml  
   │   ├── TEST-SomethingIntegrationTests.xml  
   │   └── TEST-SomethingTest.xml  
   └── test-classes  
     ├── SomethingAcceptanceTests.class  
     ├── SomethingIntegrationTests.class  
     ├── SomethingTest.class  
     ├── acceptance-resource.txt  
     ├── integration-resource.txt  
     └── unit-resource.txt  

Updated Maven pom.xml

 <?xml version="1.0" encoding="UTF-8"?>  
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">  
   <modelVersion>4.0.0</modelVersion>  
   <groupId>some.group</groupId>  
   <artifactId>some.artifact.id</artifactId>  
   <version>1.0-SNAPSHOT</version>  
   <packaging>jar</packaging>  
   <name>some.group.some.artifact.id</name>  
   <properties>  
    <project.dir.test.unit.java>src/test/unit/java</project.dir.test.unit.java>  
    <project.dir.test.unit.resources>src/test/unit/resources</project.dir.test.unit.resources>  
    <project.dir.test.integration.java>src/test/integration/java</project.dir.test.integration.java>  
    <project.dir.test.integration.resources>src/test/integration/resources</project.dir.test.integration.resources>  
    <project.dir.test.acceptance.java>src/test/acceptance/java</project.dir.test.acceptance.java>  
    <project.dir.test.acceptance.resources>src/test/acceptance/resources</project.dir.test.acceptance.resources>  
    <mvn.plug.failsafe.version>2.17</mvn.plug.failsafe.version>  
    <mvn.plug.build-helper.version>1.5</mvn.plug.build-helper.version>  
   </properties>  
   <build>  
    <testSourceDirectory>${project.dir.test.unit.java}</testSourceDirectory>  
    <testResources>  
      <testResource>  
       <directory>${project.dir.test.unit.resources}</directory>  
      </testResource>  
    </testResources>  
    <plugins>  
      <plugin>  
       <groupId>org.apache.maven.plugins</groupId>  
       <artifactId>maven-failsafe-plugin</artifactId>  
       <version>${mvn.plug.failsafe.version}</version>  
       <executions>  
         <execution>  
          <id>integration-test</id>  
          <phase>integration-test</phase>  
          <goals>  
            <goal>integration-test</goal>  
            <goal>verify</goal>  
          </goals>  
          <configuration>  
            <includes>  
             <include>**/*IntegrationTests.java</include>  
            </includes>  
          </configuration>  
         </execution>  
         <execution>  
          <id>acceptance-test</id>  
          <phase>post-integration-test</phase>  
          <goals>  
            <goal>integration-test</goal>  
            <goal>verify</goal>  
          </goals>  
          <configuration>  
            <includes>  
             <include>**/*AcceptanceTests.java</include>  
            </includes>  
          </configuration>  
         </execution>  
       </executions>  
      </plugin>  
      <plugin>  
       <groupId>org.codehaus.mojo</groupId>  
       <artifactId>build-helper-maven-plugin</artifactId>  
       <version>${mvn.plug.build-helper.version}</version>  
       <executions>  
         <execution>  
          <id>add-test-source</id>  
          <phase>process-resources</phase>  
          <goals>  
            <goal>add-test-source</goal>  
          </goals>  
          <configuration>  
            <sources>  
             <source>${project.dir.test.acceptance.java}</source>  
             <source>${project.dir.test.integration.java}</source>  
            </sources>  
          </configuration>  
         </execution>  
         <execution>  
          <id>add-test-resource</id>  
          <phase>generate-test-resources</phase>  
          <goals>  
            <goal>add-test-resource</goal>  
          </goals>  
          <configuration>  
            <resources>  
             <resource>  
               <directory>${project.dir.test.integration.resources}</directory>
             </resource>  
             <resource>  
               <directory>${project.dir.test.acceptance.resources}</directory>
             </resource>  
            </resources>  
          </configuration>  
         </execution>  
       </executions>  
      </plugin>  
    </plugins>  
   </build>  
 </project>  

Summary
We looked at how we can segregate different types of tests within the project using maven-failsafe-plugin and build-helper-maven-plugin

Tiny Types

Overview:

This article looks at Tiny Types, a pattern for writing code in an expressive manner.

Every developer should aim to write highly maintainable piece of software. This not only promotes minimal effort to maintain the software but also cost effective in the long run. One such way of writing a maintainable software is to make your code (including your tests) highly readable. Writing code in an expressive manner(using domain concepts that your software is targeted towards) greatly improves the readability of the code.

Tiny Types, is one such way that allows to write highly expressive code. This is a pattern used to encapsulate built-in types such as String, Integer, Big Decimal etc in a domain specific concept. I have used this pattern in several projects to great-effect that promotes Domain Driven Design concepts.

Snippet 1: Writing using built-in types

 public class Student {  
   public final String id;  
   public final String name;  

   public Student(String id, String name) {  
      this.id = id;  
      this.name = name;  
   }  
   . . .  
 }  

The above example looks fine, however it doesn’t guarantee from us interchanging the two parameters,

 Student s1 = new Student(“SID001”, “Harry”);
  
 // syntactically correct, however, this will cause system failure in runtime.  
 Student s2 = new Student(“Sam”, “SID002”);  

which would lead to bugs in the system that are hard to discover and waste precious time and money on finding and fixing them.

Snippet 2: Rewriting the above as follows

 public class Id {  
   public final String id;  

   public Id(String id) {  
      this.id = id;  
   }  
   . . .  
 }  
  public class Name {  
   public final String name; 
 
   public Id(String name) {  
      this.name = name;  
   }  
   . . .  
 }  
  public class Student {  
   public final Id id;  
   public final Name name; 
 
   public Student(Id id, Name name) {  
      this.id = id;  
      this.name = name;  
   }  
   . . .  
 }  

Where, Id and Name are separate classes to represent student id and name respectively. Now, you have THREE classes altogether instead of one single Student class. That means you have to write extra bit of boiler template code, but it should be fairly easy with the IDE support available, today.

With this approach several advantages are immediately visible.

Improved Readability - Now, the definition of the classes becomes very expressive and concepts around the system gets more clear.

Segregation of Responsibility - All the responsibility specific to a given type should reside in its class. With the new design, the responsibilities are well-defined and self-contained in the type definition.

e.i. The validation logic related to a name should be placed in the Name class itself. Otherwise, as per code-snippet-1, we would have done the validation in the student class, which isn’t really relevant there.

Compile-time Error Detection - Since Java is statically typed, with the current design, we will not be able to interchange an id with a name, whereas, in the previous design it was allowed.

Student s1 = new Student(new Id(“SID001”), new Name(“Harry”));

// Not allowed anymore, this will cause compilation error.

Student s2 = new Student(new Name(“Sam”), new Id(“SID002”));

Thread-safe - We can make the tiny types immutable, thus they can be used in a concurrent environment. Also, it will ensure that no other parts of the system will be able to modify the state of these objects.

Automated Tool Usage - With the new design, code refactoring and finding usage of the references of these types becomes much more simpler and provides far better useful results.

Finding the references on the “Name” class results more helpful results than performing the same operation on a String typed field.

On the contrary, many would argue that introducing this pattern to a system would end up in creating a lot of objects has a result of encapsulating built-in types and hence, a high memory usage and makes the system slow. Actually, these tiny type objects are short-lived and If you consider how the Garbage Collector works, it actually tries to preserve the objects (long lived) that are referenced by the system and not otherwise. Thus, creating short-lived tiny types will not affect the Garbage Collector. In fact, the  Garbage Collector will have less work because it simply doesn’t care about short-lived objects.

In summary, based on my personal experience, the adoption of Tiny Types immensely improves the readability, quality and the maintainability of a piece of software, and the benefits of this pattern overweighs the initial effort required to adapt.