public interface EntityPart
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.
Modifier and Type | Interface and Description |
---|---|
static interface |
EntityPart.Builder
Builder for
EntityPart instances. |
Modifier and Type | Method and Description |
---|---|
java.io.InputStream |
getContent()
Returns the input stream for this part.
|
<T> T |
getContent(java.lang.Class<T> type)
Converts the content stream for this part to the specified class and returns
it.
|
<T> T |
getContent(GenericType<T> type)
Converts the content stream for this part to the specified type 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. |
static EntityPart.Builder withName(java.lang.String partName)
EntityPart.Builder
instance.partName
- name of the part to create within the multipart entityEntityPart.Builder
for building new EntityPart
instancesstatic EntityPart.Builder withFileName(java.lang.String partAndFileName)
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)
.
partAndFileName
- name and filename of the part to create within the
multipart entityEntityPart.Builder
for building new EntityPart
instancesjava.lang.String getName()
Content-Disposition
header for this part.java.util.Optional<java.lang.String> getFileName()
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()
.Optional<String>
indicating the filename if presentjava.io.InputStream getContent()
InputStream
representing the content of this part<T> T getContent(java.lang.Class<T> type) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException, java.io.IOException, WebApplicationException
MessageBodyReader
that handles the specified type
as well as the MediaType
of the part. If no
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)
.T
- the entity typetype
- the Class
that the implementation should convert this
part toClass
representing the content
of this partjava.lang.IllegalArgumentException
- if no
MessageBodyReader
can handle the conversion of this part to
the specified typejava.lang.IllegalStateException
- if this method or any of the other
getContent
methods has already been
invokedjava.io.IOException
- if the
MessageBodyReader.readFrom(Class,
java.lang.reflect.Type, java.lang.annotation.Annotation[], MediaType, MultivaluedMap, InputStream)
method throws an IOException
WebApplicationException
- if the
MessageBodyReader.readFrom(Class,
java.lang.reflect.Type, java.lang.annotation.Annotation[], MediaType, MultivaluedMap, InputStream)
method throws an
WebApplicationException
<T> T getContent(GenericType<T> type) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException, java.io.IOException, WebApplicationException
MessageBodyReader
that handles the specified type
as well as the MediaType
of the part. If no
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)
.T
- the entity typetype
- the generic type that the implementation should convert this part
tojava.lang.IllegalArgumentException
- if no
MessageBodyReader
can handle the conversion of this part to
the specified typejava.lang.IllegalStateException
- if this method or any of the other
getContent
methods has already been
invokedjava.io.IOException
- if the
MessageBodyReader.readFrom(Class,
java.lang.reflect.Type, java.lang.annotation.Annotation[], MediaType, MultivaluedMap, InputStream)
method throws an IOException
WebApplicationException
- if the
MessageBodyReader.readFrom(Class,
java.lang.reflect.Type, java.lang.annotation.Annotation[], MediaType, MultivaluedMap, InputStream)
method throws an
WebApplicationException
MultivaluedMap<java.lang.String,java.lang.String> getHeaders()
MultivaluedMap<String, String>
of part headersMediaType getMediaType()
MediaType.valueOf(part.getHeaders().getFirst(HttpHeaders.CONTENT_TYPE))
.