Text Blocks in Java — Multi-Line Strings, Incidental Whitespace, Escape Tricks

Text blocks (Java 15, JEP 378) are multi-line string literals delimited by triple quotes ("""). They eliminate the noise of \n and + concatenation when embedding SQL, JSON, HTML, or any multi-line text.

Syntax basics

• Opening """ must be followed by a newline — no text on the same line
• Closing """ on its own line OR at end of last line
• Position of closing """ determines indentation stripping

Incidental whitespace stripping — the crucial rule

• Compiler finds the common minimum leading-whitespace prefix across all lines
• Strips that many leading spaces from each line
• Closing """ indentation participates in the calculation
• Result: text aligns visually with Java code, but has no extra leading indent in the string

Quoting inside

• Single " doesn't need escaping
• Only """ itself needs escaping (rare)

Two unique escapes

`\` — line continuation

• Joins next line without a newline in the result
• Useful for very long URLs or single-line SQL clauses you want wrapped in source

`\s` — literal space, preserves trailing whitespace

• Per-line trailing whitespace is auto-stripped
• \s opts back in: "red \s" keeps the spaces

Standard escapes still work: \n, \t, \\, \u00XX

Result always uses LF (`\n`)

• Regardless of source file line endings
• For Windows endings in output, use formatted or replace explicitly

No string interpolation — use `formatted`

• ${...} is literal in text blocks — no expansion
• String templates JEP was withdrawn (design concerns)
• Use `String.formatted(args...)` (Java 15) — fluent inline alternative to String.format
• Same format spec; reads naturally chained off the text block
• For complex templating, use Mustache/FreeMarker/Pebble — not text blocks + concat

Companion String methods (Java 11–15)

• isBlank() — empty or whitespace-only
• strip(), stripLeading(), stripTrailing() — Unicode-aware trim
• repeat(n) — repeat the string n times
• lines() — stream of lines
• indent(n) — add/remove leading spaces
• stripIndent(), translateEscapes() — lower-level for runtime text-block processing
• formatted(args) — fluent format

Best uses

• SQL queries (especially @Query annotations in Spring Data)
• JSON / XML / GraphQL test fixtures
• HTML snippets in templates
• Multi-line error messages
• Embedded scripts (Bash, JavaScript) in code

Don't use for

• Single-line strings — use regular literals
• User-facing UI text — use ResourceBundle or i18n libraries
• Anything where dedicated templating libraries fit better

Common gotchas

1. Text on opening line — compile error

• """ hello """ — doesn't compile

2. Trailing whitespace silently stripped

• 'hello \n' becomes 'hello\n'
• Use \s if you need them preserved

3. Indentation drift after IDE reformatting

• Review autoformatter changes
• Use // @formatter:off if necessary

4. Line endings always LF

• For Windows line endings in output, replace or format explicitly

5. No interpolation

• Use .formatted(args) for value injection

Performance

• Compile-time concatenation — same bytecode as old + joins
• formatted mild overhead vs raw concat — usually negligible

Recommendation: Use text blocks as your default for any multi-line string — SQL queries, JSON payloads, HTML snippets, GraphQL queries, multi-line error messages. The most common real-world use is `@Query` annotations in Spring Data and JSON test fixtures. Place the closing `"""` at the same indentation as your surrounding Java (usually 8 spaces in for a method body) — this controls the strip and gives you visual alignment with code without leading indent in the string. Remember: trailing whitespace per line is auto-stripped — use `\s` if you need it preserved (rare). Use `\` for line continuation when a long logical line needs source-level wrapping. For value injection, use `String.formatted(args...)` (Java 15) — it's a fluent alternative to String.format that chains naturally off the text block. Java does NOT have string interpolation — the templates JEP was withdrawn over safety/design concerns; don't expect ${name} to work. Pair text blocks with the String API additions (isBlank, strip, lines, repeat, indent) for complete multi-line text handling. The mental model: text blocks are like Heredoc in Bash or triple-quoted strings in Python — same idea, with Java's incidental-whitespace twist for clean alignment with surrounding code.