Marshalling I: Forms

You should by now have a basic understanding of setting up a simple HttpMaid instance with request handlers and know how to connect it to an endpoint. This chapter will show you how HttpMaid can help you with handling forms.

Forms

One recurring challenge in web applications is the processing of forms. To start, let’s create a form as a Java resource named form.html somewhere in the classpath:

<!--
  ~ Copyright (c) 2020 Richard Hauswald - https://quantummaid.de/.
  ~
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements.  See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership.  The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License.  You may obtain a copy of the License at
  ~
  ~   http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied.  See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->

<html>
<form action="/submit" method="post">
    Name:<input type="text" name="name"><br>
    Profession:<input type="text" name="profession">
    <input type="submit" value="Send">
</form>
</html>

The form will consist of two textfields (name and profession) and a button to submit the form. The following code creates a HttpMaid instance to serve the form:

final HttpMaid httpMaid = anHttpMaid()
        .get("/form", (request, response) -> response.setJavaResourceAsBody("form.html"))
        .post("/submit", (request, response) -> response.setBody(request.bodyString()))
        .build();

We configured two routes in the endpoint. The first one serves every GET request to the /form route with our html resource. The second one accepts POST requests to the /submit route, since the <form action="/submit" method="post"> line in the html suggests that submitted forms will be sent there. The handler of this route only returns the body of the request, so we can inspect it.

Once started, the form should be available at http://localhost:1337/form. When you now submit the form with Bob as name and Developer as profession, you should see the following message sent back:

name=Bob&profession=Developer

This type of key-value encoding is called form encoded (or application/x-www-form-urlencoded, to be specific).

Now, just returning the form encoded form submission to the sender is not a very reasonable way to handle forms. In order to handle it productively, we need a way to decode the key-value pairs that we received. Luckily, HttpMaid is able to this for us with an operation called unmarshalling.

What is unmarshalling?

The concept of unmarshalling in the context of HttpMaid is the process of translating a String of a given format (in our case: form encoded) into a Map<String, Object> that contains all the values encoded in the String. For us and our form example, this means we will receive a Map with two entries:

"name" = "Bob"

and

"profession" = "Developer"

which is exactly what we need.

The body map

In order to access the unmarshalled form contents, the HttpRequest object offers a method bodyMap(). Let’s use this to change our handler to something slightly more productive:

final HttpMaid httpMaid = anHttpMaid()
        .get("/form", (request, response) -> response.setJavaResourceAsBody("form.html"))
        .post("/submit", (request, response) -> {
            final Map<String, Object> bodyMap = request.bodyMap();
            final String name = (String) bodyMap.get("name");
            final String profession = (String) bodyMap.get("profession");
            response.setBody("Hello " + name + " and good luck as a " + profession + "!");
        })
        .build();

When you now submit the form again with the values Bob and Developer, the resulting web page should look like this:

Hello Bob and good luck as a Developer!

Multipart uploads

Marshalling II: APIs