Getting started with Spark: it is possible to create lightweight RESTful application also in Java
Recently I have been writing a RESTful service using Spark, a web framework for Java (which is not related to Apache Spark). When we planned to write this I was ready to the unavoidable Javaesque avalanche of interfaces, boilerplate code and deep hierarchies. I was very surprised to find out that an alternative world exists also for the developers confined to Java.
In this post we are going to see how to build a RESTful application for a blog, using JSON to transfer data. We will see:
- how to create a simple Hello world in Spark
- how to specify the layout of the JSON object expected in the request
- how to send a post request to create a new post
- how to send a get request to retrieve the list of posts
We are not going to see how to insert this data in a DB. We will just keep the list in memory (in my real service I have been using sql2o).
A few dependencies
We will be using Maven so I will start by creating a new pom.xml throwing in a few things. Basically:
- Spark
- Jackson
- Lombok
- Guava
- Easymock (used only in tests, not presented in this post)
- Gson
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.12</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.sparkjava</groupId>
<artifactId>spark-core</artifactId>
<version>2.1</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>2.5.1</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.5.1</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.16.2</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.sql2o</groupId>
<artifactId>sql2o</artifactId>
<version>1.5.4</version>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>9.4-1201-jdbc41</version>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>18.0</version>
</dependency>
<dependency>
<groupId>org.easymock</groupId>
<artifactId>easymock</artifactId>
<version>3.3.1</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.3.1</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.2</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>1.2.1</version>
<configuration>
<mainClass>me.tomassetti.BlogService</mainClass>
<arguments>
</arguments>
</configuration>
</plugin>
</plugins>
</build>Spark hello world
Do you have all of this? Cool let’s write some code then.
package me.tomassetti;
import static spark.Spark.get;
import static spark.Spark.post;
import spark.Request;
import spark.Response;
import spark.Route;
public class BlogService
{
public static void main( String[] args) {
get("/posts", (req, res) -> {
return "Hello Sparkingly World!";
});
}
}And now we can run it with something like:
mvn compile && mvn exec:java
Let’s open a browser and visit localhost http://localhost:4567/posts. Here we want to do a simple get. For performing posts you could want to use the Postman plugin for your browser or just run curl. Whatever works for you.
Using Jackson and Lombok for awesome descriptive exchange objects
In a typical RESTful application we expect to receive POST requests with json objects as part of the payload. Our job will be to check the code is well-formed JSON, that it corresponds to the expected structure, that the values are in the valid ranges, etc. Kind of boring and repetitive. We could do that in different ways. The most basic one is to use gson:
JsonParser parser = new JsonParser();
JsonElement responseData = parser.parse(response);
if (!responseData.isJsonObject()){
// send an error like: "Hey, you did not pass an Object!
}
JsonObject obj = responseData.getAsJsonObject();
if (!obj.hasField("title")){
// send an error like: "Hey, we were expecting a field name title!
}
JsonElement titleAsElem = obj.get("title");
if (!titleAsElem.isString()){
// send an error like: "Hey, title is not an string!
}
// etc, etc, etcWe probably do not want to do that.
A more declarative way to specify what structure we expect is creating a specific class.
class NewPostPayload {
private String title;
private List<String> categories;
private String content;
public String getTitle() { ... }
public void setTitle(String title) { ... }
public List<String> getCategories() { ... }
public void setCategories(List<String> categories){ ... }
public String getContent() { ... }
public void setContent(String content) { ... }
}And then we could use Jackson:
try {
ObjectMapper mapper = new ObjectMapper();
NewPostPayload newPost = mapper.readValue(request.body(), NewPostPayload.class);
} catch (JsonParseException e){
// Hey, you did not send a valid request!
}In this way Jackson check automatically for us if the payload has the expected structure. We could want to verify if additional constraints are respected. For example we could want to check if the title is not empty and at least one category is specified. We could create an interface just for validation:
interface Validable {
boolean isValid();
}
class NewPostPayload implements Validable {
private String title;
private List<String> categories;
private String content;
public String getTitle() { ... }
public void setTitle(String title) { ... }
public List<String> getCategories() { ... }
public void setCategories(List<String> categories){ ... }
public String getContent() { ... }
public void setContent(String content) { ... }
public boolean isValid() {
return title != null && !title.isEmpty() && !categories.isEmpty();
}
}Still we have a bunch of boring getters and setters. They are not very informative and just pollute the code. We can get rid of them using Lombok. Lombok is an annotation processor that add repetitive methods for you (getters, setters, equals, hashCode, etc.). You can think of it as a plugin for your compiler that looks for annotations (like @Data) and generates methods based on them. If you add it to your dependencies maven will be fine but your IDE could not give you auto-completion for the methods that Lombok adds. You may want to install a plugin. For Intellij Idea I am using Lombok Plugin version 0.9.1 and it works great.
Now you can revise the class NewPostPayload as:
@Data
class NewPostPayload {
private String title;
private List<String> categories;
private String content;
public boolean isValid() {
return title != null && !title.isEmpty() && !categories.isEmpty();
}
}Much nicer, eh?
A complete example
We need to do basically two things:
- insert a new post
- retrieve the whole list of posts
The first operation should be implemented as a POST (it has side effects), while the second one as a GET. Both of them are operation on the posts collection so we will use the endpoint /posts .
Let’s start by inserting post. First of all we will parse
// insert a post (using HTTP post method)
post("/posts", (request, response) -> {
try {
ObjectMapper mapper = new ObjectMapper();
NewPostPayload creation = mapper.readValue(request.body(), NewPostPayload.class);
if (!creation.isValid()) {
response.status(HTTP_BAD_REQUEST);
return "";
}
int id = model.createPost(creation.getTitle(), creation.getContent(), creation.getCategories());
response.status(200);
response.type("application/json");
return id;
} catch (JsonParseException jpe) {
response.status(HTTP_BAD_REQUEST);
return "";
}
});And then see how to retrieve all the posts:
// get all post (using HTTP get method)
get("/posts", (request, response) -> {
response.status(200);
response.type("application/json");
return dataToJson(model.getAllPosts());
});And the final code is:
package me.tomassetti;
import static spark.Spark.get;
import static spark.Spark.post;
import com.fasterxml.jackson.core.JsonParseException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import lombok.Data;
import spark.Request;
import spark.Response;
import spark.Route;
import java.io.IOException;
import java.io.StringWriter;
import java.util.HashMap;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;
import java.util.stream.Collector;
import java.util.stream.Collectors;
public class BlogService
{
private static final int HTTP_BAD_REQUEST = 400;
interface Validable {
boolean isValid();
}
@Data
static class NewPostPayload {
private String title;
private List<String> categories = new LinkedList<>();
private String content;
public boolean isValid() {
return title != null && !title.isEmpty() && !categories.isEmpty();
}
}
// In a real application you may want to use a DB, for this example we just store the posts in memory
public static class Model {
private int nextId = 1;
private Map<Integer, Post> posts = new HashMap<>();
@Data
class Post {
private int id;
private String title;
private List<String> categories;
private String content;
}
public int createPost(String title, String content, List<String> categories){
int id = nextId++;
Post post = new Post();
post.setId(id);
post.setTitle(title);
post.setContent(content);
post.setCategories(categories);
posts.put(id, post);
return id;
}
public List<Post> getAllPosts(){
return posts.keySet().stream().sorted().map((id) -> posts.get(id)).collect(Collectors.toList());
}
}
public static String dataToJson(Object data) {
try {
ObjectMapper mapper = new ObjectMapper();
mapper.enable(SerializationFeature.INDENT_OUTPUT);
StringWriter sw = new StringWriter();
mapper.writeValue(sw, data);
return sw.toString();
} catch (IOException e){
throw new RuntimeException("IOException from a StringWriter?");
}
}
public static void main( String[] args) {
Model model = new Model();
// insert a post (using HTTP post method)
post("/posts", (request, response) -> {
try {
ObjectMapper mapper = new ObjectMapper();
NewPostPayload creation = mapper.readValue(request.body(), NewPostPayload.class);
if (!creation.isValid()) {
response.status(HTTP_BAD_REQUEST);
return "";
}
int id = model.createPost(creation.getTitle(), creation.getContent(), creation.getCategories());
response.status(200);
response.type("application/json");
return id;
} catch (JsonParseException jpe) {
response.status(HTTP_BAD_REQUEST);
return "";
}
});
// get all post (using HTTP get method)
get("/posts", (request, response) -> {
response.status(200);
response.type("application/json");
return dataToJson(model.getAllPosts());
});
}
}Using PostMan to try the application
You may want to use curl instead, if you prefer the command line. I like not having to escape my JSON and having a basic editor so I use PostMan (a Chrome plugin).
Let’s insert a post. We specify all the fields as part of a Json object inserted in the body of the request. We get back the ID of the post created.
Then we can get the list of the posts. In this case we use a GET (no body in the request) and we get the data of all the posts (just the one we inserted above).
Conclusions
I have to say that I was positively surprised by this project. I was ready for the worse: this is the kind of application that requires a basic logic and a lot of plumbing. I found out that Python, Clojure and Ruby do all a great jobs for this kinds of problems, while the times I wrote simple web applications in Java the logic was drown in boilerplate code. Well, things can be different. The combination of Spark, Lombok, Jackson and Java 8 is really tempting. I am very grateful to the authors of these pieces of software, they are really improving the life of Java developers. I consider it also a lesson: great frameworks can frequently improves things much more than we think.
Edit: I received a suggestion to improve one of the example from the good folks on reddit. Thanks! Please keep the good suggestions coming!
| Reference: | Getting started with Spark: it is possible to create lightweight RESTful application also in Java from our JCG partner Federico Tomassetti at the Federico Tomassetti blog. |
