Interface ReadableEntity

All Known Subinterfaces:
ReadablePart
All Known Implementing Classes:
ClientResponseEntity, Http2ServerRequestEntity, ReadableEntityBase, ServerRequestEntity

public interface ReadableEntity
Readable HTTP entity. This may be server request entity, or client response entity. Materializing conversions are limited by the HTTP protocol's max-buffered-entity-size (decoded input bytes, not heap usage). inputStream() and media readers that declare streaming behavior are exempt. Server-side max-payload-size applies independently to both streamed and materialized decoded request bodies when configured.
  • Method Summary

    Modifier and Type
    Method
    Description
    <T> T
    as(GenericType<T> type)
    Get the entity as a specific type.
    default <T> T
    as(Class<T> type)
    Get the entity as a specific class.
    <T> Optional<T>
    Get the entity as a specific type (optional).
    default <T> Optional<T>
    asOptional(Class<T> type)
    Get the entity as a specific class (optional).
    default void
    If called before inputStream(), it will buffer the entity and support multiple calls to inputStream() after that.
    default void
    Consume the entity if not yet consumed.
    boolean
    Whether this entity has been consumed already.
    copy(Runnable entityProcessedRunnable)
    Copy this entity and add a new runnable to be executed after this entity is consumed.
    boolean
    Whether an entity actually exists.
    Input stream to read bytes of the entity.
  • Method Details

    • inputStream

      InputStream inputStream()
      Input stream to read bytes of the entity. Cannot be combined with methods as(Class) or as(io.helidon.common.GenericType) If there is no entity, returns input stream on empty byte array. This stream is not limited by max-buffered-entity-size.
      Returns:
      input stream to entity bytes
    • buffer

      default void buffer()
      If called before inputStream(), it will buffer the entity and support multiple calls to inputStream() after that. Normally, inputStream() can only be called at most once. On a server request, this buffers decoded bytes and applies both the protocol's max-buffered-entity-size and the configured max-payload-size before allowing the entity to be read again.
      Throws:
      IllegalStateException - if called after inputStream() or if the buffer size limit was exceeded outside a server request
      HttpException - if a server request exceeds either size limit
      UnsupportedOperationException - if not supported
    • as

      default <T> T as(Class<T> type)
      Get the entity as a specific class. The entity will use MediaContext to find correct media mapper.
      Type Parameters:
      T - type of the entity
      Parameters:
      type - class of the entity
      Returns:
      entity correctly typed
      Throws:
      IllegalArgumentException - in case the entity type is not supported
      IllegalStateException - if there is no entity or the materialized entity size limit is exceeded outside a server request
      HttpException - if a server request exceeds its materialized entity size limit
      UncheckedIOException - in case I/O fails
    • asOptional

      default <T> Optional<T> asOptional(Class<T> type)
      Get the entity as a specific class (optional). The entity will use MediaContext to find correct media mapper.
      Type Parameters:
      T - type of the entity
      Parameters:
      type - class of the entity
      Returns:
      entity correctly typed, or an empty optional if entity is not present
      Throws:
      IllegalArgumentException - in case the entity type is not supported
      IllegalStateException - if the materialized entity size limit is exceeded outside a server request
      HttpException - if a server request exceeds its materialized entity size limit
      UncheckedIOException - in case I/O fails
    • as

      <T> T as(GenericType<T> type)
      Get the entity as a specific type. The entity will use MediaContext to find correct media mapper.
      Type Parameters:
      T - type of the entity
      Parameters:
      type - generic type of the entity
      Returns:
      entity correctly typed
      Throws:
      IllegalArgumentException - in case the entity type is not supported
      IllegalStateException - if there is no entity or the materialized entity size limit is exceeded outside a server request
      HttpException - if a server request exceeds its materialized entity size limit
      UncheckedIOException - in case I/O fails
    • asOptional

      <T> Optional<T> asOptional(GenericType<T> type)
      Get the entity as a specific type (optional). The entity will use MediaContext to find correct media mapper.
      Type Parameters:
      T - type of the entity
      Parameters:
      type - generic type of the entity
      Returns:
      entity correctly typed, or an empty optional if entity is not present
      Throws:
      IllegalArgumentException - in case the entity type is not supported
      IllegalStateException - if the materialized entity size limit is exceeded outside a server request
      HttpException - if a server request exceeds its materialized entity size limit
      UncheckedIOException - in case I/O fails
    • hasEntity

      boolean hasEntity()
      Whether an entity actually exists.
      Returns:
      true if an entity exists and can be read
    • consumed

      boolean consumed()
      Whether this entity has been consumed already.
      Returns:
      true if the entity is already consumed; a consumed entity cannot be consumed again
    • copy

      ReadableEntity copy(Runnable entityProcessedRunnable)
      Copy this entity and add a new runnable to be executed after this entity is consumed.
      Parameters:
      entityProcessedRunnable - runnable to execute on consumed entity
      Returns:
      a new entity delegating to this entity
    • consume

      default void consume()
      Consume the entity if not yet consumed. Reads all bytes from the entity and discards them. If entity is larger than allowed, appropriate HTTP exception is thrown. If entity is already consumed, this is a no-op.