Form Data and Multipart

/**
 * Builder for HTML form-encoded request bodies.
 */
public final class FormEncodingBuilder {
    public FormEncodingBuilder();
    public FormEncodingBuilder add(String name, String value);
    public FormEncodingBuilder addEncoded(String name, String value);
    public RequestBody build();
}

// Simple form data
RequestBody formBody = new FormEncodingBuilder()
    .add("username", "john")
    .add("password", "secret")
    .add("remember", "true")
    .build();

Request request = new Request.Builder()
    .url("https://example.com/login")
    .post(formBody)
    .build();

// Using encoded values (pre-encoded data)
RequestBody encodedFormBody = new FormEncodingBuilder()
    .addEncoded("query", "search%20term")  // Already URL-encoded
    .add("filter", "active")               // Will be encoded automatically
    .build();

/**
 * Add a form field with the specified name and value. Both name and value
 * will be URL-encoded.
 * @param name the form field name
 * @param value the form field value
 * @return this builder for method chaining
 */
public FormEncodingBuilder add(String name, String value);

/**
 * Add a form field with the specified name and value. Assumes both name
 * and value are already URL-encoded.
 * @param name the form field name (already encoded)
 * @param value the form field value (already encoded)
 * @return this builder for method chaining
 */
public FormEncodingBuilder addEncoded(String name, String value);

/**
 * Build the RequestBody with all added form fields.
 * @return RequestBody with Content-Type application/x-www-form-urlencoded
 */
public RequestBody build();

// Complex form with special characters
RequestBody complexForm = new FormEncodingBuilder()
    .add("user_name", "john@example.com")      // Email will be encoded
    .add("bio", "Software developer & mentor") // Special chars encoded
    .add("preferences", "setting1,setting2")   // Comma will be encoded
    .build();

// Mixed encoded/unencoded (when you control encoding)
String preEncodedValue = URLEncoder.encode("value with spaces", "UTF-8");
RequestBody mixedForm = new FormEncodingBuilder()
    .add("normal_field", "normal value")       // Auto-encoded
    .addEncoded("custom_field", preEncodedValue) // Pre-encoded
    .build();

/**
 * Builder for multipart request bodies.
 */
public final class MultipartBuilder {
    public static final MediaType MIXED;
    public static final MediaType ALTERNATIVE;
    public static final MediaType DIGEST;
    public static final MediaType PARALLEL;
    public static final MediaType FORM;
    
    public MultipartBuilder();
    public MultipartBuilder(String boundary);
    public MultipartBuilder type(MediaType type);
    public MultipartBuilder addPart(RequestBody body);
    public MultipartBuilder addPart(Headers headers, RequestBody body);
    public MultipartBuilder addFormDataPart(String name, String value);
    public MultipartBuilder addFormDataPart(String name, String filename, RequestBody value);
    public RequestBody build();
}

// Form with file upload
File file = new File("document.pdf");
RequestBody fileBody = RequestBody.create(MediaType.parse("application/pdf"), file);

RequestBody multipartBody = new MultipartBuilder()
    .type(MultipartBuilder.FORM)
    .addFormDataPart("title", "My Document")
    .addFormDataPart("description", "Important document")
    .addFormDataPart("file", "document.pdf", fileBody)
    .build();

Request request = new Request.Builder()
    .url("https://api.example.com/upload")
    .post(multipartBody)
    .build();

/**
 * Set the multipart type. Default is MIXED if not specified.
 * @param type the MediaType for multipart content
 * @return this builder for method chaining
 */
public MultipartBuilder type(MediaType type);

// Predefined multipart types
public static final MediaType MIXED;        // multipart/mixed
public static final MediaType ALTERNATIVE;  // multipart/alternative  
public static final MediaType DIGEST;       // multipart/digest
public static final MediaType PARALLEL;     // multipart/parallel
public static final MediaType FORM;         // multipart/form-data

// File upload form (most common)
RequestBody formMultipart = new MultipartBuilder()
    .type(MultipartBuilder.FORM)
    .addFormDataPart("user_id", "123")
    .addFormDataPart("avatar", "profile.jpg", avatarBody)
    .build();

// Mixed content multipart  
RequestBody mixedMultipart = new MultipartBuilder()
    .type(MultipartBuilder.MIXED)
    .addPart(textBody)
    .addPart(imageBody)
    .build();

// Custom boundary
RequestBody customBoundary = new MultipartBuilder("CustomBoundary123")
    .type(MultipartBuilder.FORM)
    .addFormDataPart("data", "value")
    .build();

/**
 * Add a part with just a body. Content-Disposition header will be omitted.
 * @param body the part body
 * @return this builder for method chaining
 */
public MultipartBuilder addPart(RequestBody body);

/**
 * Add a part with custom headers and body.
 * @param headers custom headers for this part
 * @param body the part body
 * @return this builder for method chaining
 */
public MultipartBuilder addPart(Headers headers, RequestBody body);

/**
 * Add a form data part with name and string value.
 * @param name the form field name
 * @param value the form field value
 * @return this builder for method chaining
 */
public MultipartBuilder addFormDataPart(String name, String value);

/**
 * Add a form data part with name, filename, and body (typically for file uploads).
 * @param name the form field name
 * @param filename the filename to include in Content-Disposition
 * @param value the RequestBody containing file data
 * @return this builder for method chaining
 */
public MultipartBuilder addFormDataPart(String name, String filename, RequestBody value);

// Complex multipart with different content types
RequestBody jsonPart = RequestBody.create(
    MediaType.parse("application/json"), 
    "{\"metadata\":\"info\"}"
);

Headers customHeaders = new Headers.Builder()
    .add("Content-Disposition", "form-data; name=\"metadata\"")
    .add("Content-Type", "application/json")
    .build();

RequestBody complexMultipart = new MultipartBuilder()
    .type(MultipartBuilder.FORM)
    // Simple form field
    .addFormDataPart("user_id", "456")
    // JSON part with custom headers
    .addPart(customHeaders, jsonPart)
    // File upload
    .addFormDataPart("document", "report.pdf", 
        RequestBody.create(MediaType.parse("application/pdf"), pdfFile))
    // Image upload with different name/filename
    .addFormDataPart("photo", "vacation.jpg",
        RequestBody.create(MediaType.parse("image/jpeg"), imageFile))
    .build();

// Multiple file uploads
RequestBody multiFileUpload = new MultipartBuilder()
    .type(MultipartBuilder.FORM)
    .addFormDataPart("description", "Photo gallery upload")
    .addFormDataPart("photo1", "beach.jpg", 
        RequestBody.create(MediaType.parse("image/jpeg"), photo1))
    .addFormDataPart("photo2", "sunset.jpg",
        RequestBody.create(MediaType.parse("image/jpeg"), photo2))
    .addFormDataPart("photo3", "mountains.jpg",
        RequestBody.create(MediaType.parse("image/jpeg"), photo3))
    .build();

/**
 * Build the multipart RequestBody with all added parts.
 * @return RequestBody with appropriate multipart Content-Type
 */
public RequestBody build();

// Build and use in request
MultipartBuilder builder = new MultipartBuilder()
    .type(MultipartBuilder.FORM)
    .addFormDataPart("field1", "value1")
    .addFormDataPart("field2", "value2");

// Can add more parts dynamically
if (includeFile) {
    builder.addFormDataPart("file", "data.txt", fileBody);
}

RequestBody multipartBody = builder.build();
Request request = new Request.Builder()
    .url("https://api.example.com/upload")
    .post(multipartBody)
    .build();