[RT] validation grammar inside components

[Christian Haul]

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.

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?

        Chris.
-- 
C h r i s t i a n       H a u l
[EMAIL PROTECTED]
    fingerprint: 99B0 1D9D 7919 644A 4837  7D73 FEF9 6856 335A 9E08

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