Class TagTrailerDataContentBuilder<T>

java.lang.Object
zeroecho.sdk.builders.TagTrailerDataContentBuilder<T>
Type Parameters:
T - the engine-specific verification type parameter used by TagEngine
All Implemented Interfaces:
DataContentBuilder<DataContent>
public final class TagTrailerDataContentBuilder<T> extends Object implements DataContentBuilder<DataContent>
Builder for DataContent pipelines that attach or verify an authentication tag at end of stream.

A TagTrailerDataContentBuilder composes with a TagEngine to produce DataContent instances for two complementary flows:

  • Encrypt (produce): the wrapped engine emits [body][tag] when EOF is reached.
  • Decrypt (verify): the trailer is stripped from input, supplied to TagEngine.setExpectedTag(byte[]), and the body is streamed through the engine for verification.

Construction

  • Use the single-engine constructor if only one stream will be built from this instance.
  • Prefer the factory constructor (for example, with TagEngineBuilder) to obtain a fresh TagEngine per stream and avoid state reuse.

Verification behavior

Since:
1.0

  • Constructor Details

    • TagTrailerDataContentBuilder

      public TagTrailerDataContentBuilder(TagEngine<T> engine)
      Creates a builder bound to a fixed engine instance.

      This form ties the builder to a single-use engine. Prefer TagTrailerDataContentBuilder(Supplier) when multiple streams are expected.

      Parameters:
      engine - preconstructed engine instance; must not be null
      Throws:
      NullPointerException - if engine is null

    • TagTrailerDataContentBuilder

      public TagTrailerDataContentBuilder(Supplier<? extends TagEngine<T>> engineFactory)
      Creates a builder with an engine factory.

      A fresh engine is obtained for each built stream. See TagEngineBuilder for standard factories.

      Parameters:
      engineFactory - supplier producing a new TagEngine; must not be null
      Throws:
      NullPointerException - if engineFactory is null

  • Method Details

    • bufferSize

      public TagTrailerDataContentBuilder<T> bufferSize(int bytes)
      Sets the internal I/O buffer size used when stripping the trailer.
      Parameters:
      bytes - buffer size in bytes; must be at least 1
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if bytes < 1

    • throwOnMismatch

      public TagTrailerDataContentBuilder<T> throwOnMismatch()
      Configures decryption to throw on verification mismatch.

      This is the default. The underlying engine is set up to raise IOException at EOF when the computed tag does not equal the expected tag.

      Returns:
      this builder for chaining

    • flagInContext

      public TagTrailerDataContentBuilder<T> flagInContext(CtxInterface ctx, Key<Boolean> verifyKey)
      Configures decryption to flag the verification outcome in the provided context instead of throwing.

      On mismatch, Boolean.FALSE is stored under verifyKey; on success, Boolean.TRUE is stored.

      Parameters:
      ctx - context for recording the result; must not be null
      verifyKey - key under which to record the verification result; must not be null
      Returns:
      this builder for chaining
      Throws:
      NullPointerException - if ctx or verifyKey is null

    • build

      public DataContent build(boolean encrypt)
      Builds a DataContent pipeline for the selected direction.
      • Encrypt: the engine appends the tag trailer after body bytes.
      • Decrypt: the trailer is stripped, supplied to the engine, and the body is streamed and verified.
      Specified by:
      build in interface DataContentBuilder<T>
      Parameters:
      encrypt - true to build the encrypting path, false for the decrypting path
      Returns:
      the configured DataContent pipeline