Top Description Inners Methods
jakarta.ws.rs.core

public Interface EntityPart

Imports
java.io.IOException, .InputStream, java.util.Optional, jakarta.ws.rs.WebApplicationException, jakarta.ws.rs.ext.RuntimeDelegate
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 and Inner Type Summary

Modifier and TypeClass and Description
public static interface
EntityPart.Builder

Builder for EntityPart instances.

Method Summary

Modifier and TypeMethod and Description
public InputStream

Returns:

an InputStream representing the content of this part
getContent()

Returns the input stream for this part.

public <
the entity type
T> T

Returns:

an instance of the specified Class representing the content of this part
getContent(Class<T>
the Class that the implementation should convert this part to
type)

Converts the content stream for this part to the specified class and returns it.

public <
the entity type
T> T

Returns:

an instance of the specified generic type representing the content of this part
getContent(GenericType<T>
the generic type that the implementation should convert this part to
type)

Converts the content stream for this part to the specified type and returns it.

public Optional<String>

Returns:

an Optional<String> indicating the filename if present
getFileName()

Returns the filename of this part.

public MultivaluedMap<String, String>

Returns:

immutable MultivaluedMap<String, String> of part headers
getHeaders()

Returns an immutable multivalued map of headers for this specific part.

public MediaType

Returns:

the media type for this part
getMediaType()

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

public String

Returns:

the part name
getName()

Returns the name of this part within the multipart entity.

public static EntityPart.Builder

Returns:

Builder for building new EntityPart instances
withFileName(String
name and filename of the part to create within the multipart entity
partAndFileName)

Creates a new EntityPart.Builder instance that sets the part name and fileName to the passed in partAndFileName value.

public static EntityPart.Builder

Returns:

Builder for building new EntityPart instances
withName(String
name of the part to create within the multipart entity
partName)

Creates a new EntityPart.Builder instance.

Method Detail

getContentback to summary
public 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:InputStream

an InputStream representing the content of this part

getContentback to summary
public <T> T getContent(Class<T> type) throws IllegalArgumentException, IllegalStateException, IOException, WebApplicationException

Converts the content stream for this part to the specified class and returns it. The implementation must convert the stream by finding a jakarta.ws.rs.ext.MessageBodyReader that handles the specified type as well as the MediaType of the part. If no jakarta.ws.rs.ext.MessageBodyReader can be found to perform the conversion, this method will throw an IllegalArgumentException. The implementation is required to close the content stream when this method is invoked, so it may only be invoked once. Subsequent invocations will result in an IllegalStateException. Likewise this method will throw an IllegalStateException if it is called after calling getContent or getContent(GenericType).

Parameters
<T>
the entity type
type:Class<T>

the Class that the implementation should convert this part to

Returns:T

an instance of the specified Class representing the content of this part

Exceptions
IllegalArgumentException:
if no jakarta.ws.rs.ext.MessageBodyReader can handle the conversion of this part to the specified type
IllegalStateException:
if this method or any of the other getContent methods has already been invoked
IOException:
if the jakarta.ws.rs.ext.MessageBodyReader#readFrom(Class, java.lang.reflect.Type, java.lang.annotation.Annotation[], MediaType, MultivaluedMap, InputStream) method throws an IOException
WebApplicationException:
if the jakarta.ws.rs.ext.MessageBodyReader#readFrom(Class, java.lang.reflect.Type, java.lang.annotation.Annotation[], MediaType, MultivaluedMap, InputStream) method throws an WebApplicationException
getContentback to summary
public <T> T getContent(GenericType<T> type) throws IllegalArgumentException, IllegalStateException, IOException, WebApplicationException

Converts the content stream for this part to the specified type and returns it. The implementation must convert the stream by finding a jakarta.ws.rs.ext.MessageBodyReader that handles the specified type as well as the MediaType of the part. If no jakarta.ws.rs.ext.MessageBodyReader can be found to perform the conversion, this method will throw an IllegalArgumentException. The implementation is required to close the content stream when this method is invoked, so it may only be invoked once. Subsequent invocations will result in an IllegalStateException. Likewise this method will throw an IllegalStateException if it is called after calling getContent or getContent(Class).

Parameters
<T>
the entity type
type:GenericType<T>

the generic type that the implementation should convert this part to

Returns:T

an instance of the specified generic type representing the content of this part

