Package com.nsdev.lettergenerator.builder

Class HtmlLetterBuilder

java.lang.Object
com.nsdev.lettergenerator.builder.HtmlLetterBuilder
public final class HtmlLetterBuilder extends Object
Mutable compiler input for the supported HTML-like letter template language. Prefer Letter.template(String) or Letter.fromHtml(String) as entry points. A single <letter> root defines regions and page settings; arbitrary browser HTML is not supported. Placeholder values replace parsed text and attribute values without creating new markup nodes. Image references use explicitly registered asset bytes.

Values replace the previous binding map; assets accumulate by name and replace an existing name. Parsing, substitution, and asset resolution happen at build(). Each build returns an independent immutable document; full rendering validation happens in LetterPdfGenerator.

  • Method Details

    • template

      public static HtmlLetterBuilder template(String source)
      Creates a builder with ${name} substitution enabled. Missing bindings fail at build time; replacement values are not recursively substituted.
      Parameters:
      source - non-null source containing one supported <letter> root
      Returns:
      a fresh template builder
      Throws:
      IllegalArgumentException - if source is null

    • resolvedHtml

      public static HtmlLetterBuilder resolvedHtml(String source)
      Creates a builder for already-resolved letter markup with substitution disabled. Calling values(Map) on this builder is an error.
      Parameters:
      source - non-null source containing one supported <letter> root
      Returns:
      a fresh builder for resolved markup
      Throws:
      IllegalArgumentException - if source is null

    • values

      public HtmlLetterBuilder values(Map<String,?> replacements)
      Replaces all bindings with an owned typed snapshot. Maps with nonblank string keys, lists, finite numbers, booleans, text, characters and supported immutable java.time values are accepted. Null values, cycles and arbitrary objects fail with the input path.
      Parameters:
      replacements - non-null map of nonblank keys to non-null supported values
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if substitution is disabled, the map is null, a key is null or blank, or a value is null or unsupported

    • locale

      public HtmlLetterBuilder locale(LocaleSettings value)
      Sets deterministic document locale while preserving other explicit settings.
      Parameters:
      value - non-null formatting settings
      Returns:
      this builder

    • settings

      public HtmlLetterBuilder settings(DocumentSettings value)
      Sets immutable language, metadata and text configuration.
      Parameters:
      value - non-null document settings
      Returns:
      this builder

    • compile

      public PreparedLetterTemplate compile()
      Captures parsed source and owned configuration for concurrent repeated binding.
      Returns:
      immutable prepared template

    • asset

      public HtmlLetterBuilder asset(String name, byte[] data)
      Registers a defensive copy of named image bytes for later HTML asset resolution. Reusing a name replaces its previous bytes. Image decoding and format checks occur when markup referencing the asset is built, so registration can follow content calls.
      Parameters:
      name - nonblank asset identifier used by markup image references
      data - non-null image bytes; supported image formats are PNG, JPEG and static SVG
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the name is null or blank, or the bytes are null

    • asset

      public HtmlLetterBuilder asset(String name, Path path) throws IOException
      Reads a local file immediately and registers its bytes as a named markup image asset. Reusing a name replaces the existing asset; image decoding is deferred until referenced markup is built.
      Parameters:
      name - nonblank asset identifier
      path - non-null image file to read
      Returns:
      this builder
      Throws:
      IOException - if the file cannot be read
      NullPointerException - if path is null
      IllegalArgumentException - if name is null or blank

    • theme

      public HtmlLetterBuilder theme(LetterTheme value)
      Supplies per-document role defaults and named styles.
      Parameters:
      value - non-null immutable theme
      Returns:
      this builder

    • component

      public HtmlLetterBuilder component(String name, LetterComponent value)
      Registers a fragment referenced by an empty component tag with a ref attribute.
      Parameters:
      name - nonblank component name
      value - immutable content
      Returns:
      this builder

    • validate

      public ValidationReport validate()
      Inspects bindings, assets and declared model constraints using built-in fonts, without PDF layout.
      Returns:
      immutable report aggregating missing variable occurrences and invalid assets

    • validate

      public ValidationReport validate(LetterPdfGenerator generator)
      Inspects with the selected generator's registered fonts. Success does not guarantee content fit.
      Parameters:
      generator - non-null font-aware validator
      Returns:
      immutable authoring report

    • build

      public LetterDocument build()
      Compiles the current source, bindings and assets into an immutable document snapshot. Template parsing, supported-tag and style checks, placeholder binding, image decoding and region arrangement occur here. Rendering validation, including font availability and layout constraints, is performed later by LetterPdfGenerator. The builder remains reusable after a build.
      Returns:
      a new immutable letter document
      Throws:
      InvalidLetterException - if markup, placeholders, referenced assets or constructed letter regions are invalid, or no body content is produced