.JAVA File Format – Lexical structure

Documentation comments

The javadoc tool reads a documentation comment placed directly before a module, package, class, field, constructor or method declaration. The language gives them no meaning. The first sentence is the summary; block tags follow the main description, and inline tags may appear anywhere in braces.

/**
 * Returns the larger of two values.
 *
 * @param a the first value
 * @param b the second value
 * @return {@code a} if it is not smaller than {@code b}, otherwise {@code b}
 * @see Math#max(int, int)
 */
static int larger(int a, int b) { return a >= b ? a : b; }

/// Returns the larger of two values.
///
/// @param a the first value
/// @param b the second value
/// @return `a` if it is not smaller than `b`, otherwise `b`
static int larger2(int a, int b) { return Math.max(a, b); }

Contextual keywords

Seventeen more words are keywords only in certain places and are ordinary identifiers everywhere else, so old code that uses them as names still compiles:

non-sealed is the only keyword with a hyphen. Written with spaces, non - sealed, it is a subtraction.

Integer literals

IntegerLiteral:  DecimalIntegerLiteral | HexIntegerLiteral | OctalIntegerLiteral | BinaryIntegerLiteral
DecimalNumeral:  0 | NonZeroDigit [Digits] | NonZeroDigit Underscores Digits
HexNumeral:      0 x HexDigits | 0 X HexDigits
OctalNumeral:    0 OctalDigits | 0 Underscores OctalDigits
BinaryNumeral:   0 b BinaryDigits | 0 B BinaryDigits
IntegerTypeSuffix:  l | L

• Underscores (Java 7) may go between digits, any number of them, but not at the start or end of the digits, next to the 0x or 0b prefix, or next to a suffix: 1_000 and 0x7fff_ffff are valid, _1000, 1000_ and 0x_FF are not. 0_7 is a valid octal literal.
• A literal with L or l is a long; use L, since l looks like 1. There is no suffix for byte or short; an int constant is narrowed when assigned to them (see Conversions).
• A leading 0 makes the literal octal: 010 is 8, and 09 is an error.
• The largest decimal int literal is 2147483647. 2147483648 (2³¹) is allowed only as the operand of unary minus, to write -2147483648. The same holds for long and 9223372036854775808L.
• Hexadecimal, octal and binary literals may set the sign bit: 0xFFFF_FFFF is the int −1 and 0x8000_0000 is −2147483648. A literal that does not fit 32 bits (or 64 with L) is an error.

Floating-point literals

DecimalFloatingPointLiteral:
    Digits . [Digits] [ExponentPart] [FloatTypeSuffix]
    . Digits [ExponentPart] [FloatTypeSuffix]
    Digits ExponentPart [FloatTypeSuffix]
    Digits [ExponentPart] FloatTypeSuffix
ExponentPart:        e [+|-] Digits  |  E [+|-] Digits
HexadecimalFloatingPointLiteral:
    HexSignificand BinaryExponent [FloatTypeSuffix]
BinaryExponent:      p [+|-] Digits  |  P [+|-] Digits
FloatTypeSuffix:     f | F | d | D

• Without a suffix, or with d or D, the literal is a double; with f or F it is a float. 1f and 1d are floating-point literals even without a point.
• The value is the nearest representable value (IEEE 754 round to nearest).
• A literal too large for its type, such as 1e39f, is a compile-time error, as is a non-zero literal that rounds to zero, such as 1e-50f. There are no literals for infinity or NaN; use Double.POSITIVE_INFINITY and Double.NaN.
• Hexadecimal floating-point literals (Java 5) give exact binary values: the significand is hexadecimal and the exponent, after p, is a decimal power of two, which is required. 0x1.8p1 is 1.5 × 2 = 3.0, and 0x1p-1074 is Double.MIN_VALUE.
• Underscores may go between digits, as in integer literals: 3.141_592_653.

Character literals

A character literal is one character or one escape sequence in single quotes. It holds one UTF-16 code unit, so a character outside the Basic Multilingual Plane cannot be written as a char literal; use a string or an int code point. A line terminator cannot appear inside, and neither can ' or \ unescaped. Note that ''' is an error: the escape becomes ' before the literal is read, leaving '''. Write '\''.

String literals

A string literal is zero or more characters or escape sequences in double quotes, all on one line. It is a reference to an instance of String. String literals, and all constant expressions of type String, are interned: equal literals anywhere in the program, even in different classes and packages, refer to the same object, so "a" + "b" == "ab" is true. Strings computed at run time are new objects unless intern() is called; compare strings with equals.

Text blocks

A text block (Java 15) is a multi-line string literal. It opens with """, then optional spaces, tabs or form feeds, then a line terminator; the content starts on the next line and ends at the closing """ (JLS 3.10.6).

TextBlock:
    " " " {TextBlockWhiteSpace} LineTerminator {TextBlockCharacter} " " "

String html = """
        <html>
            <body>
                <p>Hello, "world"</p>
            </body>
        </html>
        """;
// "<html>\n    <body>\n        <p>Hello, \"world\"</p>\n    </body>\n</html>\n"

The compiler turns the content into a string in three steps:

1. Line terminators are all changed to LF (\u000a).
2. Incidental white space is removed, as by String.stripIndent. The compiler finds the smallest count of leading white space over the non-blank lines and the line of the closing delimiter (if it stands alone on its line), and removes that many characters from the start of each non-blank line. Trailing white space is removed from every line, and blank lines become empty. Spaces and tabs each count as one character, so mixing them gives surprising results.
3. Escape sequences are interpreted. Because this comes last, an escape can produce characters that the stripping would otherwise remove.

• If the closing """ is on its own line, the string ends with a line feed; if it follows the last text on the same line, it does not.
• Double quotes need no escape unless three appear together: write \""" or ""\".
• \s is a single space that survives stripping, useful to keep trailing spaces: red\s.
• A backslash at the end of a line (\ then the line terminator) joins the line to the next without a line feed. It is allowed only in text blocks.
• The content cannot start on the opening line: """abc""" is an error.

Escape sequences

Character literals, string literals and text blocks share these escapes (JLS 3.10.7). They are interpreted after Unicode escapes, and any other character after a backslash is a compile-time error.

There is no \a, \v, \e or \x escape; use a Unicode escape, such as \u001b for escape.