Package com.nsdev.lettergenerator

Class LetterPdfGenerator

java.lang.Object
com.nsdev.lettergenerator.LetterPdfGenerator
public final class LetterPdfGenerator extends Object
Generates complete PDF letters from immutable Java models or JSON. Instances are safe to share between concurrent callers; each rendering uses its own engine state.

  • Constructor Details

    • LetterPdfGenerator

      public LetterPdfGenerator()
      Uses the PDF engine's built-in fonts; no font files or registration are required.

  • Method Details

    • builder

      public static LetterPdfGenerator.Builder builder()
      Starts mutable generator configuration for application-supplied TrueType fonts. Built-in Helvetica, Times and Courier remain available without registration.
      Returns:
      a new configuration builder; fonts are loaded by its LetterPdfGenerator.Builder.build() method

    • generateJson

      public byte[] generateJson(String json)
      Parses strict schema-version-1 JSON, validates the resulting model, and renders a PDF. Unknown fields, duplicate keys, trailing tokens and incompatible scalar types are rejected. No partial result is returned if any processing step fails.
      Parameters:
      json - non-null JSON document in the library's letter schema
      Returns:
      complete PDF file bytes, including any requested watermark processing
      Throws:
      InvalidLetterException - if the input is null, malformed, or fails document validation; the exception identifies the affected field path
      PdfGenerationException - if composition, layout, or watermark processing fails

    • renderJson

      public RenderResult renderJson(String json)
      Renders strict JSON and returns actual pagination and diagnostic information.
      Parameters:
      json - nonnull shared-model JSON
      Returns:
      accepted PDF and report using the standard output profile

    • renderJson

      public RenderResult renderJson(String json, RenderOptions options)
      Renders strict JSON with the same output choices available to Java and HTML models.
      Parameters:
      json - nonnull shared-model JSON
      options - per-call output choices
      Returns:
      complete accepted PDF and rendering report
      Throws:
      InvalidLetterException - for invalid input or incompatible output choices
      PdfGenerationException - for rejected native layout or PDF processing

    • generate

      public byte[] generate(LetterDocument document)
      Validates an immutable document and renders it using this generator's font snapshot. All requested processing must succeed before PDF bytes are returned. This method can be called concurrently on the same generator.
      Parameters:
      document - non-null document to validate and render
      Returns:
      complete PDF file bytes
      Throws:
      InvalidLetterException - if the document is null or invalid, with its field path
      PdfGenerationException - if composition, layout, or watermark processing fails

    • validate

      public ValidationReport validate(LetterDocument document)
      Validates composition references, declared geometry, fonts and content without running PDF layout. Reports the first semantic model error; template inspection separately aggregates missing variables and asset errors. Success does not guarantee that content fits.
      Parameters:
      document - nullable model to inspect
      Returns:
      immutable input report

    • render

      public RenderResult render(LetterDocument document)
      Renders a validated model and returns its actual pagination and processing diagnostics.
      Parameters:
      document - non-null input
      Returns:
      accepted PDF and rendering report
      Throws:
      InvalidLetterException - for invalid input
      PdfGenerationException - for rejected layout or PDF processing

    • render

      public RenderResult render(LetterDocument document, RenderOptions options)
      Renders with optional authoring overlays. Invalid input and rejected layouts still throw; no partial PDF is returned. Debug geometry describes allocated regions, not glyph bounds.
      Parameters:
      document - non-null input
      options - non-null rendering options
      Returns:
      accepted PDF with actual page count and optional declared geometry
      Throws:
      InvalidLetterException - for invalid input
      IllegalArgumentException - if options is null
      PdfGenerationException - for rejected layout or PDF processing