Package com.nsdev.lettergenerator.builder

Class LetterBuilder

java.lang.Object
com.nsdev.lettergenerator.builder.LetterBuilder
public final class LetterBuilder extends Object
Mutable builder for ordinary letters, obtained from Letter.builder() or the public no-argument constructor. Body content, tables, blocks and fixed elements append in call order; header, footer, signature, logo, watermark and configuration calls replace the corresponding setting. Each build() returns an independent immutable LetterDocument; the builder remains reusable and is not intended for concurrent use.

Defaults are A4 with 20 mm margins, 3 mm paragraph spacing, a 25 mm header box, a 15 mm footer box, and a flowing signature. HTML signature images use a 20 mm height basis by default. Body typography defaults to 11 pt black Helvetica with a 1.2 line-height multiplier. Header and footer reserve space only when present, with a 5 mm gap to the body; footer text defaults to 9 pt and #666666. Images preserve their aspect ratio. Named assets and HTML regions resolve against final builder settings at build time.

Argument checks catch nulls and basic geometry during configuration or building. The resulting model still needs LetterPdfGenerator validation for fonts, styles, collisions and final layout.

  • Constructor Details

    • LetterBuilder

      public LetterBuilder()

  • Method Details

    • part

      public LetterBuilder part(LetterElement element, List<Block> blocks)
      Replaces one semantic role while preserving conventional letter order.
      Parameters:
      element - semantic role
      blocks - immutable-model content
      Returns:
      this builder

    • part

      public LetterBuilder part(LetterElement element, List<Block> blocks, Style localStyle)
      Replaces one semantic role with explicit local wrapper styling.
      Parameters:
      element - semantic role
      blocks - ordered model content
      localStyle - optional local style
      Returns:
      this builder

    • sender

      public LetterBuilder sender(Party value)
      Replaces the sender identity/address.
      Parameters:
      value - non-null validated sender
      Returns:
      this builder

    • recipient

      public LetterBuilder recipient(Party value)
      Replaces the recipient identity/address.
      Parameters:
      value - non-null validated recipient
      Returns:
      this builder

    • date

      public LetterBuilder date(LocalDate value)
      Defers date formatting until final builder locale is known.
      Parameters:
      value - non-null letter date
      Returns:
      this builder

    • date

      public LetterBuilder date(LocalDate value, Style localStyle)
      Defers a locally styled date until final locale is known.
      Parameters:
      value - non-null date
      localStyle - optional local style
      Returns:
      this builder

    • subject

      public LetterBuilder subject(String value)
      Replaces the nonblank literal subject.
      Parameters:
      value - subject text
      Returns:
      this builder

    • reference

      public LetterBuilder reference(String label, String value)
      Replaces the reference with a bold label and literal value.
      Parameters:
      label - nonblank label
      value - nonblank value
      Returns:
      this builder

    • salutation

      public LetterBuilder salutation(String value)
      Replaces the nonblank opening greeting.
      Parameters:
      value - greeting
      Returns:
      this builder

    • closing

      public LetterBuilder closing(String value)
      Replaces the nonblank closing phrase after body content.
      Parameters:
      value - closing phrase
      Returns:
      this builder

    • addressLayout

      public LetterBuilder addressLayout(AddressLayout value)
      Places configured sender/recipient/date fields inside an editable body-relative panel.
      Parameters:
      value - optional-bound layout preset
      Returns:
      this builder

    • canvas

      public LetterBuilder canvas(CanvasBlock value)
      Appends one bounded arbitrary-position body canvas.
      Parameters:
      value - immutable canvas
      Returns:
      this builder

    • settings

      public LetterBuilder settings(DocumentSettings value)
      Replaces optional language, font and PDF metadata settings.
      Parameters:
      value - settings, null selects defaults
      Returns:
      this builder

    • locale

      public LetterBuilder locale(LocaleSettings value)
      Sets deterministic country-aware formatting.
      Parameters:
      value - language and formatting settings
      Returns:
      this builder

    • locale

      public LetterBuilder locale(Locale value)
      Sets a locale using its language tag and default date/currency conventions.
      Parameters:
      value - country-aware locale
      Returns:
      this builder

    • metadata

      public LetterBuilder metadata(DocumentMetadata value)
      Replaces PDF metadata.
      Parameters:
      value - optional title, author, subject and keywords
      Returns:
      this builder

    • direction

      public LetterBuilder direction(TextDirection value)
      Sets writing direction independently from formatting locale.
      Parameters:
      value - explicit direction or AUTO for language-derived direction
      Returns:
      this builder

    • fallbackFonts

      public LetterBuilder fallbackFonts(String... values)
      Sets ordered explicit registered fallback font families.
      Parameters:
      values - registered family names, tried after the selected family
      Returns:
      this builder

    • hyphenate

      public LetterBuilder hyphenate(boolean value)
      Enables dictionary hyphenation using explicitly registered trusted patterns.
      Parameters:
      value - whether hyphenation should be enabled
      Returns:
      this builder

    • attach

      public LetterBuilder attach(PdfAttachment value)
      Appends an immutable existing PDF to the output pack.
      Parameters:
      value - validated attachment snapshot
      Returns:
      this builder

    • pageSizeMm

      public LetterBuilder pageSizeMm(double widthMm, double heightMm)
      Selects custom physical paper dimensions, preserving the supplied orientation.
      Parameters:
      widthMm - sheet width in millimeters
      heightMm - sheet height in millimeters
      Returns:
      this builder

    • orientation

      public LetterBuilder orientation(Orientation value)
      Selects the shorter or longer edge as the horizontal edge.
      Parameters:
      value - sheet orientation
      Returns:
      this builder

    • landscape

      public LetterBuilder landscape()
      Returns:
      this builder configured for landscape paper

    • body

      public LetterBuilder body(LetterComponent value)
      Appends an immutable fragment as a softly kept body group.
      Parameters:
      value - reusable content
      Returns:
      this builder

    • header

      public LetterBuilder header(LetterComponent value)
      Replaces header content with a reusable fragment.
      Parameters:
      value - reusable content
      Returns:
      this builder

    • footer

      public LetterBuilder footer(LetterComponent value)
      Replaces footer content with a reusable fragment.
      Parameters:
      value - reusable content
      Returns:
      this builder

    • signature

      public LetterBuilder signature(LetterComponent value)
      Replaces signature content with a reusable fragment.
      Parameters:
      value - reusable content
      Returns:
      this builder

    • theme

      public LetterBuilder theme(LetterTheme value)
      Sets role defaults and named styles for this document.
      Parameters:
      value - non-null theme
      Returns:
      this builder

    • component

      public LetterBuilder component(String name, LetterComponent value)
      Registers a reusable document-local fragment; later registrations replace the same name.
      Parameters:
      name - nonblank reference name
      value - immutable content
      Returns:
      this builder

    • include

      public LetterBuilder include(String name)
      Appends a reference to a registered fragment at this position in body flow.
      Parameters:
      name - component name resolved during generation
      Returns:
      this builder

    • page

      public LetterBuilder page(PageSize size)
      Replaces the paper size, initially PageSize.A4. Header geometry and image fitting use the selected size when built.
      Parameters:
      size - non-null paper size
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if size is null

    • marginsMm

      public LetterBuilder marginsMm(double allSides)
      Replaces all four page margins with the same millimeter value. Margins must leave positive body space when the document is built.
      Parameters:
      allSides - finite nonnegative distance from every paper edge, in mm
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the value is negative or nonfinite

    • margins

      public LetterBuilder margins(Margins value)
      Replaces the four page margins. Nonnegative values and available page space are checked when building, allowing the page size to be changed before then.
      Parameters:
      value - non-null top, right, bottom and left margins in mm
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if value is null

    • style

      public LetterBuilder style(Style value)
      Replaces body style overrides, overlaid on the default 3 mm paragraph gap. Specified block or run styles can override inherited fields. This call does not accumulate overrides from earlier calls to this method.
      Parameters:
      value - non-null body defaults; unspecified fields retain library defaults
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if value is null

    • body

      public LetterBuilder body(String... content)
      Appends plain text chunks in order. Single newlines change lines, blank lines separate paragraphs, and form feeds (including Letter.PAGE_BREAK) insert page breaks. Each chunk begins its own paragraph sequence; CRLF and CR are normalized.
      Parameters:
      content - non-null array of non-null body strings
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the array or a chunk is null

    • heading

      public LetterBuilder heading(String text)
      Appends a heading block whose appearance inherits the document style and heading defaults.
      Parameters:
      text - non-null heading text
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if text is null

    • pageBreak

      public LetterBuilder pageBreak()
      Appends an explicit break so subsequent body content begins on a new page.
      Returns:
      this builder

    • table

      public LetterBuilder table(TableBlock value)
      Appends a table block, commonly produced by Table.builder(String...).
      Parameters:
      value - non-null table snapshot
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if value is null

    • block

      public LetterBuilder block(Block value)
      Appends an advanced model block without leaving the fluent API. Its explicit style fields override document defaults; detailed validation occurs at generation.
      Parameters:
      value - non-null body block
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if value is null

    • group

      public LetterBuilder group(Block... blocks)
      Appends an explicit softly kept group of immutable blocks.
      Parameters:
      blocks - non-null ordered child blocks
      Returns:
      this builder

    • group

      public LetterBuilder group(String... content)
      Appends grouped plain text using the ordinary newline/paragraph rules.
      Parameters:
      content - non-null text chunks without page breaks
      Returns:
      this builder

    • header

      public LetterBuilder header(String... text)
      Replaces the header with plain text repeated on every page. Single newlines change lines and blank lines separate paragraphs. The strings are copied; the final header style is applied when built. An empty array clears the content.
      Parameters:
      text - non-null array of non-null strings without form-feed page breaks
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the array or a string is null, or a string contains a form-feed page break

    • header

      public LetterBuilder header(PageSelector pages, String... text)
      Replaces header content for one page selection; ALL is fallback for unspecified selections. Geometry and inherited region defaults are shared across variants. Empty text/block content suppresses the fallback on that selection. Paths are read immediately; other inputs retain the corresponding ordinary overload's validation and snapshot rules.
      Parameters:
      pages - non-null page selection
      text - region content
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if input or page selection is invalid

    • footer

      public LetterBuilder footer(String... text)
      Replaces the footer with plain text repeated on every page. Single newlines change lines and blank lines separate paragraphs. The strings are copied; the final footer style is applied when built. An empty array clears the content.
      Parameters:
      text - non-null array of non-null strings without form-feed page breaks
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the array or a string is null, or a string contains a form-feed page break

    • footer

      public LetterBuilder footer(PageSelector pages, String... text)
      Replaces footer content for one page selection; ALL is fallback for unspecified selections. Geometry and inherited region defaults are shared across variants. Empty text/block content suppresses the fallback on that selection. Paths are read immediately; other inputs retain the corresponding ordinary overload's validation and snapshot rules.
      Parameters:
      pages - non-null page selection
      text - region content
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if input or page selection is invalid

    • headerStyle

      public LetterBuilder headerStyle(Style value)
      Replaces header style overrides on top of zero before/after spacing and the currently selected header alignment. Explicit block styles can override these inherited fields.
      Parameters:
      value - non-null header style overrides
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if value is null

    • headerStyle

      public LetterBuilder headerStyle(PageSelector pages, Style value)
      Applies appearance overrides to one header selection after the shared header defaults.
      Parameters:
      pages - non-null page selection
      value - non-null appearance overrides
      Returns:
      this builder

    • footerStyle

      public LetterBuilder footerStyle(PageSelector pages, Style value)
      Applies appearance overrides to one footer selection after the shared footer defaults.
      Parameters:
      pages - non-null page selection
      value - non-null appearance overrides
      Returns:
      this builder

    • headerAlignment

      public LetterBuilder headerAlignment(TextAlign alignment)
      Positions an automatic header box within the space beside the logo and supplies default content alignment. Explicit block styles can override the content alignment. With exact bounds, only content alignment changes; the box origin stays fixed.
      Parameters:
      alignment - LEFT, CENTER or RIGHT
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if alignment is null or JUSTIFY

    • headerWidthMm

      public LetterBuilder headerWidthMm(double width)
      Replaces the header box width in millimeters. Automatic placement follows the selected alignment; an exact box is resized without moving its origin. Available width beside the final logo is checked when built. Without an explicit width, automatic headers fill the available space.
      Parameters:
      width - finite positive header width in mm
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if width is nonpositive or nonfinite

    • headerBoundsMm

      public LetterBuilder headerBoundsMm(double x, double y, double width, double height)
      Replaces automatic placement with an exact header box measured from the inner page upper-left corner. Add left/top margins to obtain paper-edge coordinates. The box bottom reserves body space followed by a 5 mm gap. Later width/height calls retain this origin; page fit is checked when built.
      Parameters:
      x - finite nonnegative horizontal offset from the left margin, in mm
      y - finite nonnegative vertical offset from the top margin, in mm
      width - finite positive box width in mm
      height - finite positive box height in mm
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if offsets are negative/nonfinite or dimensions are nonpositive/nonfinite

    • footerStyle

      public LetterBuilder footerStyle(Style value)
      Replaces footer overrides on top of the default 9 pt gray text and zero before/after spacing. Explicit block styles can override the inherited fields.
      Parameters:
      value - non-null footer style overrides
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if value is null

    • headerHeightMm

      public LetterBuilder headerHeightMm(double value)
      Replaces the header content-box height, initially 25 mm. An exact box keeps its origin. Automatic layout also accommodates a taller logo. Images passed directly as bytes have an initial fit at registration time and are refitted to the final box when built.
      Parameters:
      value - finite positive height in mm
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the value is nonpositive or nonfinite

    • footerHeightMm

      public LetterBuilder footerHeightMm(double value)
      Replaces footer content-box height, initially 15 mm. A nonempty footer reserves this height plus a 5 mm gap from the body. Footer content is resolved against this final height.
      Parameters:
      value - finite positive height in mm
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the value is nonpositive or nonfinite

    • logo

      public LetterBuilder logo(byte[] image)
      Replaces the logo by immediately decoding copied PNG/JPEG/static SVG bytes and fitting their aspect ratio into a 45 by 20 mm box. The logo repeats on every page; the header is placed beside it. A logo wider than the final inner page width is refitted at build time.
      Parameters:
      image - non-null readable PNG, JPEG or static SVG bytes
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if bytes are null, unreadable or not PNG/JPEG/static SVG

    • logo

      public LetterBuilder logo(Path image) throws IOException
      Reads and replaces the logo immediately, fitting it into a 45 by 20 mm box with its aspect ratio preserved.
      Parameters:
      image - non-null path to a PNG, JPEG or static SVG file
      Returns:
      this builder
      Throws:
      IOException - if the file cannot be read
      NullPointerException - if image is null
      IllegalArgumentException - if the file is not a readable PNG, JPEG or static SVG image

    • signature

      public LetterBuilder signature(SignatureContent... parts)
      Replaces signature content with the supplied immutable parts stacked in argument order. Text and image parts may be combined. Placement and reserved height are configured separately; the default placement follows the body.
      Parameters:
      parts - non-null, nonempty array of non-null signature parts
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the array is null or empty, or a part is null

    • signaturePlacement

      public LetterBuilder signaturePlacement(SignaturePlacement value)
      Replaces signature placement. SignaturePlacement.FLOW follows the body and is the default; SignaturePlacement.BOTTOM_LAST anchors above the footer on the final page using the configured signature height.
      Parameters:
      value - non-null placement policy
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if value is null

    • signatureHeightMm

      public LetterBuilder signatureHeightMm(double value)
      Replaces the signature height, initially 20 mm. When content exists and SignaturePlacement.BOTTOM_LAST is selected, this reserves the final-page signature box. FLOW reserves no signature zone.

      Signature HTML uses this height for default and percentage-based image sizes. Explicit signature parts and typed blocks retain their own dimensions; resize an image part with ImageSignature.sizeMm(double, double).

      Parameters:
      value - finite positive height in mm
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the value is nonpositive or nonfinite

    • watermark

      public LetterBuilder watermark(String text)
      Replaces the watermark with the default text-watermark configuration. Watermarks are applied during PDF generation; text validity is checked there.
      Parameters:
      text - text for TextWatermark.of(String)
      Returns:
      this builder

    • watermark

      public LetterBuilder watermark(Watermark value)
      Replaces the watermark configuration for PDF post-processing. Content, opacity and geometry are validated when generating the PDF.
      Parameters:
      value - non-null text or image watermark
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if value is null

    • fixedElement

      public LetterBuilder fixedElement(FixedElement element)
      Appends an advanced fixed element using the configured header/footer zones. Its page selector and bounds are preserved; collision and zone-fit checks occur during generation. Configure suitable region heights for the supplied geometry.
      Parameters:
      element - non-null fixed element
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if element is null

    • asset

      public LetterBuilder 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 LetterBuilder 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

    • bodyHtml

      public LetterBuilder bodyHtml(String markup)
      Appends body content as a fragment of the supported HTML subset. Parsing and named asset resolution are deferred to build time, using final page/region dimensions. Assets may be registered before or after this call.
      Parameters:
      markup - non-null supported HTML fragment
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if markup is null

    • headerHtml

      public LetterBuilder headerHtml(String markup)
      Replaces header content with a fragment of the supported HTML subset. Parsing and named asset resolution are deferred to build time, using final page/region dimensions. Assets may be registered before or after this call. Page breaks are rejected in this region.
      Parameters:
      markup - non-null supported HTML fragment
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if markup is null

    • headerHtml

      public LetterBuilder headerHtml(PageSelector pages, String markup)
      Replaces header content for one page selection; ALL is fallback for unspecified selections. Geometry and inherited region defaults are shared across variants. Empty text/block content suppresses the fallback on that selection. Paths are read immediately; other inputs retain the corresponding ordinary overload's validation and snapshot rules.
      Parameters:
      pages - non-null page selection
      markup - region content
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if input or page selection is invalid

    • footerHtml

      public LetterBuilder footerHtml(String markup)
      Replaces footer content with a fragment of the supported HTML subset. Parsing and named asset resolution are deferred to build time, using final page/region dimensions. Assets may be registered before or after this call. Page breaks are rejected in this region.
      Parameters:
      markup - non-null supported HTML fragment
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if markup is null

    • footerHtml

      public LetterBuilder footerHtml(PageSelector pages, String markup)
      Replaces footer content for one page selection; ALL is fallback for unspecified selections. Geometry and inherited region defaults are shared across variants. Empty text/block content suppresses the fallback on that selection. Paths are read immediately; other inputs retain the corresponding ordinary overload's validation and snapshot rules.
      Parameters:
      pages - non-null page selection
      markup - region content
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if input or page selection is invalid

    • signatureHtml

      public LetterBuilder signatureHtml(String markup)
      Replaces signature content with a fragment of the supported HTML subset. Parsing and named asset resolution are deferred to build time, using final page/region dimensions. Assets may be registered before or after this call. Page breaks are rejected in this region.
      Parameters:
      markup - non-null supported HTML fragment
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if markup is null

    • headerBlocks

      public LetterBuilder headerBlocks(Block... blocks)
      Replaces header content with an ordered snapshot of advanced model blocks. An empty array clears the content. The final region defaults are overlaid when built; explicit block style fields take precedence. Region restrictions and layout are validated at build or generation time.
      Parameters:
      blocks - non-null array of non-null blocks
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the array is null
      NullPointerException - if any block is null

    • headerBlocks

      public LetterBuilder headerBlocks(PageSelector pages, Block... blocks)
      Replaces header content for one page selection; ALL is fallback for unspecified selections. Geometry and inherited region defaults are shared across variants. Empty text/block content suppresses the fallback on that selection. Paths are read immediately; other inputs retain the corresponding ordinary overload's validation and snapshot rules.
      Parameters:
      pages - non-null page selection
      blocks - region content
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if input or page selection is invalid

    • footerBlocks

      public LetterBuilder footerBlocks(Block... blocks)
      Replaces footer content with an ordered snapshot of advanced model blocks. An empty array clears the content. The final region defaults are overlaid when built; explicit block style fields take precedence. Region restrictions and layout are validated at build or generation time.
      Parameters:
      blocks - non-null array of non-null blocks
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the array is null
      NullPointerException - if any block is null

    • footerBlocks

      public LetterBuilder footerBlocks(PageSelector pages, Block... blocks)
      Replaces footer content for one page selection; ALL is fallback for unspecified selections. Geometry and inherited region defaults are shared across variants. Empty text/block content suppresses the fallback on that selection. Paths are read immediately; other inputs retain the corresponding ordinary overload's validation and snapshot rules.
      Parameters:
      pages - non-null page selection
      blocks - region content
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if input or page selection is invalid

    • signatureBlocks

      public LetterBuilder signatureBlocks(Block... blocks)
      Replaces signature content with an ordered snapshot of advanced model blocks. An empty array clears the content. The blocks retain their own style settings. Region restrictions and layout are validated at build or generation time.
      Parameters:
      blocks - non-null array of non-null blocks
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the array is null
      NullPointerException - if any block is null

    • header

      public LetterBuilder header(byte[] image)
      Replaces the header with a repeated PNG/JPEG/static SVG image. Bytes are copied and decoded immediately, preserving aspect ratio inside a 160 mm wide box with the current header height (default 25 mm). The image is refitted to final region dimensions when built.
      Parameters:
      image - non-null readable PNG, JPEG or static SVG bytes
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if bytes are null, unreadable or not PNG/JPEG/static SVG

    • header

      public LetterBuilder header(PageSelector pages, byte[] image)
      Replaces header content for one page selection; ALL is fallback for unspecified selections. Geometry and inherited region defaults are shared across variants. Empty text/block content suppresses the fallback on that selection. Paths are read immediately; other inputs retain the corresponding ordinary overload's validation and snapshot rules.
      Parameters:
      pages - non-null page selection
      image - region content
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if input or page selection is invalid

    • header

      public LetterBuilder header(Path image) throws IOException
      Reads a PNG/JPEG/static SVG file immediately and replaces the header with its fitted image. See header(byte[]) for sizing and final fitting behavior.
      Parameters:
      image - non-null path to the header image
      Returns:
      this builder
      Throws:
      IOException - if the file cannot be read
      NullPointerException - if image is null
      IllegalArgumentException - if the file is not a readable PNG, JPEG or static SVG image

    • header

      public LetterBuilder header(PageSelector pages, Path image) throws IOException
      Replaces header content for one page selection; ALL is fallback for unspecified selections. Geometry and inherited region defaults are shared across variants. Empty text/block content suppresses the fallback on that selection. Paths are read immediately; other inputs retain the corresponding ordinary overload's validation and snapshot rules.
      Parameters:
      pages - non-null page selection
      image - region content
      Returns:
      this builder
      Throws:
      IOException - if image bytes cannot be read

    • footer

      public LetterBuilder footer(byte[] image)
      Replaces the footer with a repeated PNG/JPEG/static SVG image. Bytes are copied and decoded immediately, preserving aspect ratio inside a 160 mm wide box with the current footer height (default 15 mm). The image is refitted to final region dimensions when built.
      Parameters:
      image - non-null readable PNG, JPEG or static SVG bytes
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if bytes are null, unreadable or not PNG/JPEG/static SVG

    • footer

      public LetterBuilder footer(PageSelector pages, byte[] image)
      Replaces footer content for one page selection; ALL is fallback for unspecified selections. Geometry and inherited region defaults are shared across variants. Empty text/block content suppresses the fallback on that selection. Paths are read immediately; other inputs retain the corresponding ordinary overload's validation and snapshot rules.
      Parameters:
      pages - non-null page selection
      image - region content
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if input or page selection is invalid

    • footer

      public LetterBuilder footer(Path image) throws IOException
      Reads a PNG/JPEG/static SVG file immediately and replaces the footer with its fitted image. See footer(byte[]) for sizing and final fitting behavior.
      Parameters:
      image - non-null path to the footer image
      Returns:
      this builder
      Throws:
      IOException - if the file cannot be read
      NullPointerException - if image is null
      IllegalArgumentException - if the file is not a readable PNG, JPEG or static SVG image

    • footer

      public LetterBuilder footer(PageSelector pages, Path image) throws IOException
      Replaces footer content for one page selection; ALL is fallback for unspecified selections. Geometry and inherited region defaults are shared across variants. Empty text/block content suppresses the fallback on that selection. Paths are read immediately; other inputs retain the corresponding ordinary overload's validation and snapshot rules.
      Parameters:
      pages - non-null page selection
      image - region content
      Returns:
      this builder
      Throws:
      IOException - if image bytes cannot be read

    • logo

      public LetterBuilder logo(ImageBlock image)
      Replaces the logo with an advanced image block retaining its supplied dimensions. If wider than the final inner page, its bytes are refitted during building. Detailed image and style validation is performed during PDF generation.
      Parameters:
      image - non-null image block
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if image is null

    • build

      public LetterDocument build()
      Resolves deferred HTML, assets, images and region geometry into an immutable snapshot. Body blocks remain in append order, and header/logo/footer space is reserved before creating the page specification. This does not render a PDF or validate every advanced model constraint: pass the result to LetterPdfGenerator. Later builder changes do not modify the returned document.
      Returns:
      a new independent immutable document
      Throws:
      IllegalStateException - if no body content was supplied or resolved
      IllegalArgumentException - if page/region geometry is invalid
      InvalidLetterException - if deferred markup or a referenced image asset is invalid