[logback-dev] svn commit: r2136 - in logback/trunk: logback-examples/src/main/java/chapter10/calculator logback-site/src/site/pages/css logback-site/src/site/pages/manual
noreply.ceki at qos.ch
noreply.ceki at qos.ch
Wed Jan 28 22:06:55 CET 2009
Author: ceki
Date: Wed Jan 28 22:06:55 2009
New Revision: 2136
Modified:
logback/trunk/logback-examples/src/main/java/chapter10/calculator/AddAction.java
logback/trunk/logback-examples/src/main/java/chapter10/calculator/Calculator1.java
logback/trunk/logback-examples/src/main/java/chapter10/calculator/LiteralAction.java
logback/trunk/logback-examples/src/main/java/chapter10/calculator/MultiplyAction.java
logback/trunk/logback-examples/src/main/java/chapter10/calculator/calculator1.xml
logback/trunk/logback-site/src/site/pages/css/common.css
logback/trunk/logback-site/src/site/pages/manual/onJoran.html
Log:
Continuing improving Joran documentation as mandated by LBSITE-25
Modified: logback/trunk/logback-examples/src/main/java/chapter10/calculator/AddAction.java
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter10/calculator/AddAction.java (original)
+++ logback/trunk/logback-examples/src/main/java/chapter10/calculator/AddAction.java Wed Jan 28 22:06:55 2009
@@ -1,7 +1,7 @@
/**
- * Logback: the reliable, fast and flexible logging library for Java.
+ * Logback: the generic, reliable, fast and flexible logging framework.
*
- * Copyright (C) 1999-2006, QOS.ch
+ * Copyright (C) 2000-2009, QOS.ch
*
* This library is free software, you can redistribute it and/or modify it under
* the terms of the GNU Lesser General Public License as published by the Free
@@ -10,8 +10,6 @@
package chapter10.calculator;
-
-
import java.util.EmptyStackException;
import org.xml.sax.Attributes;
@@ -28,23 +26,23 @@
*/
public class AddAction extends Action {
- public void begin(InterpretationContext ec, String name, Attributes attributes) {
- int first = fetchInteger(ec);
- int second = fetchInteger(ec);
+ public void begin(InterpretationContext ic, String name, Attributes attributes) {
+ int first = fetchInteger(ic);
+ int second = fetchInteger(ic);
// Push the result of the addition for the following actions.
- ec.pushObject(new Integer(first + second));
+ ic.pushObject(new Integer(first + second));
}
/**
* Pop the Integer object at the top of the stack.
- * This code illustrates usage of Joran's error handling paradigm.
+ * This code also illustrates usage of Joran's error handling paradigm.
*/
- int fetchInteger(InterpretationContext ec) {
+ int fetchInteger(InterpretationContext ic) {
int result = 0;
try {
- // Pop the object at the top of the exection context stack.
- Object o1 = ec.popObject();
+ // Pop the object at the top of the interpretation context's stack.
+ Object o1 = ic.popObject();
if (o1 instanceof Integer) {
result = ((Integer) o1).intValue();
@@ -52,20 +50,17 @@
String errMsg =
"Object [" + o1
+ "] currently at the top of the stack is not an integer.";
- ec.addError(errMsg);
+ ic.addError(errMsg);
throw new IllegalArgumentException(errMsg);
}
} catch (EmptyStackException ese) {
- ec.addError(("Expecting an integer on the execution stack."));
+ ic.addError(("Expecting an integer on the execution stack."));
throw ese;
}
return result;
}
- public void end(InterpretationContext ec, String name) {
+ public void end(InterpretationContext ic, String name) {
// Nothing to do here.
- // In general, the end() method of actions associated with elements
- // having no children do not need to perform any processing in their
- // end() method.
}
}
Modified: logback/trunk/logback-examples/src/main/java/chapter10/calculator/Calculator1.java
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter10/calculator/Calculator1.java (original)
+++ logback/trunk/logback-examples/src/main/java/chapter10/calculator/Calculator1.java Wed Jan 28 22:06:55 2009
@@ -1,7 +1,7 @@
/**
- * Logback: the reliable, fast and flexible logging library for Java.
+ * Logback: the generic, reliable, fast and flexible logging framework.
*
- * Copyright (C) 1999-2006, QOS.ch
+ * Copyright (C) 2000-2009, QOS.ch
*
* This library is free software, you can redistribute it and/or modify it under
* the terms of the GNU Lesser General Public License as published by the Free
@@ -16,7 +16,6 @@
import ch.qos.logback.core.Context;
import ch.qos.logback.core.ContextBase;
import ch.qos.logback.core.joran.action.Action;
-import ch.qos.logback.core.joran.spi.JoranException;
import ch.qos.logback.core.joran.spi.Pattern;
import ch.qos.logback.core.util.StatusPrinter;
import chapter10.SimpleConfigurator;
@@ -25,18 +24,6 @@
* This examples illustrates collaboration between multiple actions through the
* common execution context stack.
*
- * The first and only argument of this application must be the path to the XML
- * file to interpret. There are sample XML files in the
- * <em>examples/src/joran/calculator/</em> directory.
- *
- * For example,
- *
- * <pre>
- * java joran.calculator.Calculator1 examples/src/joran/calculator/calculator1.xml
- * </pre>
- *
- * Please refer to the comments in the source code for more information.
- *
* @author Ceki Güulcü
*/
public class Calculator1 {
@@ -58,11 +45,8 @@
// link the configurator with its context
simpleConfigurator.setContext(context);
- try {
- simpleConfigurator.doConfigure(args[0]);
- } catch (JoranException e) {
- // Print any errors that might have occured.
- StatusPrinter.print(context);
- }
+ simpleConfigurator.doConfigure(args[0]);
+ // Print any errors that might have occured.
+ StatusPrinter.print(context);
}
}
Modified: logback/trunk/logback-examples/src/main/java/chapter10/calculator/LiteralAction.java
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter10/calculator/LiteralAction.java (original)
+++ logback/trunk/logback-examples/src/main/java/chapter10/calculator/LiteralAction.java Wed Jan 28 22:06:55 2009
@@ -1,7 +1,7 @@
/**
- * Logback: the reliable, fast and flexible logging library for Java.
+ * Logback: the generic, reliable, fast and flexible logging framework.
*
- * Copyright (C) 1999-2006, QOS.ch
+ * Copyright (C) 2000-2009, QOS.ch
*
* This library is free software, you can redistribute it and/or modify it under
* the terms of the GNU Lesser General Public License as published by the Free
@@ -17,37 +17,36 @@
import ch.qos.logback.core.util.OptionHelper;
/**
- *
- * This action converts the value attribute of the associated element to
- * an integer and pushes the resulting Integer object on top of the execution
+ * This action converts the value attribute of the associated element to an
+ * integer and pushes the resulting Integer object on top of the execution
* context stack.
- *
- * It also illustrates usage of Joran's error handling paradigm.
- *
+ *
+ * <p>It also illustrates usage of Joran's error reporting/handling paradigm.
+ *
* @author Ceki Gülcü
*/
public class LiteralAction extends Action {
public static String VALUE_ATR = "value";
- public void begin(InterpretationContext ec, String name, Attributes attributes) {
+ public void begin(InterpretationContext ic, String name, Attributes attributes) {
String valueStr = attributes.getValue(VALUE_ATR);
if (OptionHelper.isEmpty(valueStr)) {
- ec.addError("The literal action requires a value attribute");
+ ic.addError("The literal action requires a value attribute");
return;
}
try {
Integer i = Integer.valueOf(valueStr);
- ec.pushObject(i);
+ ic.pushObject(i);
} catch (NumberFormatException nfe) {
- ec.addError("The value [" + valueStr + "] could not be converted to an Integer",
- nfe);
+ ic.addError("The value [" + valueStr
+ + "] could not be converted to an Integer", nfe);
throw nfe;
}
}
- public void end(InterpretationContext ec, String name) {
+ public void end(InterpretationContext ic, String name) {
// Nothing to do here.
// In general, the end() method of actions associated with elements
// having no children do not need to perform any processing in their
Modified: logback/trunk/logback-examples/src/main/java/chapter10/calculator/MultiplyAction.java
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter10/calculator/MultiplyAction.java (original)
+++ logback/trunk/logback-examples/src/main/java/chapter10/calculator/MultiplyAction.java Wed Jan 28 22:06:55 2009
@@ -1,7 +1,7 @@
/**
* Logback: the generic, reliable, fast and flexible logging framework.
*
- * Copyright (C) 1999-2006, QOS.ch
+ * Copyright (C) 2000-2009, QOS.ch
*
* This library is free software, you can redistribute it and/or modify it under
* the terms of the GNU Lesser General Public License as published by the Free
@@ -10,7 +10,6 @@
package chapter10.calculator;
-
import org.xml.sax.Attributes;
import ch.qos.logback.core.joran.action.Action;
@@ -18,53 +17,47 @@
import java.util.EmptyStackException;
-
/**
- *
- * This action multiplies the two integers at the top of the stack (they are removed)
- * and pushes the result on top the stack.
- *
+ *
+ * This action multiplies the two integers at the top of the stack (they are
+ * removed) and pushes the result on top the stack.
+ *
* @author Ceki Gülcü
*/
public class MultiplyAction extends Action {
-
-
- public void begin(InterpretationContext ec, String name, Attributes attributes) {
- int first = fetchInteger(ec);
- int second = fetchInteger(ec);
- ec.pushObject(new Integer(first * second));
+
+ public void begin(InterpretationContext ic, String name, Attributes attributes) {
+ int first = fetchInteger(ic);
+ int second = fetchInteger(ic);
+ ic.pushObject(new Integer(first * second));
}
/**
- * Pop the Integer object at the top of the stack.
- * This code illustrates usage of Joran's error handling paradigm.
+ * Pop the Integer object at the top of the stack. This code illustrates usage
+ * of Joran's error handling paradigm.
*/
- int fetchInteger(InterpretationContext ec) {
+ int fetchInteger(InterpretationContext ic) {
int result = 0;
try {
- Object o1 = ec.popObject();
+ Object o1 = ic.popObject();
if (o1 instanceof Integer) {
result = ((Integer) o1).intValue();
} else {
- String errMsg =
- "Object [" + o1
- + "] currently at the top of the stack is not an integer.";
- ec.addError(errMsg);
+ String errMsg = "Object [" + o1
+ + "] currently at the top of the stack is not an integer.";
+ ic.addError(errMsg);
throw new IllegalArgumentException(errMsg);
}
} catch (EmptyStackException ese) {
- ec.addError("Expecting an integer on the execution stack.");
+ ic.addError("Expecting an integer on the execution stack.");
throw ese;
}
return result;
}
- public void end(InterpretationContext ec, String name) {
+ public void end(InterpretationContext ic, String name) {
// Nothing to do here.
- // In general, the end() method of actions associated with elements
- // having no children do not need to perform any processing in their
- // end() method.
}
}
Modified: logback/trunk/logback-examples/src/main/java/chapter10/calculator/calculator1.xml
==============================================================================
--- logback/trunk/logback-examples/src/main/java/chapter10/calculator/calculator1.xml (original)
+++ logback/trunk/logback-examples/src/main/java/chapter10/calculator/calculator1.xml Wed Jan 28 22:06:55 2009
@@ -1,6 +1,3 @@
-<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE computation>
-
<computation name="total">
<literal value="3"/>
</computation>
Modified: logback/trunk/logback-site/src/site/pages/css/common.css
==============================================================================
--- logback/trunk/logback-site/src/site/pages/css/common.css (original)
+++ logback/trunk/logback-site/src/site/pages/css/common.css Wed Jan 28 22:06:55 2009
@@ -18,26 +18,26 @@
margin-top: 1em;
}
-.source {
+.source, .command, .console {
border-top: 1px solid #DDDDDD;
border-bottom: 1px solid #DDDDDD;
background:#eee;
font-family: Courier, "MS Courier New", Prestige, monospace;
- padding-bottom: 0.5ex;
- padding-top: 0.5ex;
padding-left: 1ex;
white-space: pre;
}
-.command {
- border-top: 1px solid #DDDDDD;
- border-bottom: 1px solid #DDDDDD;
- background:#eee;
- font-family: Courier, "MS Courier New", Prestige, monospace;
+.source {
+ padding-bottom: 0.5ex;
+ padding-top: 0.5ex;
+}
+
+.command {
padding-bottom: 0ex;
padding-top: 0ex;
- padding-left: 1ex;
- white-space: pre;
+}
+
+.console {
}
pre {
Modified: logback/trunk/logback-site/src/site/pages/manual/onJoran.html
==============================================================================
--- logback/trunk/logback-site/src/site/pages/manual/onJoran.html (original)
+++ logback/trunk/logback-site/src/site/pages/manual/onJoran.html Wed Jan 28 22:06:55 2009
@@ -126,15 +126,21 @@
problems.
</p>
-
+ <h3>Non goals</h3>
+
+ <p>Given its highly dynamic nature, the Joran API is not intended
+ to be used to parse very large XML documents with many thousands
+ of elements.
+ </p>
+
+
<h3><a name="pattern" href="#pattern">Pattern</a></h3>
<p>A Joran pattern is essentially a string. There are two kind of
- patterns, <em>exact</em> and <em>wildcard</em>. The pattern
- "a/b" can be used to match <code><b></code> element nested
- within a top-level <code><a></code> element but not a
- <code><c></code> element, even if nested within a
- <code><b></code> element.</p>
+ patterns, <em>exact</em> and <em>wildcard</em>. The pattern "a/b"
+ can be used to match <code><b></code> element nested within a
+ top-level <code><a></code> element. The "a/b" will not match
+ any other element, hence the <em>exact</em> match designation.</p>
<p>Wildcards can be used to match suffixes or prefixes. For
example, the "*/a" pattern can be used to match any suffix ending
@@ -145,13 +151,6 @@
<code><a></code> element.
</p>
- <p>When several rules match the current pattern, then exact
- matches override suffix matches, and suffix matches overide prefix
- matches. For exact details of implementation, please see the <a
- href="../xref/ch/qos/logback/core/joran/spi/SimpleRuleStore.java">SimpleRuleStore</a>
- class.
- </p>
-
<h3><a name="action" href="#action">Actions</a></h3>
<p>As mentioned above, Joran parsing rules consists of the
@@ -190,9 +189,33 @@
<h3><a name="ruleStore" href="#ruleStore">RuleStore</a> </h3>
+ <p>As mentioned previously, the invocation of actions according to
+ matching patterns is a central concept in Joran. A rule is an
+ association of a pattern and an action. Rules are stored in a <a
+ href="../xref/ch/qos/logback/core/joran/spi/RuleStore.java">RuleStore</a>.
+ </p>
+
+ <p>As mentioned above, Joran is built on top of the SAX API. As an
+ XML document is parsed, each element generates events corresponding
+ to the start, body and end of each element. When a joran
+ configurator receives these events, it will attempt to find in its
+ rule store an action corresponding to the <em>current
+ pattern</em>.. For example, the current pattern for the start, body
+ or end event of element <em>B</em> nested within a top-level
+ <em>A</em> element is "A/B". The current pattern is a data
+ structure maintained automatically by Joran as it receives and
+ processes SAX events. </p>
+
+ <p>When several rules match the current pattern, then exact
+ matches override suffix matches, and suffix matches overide prefix
+ matches. For exact details of implementation, please see the <a
+ href="../xref/ch/qos/logback/core/joran/spi/SimpleRuleStore.java">SimpleRuleStore</a>
+ class.
+ </p>
- <h2>Interpretation context</h2>
+ <h3><a name="interpretationContext"
+ href="#interpretationContext">Interpretation context</a></h3>
<p>To allow various actions to collaborate, the invocation of begin
and end methods include an interpretation context as the first
@@ -242,8 +265,6 @@
if any, are printed</li>
</ul>
-
-
<p>The <em>hello.xml</em> file contains one <hello-world>
element, without any other nested elements. See the
<em>logback-examples/src/main/java/chapter10/helloWorld/</em>
@@ -253,7 +274,14 @@
<p>Running the HelloWorld application with <em>hello.xml</em> file
will print "Hello World" on the console.</p>
- <p class="source">java chapter10.helloWorld.HelloWorld src/main/java/chapter10/helloWorld/hello.xml</p>
+ <p class="command">java chapter10.helloWorld.HelloWorld src/main/java/chapter10/helloWorld/hello.xml</p>
+
+ <p>You are highly encourared to poke about this example, by adding
+ new rules on the rule store, modifying the XML document
+ (hello.xml) and adding new actions.
+ </p>
+
+ <!-- ====================================================== -->
<h3><a name="calculator" href="#calculator">Collaborating
actions</a></h3>
@@ -266,15 +294,35 @@
<p>The <em>calculator1.xml</em> file contains a
<code>computation</code> element, with a nested
- <code>literal</code> element.
+ <code>literal</code> element. Here are its contents.
</p>
+ <em>Example 10.<span class="autoEx"/>: First calculator example
+ (logback-examples/src/main/java/chapter10/calculator/calculator1.xml)</em>
+
+ <em> </em>
+ <p class="source"><computation name="total">
+ <literal value="3"/>
+</computation></p>
+
<p>In the <a href="../xref/chapter3/calculator/Calculator1.html">
- <code>Calculator1</code></a> class, we declare various patterns
- and actions, that will collaborate and calculate a result based on
- the xml file. The simple <em>calculator1.xml</em> file only
- creates a computation and declares a literal value. The resulting
- parsing is pretty simple:
+ <code>Calculator1</code></a> application, we declare various
+ parsing rules (patterns and actions) collaborating together to
+ compute a result based on the contents of an XML document.
+ </p>
+
+ <p> Running <code>Calculator1</code> application with
+ <em>calculator1.xml</em></p>
+
+ <p class="command">java chapter10.calculator.Calculator1 src/main/java/chapter10/calculator/calculator1.xml</p>
+
+ <p>will print:</p>
+
+ <p class="console">The computation named [total] resulted in the value 3</p>
+
+
+ <p>Parsing the <em>calculator1.xml</em> document (listed above)
+ involves the following steps:
</p>
<ul>
@@ -290,15 +338,17 @@
is called</li>
</ul>
- <p>What is interesting here is the way that the Actions
- collaborate. The <code>LiteralAction</code> reads a literal value
- and pushes it in the object stack maintained by the
+ <p>What is interesting here is the way actions collaborate. The
+ <code>LiteralAction</code> reads a literal value and pushes it in
+ the object stack maintained by the
<code>InterpretationContext</code>. Once done, any other action
can pop the value to read or modify it. Here, the
<code>end()</code> method of the <code>ComputationAction1</code>
class pops the value from the stack and prints it.
</p>
+ <!-- TO BE CONTINUED -->
+
<p>The <em>calculator2.xml</em> file is a bit more complex, but
much more interesting.</p>
@@ -544,14 +594,6 @@
<multiply/>
</computation></pre></div>
-
- <h3>Non goals</h3>
-
- <p>The Joran API is not intended to be used to parse documents with
- thousands of elements.
- </p>
-
-
<script src="templates/footer.js" type="text/javascript"></script>
</div>
</body>
More information about the logback-dev
mailing list