@FormDataParam vs. @FormParam in Jersey

 1. Introduction

Jersey is a full-featured open-source framework for developing web services and clients using Java. By using Jersey, we can create robust web applications that support the full set of HTTP features.

In this article, we’ll look at two specific features of Jersey: the @FormDataParam and @FormParam annotations. While these two annotations are similar in nature, they have significant differences, as we’ll see below.

2. Background

There are many ways to exchange data between clients and servers. The two most popular are XML and JSON, but they aren’t the only options.

Form encoded data is another way to format data when sending it between a client and server, particularly when the client is a web page. This is because HTML makes it easy to define forms with a variety of inputs (text, checkboxes, drop downs, etc) and send that data back to a remote server.

This is where the @FormDataParam vs. @FormParam annotations come in. They are both used to handle form data in a Jersey server application but with some important differences.

Now that we know the background of both annotations, let’s take a look at how to use each one and some of their differences.

3. Using @FormParam

In short, we use the @FormParam annotation whenever the API expects URL-encoded data. Let’s look at a simple HTML form with only text fields:

<form method="post" action="/example1">
    <input name="first_name" type="text">
    <input name="last_name" type="text">
    <input name="age" type="text">
    <input type="submit">
</form>

This form has three fields: first name, last name, and age. It also uses the HTTP POST method to send the form data to a URL located at /example1.

To process this form using Jersey, we would define the following endpoint in our server application:

@POST
@Path("/example1")
public String example1(
  @FormParam("first_name") String firstName,
  @FormParam("last_name") String lastName,
  @FormParam("age") String age)
{
    // process form data
}

Notice that we use the annotation for each field in the HTML form. This works the same regardless of how many or what types of fields the form has. By using the @FormParam annotation, Jersey binds the value from each field into the corresponding method parameter.

In practice, form-encoded data correlates to the MIME type application/x-www-form-urlencoded. Under the hood, the data sent between the web browser and our service looks like this:

first_name=john&last_name=smith&age=42

The benefit of this approach is that the data is easy to process because it only involves text and no binary data. Additionally, this approach can work using the HTTP GET verb because the string can be passed as query parameters in the URL. However, we should be careful when passing form data via URL since it may contain sensitive data.

4. Using @FormDataParam

In contrast, the @FormDataParam annotation is more flexible and can handle any combination of text and binary data. In practical terms, this is useful for things like file uploads with HTML forms.

Let’s look at an example form using the @FormDataParam annotation. To start, we must first import the jersey-media-multipart module from Maven Central into our project:

<dependency>
    <groupId>org.glassfish.jersey.media</groupId>
    <artifactId>jersey-media-multipart</artifactId>
    <version>3.1.3</version>
</dependency>

Now, let’s add a file upload field to the HTML form we created above:

<form method="post" action="/example2" enctype="multipart/form-data >
    <input name="first_name" type="text">
    <input name="last_name" type="text">
    <input name="age" type="text">
    <input name="photo" type="file">
    <input type="submit">
</form>

Notice that we’re now specifying the encoding type of multipart/form-data in the form element. This is necessary so the web browser sends the data in a format that our service is expecting.

Next, in our application, we would create the following endpoint to handle the data from this form:

@POST
@Path("/example2")
public String example2(
  @FormDataParam("first_name") String firstName,
  @FormDataParam("last_name") String lastName,
  @FormDataParam("age") String age,
  @FormDataParam("photo") InputStream photo)
{
    // handle form data
}

Notice that each form field now uses the @FormDataParam annotation. We also use an InputStream as the parameter type that handles the binary data.

Unlike the previous example, where each field and its value were combined into a string, this example combines the fields into parts. Each part is separated by a unique token, allowing Jersey to easily identify each parameter and bind each part into the corresponding method parameter.

For example, the raw message sent from this form into our service might look like this:

------WebKitFormBoundarytCyB57mkvJedAHFx
Content-Disposition: form-data; name="first_name"

John
------WebKitFormBoundarytCyB57mkvJedAHFx
Content-Disposition: form-data; name="last_name"

Smith
------WebKitFormBoundarytCyB57mkvJedAHFx
Content-Disposition: form-data; name="age"

42
------WebKitFormBoundarytCyB57mkvJedAHFx
Content-Disposition: form-data; name="photo"; filename="john-smith-profile.jpeg"
Content-Type: image/jpeg


------WebKitFormBoundarytCyB57mkvJedAHFx--

The main benefit of this approach is that we can send text and binary data together. However, there are some downsides when compared to using traditional form-encoded data.

First, we can only use the HTTP POST verb with this type. This is because the binary data cannot be encoded and passed along the URL string. Second, the payload sizes are much larger in size. As we can see in the example above, the additional text required to define separators and headers adds quite a bit of size above normal form-encoded data.

5. Conclusion

In this article, we have looked at two different annotations in the Jersey library: @FormParam and @FormDataParam. Both of these annotations process form data in an application, but as we saw, they have very different purposes.

The @FormParam is better when sending form-encoded data. This can use either GET or POST verbs but can only include text fields. On the other hand, the @FormDataParam annotation processes multi-part data. This can include text and binary data but only works with the POST verb.