Author: ceki Date: Sun Oct 8 19:43:21 2006 New Revision: 636 Added: logback/trunk/logback-site/src/site/xdocTemplates/joran.xml Modified: logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml Log: Added mini joran tutorial/introduction Modified: logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml Sun Oct 8 19:43:21 2006 @@ -17,12 +17,18 @@ <li> <a href="shortIntro.html"><b>A short introduction to logback-classic</b></a> </li> + <li> <a href="accessLogJetty.html"><b>A short introduction to access logging with logback-access and Jetty</b></a> </li> + <li> <a href="apidocs/index.html"><b>Javadoc</b></a> </li> + + <li> + <a href="joran.html">A introduction to Joran</a> + </li> </ul> </body> Added: logback/trunk/logback-site/src/site/xdocTemplates/joran.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-site/src/site/xdocTemplates/joran.xml Sun Oct 8 19:43:21 2006 @@ -0,0 +1,225 @@ +<?xml version="1.0"?> +<document> + +<body> +<h2>Introduction to Joran (DRAFT)</h2> + + +<h3>Ceki Gülcü, 2003-2006, All rights reserved </h3> + +<p>Joran stands for a cold north-west wind which, every now and then, +blows force-fully on Lake Leman, a.k.a lake Geneva. Located right in +the middle of Europe, the Leman happens to be the continent's largest +sweet water reserve. +</p> + +<h2>Introduction</h2> + +<p>One of the most powerful features of the Java language is +reflection. Reflection makes it possible to configure software systems +declaratively. For example, many important properties of an EJB are +configured with the ejb.xml file. While EJBs are written in Java, many +of their properties are specified within the ejb.xml file. Similarly, +logback settings can be specified in a configuration file, expressed +in XML format. +</p> + +<p>In log4j, logback's predecessor, DOMConfigurator that shipped with +log4j version 1.2.x can parse configuration files written in XML. The +DOMConfigurator is written in Java such that each time the structure +of the configuration file changes the DOMConfigurator must be tweaked +accordingly. Moreover, the modified code must be recompiled and +re-deployed. Just as importantly, the code of the DOMConfigurator +consists of loops dealing with children elements containing many +interspersed if/else statements. One can't help but notice that that +particular code reeks of redundancy. The <a +href="http://jakarta.apache.org/commons/digester/">digester +project</a> has shown that it is possible to parse XML files using +pattern matching rules. At parse time, digester will apply the rules +that match previously stated patterns. Rule classes are usually quite +small and specialized. Consequently, they are relatively easy to +understand and to maintain. +</p> + +<p>Joran is heavily inspired by the commons-digester project but uses +a slightly different terminology. In commons-digester, a rule can be +seen as consisting of a pattern and a rule, as shown by the +<code>Digester.addRule(String pattern, Rule rule)</code> method. We +find it unnecessarily confusing to have a rule to consist of itself, +not recursively but with a different meaning. In Joran, a rule +consists of a pattern and an action. An action is invoked when a match +occurs for the corresponding pattern. This relation between patterns +and actions lies at the core of Joran. Quite remarkably, one can deal +with quite complex requirements by using simple patterns, or more +precisely with exact matches and wildcard matches. For example, the +pattern "a/b" will match a <code><b></code> element nested within +an <code><a></code> element but not a <code><c></code> element, +even if nested within a <code><b></code> element. It is also +possible to match a particular XML element, regardless of its nesting +level, by using the "*" wildcard character. For example, the pattern +"*/a" will match an <code><a></code> element at any nesting +position within the document. Other types of patterns, for example +"a/*", are not currently supported by Joran. +</p> + +<h2>SAX or DOM?</h2> + +<p>Due to the event-based architecture of the SAX API, a tool based on +SAX cannot easily deal with forward references, that is, references to +elements which are defined later than the current element being +processed. Elements with cyclical references are equally +problematic. More generally, the DOM API allows the user to perform +searches on all the elements and make forward jumps. +</p> + +<p>This extra flexibility initially led us to choose the DOM API as +the underlying parsing API for Joran. After some experimentation, it +quickly became clear that dealing with jumps to distant elements while +parsing the DOM tree did not make sense when the interpretation rules +were expressed in the form of patterns and actions. <em>Joran only +needs to be given the elements in the XML document in a sequential, +depth-first order.</em> +</p> + +<p>Joran was first implemented in DOM. However, the author migrated to +SAX in order to benefit form the location information provided to the +user, that is, to an org.w3.sax.ContentHandler. With the help of +location information, it becomes possible to display essential error +reports to the user which include exact line and column. This extra +information turns out to be handy in hunting down problems. +</p> + +<h2>Actions</h2> + +<p>Actions extend the +<code>ch.qos.logback.core.joran.action.Action</code> class which +consists of the following abstract methods. +</p> + + +<div class="source">package ch.qos.logback.core.joran.action; + +import org.xml.sax.Attributes; +import ch.qos.logback.core.joran.spi.ExecutionContext; + +public abstract class Action { + + + /** + * Called when the parser first encounters an element. + */ + public abstract void begin(ExecutionContext ec, + String name, + Attributes attributes); + + /** + * Called when the parser encounters the element end. At + * this stage, we can assume that child elements, if any, + * have been processed. + */ + public abstract void end(ExecutionContext ec, String name); +} +</div> + +<p>Thus, every action must implement the begin and end methods.</p> + + +<h2>Execution context</h2> + +<p>To allow various actions to collaborate, the invocation of begin +and end methods include an execution context as the first +parameter. The execution context includes an object stack, an object +map, an error list and a reference to the Joran interpreter invoking +the action. Please see the +<code>ch.qos.logback.core.joran.spi.ExecutionContext</code> class for +the exact list of fields contained in the execution context. +</p> + +<p>Actions can collaborate together by fetching, pushing or popping +objects from the common object stack, or by putting and fetching keyed +objects on the common object map. Actions can report any error +conditions by adding error items on the execution context's +<code>StatusManager</code>. +</p> + +<h3>A hello world example</h3> + +<p>The <em>examples/src/joran/helloWorld/</em> directory includes a +trivial action and Joran interpreter setup which just diaplays "hello +world" when a <hello-world> element is encountered in an XML file. +Look into this example to learn about the basic steps which are +necessary to set up and invoke a Joran interpreter. +</p> + +<h3>Collaborating actions</h3> + +The examples/src/joran/calculator/ directory includes several actions +which collaborate together through the common object stack in order +to accomplish simple computations. + +<h3>New-rule action</h3> + +<p>Joran includes an action which allows the Joran interpreter to lean +new rules on the fly while interpreting the XML file containing the +new rules. See the <em>logback-core/examples/src/joran/newRule/</em> +directory for sample code. +</p> + +<h3>Implicit actions </h3> + +<p>The rules defined thus far are called explicit rules because they +require an explicit pattern, hence fixing the tag name of the elements +for which they apply. +</p> + +<p>In highly extensible systems, the number and type of components to +handle are innumerable so that it would become very tedious or even +impossible to list all the applicable patterns by name. +</p> + +<p>At the same time, even in highly extensible systems one can observe +well-defined patterns linking the various parts together. Implicit +rules come in very handy when processing components composed of +sub-components unknown ahead of time. For example, Apache Ant is +capable of handling tasks which contain tags unknown at compile time +by looking at methods whose names start with add, as in addFile, or +addClassPath. When Ant encounters an embedded tag within a task, it +simply instantiates an object that matches the signature of the task +class' add method and attaches the resulting object to the parent. +</p> + +<p>Joran includes similar capability in the form of implicit +actions. Joran keeps a list of implicit actions which can be applied +if no explicit pattern matches the current XML element. However, +applying an implicit action may not be always appropriate. Before +executing the implicit action, Joran asks an implicit action whether +it is appropriate in the current context. Only if the action replies +affirmatively does Joran interpreter invoke the (implicit) +action. This extra step makes it possible to support multiple implicit +actions or obviously none, if no implicit action is appropriate for a +given situation. +</p> + +<p>For example, the NestedComponentIA extending ImplicitAction , will +instantiate the class specified in a nested component and attach it +to the parent component by using setter method of the parent +component and the nested element's name. Under certain circumstances, +a nested action needs to be applied to an element say <a> and also +to another element <b> nested within <a>. The current +implementation of <code>NestedComponentIA</code> is capable of +handling multiply nested elements requiring intervention by the same +implicit action. +</p> + +<p>Refer to the <em>logback-core/examples/src/joran/implicit</em> +directory for an example of an implicit action. +</p> + +<h3>Non goals</h3> + +<p>The Joran API is not intended to be used to parse documents with +thousands of elements. +</p> + +</body> +</document> \ No newline at end of file