7:29 p.m.
I've done some work to pretty-print XML validation errors that occur
when parsing (standalone|domain|host).xml, and wanted to get some
feedback on what I have so far to see if:
1) there is interest in seeing this completed
2) the current approach is the best way to integrate with WildFly
3) this same approach could be used to pretty-print issues with other
xml parsed by WildFly (web.xml, jboss-deployment-structure.xml,
etc)
# Background
Inspired by error reporting in the Elm language[1] and improvements in
configuration feedback for Clojure tooling[2], I looked at what it
would take to provide better feedback when parsing XML configuration.
My goals were:
* 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.
I've partially implemented a library (vdx)[3] that, given a validation
error, the source document, and the relevant schemas, generates and
prints a friendly error message. I've also made minimal changes to
WildFly to report validation errors to vdx (see below).
# Examples
Below is some examples of the current startup output from WildFly when
a validation error occurs:
## Detecting a misspelled attribute
13:18:03,798 INFO [org.jboss.modules] (main) JBoss Modules version 1.5.2.Final
13:18:03,949 INFO [org.jboss.msc] (main) JBoss MSC version 1.2.6.Final
13:18:04,010 INFO [org.jboss.as] (MSC service thread 1-6)
WFLYSRV0049: WildFly Core 2.2.0.CR5-SNAPSHOT "Kenny" starting
13:18:04,751 ERROR [org.jboss.as.controller] (Controller Boot Thread)
====================== Validation Error in standalone.xml ======================
28: <extension
module="org.wildfly.extension.request-controller"/>
29: <extension module="org.wildfly.extension.security.manager"/>
30: <extension modue="org.wildfly.extension.undertow"/>
^ 'modue' isn't an allowed attribute for the
'extension' element
31: </extensions>
32: <management>
33: <security-realms>
Did you mean 'module'?
================================================================================
13:18:04,753 ERROR [org.jboss.as.server] (Controller Boot Thread)
WFLYSRV0055: Caught exception during boot:
org.jboss.as.controller.persistence.ConfigurationPersistenceException:
WFLYCTL0085: Failed to parse configuration
at
org.jboss.as.controller.persistence.XmlConfigurationPersister.load(XmlConfigurationPersister.java:175)
at org.jboss.as.server.ServerService.boot(ServerService.java:357)
at
org.jboss.as.controller.AbstractControllerService$1.run(AbstractControllerService.java:299)
at java.lang.Thread.run(Thread.java:745)
13:18:04,754 FATAL [org.jboss.as.server] (Controller Boot Thread)
WFLYSRV0056: Server boot has failed in an unrecoverable manner;
exiting. See previous messages for details.
13:18:04,762 INFO [org.jboss.as] (MSC service thread 1-3)
WFLYSRV0050: WildFly Core 2.2.0.CR5-SNAPSHOT "Kenny" stopped in 4ms
## Detecting a misplaced attribute
...
14:32:23,842 ERROR [org.jboss.as.controller] (Controller Boot Thread)
====================== Validation Error in standalone.xml ======================
89: </console-handler>
90: <periodic-rotating-file-handler name="FILE"
autoflush="true"
91: category="WARN">
^ 'category' isn't an
allowed attribute for the 'periodic-rotating-file-handler' element
92: <formatter>
93: <named-formatter name="PATTERN"/>
94: </formatter>
'category' is allowed on elements: subsystem > logger, subsystem >
logging-profiles > logging-profile > logger
Did you intend to put it on one of those elements?
================================================================================
...
## Detecting a misplaced element
...
10:54:27,359 ERROR [org.jboss.as.controller] (Controller Boot Thread)
====================== Validation Error in standalone.xml ======================
81: </management>
82: <profile>
83: <extension/>
^ 'extension' isn't an allowed element here
84: <subsystem xmlns="urn:jboss:domain:logging:3.0">
85: <console-handler name="CONSOLE">
86: <level name="INFO"/>
'extension' is allowed in elements: domain > extensions, domain >
host-excludes > host-exclude > excluded-extensions, host > extensions,
host > servers > server > extensions, server > extensions
Did you intend to put it in one of those elements?
================================================================================
...
# Changes to WildFly
To support this, I've made some small changes changes to
wildfly-core[4], but anticipate more before this is complete.
The current changes are:
* Modifications to ParseUtils to wrap the XMLStreamExceptions with
an exception that can convey more context to vdx
* Modifications to XmlConfigurationPersistor to:
* catch the wrapped exception
* see if ${jboss.home.dir}/docs/schema/ is available. If so,
pretty-print the error. If not, throw the wrapped exception
(which is the behavior before my changes).
# Current issues
* Only the first validation issue is reported, but this is
unavoidable, since the subsystem parsers throw on the first error
encountered
* This uses xmlschema-walker from Apache XmlSchema[5], which has a
couple of bugs that will need to be fixed and released (or forked)
* Only errors reported by throwing Exceptions returned by ParseUtils
are pretty-printed. Exceptions that come from within STAX reader
aren't yet handled (for example, a misplaced element in the logging
parser causes reader.handleAny() to be called[6], which triggers an
unwrapped exception)
* vdx itself is far from complete[7] - that work is pending the
outcome of this discussion
# Next steps
As I said above, the first question to answer is: is this an
interesting feature that you would like to see completed? If so, I'm
willing to continue working on this, and would be happy to discuss
here or on JIRA/HipChat as appropriate.
[1]: http://elm-lang.org/blog/compilers-as-assistants
[2]: http://rigsomelight.com/2016/05/17/good-configuration-feedback-is-essenti...
[3]: https://github.com/projectodd/vdx
[4]:
https://github.com/tobias/wildfly-core/commit/b4d03897a6ea1b8c786d983da3b...
[5]: https://ws.apache.org/xmlschema/
[6]:
https://github.com/wildfly/wildfly-core/blob/2.x/logging/src/main/java/or...
[7]: https://github.com/projectodd/vdx/issues