## Using Joran in your own applications

As we've seen, logback relies on Joran, a mature, flexible and powerful configuration framework. Many of the capabilities offered by logback modules are possible with the help of Joran.

Joran is actually a generic configuration system which can be used independently of logging. To emphaises this point, we should mention that the logback-core module does not have a notion of loggers. In that spirit, many of the examples related to this tutorial, have nothing to do with loggers, appenders or layouts.

The examples for this chapter can be found under LOGBACK_HOME/logback-examples/src/main/java/chapter3.

To install joran, simply download logback and add logback-core-${version}.jar to your classpath.

## Historical perspective

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.

In log4j, logback's predecessor, `DOMConfigurator` which shipped with log4j version 1.2.x could also parse configuration files written in XML. The `DOMConfigurator` was written in a way that forced to tweak it each time the structure of the configuration file changed. The modified code had to be recompiled and redeployed. Just as importantly, the code of the DOMConfigurator consists of loops dealing with children elements containing many interspersed if/else statements. One could not help but notice that that particular code reeked of redundancy. The digester project 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.

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 `Digester.addRule(String pattern, Rule rule)` 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 `<b>` element nested within an `<a>` element but not a `<c>` element, even if nested within a `<b>` 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 `<a>` element at any nesting position within the document. Other types of patterns, for example a/*, are not currently supported by Joran.

## SAX or DOM?

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.

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. Joran only needs to be given the elements in the XML document in a sequential, depth-first order.

Joran was first implemented in DOM. However, the author migrated to SAX in order to benefit location information, available only with the SAX API. Location information allows Joran to display the exact line and column number where an error occured, which comes in quite handy when hunting down problems.

## Actions

Actions extend the `ch.qos.logback.core.joran.action.Action` class which consists of the following abstract methods.

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); }

Thus, every action must implement the begin and end methods.

## Execution context

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 `ch.qos.logback.core.joran.spi.ExecutionContext` class for the exact list of fields contained in the execution context.

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 `StatusManager`.

### A hello world example

The logback-examples/src/main/java/chapter3/helloWorld/ directory includes a trivial action and Joran interpreter setup which just displays Hello World when a <hello-world> element is encountered in an XML file. It also includes the basic steps which are necessary to set up and invoke a Joran interpreter.

The hello.xml file contains only one element, without any other nested elements. The `HelloWorldAction` class is a trivial implementation: it only prints "Hello World" in the console when it's `begin()` method is called.

`HelloWorld` is a class that sets up the Joran interpreter, with the minimal steps necessary:

- It creates a `RuleStore` and a `Context`
- It adds the hello-world pattern, with it's corresponding action
- It creates a Joran interpreter, and passes the `RuleStore`
- It creates a SAX parser and parses the given file, specifying the newly created Joran interpreter as the `ContentHandler`

It's last step is to print the content of the `Context`. Since Joran uses logback's powerfull `Status` objects for error reporting, one can have a good feedback on what happened during the parsing.

In this example, the parsing is rather simple. The hello-world element will activate `HelloWorldAction`'s `begin()` and `end()` methods. In the first method, a simple call to `System.out.println()` will be issued, displaying Hello World in the console.

### Collaborating actions

The logback-examples/src/main/java/joran/calculator/ directory includes several actions which collaborate together through the common object stack in order to accomplish simple computations.

The calculator1.xml file contains a `computation` element, with a nested `literal` element.

In the `Calculator1` class, we declare various patterns and actions, that will collaborate and calculate a result based on the xml file. The simple calculator1.xml file only creates a computation and declares a literal value. The resulting parsing is pretty simple:

- The `ComputationAction1` class' `begin()` method is called
- The `LiteralAction` class' `begin()` and `end()` methods are called
- The `ComputationAction1` class' `end()` method is called

What is interesting here is the way that the Actions collaborate. The `LiteralAction` reads a literal value and pushes it in the object stack maintained by the `ExecutionContext`. Once done, any other action can pop the value to read or modify it. Here, the `end()` method of the `ComputationAction1` class pops the value from the stack and prints it.

The calculator2.xml file is a bit more complex, but much more interesting.

It contains the following elements:

Example 3.: Calculator configuration file (logback-examples/src/main/java/chapter3/calculator/calculator2.xml)

    <computation name="toto">
      <literal value="7"/>
      <literal value="3"/>
      <add/>
      <literal value="3"/>
      <multiply/>
    </computation>

Here, there are obviously more actions that will be part of the computation.

When called, the `AddAction` class will remove the two integers at the bottom of the stack, add them and push the resulting integer at the top of the stack, for further use.

Later in the computation, the `MultiplyAction` class will be called. It will take the last two integers from the stack, multiply them and push the result in the stack.

We have here two examples of action whose `begin()` method behaves in a certain, predictable way, but whose `end()` methods are empty.

Finally, a calculator3.xml is also provided, to demonstrate the possibility elements that contain instances of the same element. Here's the content of calculator3.xml:

Example 3.: Calculator configuration file (logback-examples/src/main/java/chapter3/calculator/calculator3.xml)

    <computation name="toto">
      <computation>
        <literal value="7"/>
        <literal value="3"/>
        <add/>
      </computation>

      <literal value="3"/>
      <multiply/>
    </computation>

Much like the use of parentheses in an algebrical equation, the presence of a `computation` element nested in another is managed by the `ComputationAction2` class using an internal stack. The well-formedness of XML will guarantee that a value saved by one `begin()` will be consumed only by the matching `end()` method.

### New-rule action

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 logback-examples/src/main/java/joran/newRule/ directory for sample code.

In this package, the `NewRuleCalculator` class contains the same setup as we have seen so far, but for one line:

ruleStore.addRule(new Pattern("/computation/new-rule"), new NewRuleAction());

By adding this line, we ask Joran to allow new rules to be learnt at parsing time. It works pretty much like the other rules: it has a `begin()` and `end()` method, and is called each time the parser finds a new-rule element.

When called, the `begin()` method looks for a pattern and a actionClass attribute. The action class is then instanciated and added to the `RuleStore`, along with its corresponding pattern.

Here is how new rules can be declared in an xml file:

    <new-rule pattern="*/computation/literal"
    actionClass="chapter3.calculator.LiteralAction"/>

