Issue analysis and design document for the feature request to pretty-print xml validation errors encountered when processing standalone/domain/host.xml documents.

Overview

Toby Crawley has created a library that uses xsd analysis to produce more informative error messages when xml parsing errors occur. His goals were to:

• Give users clear feedback that can be used to correct the configuration error without the user having to context-switch to documentation, and, in most cases, enable the user to quickly identify and understand the issue before looking away from the validation output, by:
  • Showing (instead of telling) where in the XML the error occurred
  • Providing richer feedback than the native validation error provides (detect potential misspellings, provide alternate locations, etc)
  • Showing documentation for the element/attribute where possible (pulled from the XSD)
• Use what we already produce (XSDs), without having to create additional context-specific schema. Ideally, a project would be able to integrate this tool with very little effort.

Toby has proposed including this library in WildFly for use in server and host controller configuration document parsing. See [wildfly-dev] Pretty-printing XML validation errors for the discussion of this proposal.

Issue Metadata

EAP ISSUE: https://issues.jboss.org/browse/EAP7-599

RELATED ISSUES: [WFCORE-1728] Pretty-printing XML validation errors - JBoss Issue Tracker

DEV CONTACTS: Toby Crawley (primary), Brian Stansberry (secondary)

QE CONTACTS:

AFFECTED PROJECTS OR COMPONENTS: WildFly Core kernel, WildFly

OTHER INTERESTED PARTIES: N/A

Requirements

Hard Requirements

• Integrate the VDX library into WildFly Core.
• Update WildFly Core's xml parsing utility methods used for producing basic error messages when parsing standalone.xml, host.xml and domain.xml documents to produce an exception with more context about the type and location of the failure. These utility methods are used for basic things like invalid attribute and element names and missing required attributes and elements.
• Update WildFly Core's basic xml parsing method to catch XMLStreamExceptions and pass them to VDX allowing it to output a pretty error message.
• VDX must use the ASL license or some other license compatible with ASL. Inclusion of ASL must not interfere with the ability to relicense WildFly Core from LGPL to ASL.
• VDX integration must not increase the WildFly Core dist size by more than 100k. This includes any dependencies VDX brings in that are not otherwise needed.
  
• VDX must support internationalization of its output and must work with the Red Hat translation team to integrate with the Zanata tool and allow localization of its text.
• VDX must produce an Andiamo-compliant message code (e.g. VDX000001) for its messages.
  • In a pretty-printed error message, only the initial text needs the message code. The individual details parts of the message do not need individual message codes.
• If WildFly throws an exception with a message code and that exception is caught and handled by VDX, the original message with the WildFly message code must appear at some place in the output.
• Problems producing the pretty VDX output must not interfere with the function of the server or negatively impact the user experience. Specifically:
  • VDX processing cannot result in a runtime exception being thrown.
  • VDX or its integration cannot output any WARN level or above error message related to its failure to process unless the original exception that would have been logged has already been logged. In practice this likely means VDX problems must be logged at INFO or below. The point here is the meaningful-to-the-user problem is the original one not the VDX one, so it must come first.

Nice-to-Have Requirements

Currently none

Non-Requirements

• Use of VDX for other document parsing besides standalone/domain/host.xml. (This non-requirement doesn't rule out other RFEs to do that; it's just not in scope for this one.)
• Improvements to kernel and subsystem parsers to better take advantage of VDX. The VDX integration discussed in the Hard Requirements section should result in better output for a large number of problems, but getting this better output for all possible problems is not a requirement, and failure to get it for some problem will not be considered to be a bug. Possible parser improvements that are not required include but are not limited to:
  • Use of WildFly Core's ParseUtils class for creating exceptions. This is the class that contains the utility methods discussed in the Hard Requirements section.
  • Doing validation in an xml parser that is currently deferred to the handling of the management operation that the parser generates. Management operation handling does validation, in order to ensure post-boot changes made by management clients are valid. Since parsers produce management ops that will undergo this validation, doing validation in the parser as well is redundant. It's nice to do as it produces a more helpful error message, even without VDX. But the introduction of VDX does not mean that increased validation at the parser level is required.
  • Note that the above doesn't mean that parser improvements are forbidden. It just means they don't suddenly get increased priority compared to what they would receive if VDX were not present.
• Involvement of VDX in reporting failures that occur outside of normal xml parsing during initial boot and reload. For example, if a user uses the CLI to make a config change and that operation fails due to an invalid setting, there is no requirement to somehow figure out how that config change would have been reflected in xml and then provide an xml-oriented failure message.

Design Notes

• Update the utility exception generation methods in org.jboss.as.controller.parsing.ParseUtils to generate exceptions (subclassed from XMLStreamException) that capture more context about the failure. This is the more "tailored" way to convey a failure to VDX as the exception generation methods have some sort of contextual knowledge they can provide to VDX.
• Update XmlConfigurationPersister to catch XMLStreamExceptions and hand them off to VDX. This handles the extra-context exceptions from ParseUtils, along with parsing errors that don't pass through ParseUtils.