Java Implementation

Relevant source files

• docs/contributing/coding_guidelines.md
• java/com/google/dotprompt/helpers/BUILD.bazel
• java/com/google/dotprompt/helpers/package-info.java
• java/com/google/dotprompt/models/BUILD.bazel
• java/com/google/dotprompt/models/package-info.java
• java/com/google/dotprompt/parser/BUILD.bazel
• java/com/google/dotprompt/parser/package-info.java
• java/com/google/dotprompt/resolvers/package-info.java

Purpose and Scope

This document covers the Java implementation of Dotprompt, which provides a Java API for parsing, compiling, and rendering Dotprompt templates. The implementation is organized under the com.google.dotprompt package and follows the same specification-driven architecture as other language implementations.

For the core concepts underlying all implementations, see Core Concepts. For language-specific implementations in other ecosystems, see JavaScript Implementation, Python Implementation, or Go Implementation.

Overview

The Java implementation (v0.1.0) provides a complete Dotprompt runtime with strong typing through sealed interfaces, asynchronous resolution via CompletableFuture, and integration with the Bazel build system. Key characteristics include:

• JSON Processing: Jackson for YAML parsing and JSON Schema manipulation
• Templating: Handlebars.java for template compilation and rendering
• Type Safety: Sealed interfaces and records for the Part hierarchy
• Async Support: CompletableFuture-based resolvers for external resource loading
• Build System: Bazel for compilation, testing, and Maven Central publishing

Sources: java/com/google/dotprompt/parser/package-info.java1-118 java/com/google/dotprompt/helpers/package-info.java1-130 java/com/google/dotprompt/models/package-info.java1-132

Package Structure

The Java implementation is organized into four primary packages under com.google.dotprompt:

Package	Purpose	Key Classes
models	Data structures for prompts, messages, and parts	Prompt, Message, Part, RenderedPrompt
parser	Template parsing and Picoschema conversion	Parser, Picoschema
helpers	Handlebars helper functions	Helpers
resolvers	Interfaces for dynamic resource loading	PartialResolver, SchemaResolver, ToolResolver

Diagram: Java Package Architecture

Sources: java/com/google/dotprompt/parser/BUILD.bazel1-58 java/com/google/dotprompt/helpers/BUILD.bazel1-44 java/com/google/dotprompt/models/BUILD.bazel1-99

Models Package

The models package defines the core data structures using Java records and sealed interfaces for type safety.

Part Hierarchy

The Part sealed interface represents different types of content within a message:

Diagram: Part Type Hierarchy

The sealed interface pattern ensures exhaustive pattern matching and prevents external implementations:

Part Type	Purpose	Key Fields
TextPart	Plain text content	text
MediaPart	Images, audio, video	media (MediaContent)
DataPart	Structured JSON data	data (Map)
ToolRequestPart	Function call requests	toolRequest (ToolArgument)
ToolResponsePart	Function call responses	toolResponse (ToolArgument)
PendingPart	Unresolved content	pending (Map)

Sources: java/com/google/dotprompt/models/BUILD.bazel21-56 java/com/google/dotprompt/models/package-info.java26-50

Message and Prompt Types

The core types for representing prompts and their rendered output:

Diagram: Prompt Processing Types

Sources: java/com/google/dotprompt/models/BUILD.bazel21-56 java/com/google/dotprompt/models/package-info.java72-81

Storage and Reference Types

Types for working with prompt storage systems:

Type	Purpose	Key Fields
PromptRef	Reference to a stored prompt	name, version, variant
PromptData	Raw prompt source from storage	template, config
PartialRef	Reference to a stored partial	name
PartialData	Raw partial template source	template
PromptBundle	Collection of prompts	name, prompts
PaginatedPrompts	Paginated prompt listing	items, nextPageToken
PaginatedPartials	Paginated partial listing	items, nextPageToken

Sources: java/com/google/dotprompt/models/BUILD.bazel36-46 java/com/google/dotprompt/models/package-info.java83-90

Parser Package

The parser package handles document parsing, Picoschema conversion, and message generation from rendered templates.

Parser Class

The Parser class provides the core parsing functionality:

Diagram: Parser Class Methods

The parsing pipeline extracts YAML frontmatter, parses the template body, and converts Picoschema definitions:

1. Extract Frontmatter: Split source on --- delimiter
2. Parse YAML: Convert frontmatter to Map<String, Object> using Jackson
3. Process Picoschema: Convert compact schema notation to JSON Schema
4. Extract Template: Remaining content after frontmatter

Sources: java/com/google/dotprompt/parser/package-info.java26-55 java/com/google/dotprompt/parser/BUILD.bazel19-33

Picoschema Class

The Picoschema class converts compact Picoschema notation to full JSON Schema:

Diagram: Picoschema Conversion Pipeline

The conversion algorithm:

1. Parse Field Notation: Extract field name, type, and modifiers (? for optional, (array) for arrays)
2. Resolve References: Use SchemaResolver to fetch named schemas
3. Build JSON Schema: Construct full JSON Schema with properties and required fields
4. Handle Nesting: Recursively process nested object schemas

Sources: java/com/google/dotprompt/parser/package-info.java70-86 java/com/google/dotprompt/parser/BUILD.bazel48-57

Message Generation

The Parser.toMessages() method converts rendered template strings into structured messages by processing special marker strings:

