FormData

java.lang.Object
- bayou.form.FormData

```
public class FormData
extends Object
```
Html form data set.
A form data set contains a list of entries. Each entry has a key and a value.

The entry key is case sensitive; it should not contain '\r' or '\n'. Multiple entries can have the same name.

There are two types of entries: parameter entry where the value is a String, file entry where the value is a file represented by FormDataFile.

This class also contains form attributes method, action, charset, enctype.

FormData can usually be used in two ways:

Parse form data from an http request: call parse(uri) or parse(request) to get a FormData, then read and process parameters and files.
```
     FormData.parse(request)
         .then( (FormData fd)->
         {
             print(fd.param("n1");
             ...
         })
 
```
Create an http request from a FormData: create a FormData, populate parameters and files, then convert it toUri() or toRequest().
```
     new FormData("POST", "http://localhost:8080/submit")
         .param("n1", "v1")
         .file("f1", "/tmp/100.txt")
         .toRequest();
 
```

Field Summary

Fields
Modifier and Type Field and Description

static String ENC_MULTIPART
The "multipart/form-data" enctype.

static String ENC_URLENCODED
The "application/x-www-form-urlencoded" enctype.

Fields
Modifier and Type	Field and Description
`static String`	`ENC_MULTIPART` The `"multipart/form-data"` enctype.
`static String`	`ENC_URLENCODED` The `"application/x-www-form-urlencoded"` enctype.

Constructor Summary

Constructors
Constructor and Description

FormData(String method, String action)
Create a FormData.

Constructors
Constructor and Description
`FormData(String method, String action)` Create a FormData.

Method Summary

Instance Methods
`String`	`method()` The form's method, either "GET" or "POST".
`String`	`action()` The form's action.
`Charset`	`charset()` The form's charset, used for converting between chars and bytes.
`String`	`enctype()` The form's enctype, either `"multipart/form-data"` or `"application/x-www-form-urlencoded"`.
`Map<String,List<String>>`	`params()` Get all parameter entries.
`List<String>`	`params(String key)` Get values of the parameter.
`String`	`param(String name)` Get the value of the parameter; null if none.
`Map<String,List<FormDataFile>>`	`files()` Get all file entries.
`List<FormDataFile>`	`files(String key)` Get files under the key.
`FormDataFile`	`file(String key)` Get the file under the key; null if none.
`int`	`fileCount()` Return the total number of files.
`void`	`deleteFiles()` Delete all files in this FormData from local file system.
`FormData`	`charset(Charset charset)` Set the charset for this form.
`FormData`	`enctype(String enctype)` Set the enctype for this form.
`FormData`	`param(String key, Object value)` Add a parameter entry.
`FormData`	`params(String key, Object... values)` Add multiple parameter entries.
`FormData`	`file(String key, String filePath)` Add a file entry.
`FormData`	`file(String key, FormDataFile ff)` Add a file entry.
`String`	`toUri()` Create a URI containing the form data.
`HttpRequestImpl`	`toRequest()` Create an http request that submits the form data.
Static Methods
`FormData`	`parse(CharSequence uri)` Parse the URI for form data.
`Async<FormData>`	`parse(HttpRequest request)` Parse the request for POST form data.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - ENC_MULTIPART
```
public static final String ENC_MULTIPART
```
    The "multipart/form-data" enctype. This is the recommended enctype.
    
    See Also:
    
    Constant Field Values
  - ENC_URLENCODED
```
public static final String ENC_URLENCODED
```
    The "application/x-www-form-urlencoded" enctype.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - FormData
```
public FormData(String method,
                String action)
```
    Create a FormData.
    The method must be "GET" or "POST". The action must be an absolute URI or path-query. For example
```
     new FormData("GET", "https://example.com/search")

     new FormData("POST", "/submit")
 
```
    This constructor sets charset=UTF-8, enctype="multipart/form-data". They can be changed by charset(Charset) and enctype(String).
- Method Detail
  - method
```
public String method()
```
    The form's method, either "GET" or "POST".
  - action
```
public String action()
```
    The form's action.
    The action is an absolute URI or path-query, for example
```
     "https://example.com/search"

     "/submit"
 
```
  - charset
```
public Charset charset()
```
    The form's charset, used for converting between chars and bytes.
  - enctype
```
public String enctype()
```
    The form's enctype, either "multipart/form-data" or "application/x-www-form-urlencoded".
    
    See Also:
    
    ENC_MULTIPART, ENC_URLENCODED
  - params
```
public Map<String,List<String>> params()
```
    Get all parameter entries.
    The caller can freely modify the Map and the Lists within.
  - params
