Package org.apache.hc.client5.http.entity.mime

Class MultipartEntityBuilder

  • public class MultipartEntityBuilder
extends java.lang.Object
    Builder for multipart HttpEntitys.

    This class constructs multipart entities with a boundary determined by either a random UUID or an explicit boundary set via setBoundary(String).

    IMPORTANT: it is responsibility of the caller to validate / sanitize content of body parts. For instance, when using an explicit boundary, it's the caller's responsibility to ensure the body parts do not contain the boundary value, which can prevent the consumer of the entity from correctly parsing / processing the body parts.

    Since:
    5.0

    • Field Detail

      • contentType

        private org.apache.hc.core5.http.ContentType contentType

      • boundary

        private java.lang.String boundary

      • charset

        private java.nio.charset.Charset charset

      • multipartParts

        private java.util.List<MultipartPart> multipartParts

      • LOG

        private static final org.slf4j.Logger LOG
        The logger for this class.

      • preamble

        private java.lang.String preamble
        The preamble of the multipart message. This field stores the optional preamble that should be added at the beginning of the multipart message. It can be null if no preamble is needed.

      • epilogue

        private java.lang.String epilogue
        The epilogue of the multipart message. This field stores the optional epilogue that should be added at the end of the multipart message. It can be null if no epilogue is needed.

      • EMPTY_NAME_VALUE_ARRAY

        private static final org.apache.hc.core5.http.NameValuePair[] EMPTY_NAME_VALUE_ARRAY
        An empty immutable NameValuePair array.

    • Constructor Detail

      • MultipartEntityBuilder

        MultipartEntityBuilder()

    • Method Detail

      • setBoundary

        public MultipartEntityBuilder setBoundary​(java.lang.String boundary)
        Sets a custom boundary string for the multipart entity.

        If null is provided, the builder reverts to its default logic of using a random UUID.

        IMPORTANT: when setting an explicit boundary, it is responsibility of the caller to validate / sanitize content of body parts to ensure they do not contain the boundary value.

        Parameters:
        boundary - the boundary string, or null to use a random UUID.
        Returns:
        this builder instance

      • setContentType

        public MultipartEntityBuilder setContentType​(org.apache.hc.core5.http.ContentType contentType)
        Returns:
        this instance.
        Since:
        4.5

      • addParameter

        public MultipartEntityBuilder addParameter​(org.apache.hc.core5.http.message.BasicNameValuePair parameter)
        Add parameter to the current ContentType.
        Parameters:
        parameter - The name-value pair parameter to add to the ContentType.
        Returns:
        this instance.
        Since:
        5.2

      • addTextBody

        public MultipartEntityBuilder addTextBody​(java.lang.String name,
                                          java.lang.String text,
                                          org.apache.hc.core5.http.ContentType contentType)

      • addBinaryBody

        public MultipartEntityBuilder addBinaryBody​(java.lang.String name,
                                            byte[] b,
                                            org.apache.hc.core5.http.ContentType contentType,
                                            java.lang.String filename)

      • addBinaryBody

        public MultipartEntityBuilder addBinaryBody​(java.lang.String name,
                                            java.io.File file,
                                            org.apache.hc.core5.http.ContentType contentType,
                                            java.lang.String filename)

      • addBinaryBody

        public MultipartEntityBuilder addBinaryBody​(java.lang.String name,
                                            java.nio.file.Path path)
        Adds body with contents from the given source Path.
        Parameters:
        name - The part name.
        path - The source path.
        Returns:
        this instance.
        Since:
        5.6

      • addBinaryBody

        public MultipartEntityBuilder addBinaryBody​(java.lang.String name,
                                            java.nio.file.Path path,
                                            org.apache.hc.core5.http.ContentType contentType,
                                            java.lang.String fileName)
        Adds body with contents from the given source Path.
        Parameters:
        name - The part name.
        path - The source path.
        contentType - The content type.
        fileName - The file name to override the Path's file name.
        Returns:
        this instance.
        Since:
        5.6

      • addBinaryBody

        public MultipartEntityBuilder addBinaryBody​(java.lang.String name,
                                            java.io.InputStream stream,
                                            org.apache.hc.core5.http.ContentType contentType,
                                            java.lang.String filename)

      • addBinaryBody

        public MultipartEntityBuilder addBinaryBody​(java.lang.String name,
                                            java.io.InputStream stream)

      • getRandomBoundary

        private java.lang.String getRandomBoundary()
        Generates a random boundary using UUID. The UUID is a v4 random UUID generated from a cryptographically-secure random source.

        A cryptographically-secure random number source is used to generate the UUID, to avoid a malicious actor crafting a body part that contains the boundary value to tamper with the entity structure.

      • addPreamble

        public MultipartEntityBuilder addPreamble​(java.lang.String preamble)
        Adds a preamble to the multipart entity being constructed. The preamble is the text that appears before the first boundary delimiter. The preamble is optional and may be null.
        Parameters:
        preamble - The preamble text to add to the multipart entity
        Returns:
        this instance.
        Since:
        5.3

      • addEpilogue

        public MultipartEntityBuilder addEpilogue​(java.lang.String epilogue)
        Adds an epilogue to the multipart entity being constructed. The epilogue is the text that appears after the last boundary delimiter. The epilogue is optional and may be null.
        Parameters:
        epilogue - The epilogue text to add to the multipart entity
        Returns:
        this instance.
        Since:
        5.3

      • build

        public org.apache.hc.core5.http.HttpEntity build()