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 Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      IAttachment build()
      Build an instance of an IAttachment using the properties specified on this builder.
      AttachmentBuilder contentId​(java.lang.String contentId)
      Sets the Content-ID header in this attachment part.
      AttachmentBuilder contentType​(java.lang.String contentType)
      Sets the Content-Type header for this attachment part.
      AttachmentBuilder contentType​(javax.ws.rs.core.MediaType contentType)
      Sets the Content-Type header for this attachment part.
      AttachmentBuilder fileName​(java.lang.String fileName)
      Sets the file name of this attachment part.
      AttachmentBuilder header​(java.lang.String headerName, java.lang.String... headerValues)
      Sets a header for this attachment part.
      AttachmentBuilder headers​(javax.ws.rs.core.MultivaluedMap<java.lang.String,​java.lang.String> newHeaders)
      Sets headers for this attachment part.
      AttachmentBuilder inputStream​(java.io.InputStream inputStream)
      Sets the content of this attachment part as an InputStream.
      AttachmentBuilder inputStream​(java.lang.String fileName, java.io.InputStream inputStream)
      Sets the content of this attachment part as an InputStream.
      static AttachmentBuilder newBuilder​(java.lang.String fieldName)
      Create a new AttachmentBuilder instance for creating a new attachment for a multipart payload.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • newBuilder

        public static AttachmentBuilder newBuilder​(java.lang.String fieldName)
        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