Package org.apache.juneau.http.classic.entity

Class BasicHttpEntity<SELF extends BasicHttpEntity<SELF>>

java.lang.Object
org.apache.juneau.http.classic.entity.BasicHttpEntity<SELF>
Type Parameters:
SELF - The self type for fluent setters.
All Implemented Interfaces:
HttpEntity
Direct Known Subclasses:
ByteArrayEntity, FileEntity, ReaderEntity, SerializedEntity, StreamEntity, StringEntity
@BeanIgnore public abstract class BasicHttpEntity<SELF extends BasicHttpEntity<SELF>> extends Object implements HttpEntity
A basic HttpEntity implementation with additional features. Provides the following features:
  • Caching.
  • Fluent setters.
  • Fluent assertions.
  • Externally-supplied/dynamic content.

Immutability is expressed with the "funnel + nested Unmodifiable snapshot" paradigm: every fluent setter routes through the single protected modify(Runnable) choke-point, and each concrete leaf gets a nested X.Unmodifiable whose only behavioral override is a throwing modify(...). A leaf's unmodifiable() factory returns a point-in-time snapshot of type X.Unmodifiable; any attempt to set a property on it throws an UnsupportedOperationException.

This is a self-typed (CRTP) root: a leaf declares class StringEntity extends BasicHttpEntity<StringEntity> and inherits leaf-typed fluent setters with no covariant overrides.

Notes:
  • Beans are not thread safe unless they're marked as unmodifiable.