Using new rule declarations, the preceding example, involving the calculation, could be expressed this way:

Example 3.: Configuration file using new rules on the fly (logback-examples/src/main/java/chapter3/newrule/new-rule.xml)

    <computation name="toto">
      <new-rule pattern="*/computation/literal"
                actionClass="chapter3.calculator.LiteralAction"/>
      <new-rule pattern="*/computation/add"
                actionClass="chapter3.calculator.AddAction"/>
      <new-rule pattern="*/computation/multiply"
                actionClass="chapter3.calculator.MultiplyAction"/>

      <computation>
        <literal value="7"/>
        <literal value="3"/>
        <add/>
      </computation>

      <literal value="3"/>
      <multiply/>
    </computation>

### Implicit actions

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.

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.

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.

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.

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 `NestedComponentIA` is capable of handling multiply nested elements requiring intervention by the same implicit action.

Both `ImplicitAction` and `NestedComponentIA` are located in the `ch.qos.logback.core.joran.action` package.

Refer to the logback-examples/src/main/java/joran/implicit directory for an example of an implicit action.

In that directory, you will find two actions classes, one xml file and one class containing the setup of Joran.

The `NOPAction` class does nothing. It is used to set the context of the foo element, using this line:

ruleStore.addRule(new Pattern("*/foo"), new NOPAction());

After that, the implicit action, namely `PrintMeImplicitAction`, is added to the `RuleStore`. This is done by simply adding a new instance of the action to the `Joran interpreter`

ji.addImplicitAction(new PrintMeImplicitAction());

When called, the `isApplicable()` method of `PrintMeImplicitAction` checks the value of the printme attribute. If the value is `true`, the implicit action is applicable: its `begin()` method will be called.

The implicit1.xml file contains the following lines:

Example 3.: Usage of implicit rules (logback-examples/src/main/java/chapter3/implicit/implicit1.xml)

    <foo>

      <xyz printme="true">
        <abc printme="true"/>
      </xyz>

      <xyz/>

      <foo printme="true"/>

    </foo>

As you can see, the first element will be printed, since it has a printme attribute, which bears the value `true`.

The second element will not be printed, because no printme attibute is present.

The last element will not be printed, although the required attribute is present. This is because implicit rules are called only if no explicit rules are defined. Since we added a `NOPAction` with the */foo pattern, it will be used instead of the `PrintMeImplicitAction`.

Running the example yields the following output:

    Element <xyz> asked to be printed.
    Element <abc> asked to be printed.
    ERROR in ch.qos.logback.core.joran.spi.ExecutionContext@1c5c1 - no applicable action \
    for <xyz>, current pattern is [/foo/xyz]

The last line was printed because of a call to `StatusPrinter` at the end of the main class.

### Non goals

The Joran API is not intended to be used to parse documents with thousands of elements.