JBoss.orgCommunity Documentation

第 12 章 @Form

这是一个 RESTEasy 特有的注解,允许您在注入的类中重用任何 @*Param 注释。RESTEasy 将实例化该类并将值注入任何带注解的 @*Param 或 @Context 属性。如果您的方法中有很多参数,并且希望将它们压缩为一个值对象,那么这种方法很有用。

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) {...}

当有人向 /myservice 发起POST请求时,RESTEasy 将实例化 MyForm 的一个实例,并将表单参数"stuff"注入"stuff"字段,将头信息中的"myheader"注入"myheader"字段,并使用路径参数"foo"调用 setFoo 方法。

另外,@Form 有一些扩展的@FormParam 特性。如果在 Form 参数中指定前缀,则将为任何form参数查找预先设置前缀。例如,假设您有一个 Address 类,但是希望从同一组表单参数中引用 invoice 和 shipping addresses:

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

在这个例子中,客户端可以发送以下表单参数:

name=bill
invoice.street=xxx
shipping.street=yyy

将填充 Person.invoice 和 Person.shipping 字段。此外,前缀映射还支持列表和映射:

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) {} 

可以提交下列表单参数,程序将填充 Person.telephoneNumbers 和 Person.addresses 字段

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");