Exceptions
IllegalArgumentException:
if no jakarta.ws.rs.ext.MessageBodyReader can handle the conversion of this part to the specified type
IllegalStateException:
if this method or any of the other getContent methods has already been invoked
IOException:
if the jakarta.ws.rs.ext.MessageBodyReader#readFrom(Class, java.lang.reflect.Type, java.lang.annotation.Annotation[], MediaType, MultivaluedMap, InputStream) method throws an IOException
WebApplicationException:
if the jakarta.ws.rs.ext.MessageBodyReader#readFrom(Class, java.lang.reflect.Type, java.lang.annotation.Annotation[], MediaType, MultivaluedMap, InputStream) method throws an WebApplicationException
getFileNameback to summary
public Optional<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:Optional<String>

an Optional<String> indicating the filename if present

getHeadersback to summary
public MultivaluedMap<String, String> getHeaders()

Returns an immutable multivalued map of headers for this specific part.

Returns:MultivaluedMap<String, String>

immutable MultivaluedMap<String, String> of part headers

getMediaTypeback to summary
public MediaType getMediaType()

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

Returns:MediaType

the media type for this part

getNameback to summary
public 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:String

the part name

withFileNameback to summary
public static EntityPart.Builder withFileName(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:String

name and filename of the part to create within the multipart entity

Returns:EntityPart.Builder

Builder for building new EntityPart instances

withNameback to summary
public static EntityPart.Builder withName(String partName)

Creates a new EntityPart.Builder instance.

Parameters
partName:String

name of the part to create within the multipart entity

Returns:EntityPart.Builder

Builder for building new EntityPart instances

jakarta.ws.rs.core back to summary

public Interface EntityPart.Builder

Builder for EntityPart instances.
Since
3.1

Method Summary

Modifier and TypeMethod and Description
public EntityPart

Returns:

EntityPart instance built from the provided property values.
build()

Builds a new EntityPart instance using the provided property values.

public EntityPart.Builder

Returns:

the updated builder
content(InputStream
InputStream of the content of this part
content)

Sets the content for this part.

public default EntityPart.Builder

Returns:

the updated builder.
content(String
the filename of the part.
fileName, InputStream
the content stream of the part.
content)

Convenience method, equivalent to calling fileName(fileName).content(content).

public <
the entity type
T> EntityPart.Builder

Returns:

the updated builder.
content(T
the object to be used as the content
content, Class<? extends T>
the type of this object which will be used when selecting the appropriate jakarta.ws.rs.ext.MessageBodyWriter
type)

Sets the content for this part.

public default EntityPart.Builder

Returns:

the updated builder.
content(Object
the object to be used as the content
content)

Sets the content for this part.

public <
the entity type
T> EntityPart.Builder

Returns:

the updated builder.
content(T
the object to be used as the content
content, GenericType<T>
the generic type of this object which will be used when selecting the appropriate jakarta.ws.rs.ext.MessageBodyWriter
type)

Sets the content for this part.

public EntityPart.Builder

Returns:

the updated builder
fileName(String
the file name for this part
fileName)

Sets the file name for this part.

public EntityPart.Builder

Returns:

the updated builder
header(String
the header name
headerName, String...
the header value(s)
headerValues)

Adds a new header or replaces a previously added header and sets the header value(s).

public EntityPart.Builder

Returns:

the updated builder
headers(MultivaluedMap<String, String>
the multivalued map of headers to add to this part
newHeaders)

Adds new headers or replaces previously added headers.

public EntityPart.Builder

Returns:

the updated builder
mediaType(MediaType
the media type for the part to be built
mediaType)

Sets the media type for the EntityPart.

public EntityPart.Builder

Returns:

the updated builder
mediaType(String
the media type for the part to be built
mediaTypeString)

Convenience method for setting the media type for the EntityPart.

Method Detail

buildback to summary
public EntityPart build() throws IllegalStateException, IOException, WebApplicationException

Builds a new EntityPart instance using the provided property values.

Returns:EntityPart

EntityPart instance built from the provided property values.

Exceptions
IllegalStateException:
if the content was not specified or no matching jakarta.ws.rs.ext.MessageBodyWriter was found.
IOException:
if the underlying jakarta.ws.rs.ext.MessageBodyWriter throws an IOException
WebApplicationException:
if the underlying jakarta.ws.rs.ext.MessageBodyWriter throws a WebApplicationException
contentback to summary
public EntityPart.Builder content(InputStream content) throws IllegalArgumentException

Sets the content for this part. The content of this builder must be specified before invoking the build() method.

The InputStream will be closed by the implementation code after sending the multipart data. Closing the stream before it is sent could result in unexpected behavior.

Parameters
content:InputStream

InputStream of the content of this part

Returns:EntityPart.Builder

the updated builder

Exceptions
IllegalArgumentException:
if content is null
contentback to summary
public default EntityPart.Builder content(String fileName, InputStream content) throws IllegalArgumentException

Convenience method, equivalent to calling fileName(fileName).content(content).

Parameters
fileName:String

the filename of the part.

content:InputStream

the content stream of the part.

Returns:EntityPart.Builder

the updated builder.

Exceptions
IllegalArgumentException:
if either parameter is null.
contentback to summary
public <T> EntityPart.Builder content(T content, Class<? extends T> type) throws IllegalArgumentException

Sets the content for this part. The content of this builder must be specified before invoking the build() method.

If the content is specified using this method, then the build() method is responsible for finding a registered jakarta.ws.rs.ext.MessageBodyWriter that is capable of writing the object type specified here using the default MediaType or the MediaType specified in the mediaType(MediaType) or mediaType(String) methods and using any headers specified via the header(String, String...) or headers(MultivaluedMap) methods.

Parameters
<T>
the entity type
content:T

the object to be used as the content

type:Class<? extends T>

the type of this object which will be used when selecting the appropriate jakarta.ws.rs.ext.MessageBodyWriter

Returns:EntityPart.Builder

the updated builder.

Exceptions
IllegalArgumentException:
if content is null
contentback to summary
public default EntityPart.Builder content(Object content) throws IllegalArgumentException

Sets the content for this part. The content of this builder must be specified before invoking the build() method.

If the content is specified using this method, then the build() method is responsible for finding a registered jakarta.ws.rs.ext.MessageBodyWriter that is capable of writing the object's class type specified here using the default MediaType or the MediaType specified in the mediaType(MediaType) or mediaType(String) methods and using any headers specified via the header(String, String...) or headers(MultivaluedMap) methods.

This is the equivalent of calling content(content, content.getClass()).

Parameters
content:Object

the object to be used as the content

Returns:EntityPart.Builder

the updated builder.

Exceptions
IllegalArgumentException:
if content is null
contentback to summary
public <T> EntityPart.Builder content(T content, GenericType<T> type) throws IllegalArgumentException

Sets the content for this part. The content of this builder must be specified before invoking the build() method.

If the content is specified using this method, then the build() method is responsible for finding a registered jakarta.ws.rs.ext.MessageBodyWriter that is capable of writing the object type specified here using the default MediaType or the MediaType specified in the mediaType(MediaType) or mediaType(String) methods and using any headers specified via the header(String, String...) or headers(MultivaluedMap) methods.

Parameters
<T>
the entity type
content:T

the object to be used as the content

type:GenericType<T>

the generic type of this object which will be used when selecting the appropriate jakarta.ws.rs.ext.MessageBodyWriter

Returns:EntityPart.Builder

the updated builder.

Exceptions
IllegalArgumentException:
if content is null
fileNameback to summary
public EntityPart.Builder fileName(String fileName) throws IllegalArgumentException

Sets the file name for this part. The file name will be specified as an attribute in the Content-Disposition header of this part. When this method is called, the default media type used for the built part will be "application/octet-stream" if not otherwise specified.

Parameters
fileName:String

the file name for this part

Returns:EntityPart.Builder

the updated builder

Exceptions
IllegalArgumentException:
if fileName is null
headerback to summary
public EntityPart.Builder header(String headerName, String... headerValues) throws IllegalArgumentException

Adds a new header or replaces a previously added header and sets the header value(s).

Parameters
headerName:String

the header name

headerValues:String[]

the header value(s)

Returns:EntityPart.Builder

the updated builder

Exceptions
IllegalArgumentException:
if headerName is null
headersback to summary
public EntityPart.Builder headers(MultivaluedMap<String, String> newHeaders) throws IllegalArgumentException

Adds new headers or replaces previously added headers. The behavior of this method would be the same as if iterating over the entry set and invoking the header(String, String...) method.

Parameters
newHeaders:MultivaluedMap<String, String>

the multivalued map of headers to add to this part

Returns:EntityPart.Builder

the updated builder

Exceptions
IllegalArgumentException:
if newHeaders is null
mediaTypeback to summary
public EntityPart.Builder mediaType(MediaType mediaType) throws IllegalArgumentException

Sets the media type for the EntityPart. This will also set the Content-Type header for this part.

Parameters
mediaType:MediaType

the media type for the part to be built

Returns:EntityPart.Builder

the updated builder

Exceptions
IllegalArgumentException:
if mediaType is null
mediaTypeback to summary
public EntityPart.Builder mediaType(String mediaTypeString) throws IllegalArgumentException

Convenience method for setting the media type for the EntityPart. This will also set the Content-Type header for this part. This call is effectively the same as mediaType(MediaType.valueOf(mediaTypeString)).

Parameters
mediaTypeString:String

the media type for the part to be built

Returns:EntityPart.Builder

the updated builder

Exceptions
IllegalArgumentException:
if mediaTypeString cannot be parsed or is null