Configuration Basics

The Jacson configuration is is a XML with a root <application>. This XML is parsed with a SAX1 parser, i.e. no namespaces are used and is stored as a tree with name-value pairs. Storage is disregarding the difference between attributes and elements. That is

  <jacson label="otto">
    ...
  </jacson>

and

  <jacson>
    <label>otto</label>
    ...
  </jacson>

make no difference to what Jacson sees. There is als an abbreviation for element text by a reserved attribute:

  <label se:this="otto"/>

and

    <label>otto</label>

are equivalent for Jacson. While the "se:" looks like a namespace prefix it is currently only a naming rule for internal elements, but might be lifted to a namespace somewhat in the future.

Parameters

To generate flexible configuration, Jacson knows parameters. An element

  <se:param se:name="otto" se:value="waalkes"/>

declares a piece of string named otto with a default value waalkes, that can be used for substitution whereever constant text is. For example like:

    <jacson label="This is otto ${otto}">

The default value of these params can be modified

by commandline assignments when the Jacson commandline is used.
by properties or param elements when the Ant Task is used.

There is no scoping, all params are globally visible and initialized before Jacson starts digesting the config.

Structure

Within the <application> there has to be a <jacson> element. Although named differently this element is an classless Evaluator.

Within this block, you can have

zero or more <source> elements (since 0.89),
zero or more <filter> elements,
zero or more <evaluation> elements and
zero or more <report> elements.

Note these elements do not need to have a particular ordering. And in fact for evals and reports order doesn't matter at all. For filters, the very first filter gets the unfiltered input chunks to the block, and outputs it to the next filter in sequence. That is ordering among the filters matters.

A block containing not at least one filter or evaluation must be considered a no operation and is an error.

Filter's, Eval's and Report's take a class name as text. Note when you use the internal Jacson classes, you can leave away the default package, that is.

    <jacson se:this="de.spieleck.app.jacson.eval.CountEvaluator">

and

    <jacson label="CountEvaluator">

load the same plugin class. If you write your own plugins in your own package, you need to use the full qualified class name.

Different <filter>'s <eval>'s and <report>'s accept different subelements or attributes. And this needs to be documented elsewhere.

Classless eval

Unlike <filter>'s and <report>'s <eval> need not to have a class. If they do not have the JacsonBlock is used. This evaluation can carry it's own <filter>, <eval> and <report> subelements, as described above. This recursive definition is the most powerful part of the Jacson configuration syntax, enabling you to configure new evaluations by combining filters and other evaluations.

Reports attached to non top evaluations only capture output generated below them, but this output is still promoted to all Reports on higher levels.

id/idref

To avoid some work when designing complex filters, Jacson has a primitive id/idref mechanic. The usage is plugin specific, that is the programmer of the plugin decides to use that mechanic. The builtin plugins implement the following multilevel logic:

First see if a configuration for a setting is available.
If not, but there is a idref, seek the referenced node for the setting.
If the idref-ed node doesn't carry the setting, but has another idref, we look at that node.
... and so on...

The described functionality is implemented by the interaction of

Sources

Although JacsonChunkSource is considered a plugin class for Jacson. There is no configuration for them. Sources are currently defined implicitely by the usage of Jacson:

For the the basic commandline a LineChunkSource is used.
For the the tail commandline a TailSource.
For the the Ant task a LineChunkSource.

If you embed Jacson into a program yourself, you are of course free to use whatever you need.

With Jacson 0.89 a new concept of configurable sources is introduced. These so called GenericSources can be configured like Reports or Filters. For examples have a look at SQLSource.