Marker Pattern	Purpose	Example
<<<dotprompt:role:X>>>	Start new message with role X	<<<dotprompt:role:user>>>
<<<dotprompt:history>>>	Insert conversation history	<<<dotprompt:history>>>
<<<dotprompt:media:url X>>>	Add media part	<<<dotprompt:media:url https://...>>>
<<<dotprompt:section X>>>	Create named section	<<<dotprompt:section intro>>>

Sources: java/com/google/dotprompt/parser/package-info.java88-101

Helpers Package

The helpers package provides custom Handlebars helpers that emit marker strings processed by the parser.

Available Helpers

Diagram: Handlebars Helpers Architecture

Helper Implementations

Each helper is implemented as a com.github.jknack.handlebars.Helper that:

1. Receives Context: Gets template context and parameters
2. Processes Parameters: Extracts and validates helper arguments
3. Emits Markers: Returns marker string for parser processing

Example helper signatures:

• json(Object, Options): Serializes object with optional indent parameter
• role(String, Options): Emits role marker for the specified role
• history(Options): Emits history insertion marker
• section(String, Options): Emits section marker with name
• media(Options): Emits media marker with URL and content type from hash parameters
• ifEquals(Object, Object, Options): Block helper for equality comparison
• unlessEquals(Object, Object, Options): Block helper for inequality comparison

Sources: java/com/google/dotprompt/helpers/package-info.java44-107 java/com/google/dotprompt/helpers/BUILD.bazel19-32

Resolvers Package

The resolvers package defines functional interfaces for asynchronous resource resolution using CompletableFuture.

Resolver Interfaces

Diagram: Resolver Pattern Architecture

Resolver Types

Interface	Method Signature	Purpose
PartialResolver	CompletableFuture<String> resolve(String name)	Load partial templates by name
SchemaResolver	CompletableFuture<Map<String, Object>> resolve(String name)	Load JSON schemas by name
ToolResolver	CompletableFuture<ToolDefinition> resolve(String name)	Load tool definitions by name

All resolvers return CompletableFuture to support:

• Async I/O: Non-blocking database queries, HTTP requests
• Parallel Resolution: Multiple resources can be fetched concurrently
• Error Handling: Exceptions wrapped in failed futures

Sources: java/com/google/dotprompt/resolvers/package-info.java1-113

Build System

The Java implementation uses Bazel for building, testing, and publishing to Maven Central.

Bazel Configuration

Each package has a BUILD.bazel file defining its targets:

Diagram: Bazel Build Graph

Sources: java/com/google/dotprompt/parser/BUILD.bazel1-58 java/com/google/dotprompt/helpers/BUILD.bazel1-44 java/com/google/dotprompt/models/BUILD.bazel1-99

Dependencies

The Java implementation relies on the following external libraries:

Dependency	Purpose	Maven Coordinates
Jackson Databind	JSON parsing and serialization	com.fasterxml.jackson.core:jackson-databind
Jackson YAML	YAML frontmatter parsing	com.fasterxml.jackson.dataformat:jackson-dataformat-yaml
Handlebars.java	Template compilation and rendering	com.github.jknack:handlebars
Guava	Immutable collections and utilities	com.google.guava:guava
Google Truth	Test assertions	com.google.truth:truth
JUnit	Test framework	junit:junit

Sources: java/com/google/dotprompt/parser/BUILD.bazel27-32 java/com/google/dotprompt/helpers/BUILD.bazel26-30 java/com/google/dotprompt/models/BUILD.bazel58-61

Testing Framework

The Java implementation uses JUnit for test execution and Google Truth for assertions. Tests are organized into three categories:

1. Unit Tests: Test individual classes and methods

   • ParserTest: Tests for Parser.parse() and message generation
   • PicoschemaTest: Tests for Picoschema-to-JSON-Schema conversion
   • HelpersTest: Tests for Handlebars helper functions

2. Model Tests: Test data structures and serialization

   • TypeParityTest: Validates type consistency across implementations
   • ModelTest: Tests model construction and validation
   • JsonSerializationTest: Tests Jackson serialization/deserialization

3. Spec Tests: (Referenced but not shown in provided files)

   • Dynamically generated from YAML spec files
   • Validates cross-language behavior parity

Sources: java/com/google/dotprompt/parser/BUILD.bazel35-57 java/com/google/dotprompt/helpers/BUILD.bazel34-43 java/com/google/dotprompt/models/BUILD.bazel64-98

Code Style and Conventions

The Java implementation follows Google Java style guidelines:

Formatting

• Tool: google-java-format for automatic code formatting
• Imports: Always use explicit imports, never fully qualified type names inline
• Line Length: 100 characters (Google Java Style default)

Documentation

• Javadoc: Comprehensive Javadoc for all public classes and methods
• Package Info: Each package has package-info.java with detailed documentation
• Doc Sync: Javadoc comments kept in sync with code changes

Type System

• Records: Immutable data classes using Java records
• Sealed Interfaces: The Part interface is sealed for exhaustive pattern matching
• Jackson Annotations: @JsonProperty, @JsonIgnoreProperties for serialization control

Async Patterns

• CompletableFuture: All resolvers return CompletableFuture for async operations
• Error Handling: Exceptions wrapped in failed futures

Sources: docs/contributing/coding_guidelines.md14-26