Package org.glassfish.jersey.media.multipart

Annotation Interface FormDataParam

@Target({PARAMETER,METHOD,FIELD}) @Retention(RUNTIME) @ParamQualifier public @interface FormDataParam
Binds the named body part(s) of a "multipart/form-data" request entity body to a resource method parameter.

The FormParam annotation in conjunction with the media type "application/x-www-form-urlencoded" is inefficient for sending and consuming large quantities of binary data or text containing non-ASCII characters.

This annotation in conjunction with the media type "multipart/form-data" should be used for submitting and consuming forms that contain files, non-ASCII data, and binary data.

The type T of the annotated parameter must be one of the following:

  1. FormDataBodyPart. The value of the parameter will be the first named body part, otherwise null if such a named body part is not present.
  2. A List or Collection of FormDataBodyPart. The value of the parameter will one or more named body parts with the same name, otherwise null if such a named body part is not present.
  3. FormDataContentDisposition. The value of the parameter will be the content disposition of the first named body part, otherwise null if such a named body part is not present.
  4. A List or Collection of FormDataContentDisposition. The value of the parameter will one or more content dispositions of the named body parts with the same name, otherwise null if such a named body part is not present.
  5. A type for which a message body reader is available given the media type of the first named body part. The value of the parameter will be the result of reading using the message body reader given the type T, the media type of the named part, and the bytes of the named body part as input.

    If there is no named part present and there is a default value present as declared by DefaultValue then the media type will be set to "text/plain". The value of the parameter will be the result of reading using the message body reader given the type T, the media type "text/plain", and the UTF-8 encoded bytes of the default value as input.

    If there is no message body reader available and the type T conforms to a type specified by FormParam then processing is performed as specified by FormParam, where the values of the form parameter are String instances produced by reading the bytes of the named body parts utilizing a message body reader for the String type and the media type "text/plain".

    If there is no named part present then processing is performed as specified by FormParam.

For example, the use of this annotation allows one to support the following: 

     @POST
     @Consumes(MediaType.MULTIPART_FORM_DATA_TYPE)
     public String postForm(
             @DefaultValue("true") @FormDataParam("enabled") boolean enabled,
             @FormDataParam("data") FileData bean,
             @FormDataParam("file") InputStream file,
             @FormDataParam("file") FormDataContentDisposition fileDisposition) {
         ...
     }
Where the server consumes a "multipart/form-data" request entity body that contains one optional named body part "enabled" and two required named body parts "data" and "file".

The optional part "enabled" is processed as a boolean value, if the part is absent then the value will be true.

The part "data" is processed as a JAXB bean and contains some meta-data about the following part.

The part "file" is a file that is uploaded, this is processed as an InputStream. Additional information about the file from the "Content-Disposition" header can be accessed by the parameter fileDisposition.

Note that, whilst the annotation target permits use on fields and methods, this annotation is only required to be supported on resource method parameters.

Author:
Craig McClanahan, Paul Sandoz, Michal Gajdos
See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    value
    Defines the control name of a "multipart/form-data" body part whose content will be used to initialize the value of the annotated method argument.

  • Element Details

    • value

      String value
      Defines the control name of a "multipart/form-data" body part whose content will be used to initialize the value of the annotated method argument.
      Returns:
      the control name of a "multipart/form-data" body part.