cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: [RT] validation grammar inside components
Date Mon, 03 Feb 2003 14:13:08 GMT
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:jefft@apache.org">Jeff Turner</a>
>  * @author <a href="mailto:haul@apache.org">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                               <stefano@apache.org>
    Pluralitas non est ponenda sine neccesitate [William of Ockham]
--------------------------------------------------------------------



---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message