Re: [RT] validation grammar inside components

[Stefano Mazzocchi]

Christian Haul wrote:

Currently, we have the sitemap validation schema (relax ng
http://www.oasis-open.org/committees/relax-ng ) in a single file. This
schema gets only updated when a new sample violates the schema.
It is easy to forget updating the schema file and when attempting it,
it does take some time to understand it. Even if relax ng syntax is
quite simple.

NOTE: the sitemap validation is broken *right now*.

We could try to move the specialized grammars out of this single file
and move it into the java sources and extract this data in an ant
target and merge the grammars. This would improve accuracy of the
schema and would help to document available options for the
components. Especially, if we manage to transform the grammars to some
human readable format.

For this we need to define some elment classes and combine them with
the "choice" option. Example:

/**

<grammar>

<define name="input.module.config.contents" combine="choice">
<doc:annotation>
This pattern is valid for configuring this input module.
</doc:annoation>
<optional>
<element name="reloadable">
<doc:option>
<doc:descr>Should files be reloaded when changed?</doc:descr>
<doc:default>true</doc:default>
</doc:option>
<data type="boolean"/>
</element>
</optional>
<optional>
<element name="cachable">
<doc:option>
<doc:descr>Are files cachable?</doc:descr>
<doc:default>true</doc:default>
</doc:option>
<data type="boolean"/>
</element>
</optional>
<optional>
<ref name="org.apache.cocoon.components.modules.input.XMLFileModule:file">
</optional>
</define>

<define name="input.module.runtime.contents" combine="choice">
<doc:annotation>
This pattern is valid for run time configuring this input
module, e.g. inside another component's configuration.
</doc:annoation>
<optional>
<ref name="org.apache.cocoon.components.modules.input.XMLFileModule:file">
</optional>
</define>


<define name="input.module.parameters" combine="choice">
<doc:annotation>
This pattern is valid for passing sitemap parameters to the
component using the map:parameter syntax. </doc:annotation>
<empty/>
</define>


<define name="org.apache.cocoon.components.modules.input.XMLFileModule:file">
<element name="file">
<doc:option>
<doc:descr>File to run query against.</doc:descr>
</doc:option>
<attribute name="src">
<doc:option>
<doc:descr>File URI, could include e.g. cocoon: protocol.</doc:descr>
</doc:option>
<data type="anyURI"/>
</attribute>
<optional>
<attribute name="reloadable">
<doc:option>
<doc:descr>Is file cachable?</doc:descr>
<doc:default>Depends on configuration setting.</doc:default>
</doc:option>
<data type="boolean"/>
</attribute>
</optional>
<optional>
<attribute name="cachable">
<doc:option>
<doc:descr>Shall changed file be reloaded?</doc:descr>
<doc:default>Depends on configuration setting.</doc:default>
</doc:option>
<data type="boolean"/>
</attribute>
</optional>
</element>
</define>

</grammar>
* This module reads an XML file from any source available to the
* system, parses it and returns a Document. Parts can be accessed
* using XPath syntax. Sources can be held in memory for better
* perfomance and reloaded if changed.
*
* <p> Caching and reloading can be turned on / off (default: on)
* through <code>&lt;reloadable&gt;false&lt;/reloadable&gt;</code> and
* <code>&lt;cachable&gt;false&lt;/cachable&gt;</code>. The file
* (source) to use is specified through <code>&lt;file
* src="protocol:path/to/file.xml" reloadable="true"
* cachable="true"/&gt;</code> optionally overriding defaults for
* caching and or reloading.</p>
*
* @author <a href="mailto:[EMAIL PROTECTED]";>Jeff Turner</a>
* @author <a href="mailto:[EMAIL PROTECTED]";>Christian Haul</a>
* @version $Id: XMLFileModule.java,v 1.8 2003/01/31 22:51:28 pier Exp $
*
*/
public class XMLFileModule extends AbstractJXPathModule
implements Composable, ThreadSafe {
...

This would require us to create pattern names for all places where
components could have configuration data and those pattern names would
be re-used. Relax ng allows to "combine" those grammars to one. And of
course an common namespace and syntax for the annotations.

This would require a) some smart documentation tool that renders the
above e.g. to a table, b) an ant task that extracts these grammars and
c) an ant task that merges all these grammars to one file.

c) could possibly done using the XConfToolTask. b) could be done with
a simple awk script like awk '/<grammar>/,/<\/grammar>/{print $0}' in out
but that wouldn't be the java way I guess :-)

Thoughts?

I like the approach and I would suggest creating a new comment that doesn't conflict with javadoc.

What about

// -> single line comment (no machine-readable semantic meaning)

/* ... */ -> multiline comment (no machine-readable semantic meaning)

/** ... */ -> multiline javadoc (automatic documentation generation)

/*<?relaxng?> ... */
/*<?dtd?> ... */
/*<?xmlschema?> ... */ -> multiline schemas (configuration files validation)

This has the advantage of being considered a normal comment by editors and by javadoc.

Note that in the future Avalon 5 is going to include XDoclet-like metadata and there is also a new JSR about adding user-definable metadata to java classes at bytecode-level, so this path of semantically meaningful comments will be used more and more in the future.

If you think about it, we are, in fact, adding more 'namespaces' to java comments with a nice fallback capability.

what do you think?

--
Stefano Mazzocchi <[EMAIL PROTECTED]>
Pluralitas non est ponenda sine neccesitate [William of Ockham]
--------------------------------------------------------------------



---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]