Error Handling

DomTrip provides comprehensive error handling with detailed error messages, recovery strategies, and graceful degradation for robust XML processing applications.

Overview

DomTrip's error handling system includes:

• Detailed error messages with context and suggestions
• Exception hierarchy for specific error types
• Recovery strategies for common issues
• Validation errors with precise location information
• Graceful degradation for malformed content

Exception Hierarchy

DomTripException

The base exception for all DomTrip-related errors:

try {
    String malformedXml = "<<invalid xml>>";
    Document doc = Document.of(malformedXml);
} catch (Exception e) {
    System.err.println("DomTrip error: " + e.getMessage());
    System.err.println("Cause: " + e.getCause());
}

Parsing Exceptions

try {
    Document doc = Document.of("<<invalid xml>>");
} catch (Exception e) {
    System.err.println("Parse error: " + e.getMessage());
    // Note: Actual line/column info depends on parser implementation
}

Validation Exceptions

try {
    String xml = createTestXml("root");
    Document doc = Document.of(xml);
    Editor editor = new Editor(doc);
    // This would cause a validation error in strict mode
    // editor.addElement(null, "invalid", "content"); // null parent
} catch (Exception e) {
    System.err.println("Validation error: " + e.getMessage());
}

Common Error Scenarios

Malformed XML

String malformedXml =
        """
    <root>
        <unclosed-tag>
        <another>content</another>
    </root>
    """;

try {
    Document doc = Document.of(malformedXml);
} catch (Exception e) {
    System.err.println("XML syntax error:");
    System.err.println("  Message: " + e.getMessage());

    // Suggested fix
    System.err.println("  Suggestion: Check for unclosed tags");
}

Encoding Issues

try {
    // Simulate file with encoding issues
    String xmlContent = createTestXml("root");
    Document doc = Document.of(xmlContent);

} catch (Exception e) {
    System.err.println("Encoding error: " + e.getMessage());

    // Recovery strategy
    try {
        // Try with explicit encoding (simulated)
        String xmlContent = createTestXml("root");
        Document doc = Document.of(xmlContent);
    } catch (Exception recovery) {
        System.err.println("Recovery failed: " + recovery.getMessage());
    }
}

Namespace Conflicts

try {
    String xml = createTestXml("root");
    Document doc = Document.of(xml);
    Editor editor = new Editor(doc);
    Element root = editor.root();

    // Try to add conflicting namespace (conceptual example)
    root.namespaceDeclaration("ns", "http://example.com/ns1");
    // This would potentially cause a conflict in some scenarios
    root.namespaceDeclaration("ns", "http://example.com/ns2");

} catch (Exception e) {
    System.err.println("Namespace conflict: " + e.getMessage());

    // Resolution strategy
    String alternativePrefix = "ns2";
    // Use alternative prefix
}

Error Recovery Strategies

Graceful Parsing

String xml = "<root><child>content</child></root>";
Document result = parseWithRecovery(xml);

Validation with Fallbacks

String xml = createTestXml("parent");
Document doc = Document.of(xml);
Element parent = doc.root();
safeElementOperation(parent, "child", "content");

Resource Cleanup

String xmlContent = createTestXml("root");
java.io.InputStream inputStream = new java.io.ByteArrayInputStream(xmlContent.getBytes(StandardCharsets.UTF_8));
Document result = parseWithCleanup(inputStream);

Error Prevention

Input Validation

String xml = createTestXml("root");
Document result = safeParse(xml);

Safe Element Access

String xml = createTestXml("parent");
Document doc = Document.of(xml);
Element parent = doc.root();

String text = safeGetElementText(parent, "child");
safeSetAttribute(parent, "attr", "value");

Debugging Support

Error Context

try {
    String xml = createTestXml("root");
    Document document = Document.of(xml);
    Editor editor = new Editor(document);
    // ... complex operations
} catch (Exception e) {
    // Get detailed context (conceptual - actual API may vary)
    String context = e.getMessage();
    System.err.println("Error context: " + context);
}

Validation Mode

// Enable strict validation for debugging (conceptual)
DomTripConfig config = DomTripConfig.defaults();

try {
    String xml = createTestXml("root");
    Document document = Document.of(xml);
    Editor editor = new Editor(document);
    // Operations will provide detailed validation
} catch (Exception e) {
    // Detailed validation errors
    System.err.println("Validation details: " + e.getMessage());
}

Best Practices

✅ Do:

• Always catch specific exception types when possible
• Provide meaningful error messages to users
• Implement graceful degradation for non-critical errors
• Log errors with sufficient context for debugging
• Clean up resources in finally blocks or try-with-resources
• Validate inputs before processing
• Use recovery strategies for common issues

❌ Avoid:

• Catching generic Exception unless necessary
• Ignoring errors silently
• Exposing internal error details to end users
• Continuing processing after critical errors
• Assuming all XML will be well-formed
• Forgetting to close streams and resources

Integration with Logging

// Simulate logging integration
XmlProcessor processor = new XmlProcessor();
String xml = createTestXml("root");
Document result = processor.processXml(xml);

DomTrip's comprehensive error handling ensures that your applications can gracefully handle XML processing issues while providing detailed information for debugging and recovery.