I've noticed a recurring habit when developers first encounter text blocks: they treat them like simple "multiline strings" from languages like Python or JavaScript. The most common misconception I see is the belief that every single space and tab you type inside those triple quotes is preserved exactly as it appears relative to the left margin of your IDE.

If you think that way, you'll likely end up with one of two problems: either your strings are full of ugly leading tabs that break your JSON or SQL parsing, or you'll start writing your Java code with the closing triple quotes pushed all the way to the far left margin, ruining the indentation of your entire method just to "keep the string clean."

The Myth of Absolute Indentation vs. Incidental Whitespace

Let's look at why that "absolute" thinking is wrong. In Java, text blocks use a concept called incidental whitespace. Java doesn't just take everything between the quotes; it looks at the indentation of all the lines (including the closing delimiter) and strips out the common minimum indentation.

public void printJson() {
    // This looks like it has 8 spaces of indentation per line
    String json = """
                  {
                    "id": 101,
                    "status": "ACTIVE",
                    "message": "Success"
                  }
                  """;
    System.out.println(json);
}

If Java worked the way many beginners assume, the output would have a massive gap of whitespace on the left. But it doesn't. Java sees that every line in that block starts with at least 18 spaces (in this example). It treats those 18 spaces as "incidental"—meaning they are only there to make the code look nice in your editor—and strips them away. The result is a perfectly left-aligned JSON string.

Controlling the Baseline with the Closing Quote

Here is the part that usually trips people up: the position of the closing """ actually tells Java where the "baseline" of the string is. I like to think of the closing quotes as the anchor.

If you move the closing quotes to the left, you are telling Java, "The baseline is actually further left than the content." This is how you intentionally add indentation to the resulting string without having to manually type \t or   everywhere.

// The closing quotes are further left than the content.
// This means the relative indentation of the content is PRESERVED.
String indentedSql = """
        SELECT * FROM users
        WHERE status = 'ACTIVE'
        ORDER BY created_at DESC
    """; 
    // The resulting string will actually start with several spaces 
    // because the closing quotes established a baseline further left.

I personally always keep my closing quotes aligned with the content unless I specifically need the output string to be indented. It makes the code much easier to read at a glance.

Breaking Lines Without Adding Newlines

Sometimes you have a very long string—like a complex Regex or a long URL—and you want to break it across multiple lines in your editor so you don't have to scroll horizontally, but you don't want an actual newline character in the final string. This is where the backslash \ comes in.

String longQuery = """
    SELECT u.name, u.email, u.last_login \
    FROM users u \
    JOIN accounts a ON u.account_id = a.id \
    WHERE a.status = 'VERIFIED' \
    """;
    // This results in one single long line of text, despite being 5 lines in the IDE.

Without that trailing backslash, Java would insert a \n at the end of every line. Use it sparingly; if you find yourself using it on every line, you might just be fighting the tool instead of using it.

📋 Practical Task

Refactoring the API Error Payload

You are working on a legacy module where a developer used standard string concatenation to build a JSON error response. It's a nightmare to maintain and prone to typos with the escaped quotes. Your task is to refactor this into a clean Java Text Block.

Requirements:

• Replace the concatenated string with a Text Block (""").
• Ensure the resulting string is left-aligned (no leading whitespace in the final output).
• The JSON must maintain its internal structure (the keys "error" and "details" should be indented relative to the curly braces).
• Use a \ line-continuation character for the "details" message so that the long description stays on one line in the final string, even if you break it across two lines in your editor for readability.

// REFACTOR THIS:
String errorJson = "{\n" +
                   "  \"error\": \"Invalid Request\",\n" +
                   "  \"details\": \"The provided user ID was not found in the system \n" +
                   "and the request timestamp has expired.\"\n" +
                   "}";