Class AttachmentBuilder


  • public class AttachmentBuilder
    extends java.lang.Object
    The AttachmentBuilder class is used to create instances of IAttachment for sending multipart/form-data payloads in a client request or server response. Instances of the AttachmentBuilder are not intended to be re-used. Before calling the build() method, you must set the inputStream property using either the inputStream(InputStream) method or the inputStream(String, InputStream) method.

    When building a IAttachment instance, the contentType property is optional. If left unset, the default value will be "text/plain" unless the fileName property has been set. If the fileName property is set, then the default value for contentType will be "application/octet-stream". This behavior is described in RFC 7578.

    Example usage of sending a multipart request using this API might look something like:

     List<IAttachment> parts = new ArrayList<>();
     parts.add(AttachmentBuilder.newBuilder("sinpleString")
                                .inputStream(new ByteArrayInputStream("Hello World!".getBytes()))
                                .build()); // content type for this part will be "text/plain"
     parts.add(AttachmentBuilder.newBuilder("txtFileWithHeader")
                                .inputStream(new FileInputStream("/path/to/myTextFile.txt")
                                .fileName("renamedTextFile.txt")
                                .header("X-MyCustomHeader", someHeaderValue)
                                .build()); // content type for this part will be "application/octet-stream"
     parts.add(AttachmentBuilder.newBuilder("xmlFile")
                                .inputStream("myXmlFile.xml", new FileInputStream("/path/to/myXmlFile.xml"))
                                .contentType(MediaType.APPLICATION_XML)
                                .build());
     Client c = ClientBuilder.newClient();
     WebTarget target = c.target("http://somehost:9080/data/multipart/list");
     Response r = target.request()
                        .header("Content-Type", "multipart/form-data")
                        .post(Entity.entity(attachments, MediaType.MULTIPART_FORM_DATA_TYPE));
     

    Note that the InputStreams passed to the builder will be closed by the JAX-RS runtime. Closing the streams prior to sending may result in unexpected behavior.

    • Method Detail

      • newBuilder

        @Deprecated
        public static AttachmentBuilder newBuilder​(java.lang.String fieldName)
        Deprecated.
        Create a new AttachmentBuilder instance for creating a new attachment for a multipart payload. The name will be added as a parameter to the part's Content-Disposition header. See RFC 7578, section 4.2 for more details.
        Parameters:
        fieldName - the name of the attachment part
        Returns:
        this builder
        Throws:
        java.lang.IllegalArgumentException - if the fieldName is null
      • contentId

        public AttachmentBuilder contentId​(java.lang.String contentId)
        Sets the Content-ID header in this attachment part.
        Parameters:
        contentId - the ID for this particular attachment
        Returns:
        this builder
      • contentType

        public AttachmentBuilder contentType​(javax.ws.rs.core.MediaType contentType)
        Sets the Content-Type header for this attachment part. This method is analagous to calling contentType(contentType.toString())
        Parameters:
        contentType - the MediaType for this attachment part.
        Returns:
        this builder
      • contentType

        public AttachmentBuilder contentType​(java.lang.String contentType)
        Sets the Content-Type header for this attachment part.
        Parameters:
        contentType - the content type string for this attachment part.
        Returns:
        this builder
      • header

        public AttachmentBuilder header​(java.lang.String headerName,
                                        java.lang.String... headerValues)
        Sets a header for this attachment part.
        Parameters:
        headerName - the name of the header
        headerValues - the (possibly multi-valued) value of the header
        Returns:
        this builder
      • headers

        public AttachmentBuilder headers​(javax.ws.rs.core.MultivaluedMap<java.lang.String,​java.lang.String> newHeaders)
        Sets headers for this attachment part.
        Parameters:
        newHeaders - the map of header values to set for this attachment
        Returns:
        this builder
      • fileName

        public AttachmentBuilder fileName​(java.lang.String fileName)
        Sets the file name of this attachment part. If no contentType is specified, the default content type will change to "application/octet-stream" after calling this method. The fileName parameter value will be added to the Content-Disposition header. See RFC 7578, section 4.2 for more details.
        Parameters:
        fileName - the file name of this attachment part
        Returns:
        this builder
        Throws:
        java.lang.IllegalArgumentException - if fileName is null
      • inputStream

        public AttachmentBuilder inputStream​(java.io.InputStream inputStream)
        Sets the content of this attachment part as an InputStream.
        Parameters:
        inputStream - content body of this attachment part
        Returns:
        this builder
        Throws:
        java.lang.IllegalArgumentException - if inputStream is null
      • inputStream

        public AttachmentBuilder inputStream​(java.lang.String fileName,
                                             java.io.InputStream inputStream)
        Sets the content of this attachment part as an InputStream. Analogous to calling builder.fileName(fileName).inputStream(inputStream)
        Parameters:
        fileName - the file name of this attachment part
        inputStream - content body of this attachment part
        Returns:
        this builder
        Throws:
        java.lang.IllegalArgumentException - if fileName or inputStream is null
      • build

        public IAttachment build()
        Build an instance of an IAttachment using the properties specified on this builder.
        Returns:
        an instance of IAttachment
        Throws:
        java.lang.IllegalStateException - if the inputStream property has not been set