Documenting the GlassFish v3 Schema
Once work had started on GlassFish v3 the decision was made to drop schema validation for the domain.xml configuration file. In previous versions, you could be assured that your xml was valid because we shipped a DTD to enforce that. In v3, however, that is no longer the case. The decision was made because v3 is very different in some fundamental ways. In v3, you can add an arbitrary container to GlassFish and configure it via domain.xml. This dynamic nature of the document structure makes validation difficult at best so the decision was made to drop validation altogether. However, the problem still remains of how to determine what the document should look like.
First things first, you should avoid editing that xml file by hand. You should be able to do everything you need via either the admin GUI console or the asadmin CLI tool. That said, that still doesn’t necessarily help you know what values can go where. The question has come up dozens of times even among the development team. Various teams have updated and migrated their respective sections of the document leaving some confusion about the new schema. (My own work on the grizzly-config updates is probably the biggest offender here). There are, to my knowledge, two different attempts to fix this.
Tim Quinn developed the first publicly available tool. You can find that here. I had my own going on locally as well. I borrowed some ideas from Tim’s approach and came up with this. My version differs from Tim’s in that it runs in container as an asadmin command. This has a few advantages but most importantly is that I think it’s easier to use. The output I generate is also a bit more accessible than Tim’s but then Tim’s was really a rough first cut. I’m not sure he’s done much with it since. I, on the other hand, still get questions about the grizzly-config schema changes so this is near and dear to my heart.
At the moment, it only generates a javadoc-like HTML output. I plan on adding a DTD and XSD option but there are some disconnects between the internal Java API used to configure GlassFish and what a user sees in domain.xml that make this not so trivial. You can find those details here. The HTML generated reflects the currently valid structure of the document and not the content. This structure changes as you add/remove modules such as JRuby support and the like. The files are generated in the config directory (<glassfish>/domains/domain1/index.html for most people).
The color scheme is a work in progress. The main blue is a bit jarring, I think, but I just haven’t had much time to play with such things lately. You can find sample output here. In the detail frame you’ll see that some elements have properties defined. This lists all the documented properties on that attribute. In a perfect world, that list would be exhaustive but that’s not always possible. e.g., Some configuration elements such as JDBC connection pools configure third party libraries and capturing all possible properties there is impossible. Nevertheless, for all internal GlassFish items this list should give you much of what you need. If you find a missing property, don’t hesitate to file an issue with the GlassFish tracker and we’ll try to update our documentation.
If you find an issue with the doc tool itself, please file an issue and I’ll do my best to correct it. This is an unofficial contribution to GlassFish, though, so bugging the GlassFish lists isn’t likely to help much. I hope this tool helps you as you evaluate v3. We really are very excited about this one.
