|
Cernunnos_Glossary
Explanation of Cernunnos concepts.
Glossary of Cernunnos TermsThese are the core concepts or "primitives" upon which Cernunnos is built. Reviewing this vocabulary list will help you make more sense of Cernunnos. Please Note: These terms are especially important for those who wish to write Java code for Cernunnos. Those who only want to write scripts for Cernunnos may not need to understand the detailed information contained on this page. TaskA Task is the fundamental unit of value in Cernunnos. Each individual, discrete behavior is represented by a task. Every script must contain at least one task, and may contain as many tasks as system resources and personal sanity will allow. Task is a Java interface which all Cernunnos tasks must implement -- directly or indirectly. The AbstractContainerTask class provides support for subtasks. Task authors who wish to allow subtasks may extend from this class and save themselves some effort. In Cernunnos XML, each task is represented by an element. In fact, most elements in Cernunnos scripts represent tasks; there are a few tasks that use information from non-task child elements. Example XML<file-iterator dir="some_folder"> <copy-file to-dir="another_folder"/> </file-iterator> In this example both <file-iterator> and <copy-file> represent tasks. This script iterates, recursively, over all the files found in some_folder and copies each file in its turn to another_folder. ReagentA Reagent is a piece of information a task needs to do its work: it is essentially a "parameter" or "argument" to the task. I choose the word "Reagent" over "parameter," "argument," or even "attribute" because I feel these words are ubiquitous and overloaded. Dictionary.com provides this definition (among others) for reagent: A substance participating in a chemical reaction, especially one used to detect, measure, or produce another substance. All reagents have a type. Cernunnos supports the following three reagent types:
The PHRASE type is by far the most common and should be used in the majority of cases. The only situation in which a reagent's type should not -- cannot -- be PHRASE is where the value of the reagent must be known at bootstrap time, when tasks are being instantiated and linked. A reagent of type PHRASE can only be evaluated at runtime, when tasks are being executed. In Cernunnos XML, a reagent is usually represented by an attribute, though there are several exceptions. For example, the <sql-upsert> task uses nested <update-statement> and <insert-statement> elements to specify update and insert SQL respectively. Example XML<node-iterator source="http://www.w3.org/2002/08/xhtml/xhtml1-strict.xsd" xpath="//xs:documentation">
<echo-ln>${valueOf(.)}</echo-ln>
</node-iterator>In this example, the <node-iterator> task reads the XML Schema for XHTML Strict at the specified HTTP address and iterates over all the <xs:documentation> nodes found within it. The <echo-ln> task writes the textual content of each node to the console in turn. There are three reagents in this example:
Notice that the last of these is not specified with a literal value. The value of the <echo-ln> task's MESSAGE reagent is calculated at runtime from the textual content of the current node within the iteration. In Cernunnos, this sort of dynamic expression is called a Phrase. Please Note: The word Phrase here means something tied to but not precisely the same as the PHRASE reagent type. In fact all the reagents in this example are of type PHRASE. In other words, any or all of them could be specified using a dynamic expression. But as it happens, the first two are specified with literal values. Only the third uses a dymanic expression or Phrase. PhraseA Phrase is a dynamic expression that is evaluated at runtime to provide the value of a reagent. Phrase is probably the second most important concept in Cernunnos, after Task. Phrase is also a Java interface, and all values for reagents of type PHRASE are evaluated by one or more implementations of Phrase, even in cases where a literal expression is specified in the script. Phrase expressions take the following form: ${phrase-name(argument)} Example ExpressionsPhrase expressions may be literal, simple, concatenated, or nested (as shown in the following examples): location="build/WEB-INF/classes/properties/rdbm.properties"
source="${doc(properties/db/data.xml)}"
stylesheet="${req(INSTALL_DIR)}/xsl/entry.xsl"
node="${doc(${req(XML_LOCATION)})}"GrammarA Grammar binds Task and Phrase implementations to specific names. Cernunnos scripts invoke tasks and phrases using these names. Grammar is a Java interface which, if necessary, Cernunnos users are free to implement in any suitable fashion. The runtime package within Cernunnos comes with a simple implementation that reads grammar entries from an XML file. Example XML<grammar>
...
<phrase name="valueOf" impl="org.danann.cernunnos.xml.ValueOfPhrase"/>
<doc entry="valueOf">
<description>Returns the textual value of the specified XPath expression when evaluated against the specified node.</description>
<example caption="Parses a document from the resource at 'properties/db/data.xml', creates a node list from the expression '//table/name', and writes the text value of each node to System.out">
<pre><xmp><node-iterator source="${doc(properties/db/data.xml)}" xpath="//table/name">
<echo-ln>${valueOf(.)}</echo-ln>
</node-iterator></xmp></pre>
</example>
</doc>
<task name="file-iterator" impl="org.danann.cernunnos.io.FileIteratorTask"/>
<doc entry="file-iterator">
<description>Builds a collection of file names within a specified directory and iterates over them. Use optional pattern expressions to specify groups of files to include or exclude.</description>
<example caption="Copies all files from 'some_folder' to 'another_folder'">
<pre><xmp><file-iterator dir="some_folder">
<copy-file to-dir="another_folder"/>
</file-iterator></xmp></pre>
</example>
</doc>
...
</grammar>This example illustrates how the valueOf() phrase and the <file-iterator> task are defined in the Cernunnos core grammar. |
Sign in to add a comment