See Also:

  • Field Details

  • Constructor Details

  • Method Details

    • asBytes

      public byte[] asBytes() throws IOException
      Converts the contents of this entity as a byte array.

      Note that this may exhaust the content on non-repeatable, non-cached entities.

      Returns:
      The contents of this entity as a byte array.
      Throws:
      IOException - If a problem occurred while trying to read the content.

    • assertBytes

      public FluentByteArrayAssertion<BasicHttpEntity<?>> assertBytes() throws IOException
      Returns an assertion on the contents of this entity.

      Note that this may exhaust the content on non-repeatable, non-cached entities.

      Returns:
      A new fluent assertion.
      Throws:
      IOException - If a problem occurred while trying to read the byte array.

    • assertString

      public FluentStringAssertion<BasicHttpEntity<?>> assertString() throws IOException
      Returns an assertion on the contents of this entity.

      Note that this may exhaust the content on non-repeatable, non-cached entities.

      Returns:
      A new fluent assertion.
      Throws:
      IOException - If a problem occurred while trying to read the byte array.

    • asString

      public String asString() throws IOException
      Converts the contents of this entity as a string.

      Note that this may exhaust the content on non-repeatable, non-cached entities.

      Returns:
      The contents of this entity as a string.
      Throws:
      IOException - If a problem occurred while trying to read the content.

    • consumeContent

      public void consumeContent() throws IOException
      Specified by:
      consumeContent in interface HttpEntity
      Throws:
      IOException

    • copy

      public abstract SELF copy()
      Creates a builder for this class initialized with the contents of this bean.

      Allows you to create a modifiable copy of this bean.

      Returns:
      A new builder bean.

    • getCharset

      public Charset getCharset()
      Returns the charset to use when converting to and from stream-based resources.
      Returns:
      The charset to use when converting to and from stream-based resources.

    • getContent

      public InputStream getContent() throws IOException, UnsupportedOperationException
      Specified by:
      getContent in interface HttpEntity
      Throws:
      IOException
      UnsupportedOperationException

    • getContentEncoding

      public Header getContentEncoding()
      Specified by:
      getContentEncoding in interface HttpEntity

    • getContentLength

      public long getContentLength()
      Specified by:
      getContentLength in interface HttpEntity

    • getContentType

      public Header getContentType()
      Specified by:
      getContentType in interface HttpEntity

    • getMaxLength

      public int getMaxLength()
      Returns the maximum number of bytes to read or write to and from stream-based resources.
      Returns:
      The maximum number of bytes to read or write to and from stream-based resources.

    • isCached

      public boolean isCached()
      Returns true if this entity is cached in-memory.
      Returns:
      true if this entity is cached in-memory.

    • isChunked

      public boolean isChunked()
      Specified by:
      isChunked in interface HttpEntity

    • isRepeatable

      public boolean isRepeatable()
      Specified by:
      isRepeatable in interface HttpEntity

    • isStreaming

      public boolean isStreaming()
      Specified by:
      isStreaming in interface HttpEntity

    • isUnmodifiable

      public boolean isUnmodifiable()
      Returns true if this bean is unmodifiable.
      Returns:
      true if this bean is an UnmodifiableBean snapshot.

    • setCached

      public SELF setCached() throws IOException
      Specifies that the contents of this resource should be cached into an internal byte array so that it can be read multiple times.
      Returns:
      This object.
      Throws:
      IOException - If entity could not be read into memory.

    • setCharset

      public SELF setCharset(Charset value)
      Specifies the charset to use when converting to and from stream-based resources.
      Parameters:
      value - The new value. If null, UTF-8 is assumed.
      Returns:
      This object.

    • setChunked

      public SELF setChunked()
      Sets the 'chunked' flag value to true.
      Notes:
      Returns:
      This object.

    • setChunked

      public SELF setChunked(boolean value)
      Sets the 'chunked' flag value.
      Notes:
      Parameters:
      value - The new value for this flag.
      Returns:
      This object.

    • setContent

      public SELF setContent(Object value)
      Sets the content on this entity bean.
      Parameters:
      value - The entity content. Can be null (the effect depends on the concrete leaf type: e.g. treated as empty for StringEntity/ByteArrayEntity, or a NullPointerException on read for StreamEntity/ReaderEntity/FileEntity).
      Returns:
      This object.

    • setContent

      public SELF setContent(Supplier<?> value)
      Sets the content on this entity bean from a supplier.

      Repeatable entities such as StringEntity use this to allow the entity content to be resolved at serialization time.

      Parameters:
      value - The entity content, can be null (treated as a supplier that always returns null).
      Returns:
      This object.

    • setContentEncoding

      public SELF setContentEncoding(ContentEncoding value)
      Sets the content encoding header on this entity bean.
      Parameters:
      value - The new Content-Encoding header, or null to unset.
      Returns:
      This object.

    • setContentEncoding

      public SELF setContentEncoding(String value)
      Sets the content encoding header on this entity bean.
      Parameters:
      value - The new Content-Encoding header, or null to unset.
      Returns:
      This object.

    • setContentLength

      public SELF setContentLength(long value)
      Sets the content length on this entity bean.
      Parameters:
      value - The new Content-Length header value, or -1 to unset.
      Returns:
      This object.

    • setContentType

      public SELF setContentType(ContentType value)
      Sets the content type on this entity bean.
      Parameters:
      value - The new Content-Type header, or null to unset.
      Returns:
      This object.

    • setContentType

      public SELF setContentType(String value)
      Sets the content type on this entity bean.
      Parameters:
      value - The new Content-Type header, or null to unset.
      Returns:
      This object.

    • setMaxLength

      public SELF setMaxLength(int value)
      Specifies the maximum number of bytes to read or write to and from stream-based resources.

      Implementation is not universal.

      Parameters:
      value - The new value. The default is -1 which means read everything.
      Returns:
      This object.

    • unmodifiable

      public abstract SELF unmodifiable()
      Returns an unmodifiable snapshot of this bean.

      The returned instance is a point-in-time copy of the leaf's nested Unmodifiable type; any attempt to set a property on it throws an UnsupportedOperationException. This method is idempotent: if this bean is already unmodifiable it returns itself rather than taking another snapshot. The receiver is left unchanged (and still modifiable unless it was already unmodifiable).

      Returns:
      An unmodifiable snapshot of this bean, or this bean if it is already unmodifiable.

    • writeTo

      public void writeTo(OutputStream outStream) throws IOException
      Specified by:
      writeTo in interface HttpEntity
      Throws:
      IOException

    • equals

      public boolean equals(Object o)
      Compares the shared base content of two entities.

      This base implementation compares only the fields declared on BasicHttpEntity and deliberately accepts any BasicHttpEntity subtype so that concrete leaves can delegate to it via super.equals(...). It does not gate on the concrete leaf type; each concrete leaf overrides equals to first apply an instanceof <ThatLeaf> gate (so two unrelated leaves with equal base content are not equal) and then calls super.equals(...) to compare the inherited content. Using instanceof <ThatLeaf> (rather than getClass() ==) is what preserves the immutability invariant that bean.equals(bean.unmodifiable()) holds, since each X.Unmodifiable snapshot is a subclass of its leaf X.

      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • asSafeBytes

      protected byte[] asSafeBytes()
      Same as asBytes() but wraps IOExceptions inside a RuntimeException.
      Returns:
      The contents of this entity as a byte array.

    • contentOrElse

      protected <T> T contentOrElse(T def)
      Returns the content of this entity.
      Type Parameters:
      T - The value type.
      Parameters:
      def - The default value if null.
      Returns:
      The content object.

    • isSupplied

      protected boolean isSupplied()
      Returns true if the contents of this entity are provided through an external supplier.

      Externally supplied content generally means the content length cannot be reliably determined based on the content.

      Returns:
      true if the contents of this entity are provided through an external supplier.

    • self

      protected final SELF self()
      Returns this object cast to the self type.
      Returns:
      This object.

    • modify

      protected SELF modify(Runnable mutation)
      Single mutation funnel — the only choke-point through which all state changes on this bean flow.

      Every fluent setter routes through this method. The nested Unmodifiable snapshot overrides only this method to throw, which freezes the entire mutation surface with a single override.

      Parameters:
      mutation - The state change to apply.
      Returns:
      This object.

    • freeze

      protected void freeze()
      Deep-freeze hook invoked from the nested Unmodifiable constructor after the snapshot copy completes.

      Entities hold no mutable sub-beans (the content-type / content-encoding headers are immutable value objects, and the content buffer follows the copy-constructor's reference-copy behavior), so this is a documented no-op — the single throwing modify(Runnable) override on the nested Unmodifiable already freezes the entire mutation surface. A leaf that adds its own mutable sub-bean would override this method (calling super.freeze() first).