XML

Quick reference

Handling forbidden characters in XML (Java tips)

By nithidol.v

Est. read: 3 minutes

XML files require certain characters to be escaped. Use the correct entity replacements to avoid parser errors (like JsonMappingException or unexpected character errors).

1

Why it matters

Unescaped characters such as & or < will break XML parsers and serialization libraries.
2

Quick fix

Replace forbidden characters with their XML entity equivalents before serialization or when generating XML output.

Common forbidden characters → entities

< (Less than)

> (Greater than)

& (Ampersand)

" (Double quote)

' (Single quote)

Example: unescaped data (will cause errors)

<?xml version="1.0" encoding="UTF-8"?>
<Persons>
    <Person>
        <firstName>Ja&ne</firstName>
        <lastName>Doe</lastName>
    </Person>
</Persons>

Typical error:

com.fasterxml.jackson.databind.JsonMappingException: Unexpected character '<' (code 60); expected a semi-colon after the reference for entity 'ne'

Correct: characters transformed to entities

<?xml version="1.0" encoding="UTF-8"?>
<Persons>
    <Person>
        <firstName>Jane&lt;&apos;&quot;&amp;&gt;</firstName>
        <lastName>Doe</lastName>
    </Person>
</Persons>

Result: XML parses and maps to Java objects successfully.

Java helper: Apache Commons

Use StringEscapeUtils to escape XML 1.0 entities:

String escapedXml = StringEscapeUtils.escapeXml10(input);

JAXB example: unmarshalling

Basic flow to read XML into a Java object

// Create JAXB context for the Person class
JAXBContext context = JAXBContext.newInstance(Person.class);
Unmarshaller unmarshaller = context.createUnmarshaller();
File xmlFile = new File("person.xml");
Person person = (Person) unmarshaller.unmarshal(xmlFile);

Best practices

Always escape user input before embedding into XML content.
Prefer library-based escaping (e.g., Apache Commons) over manual string replace.
Validate XML after generation to catch entity mistakes early.
When serializing, ensure your serializer understands XML entities (JAXB, Jackson with XML module).

Quick checklist

Escape <, >, &, " and '
Test XML parsing in your CI pipeline
Log errors with context (field, raw value)