[[_form]]
== @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. 



[source,java]
----

public class MyForm {

    @FormParam("stuff")
    private int stuff;

    @HeaderParam("myHeader")
    private String header;

    @PathParam("foo")
    public void setFoo(String foo) {}
}


@POST
@Path("/myservice")
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:

[source,java]
----

public static class Person {
    @FormParam("name")
    private String name;

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

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

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

@Path("person")
public static class MyResource {
    @POST
    @Produces(MediaType.TEXT_PLAIN)
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    public String post(@Form Person p) {
        return p.toString();
    }
}
----

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

[source]
----
name=bill
invoice.street=xxx
shipping.street=yyy
----

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

[source,java]
----

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;
}

@Path("person")
public static class MyResource {

    @POST
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    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

[source]
----
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");
----