Home  >  Core Java

Java Text Blocks

By Arvind Rai, July 23, 2021
On this page we will learn Java text block step-by-step.
1. A text block is a multi-line string literal that avoids the need for escape sequences.
2. A text block can automatically formats the string and gives us the control over the format when desired.
3. The opening and ending delimiter for text block is sequence of three double quote characters (""").
4. Text block was introduced in Java 13 as preview feature and previewed again in Java 14. Text block has been adopted as permanent language feature in Java 15 (JEP 355).
5. A text block is useful to embed a snippet of HTML, XML, SQL, or JSON in a string literal "...". Text block avoids using lots of escapes and concatenation.
6. A text block can contain zero or more characters enclosed by opening and closing delimiters.



1. Using Text Block with HTML, SQL, JSON, XML

1. Find a HTML code snippet as string literal.
String html = "<html>\n" +
              "    <body>\n" +
              "        <div> Welcome to you. </div>\n" +
              "    </body>\n" +
              "</html>\n"; 
The same can be written using text block as following.
String html = """
              <html>
                  <body>
                      <div> Welcome to you. </div>
                  </body>
              </html>
              """; 
2. Text block with SQL code.
String query = """
	SELECT `EMP_ID`, `LAST_NAME` FROM `EMPLOYEE_TB`
	WHERE `CITY` = 'VARANASI'
	ORDER BY `EMP_ID`, `LAST_NAME`;
	"""; 
3. Text block with JSON code.
String json = """
	    {
		  "name": "Mohan",
		  "city": "Varanasi",
		  "country": "India"
	    }
            """; 
4. Text block with XML code.
String xml = """
	<company-info xmlns="com.concretepage" id="10">
          <company-name xmlns="">XYZ</company-name>
          <ceo-name xmlns="">ABC</ceo-name>
          <no-emp xmlns="">50</no-emp>
        </company-info>
	"""; 

2. Text Block Delimiter (""")

A text block delimiter is the sequence of three double quotes (""").
The opening delimiter is the sequence of three double quote characters (""") followed by zero or more white spaces followed by a line terminator. The content starts at the first character after the line terminator of the opening delimiter.
The closing delimiter is a sequence of three double quote characters ("""). The content ends at the last character before the first double quote of the closing delimiter.
Suppose we have a text below.
line 1
line 2
line 3 
We can write the above text using text block (""") as following.
String myText = """
             line 1
             line 2
             line 3
             """; 
We can also write this string literal as following.
String myText = "line 1\nline 2\nline 3\n"; 
Same can be written with a concatenation of string literal.
String myText = "line 1\n" +
               "line 2\n" +
               "line 3\n"; 

Empty string We can write an empty string using text block as following.
String myText = """
"""; 

Ill-formed text blocks
The text block delimiter cannot be used as following.
1.
String myText = """"""; 
This text block is invalid because there is no line terminator after opening delimiter.
2.
String myText = """ """; 
This text block is invalid because there is no line terminator after opening delimiter.
3.
String myText = """
           "; 
This text block is invalid because there is no closing delimiter and the text block will continue to EOF.
4.
String myText = """
           Hello \ World
           """; 
This text block is invalid because there is unescaped backslash.


3. Text Block Compilation Steps

Text block is a constant expression of type String, same as string literal. The content of text block is processed by Java compiler in three distinct steps.
1. Line terminators
Line terminators in the content are translated to LF (\u000A).
2. Incidental white space
Incidental white spaces surrounding the content that are introduced to match the indentation of Java source code are removed.
3. Escape sequences
Escape sequences in the content are interpreted.

3.1 Line Terminators

In the text block compilation, line terminators in the content are normalized from CR (\u000D) and CRLF (\u000D\u000A) to LF (\u000A). This process ensures that string derived from the text block content is equivalent across platforms. The escape sequences \n (LF), \f (FF), and \r (CR) are not interpreted during normalization and escape processing happens later.
Let us understand the advantage of this process. Suppose a Java source code was created on Unix platform and edited on a Windows platform. Line terminator on Unix platform is LF and line terminator on Windows platform is CRLF and hence without normalization the content could become one character longer for each line and any test with String::equals would fail. But normalization of line terminators solves this problem.

3.2 Incidental White Space

In formatting the content, we may give leading and trailing incidental spaces to the content. Text block handles the incidental white spaces. Look into the below text block content.
String html = """
	      <html>
	        <body>
		  <div> Welcome to you. </div>
		</body>
	      </html>
	      """; 
We have shown the incidental white spaces using dots. There are 14 leading white spaces. Trailing white spaces are also possible in copy code from anywhere.
String html = """
..............<html>
..............  <body>...
..............    <div> Welcome to you. </div>
..............  </body>..
..............</html>
.............."""; 
The leading incidental white spaces are considered only up to closing (""") delimiter and they are stripped by text block.
|<html>|
|  <body>|
|    <div> Welcome to you. </div>|
|  </body>|
|</html>| 
Find the print screen of the output.
Java Text Blocks
If the closing (""") delimiter has not incidental white spaces then leading white spaces of text block content will not be stripped.
String html = """
	      <html>
	        <body>
		  <div> Welcome to you. </div>
		</body>
	      </html>
"""; 
Find the print screen of the output, we can see the leading spaces.
Java Text Blocks

3.3 Escape Sequences

After the incidental white spaces re-indentation, escape sequences in the content of text block are interpreted.
a. All the escape sequences supported by string literals are also supported by text block, for example, \n, \t, \', \", and \\ .
b. We can use \n, \f, and \r for vertical formatting of a string without affecting the translation of line terminators.
c. We can use \b and \t for horizontal formatting of a string without affecting the removal of incidental white spaces.
d. Escape sequences are processed only after removing incidental white spaces.

Find the sample example to use \n .
String html = """
	      <html>
		<body>
		  <div>Hello \n World! \n</div>
		</body>
	      </html>
	      """; 
Find the print screen of the output.
Java Text Blocks

a. We can use " and "" freely in text block except immediately before the closing delimiter """ .
String myText = """
		My name is "Ram".    
		""";
System.out.println(myText); 
Output
My name is "Ram". 
b. To use """ in text block, we need to escape at least one " .
String myText = """
                String innerText = \"""
                                  My name is "Ram".    
                                  \""";    
                """; 
Output
String innerText = """
                    My name is "Ram".
                    """; 

New escape sequences
Java has introduced two new escape sequences for text block only.
1. First, \ for line terminator that suppresses the insertion of new line character. Find the code snippet.
String myText = """
		My name is Shiv.\
		I am Java Developer.\
		I live in Varanasi.\
		""";
System.out.println(myText); 
Output
My name is Shiv.I am Java Developer.I live in Varanasi. 
2. Second is \s that translate to a single space.
Example: Suppose we want to keep all lines of text block as fixed characters i.e. 6. Find the code snippet to use \s .
String myText = """
                Ram  \s
                Krishn
                Raju \s 
                """; 
Each line of the above content of text block contains 6 characters. The trailing incidental white spaces are removed only up to \s in text block compilation.

4. References

Programmer's Guide to Text Blocks
JEP 378: Text Blocks
POSTED BY
ARVIND RAI
ARVIND RAI











©2021 concretepage.com | Privacy Policy | Contact Us