Package jakarta.ws.rs.core

Interface EntityPart

  • public interface EntityPart
    A EntityPart is one part of a multipart entity. As defined in RFC 7578, a multipart request or response must have a content type of "multipart/form-data" with a boundary parameter indicating where one part ends the next may begin.

    Multipart entities may be received in a resource method as a collection of parts (e.g. List<EntityPart>) or as a form parameter (ex: @FormParam("part1Name") EntityPart part1).

    Likewise, a client may receive a multipart response by reading the returned entity as a collection of EntityParts (ex: response.readEntity(new GenericType<List<EntityPart>>() {})).

    In order to send a multipart entity either as a client request or a response from a resource method, you may create the Lists using EntityPart.Builder. For example: 

     Client c = ClientBuilder.newClient();
WebTarget target = c.target(someURL);
List<EntityPart> parts = Arrays.asList(
     EntityPart.withName("name1").fileName("file1.doc").content(stream1).build(),
     EntityPart.withName("name2").fileName("file2.doc").content(stream2).build(),
     EntityPart.withName("name3").fileName("file3.xml").content(myObject, MyClass.class).mediaType("application/xml").build());
GenericEntity<List<EntityPart>> genericEntity = new GenericEntity<>(parts){};
Entity entity = Entity.entity(genericEntity, MediaType.MULTIPART_FORM_DATA);
Response r = target.request().post(entity);
    Note that when building a EntityPart, the name and content are required. Other properties such as headers, file name, and media type are optional. It is the responsibility of the implementation code to close the content input streams when sending the multipart content. Closing the stream before the implementation has sent it could result in unexpected exceptions. It is the responsibility of the calling code to close the stream when receiving the multipart content.
    Since:
    3.1

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static interface  EntityPart.Builder
      Builder for EntityPart instances.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.io.InputStream getContent()
      Returns the input stream for this part.
      <T> T getContent​(GenericType<T> type)
      Converts the content stream for this part to the specified type and returns it.
      <T> T getContent​(java.lang.Class<T> type)
      Converts the content stream for this part to the specified class and returns it.
      java.util.Optional<java.lang.String> getFileName()
      Returns the filename of this part.
      MultivaluedMap<java.lang.String,​java.lang.String> getHeaders()
      Returns an immutable multivalued map of headers for this specific part.
      MediaType getMediaType()
      Returns the content type of this part, and equivalent to calling MediaType.valueOf(part.getHeaders().getFirst(HttpHeaders.CONTENT_TYPE)).
      java.lang.String getName()
      Returns the name of this part within the multipart entity.
      static EntityPart.Builder withFileName​(java.lang.String partAndFileName)
      Creates a new EntityPart.Builder instance that sets the part name and fileName to the passed in partAndFileName value.
      static EntityPart.Builder withName​(java.lang.String partName)
      Creates a new EntityPart.Builder instance.

    • Method Detail

      • withName

        static EntityPart.Builder withName​(java.lang.String partName)
        Creates a new EntityPart.Builder instance.
        Parameters:
        partName - name of the part to create within the multipart entity
        Returns:
        EntityPart.Builder for building new EntityPart instances

      • withFileName

        static EntityPart.Builder withFileName​(java.lang.String partAndFileName)
        Creates a new EntityPart.Builder instance that sets the part name and fileName to the passed in partAndFileName value.

        Logically, this is the same as EntityPart.withName(x).fileName(x).

        Parameters:
        partAndFileName - name and filename of the part to create within the multipart entity
        Returns:
        EntityPart.Builder for building new EntityPart instances

      • getName

        java.lang.String getName()
        Returns the name of this part within the multipart entity. This will be the "name" attribute of the Content-Disposition header for this part.
        Returns:
        the part name

      • getFileName

        java.util.Optional<java.lang.String> getFileName()
        Returns the filename of this part. This will be the "filename" attribute of the Content-Disposition header for this part. A filename is not required in a part, so if a filename is not present it will return Optional.empty().
        Returns:
        an Optional<String> indicating the filename if present

      • getContent

        java.io.InputStream getContent()
        Returns the input stream for this part. This is the content body of the part and is accessed as a stream to avoid loading potentially large amounts of data into the heap. It is the responsibility of the calling code to close this stream after receiving it.
        Returns:
        an InputStream representing the content of this part

      • getHeaders

        MultivaluedMap<java.lang.String,​java.lang.String> getHeaders()
        Returns an immutable multivalued map of headers for this specific part.
        Returns:
        immutable MultivaluedMap<String, String> of part headers

      • getMediaType

        MediaType getMediaType()
        Returns the content type of this part, and equivalent to calling MediaType.valueOf(part.getHeaders().getFirst(HttpHeaders.CONTENT_TYPE)).
        Returns:
        the media type for this part