Spark Java

What is Spark Java?

Spark is a Java micro framework that allows to quickly create web applications in Java 8. Spark is a lightweight and simple Java web framework designed for quick development. Sinatra, a popular Ruby micro framework, was the inspiration for it.

Spark makes considerable use of Java 8's lambda expressions, that makes Spark applications less verbose. Unlike other Java web frameworks, it does not largely rely on XML files or annotations.

Starting with Spark Java

Step 1: Create a maven project and include the dependency in the pom.xml

<dependency>
    <groupId>com.sparkjava</groupId>
    <artifactId>spark-core</artifactId>
    <version>2.9.3</version>
</dependency>

Step 2: Copy the following code.

import static spark.Spark.*;
public class HelloWorld 
{
    public static void main(String[] args) 
{
        get("/hello", (req, res) -> "Hello World");
    }
}

Step 2: Enter the following URL in the web browser to see the results.

Starting the Server

When we perform something that requires the server to be started, it is automatically started (i.e. declaring a route or setting the port).

We can also start the server manually by typing init ().

If initialization fails, we can describe what should happen:

Logging and shutting down is the default behaviour:

private Consumer<Exception> initExceptionHandler = (e) -> {
    LOG.error("ignite failed", e);
    System.exit(100);
};

Stopping the Server

The server is stopped and all routes are cleaned when the stop() method is invoked.

Routes

There are a number of routes in a Spark application. A route is a mapping between URL patterns and Java handlers.

There are three parts to a route:

A verb - get, post, put, delete, head, trace, connect, and options
a path - like /first or /hello/:name
a callback - (request, response) ->{ }

The order in which routes are defined determines how they are matched. The request is forwarded to the first route that matches the request.

To maintain decent readability, always statically import Spark methods:

get("/", (request, response) -> {
    // Show something
});
post("/", (request, response) -> {
    // Create something
});
put("/", (request, response) -> {
    // Update something
});
delete("/", (request, response) -> {
    // Annihilate something
});
options("/", (request, response) -> {
    // Appease something
});

The params() method on the request object can be used to retrieve named parameters in route patterns:

// matches "GET /hello/foo" and "GET /hello/bar"
// request.params(":name") is 'foo' or 'bar'
get("/hello/:name", (request, response) -> {
    return "Hello: " + request.params(":name");
});

Splat (or wildcard) parameters can also be used in route patterns. The splat() method on the request object can be used to retrieve these parameters:

// matches "GET /say/hello/to/world"
// request.splat()[0] is 'hello' and request.splat()[1] 'world'
get("/say/*/to/*", (request, response) -> {
    return "Number of splat parameters: " + request.splat().length;
});

Unmapping of routes

The 'unmap' function can be used to unmap routes:

unmap("/hello"); // unmaps all routes with path 'hello'
unmap("/hello", "get"); // unmaps all 'GET' routes with path 'hello'

Groups of paths

Separating routes into groups can be useful if you have a lot of them. It is accomplished by invoking the path() method. The method accepts a String prefix and returns a scope in which to create routes and filters (or nested paths):

path("/api", () -> {
    before("/*", (q, a) -> log.info("Received api call"));
    path("/email", () -> {
        post("/add",       EmailApi.addEmail);
        put("/change",     EmailApi.changeEmail);
        delete("/remove",  EmailApi.deleteEmail);
    });
    path("/username", () -> {
        post("/add",       UserApi.addUsername);
        put("/change",     UserApi.changeUsername);
        delete("/remove",  UserApi.deleteUsername);
    });
});

Request

The request parameter provides the following information and functionality:

