JBoss.orgCommunity Documentation

Chapter 12. @Form

@Form is a RESTEasy specific annotation that allows the re-use of any @*Param annotation within an injected class. RESTEasy will instantiate the class and inject values into any annotated @*Param or @Context property. This is useful when there are a lot of parameters on a method and it is wanted to condense them into a value object.

public class MyForm {

    private int stuff;

    private String header;

    public void setFoo(String foo) {...}

public void post(@Form MyForm form) {...}

When somebody posts to /myservice, RESTEasy will instantiate an instance of MyForm and inject the form parameter "stuff" into the "stuff" field, the header "myheader" into the header field, and call the setFoo method with the path param variable of "foo".

@Form has some expanded @FormParam features. If a prefix is specified within the Form param, this will prepend a prefix to any form parameter lookup. For example, say you have one Address class, but want to reference invoice and shipping addresses from the same set of form parameters:

public static class Person
    private String name;

    @Form(prefix = "invoice")
    private Address invoice;

    @Form(prefix = "shipping")
    private Address shipping;

public static class Address
    private String street;

public static class MyResource
    public String post(@Form Person p)
        return p.toString();

In this example, the client could send the following form parameters:


The Person.invoice and Person.shipping fields would be populated appropriately. Note, prefix mappings also support lists and maps:

public static class Person {
    @Form(prefix="telephoneNumbers") List<TelephoneNumber> telephoneNumbers;
    @Form(prefix="address") Map<String, Address> addresses;

public static class TelephoneNumber {
    @FormParam("countryCode") private String countryCode;
    @FormParam("number") private String number;

public static class Address {
    @FormParam("street") private String street;
    @FormParam("houseNumber") private String houseNumber;

public static class MyResource {

    public void post (@Form Person p) {} 

The following form params could be submitted and the Person.telephoneNumbers and Person.addresses fields would be populated appropriately

request.addFormHeader("telephoneNumbers[0].countryCode", "31");
request.addFormHeader("telephoneNumbers[0].number", "0612345678");
request.addFormHeader("telephoneNumbers[1].countryCode", "91");
request.addFormHeader("telephoneNumbers[1].number", "9717738723");
request.addFormHeader("address[INVOICE].street", "Main Street");
request.addFormHeader("address[INVOICE].houseNumber", "2");
request.addFormHeader("address[SHIPPING].street", "Square One");
request.addFormHeader("address[SHIPPING].houseNumber", "13");