```
public List<String> params(String key)
```
    Get values of the parameter.
    Return an empty list if there are no parameter entries with the key.
    
    The returned List should be treated as read-only.
  - param
```
public String param(String name)
```
    Get the value of the parameter; null if none.
    The caller expects only one value for this parameter. If there are multiple values, the last one is returned.
  - files
```
public Map<String,List<FormDataFile>> files()
```
    Get all file entries.
    The caller can freely modify the Map and the Lists within.
  - files
```
public List<FormDataFile> files(String key)
```
    Get files under the key.
    Return an empty list if there are no file entries with the key.
    
    The returned List should be treated as read-only.
  - file
```
public FormDataFile file(String key)
```
    Get the file under the key; null if none.
    The caller expects only one file under the key. If there are multiple files, the last one is returned.
  - fileCount
```
public int fileCount()
```
    Return the total number of files.
  - deleteFiles
```
public void deleteFiles()
```
    Delete all files in this FormData from local file system.
    This method is non-blocking; errors will be silently logged.
    
    See Also:
    
    FormDataFile.delete()
  - charset
```
public FormData charset(Charset charset)
```
    Set the charset for this form.
    
    Returns:
    
    this
  - enctype
```
public FormData enctype(String enctype)
```
    Set the enctype for this form.
    The enctype must be either "multipart/form-data" or "application/x-www-form-urlencoded". We recommend "multipart/form-data" for all forms.
    
    Returns:
    
    this
    
    See Also:
    
    ENC_MULTIPART, ENC_URLENCODED
  - param
```
public FormData param(String key,
                      Object value)
```
    Add a parameter entry.
    If value is null, this method has no effect.
    
    Previous values under the same key will not be removed.
    
    Returns:
    
    this
  - params
```
public FormData params(String key,
                       Object... values)
```
    Add multiple parameter entries.
    Any null in values will be ignored.
    
    Previous values under the same key will not be removed.
    
    Returns:
    
    this
  - file
```
public FormData file(String key,
                     String filePath)
```
    Add a file entry.
    This method is equivalent to file(key, FormDataFile.of(filePath)). See file(String, FormDataFile).
    
    CAUTION: this method reads file metadata from OS, which may involve blocking IO operations. See FormDataFile.of(String).
    
    Returns:
    
    this
  - file
```
public FormData file(String key,
                     FormDataFile ff)
```
    Add a file entry.
    Previous files under the same entry key will not be removed.
    
    Returns:
    
    this
  - toUri
```
public String toUri()
```
    Create a URI containing the form data.
    The form data is encoded in the query component of the URI as "application/x-www-form-urlencoded".
    
    For example:
```
     new FormData("GET", "http://example.com/query?a=b").param("n","v").toUri();
     // return "http://example.com/query?n=v"
     // note that the existing query in `action` is dropped.

     new FormData("POST", "/submit").param("n","v").toUri();
     // return "/submit?n=v"
 
```
    The form's method and enctype are irrelevant here.
  - toRequest
```
public HttpRequestImpl toRequest()
```
    Create an http request that submits the form data.
    The request method is the same as the form's method.
    
    If the method is GET, the form data is encoded in request URI, see toUri().
    
    If the method is POST, the form data is encoded in request entity, according to the enctype.
    
    Example usage:
```
     new FormData("GET", "/show")
         .params("a", 1, 2)
         .toRequest()
         .host("localhost:8080");

     new FormData("POST", "http://example.com/submit")
         .params("a", 1, 2)
         .toRequest()
         .header("Origin", "http://example.com");
 
```
    The caller can make further modifications to the returned HttpRequestImpl object.
    
    If the form's action() is not an absolute URI, the caller should set the request host afterwards.
    
    To avoid a POST request being treated as CSRF by FormParser, the simplest way is to set the "Origin" header.
  - parse
```
public static FormData parse(CharSequence uri)
                      throws ParseException,
                             OverLimitException
```
    Parse the URI for form data.
    This method is equivalent to FormParser.parse(CharSequence) with default parser settings.
    
    Throws:
    
    ParseException
    
    OverLimitException
  - parse
```
public static Async<FormData> parse(HttpRequest request)
```
    Parse the request for POST form data.
    This method is equivalent to FormParser.parse(HttpRequest) with default parser settings.

Class FormData

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ENC_MULTIPART

ENC_URLENCODED

Constructor Detail

FormData

Method Detail

method

action

charset

enctype

params

params

param

files

files

file

fileCount

deleteFiles

charset

enctype

param

params

file

file

toUri

toRequest

parse

parse