You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Christian Haul <ha...@dvs1.informatik.tu-darmstadt.de> on 2003/02/03 13:47:54 UTC
[RT] validation grammar inside components
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><reloadable>false</reloadable></code> and
* <code><cachable>false</cachable></code>. The file
* (source) to use is specified through <code><file
* src="protocol:path/to/file.xml" reloadable="true"
* cachable="true"/></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?
Chris.
--
C h r i s t i a n H a u l
haul@informatik.tu-darmstadt.de
fingerprint: 99B0 1D9D 7919 644A 4837 7D73 FEF9 6856 335A 9E08
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] validation grammar inside components
Posted by Christian Haul <ha...@dvs1.informatik.tu-darmstadt.de>.
On 03.Feb.2003 -- 03:13 PM, Stefano Mazzocchi wrote:
> 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*.
Thought to have fixed that this morning. rechecking ....
<snip what="large example"/>
> >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)
Looks good to me.
> This has the advantage of being considered a normal comment by editors
> and by javadoc.
Absolutely. Although javadoc seems to ignore unknown tags. Anyway,
your suggestion is cleaner.
> 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?
I agree completely.
Chris.
--
C h r i s t i a n H a u l
haul@informatik.tu-darmstadt.de
fingerprint: 99B0 1D9D 7919 644A 4837 7D73 FEF9 6856 335A 9E08
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] validation grammar inside components
Posted by Stefano Mazzocchi <st...@apache.org>.
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><reloadable>false</reloadable></code> and
> * <code><cachable>false</cachable></code>. The file
> * (source) to use is specified through <code><file
> * src="protocol:path/to/file.xml" reloadable="true"
> * cachable="true"/></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 <st...@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