Package com.ibm.websphere.jaxrs20.multipart

Class AttachmentBuilder

java.lang.Object
com.ibm.websphere.jaxrs20.multipart.AttachmentBuilder
public class AttachmentBuilder extends 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 Details

    • newBuilder

      public static AttachmentBuilder newBuilder(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:
      IllegalArgumentException - if the fieldName is null

    • contentId

      public AttachmentBuilder contentId(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(jakarta.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(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(String headerName, 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(jakarta.ws.rs.core.MultivaluedMap<String,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(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:
      IllegalArgumentException - if fileName is null

    • inputStream

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

    • inputStream

      public AttachmentBuilder inputStream(String fileName, 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:
      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:
      IllegalStateException - if the inputStream property has not been set