public interface HttpEntity
An http entity is included in an http message to represent a resource. See RFC2616 §7 Entity.
An entity contains a body, and metadata like contentType.
An entity is sharable if its body can be read multiple times by multiple readers, potentially concurrently. A sharable entity can be cached and served to multiple http messages.
| Abstract Methods | |
|---|---|
ByteSource |
body()
The body of this entity.
|
ContentType |
contentType()
The content type.
|
| Default Methods | |
Async<ByteBuffer> |
bodyBytes(int maxBytes)
Get all the bytes of the body.
|
Async<String> |
bodyString(int maxChars)
Get the body as a String.
|
Long |
contentLength()
The length of the body; null if unknown.
|
String |
contentEncoding()
Encoding that has been applied on the body; null if none.
|
Instant |
lastModified()
When this entity was last modified; null if unknown.
|
Instant |
expires()
When this entity expires; null if unknown.
|
String |
etag()
The entity tag; null if none.
|
boolean |
etagIsWeak()
Whether the etag is weak.
|
ByteSource body() throws IllegalStateException
This method must not return null. If the body is empty, return a ByteSource that contains 0 bytes.
If this entity is sharable, each invocation of this method must return a new, independent ByteSource.
If this entity is not sharable, this method can only be invoked once; further invocations throw IllegalStateException.
The caller must close() the returned ByteSource eventually.
If the producer of the entity wants to treat the body as a sink to write to,
see BytePipe.
It's possible that the consumer of an `HttpEntity` never calls the `body()` method. The implementation of `body()` should be lazy, creating body only on demand.
The length of the body should be consistent with contentLength();
however, if this is a response entity to a HEAD request, the body can be empty,
regardless of the value of contentLength().
IllegalStateException - if invoked more than once on a non-sharable entity.default Async<ByteBuffer> bodyBytes(int maxBytes)
This method is equivalent to
body().
readAll(maxBytes)
default Async<String> bodyString(int maxChars)
The default implementation calls body() .
asString(maxChars, charset) .
The charset is from contentType's
"charset" parameter;
otherwise "UTF-8" is assumed.
contentEncoding must be `null`,
or this action fails.
ContentType contentType()
This property corresponds to the Content-Type header.
This method may return null if the content type is unknown, then the recipient of the entity must guess the content type. However this is strongly discouraged.
default Long contentLength()
This property corresponds to the
Content-Length header.
Note that if this is a response entity to a HEAD request,
Content-Length reports the would-be length,
while the body() method can return an empty source.
If contentEncoding!=null,
contentLength is the length after the encoding is applied.
The default implementation returns null.
default String contentEncoding()
This property corresponds to the Content-Encoding header.
For example, if the entity is an html document, and contentEncoding=="gzip", the entity body is the html document compressed in gzip format.
If two entities represent the same resource but with different content encodings, they should have different ETags.
If contentEncoding!=null, the reader of the body needs to decode it to get the original content.
The default implementation returns null.
See also HttpServerConf.requestEncodingPolicy(String).
Note that by default HttpServer rejects any request with Content-Encoding,
in which case the server app can assert that
entity.contentEncoding==null for all requests passed to it.
default Instant lastModified()
This property corresponds to the Last-Modified header.
The default implementation returns null.
Note: the precision of HTTP Last-Modified value is 1 second, which is very poor.
It may not adequate for fast changing resources.
Consider ETag instead. The default implementation of etag() is based on
lastModified() with nano-second precision.
default Instant expires()
This property corresponds to the Expires header.
The default implementation returns null.
default String etag()
This property corresponds to the
ETag header.
For example, if entity.etag()=="123", the response will contain the header
Entity: "123"
See also etagIsWeak().
Legal chars in ETag: 0x21-0xFF, except 0x22(") and 0x7F(DEL).
Backslash 0x5C(\) is legal but should not be used either,
because some interpret it as the escape char.
The default implementation is based on lastModified() and contentEncoding():
"t-53319ee8-623a7c0.gzip".
default boolean etagIsWeak()
See rfc7232#section-2.1.
The default implementation returns false.