Package org.apache.juneau.http.annotation

Annotation Type FormData

@Documented @Target({PARAMETER,METHOD,TYPE,FIELD}) @Retention(RUNTIME) @Inherited @Repeatable(Array.class) @ContextApply(Applier.class) public @interface FormData
REST request form-data annotation.

Identifies a POJO to be used as a form-data entry on an HTTP request.

Can be used in the following locations:

  • Arguments and argument-types of server-side @RestOp-annotated methods.
  • Arguments and argument-types of client-side @RemoteResource-annotated interfaces.
  • Methods and return types of server-side and client-side @Request-annotated interfaces.
Arguments and argument-types of server-side @RestOp-annotated methods

Annotation that can be applied to a parameter of a @RestOp-annotated method to identify it as a form-data parameter.

Example:

@RestPost public void doPost( @FormData("p1") int p1, @FormData("p2") String p2, @FormData("p3") UUID p3 ) {...}

This is functionally equivalent to the following code...

@RestPost public void doPost(RestRequest req) { int p1 = req.getFormParam("p1").as(int.class).orElse(0); String p2 = req.getFormParam("p2").asString().orElse(null); UUID p3 = req.getFormParam("p3").as(UUID.class).orElse(null); ... }

See Also:
Important note concerning FORM posts

This annotation should not be combined with the @Content annotation or RestRequest.getContent() method for application/x-www-form-urlencoded POST posts, since it will trigger the underlying servlet API to parse the body content as key-value pairs resulting in empty content.

The @Query annotation can be used to retrieve a URL parameter in the URL string without triggering the servlet to drain the body content.

Arguments and argument-types of client-side @RemoteResource-annotated interfaces

Annotation applied to Java method arguments of interface proxies to denote that they are FORM post parameters on the request.

See Also:
Methods and return types of server-side and client-side @Request-annotated interfaces

See Also:
This annotation should not be combined with the @Content annotation or RestRequest#getContent() method for application/x-www-form-urlencoded POST posts, since it will trigger the underlying servlet API to parse the body content as key-value pairs resulting in empty content.
The @Query annotation can be used to retrieve a URL parameter in the URL string without triggering the servlet to drain the body content.
If using this annotation on a Spring bean, note that you are likely to encounter issues when using on parameterized types such as List<MyBean>. This is due to the fact that Spring uses CGLIB to recompile classes at runtime, and CGLIB was written before generics were introduced into Java and is a virtually-unsupported library. Therefore, parameterized types will often be stripped from class definitions and replaced with unparameterized types (e.g. List). Under these circumstances, you are likely to get ClassCastExceptions when trying to access generalized JsonMaps as beans. The best solution to this issue is to either specify the parameter as a bean array (e.g. MyBean[]) or declare the method as final so that CGLIB will not try to recompile it.
See Also:

  • Element Details

    • def

      String def
      Default value for this parameter.
      Returns:
      The annotation value.
      Default:
      ""

    • name

      String name
      FORM parameter name.

      The name of the parameter (required).

      The value should be either a valid form parameter name, or "*" to represent multiple name/value pairs

      A blank value (the default) has the following behavior:

      • If the data type is NameValuePairs, Map, or a bean, then it's the equivalent to "*" which will cause the value to be serialized as name/value pairs.
        Examples:

        // When used on a REST method @RestPost("/addPet") public void addPet(@FormData JsonMap allFormDataParameters) {...}

        // When used on a remote method parameter @RemoteResource(path="/myproxy") public interface MyProxy { // Equivalent to @FormData("*") @RemotePost("/mymethod") String myProxyMethod1(@FormData Map<String,Object> allFormDataParameters); }

        // When used on a request bean method public interface MyRequest { // Equivalent to @FormData("*") @FormData Map<String,Object> getFoo(); }

      • If used on a request bean method, uses the bean property name.
        Example:

        public interface MyRequest { // Equivalent to @FormData("foo") @FormData String getFoo(); }

      Notes:
      • The format is plain-text.
      Returns:
      The annotation value.
      Default:
      ""

    • on

      String[] on
      Dynamically apply this annotation to the specified classes.
      See Also:
      Returns:
      The annotation value.
      Default:
      {}

    • onClass

      Class<?>[] onClass
      Dynamically apply this annotation to the specified classes.

      Identical to on() except allows you to specify class objects instead of a strings.

      See Also:
      Returns:
      The annotation value.
      Default:
      {}

    • parser

      Class<? extends HttpPartParser> parser
      Specifies the HttpPartParser class used for parsing strings to values.

      Overrides for this part the part parser defined on the REST resource which by default is OpenApiParser.

      Returns:
      The annotation value.
      Default:
      org.apache.juneau.httppart.HttpPartParser.Void.class

    • schema

      Schema schema
      schema field of the Swagger Parameter Object.

      The schema defining the type used for parameter.

      The @Schema annotation can also be used standalone on the parameter or type. Values specified on this field override values specified on the type, and values specified on child types override values specified on parent types.

      Used for:
      • Server-side schema-based parsing and parsing validation.
      • Server-side generated Swagger documentation.
      • Client-side schema-based serializing and serializing validation.
      Returns:
      The annotation value.
      Default:
      @org.apache.juneau.annotation.Schema

    • serializer

      Class<? extends HttpPartSerializer> serializer
      Specifies the HttpPartSerializer class used for serializing values to strings.

      Overrides for this part the part serializer defined on the REST client which by default is OpenApiSerializer.

      Returns:
      The annotation value.
      Default:
      org.apache.juneau.httppart.HttpPartSerializer.Void.class

    • value

      String value
      A synonym for name().

      Allows you to use shortened notation if you're only specifying the name.

      The following are completely equivalent ways of defining a form post entry:

      public Order placeOrder(@FormData(name="petId") long petId) {...}

      public Order placeOrder(@FormData("petId") long petId) {...}

      Returns:
      The annotation value.
      Default:
      ""