request.attributes();             // the attributes list
request.attribute("foo");         // value of foo attribute
request.attribute("A", "V");      // sets value of attribute A to V
request.body();                   // request body sent by the client
request.bodyAsBytes();            // request body as bytes
request.contentLength();          // length of request body
request.contentType();            // content type of request.body
request.contextPath();            // the context path, e.g. "/hello"
request.cookies();                // request cookies sent by the client
request.headers();                // the HTTP header list
request.headers("BAR");           // value of BAR header
request.host();                   // the host, e.g. "example.com"
request.ip();                     // client IP address
request.params("foo");            // value of foo path parameter
request.params();                 // map with all parameters
request.pathInfo();               // the path info
request.port();                   // the server port
request.protocol();               // the protocol, e.g. HTTP/1.1
request.queryMap();               // the query map
request.queryMap("foo");          // query map for a certain parameter
request.queryParams();            // the query param list
request.queryParams("FOO");       // value of FOO query param
request.queryParamsValues("FOO")  // all values of FOO query param
request.raw();                    // raw request handed in by Jetty
request.requestMethod();          // The HTTP method (GET, ..etc)
request.scheme();                 // "http"
request.servletPath();            // the servlet path, e.g. /result.jsp
request.session();                // session management
request.splat();                  // splat (*) parameters
request.uri();                    // the uri, e.g. "http://example.com/foo"
request.url();                    // the url. e.g. "http://example.com/foo"
request.userAgent();              // user agent

Response

The response parameter provides the following information and functionality:

response.body();               // get response content
response.body("Hello");        // sets content to Hello
response.header("FOO", "bar"); // sets header FOO with value bar
response.raw();                // raw response handed in by Jetty
response.redirect("/example"); // browser redirect to /example
response.status();             // get the response status
response.status(401);          // set status code to 401
response.type();               // get the content type
response.type("text/xml");     // set content type to text/xml

Query Maps

We can use query maps to group arguments into a map based on their prefix. It allows us to add two parameters to a user map, such as user[name] and user[age].

request.queryMap().get("user", "name").value();
request.queryMap().get("user").get("name").value();
request.queryMap("user").get("age").integerValue();
request.queryMap("user").toMap();

Cookies

request.cookies();                         // get map of all request cookies
request.cookie("foo");                     // access request cookie by name
response.cookie("foo", "bar");             // set cookie with a value
response.cookie("foo", "bar", 3600);       // set cookie with a max-age
response.cookie("foo", "bar", 3600, true); // secure cookie
response.removeCookie("foo");              // remove cookie

Sessions

Every request has access to the server-side session, which is given through the following methods:

request.session(true);                     // create and return session
request.session().attribute("user");       // Get session attribute 'user'
request.session().attribute("user","foo"); // Set session attribute 'user'
request.session().removeAttribute("user"); // Remove session attribute 'user'
request.session().attributes();            // Get all session attributes
request.session().id();                    // Get session id
request.session().isNew();                 // Check if session is new
request.session().raw();                   // Return servlet object

Halting

Use halt() method to immediately stop a request within a filter or route:

halt();                // halt 
halt(401);             // halt with status
halt("Body Message");  // halt with message
halt(401, "Go away!"); // halt with status and message

Note: halt() should not be used inside an exception-mapper.

Filters

Before-filters are examined before each request and can read and alter the request and response.

Use halt() method to halt the program's execution:

before((request, response) -> {
    boolean authenticated;
    // ... check if authenticated
    if (!authenticated) {
        halt(401, "You are not welcome here");
    }
});

Following each request, after-filters are examined, and they can read the request and read/modify the response:

after((request, response) -> {
    response.header("foo", "set by after filter");
});

Following after-filters, after-after-filters are examined. Consider it a "finally" block.

afterAfter((request, response) -> {
    response.header("foo", "set by afterAfter filter");
});

Filters can optionally take a pattern, it means they'll only be evaluated if the request path matches it:

before("/protected/*", (request, response) -> {
    // ... check if authenticated
    halt(401, "Go Away!");
});

Redirects

With the redirect method on the response, we can force a browser redirect:

A browser redirect can also be triggered by a specific HTTP 3XX status code:

API for redirection

There is also a redirection convenience API that can be used without the response:

// redirect a GET to "/fromPath" to "/toPath"
redirect.get("/fromPath", "/toPath");
// redirect a POST to "/fromPath" to "/toPath", with status 303
redirect.post("/fromPath", "/toPath", Redirect.Status.SEE_OTHER);
// redirect any request to "/fromPath" to "/toPath" with status 301
redirect.any("/fromPath", "/toPath", Redirect.Status.MOVED_PERMANENTLY);

Next TopicLock in Java

← prev next →