leosimons 2003/02/21 13:19:59
Modified: logger/src/xdocs index.xml
Log:
some minimal docs. Need to explain how to use the non-logkit stuff.
Revision Changes Path
1.7 +134 -113 avalon-excalibur/logger/src/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/avalon-excalibur/logger/src/xdocs/index.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- index.xml 20 Feb 2003 14:26:57 -0000 1.6
+++ index.xml 21 Feb 2003 21:19:59 -0000 1.7
@@ -10,121 +10,141 @@
<body>
<section><title>Introduction</title>
<p>
- Find Avalon Excalibur's LogKit Management System in the
+ Find Avalon Excalibur's Log Management System in the
<code>org.apache.avalon.excalibur.logger</code> package.
- The LogKit Management System integrates neatly into the Avalon
- Excalibur's Component Management System. The main goal is to
+ Excalibur-Logger integrates neatly into the Avalon ECM
+ and Fortress. The main goal is to
be able to define the log categories on a component basis by
specifying a 'logger' attribute which denotes the log category
- to use for a particular <code>Component</code> (given the
- <code>Component</code> is <code>Loggable</code>).
+ to use for a particular component (given the
+ component is <code>LogEnabled</code> or <code>Loggable</code>).
</p>
</section>
+ <section><title>Not just for logkit</title>
+ <p>
+ Though the documentation doesn't reflect this accurately
+ yet (patches welcome), excalibur-logger has been updated
+ to support other logging toolkits like jdk1.4 logging and
+ log4j as well.
+ </p>
+ </section>
+ <section><title>Not just for ECM</title>
+ <p>
+ Though the documentation doesn't reflect this accurately
+ yet (patches welcome), excalibur-logger is not just used
+ by (or usable by) ECM. Other containers can and do make
+ use of logger, too.
+ </p>
+ </section>
<section><title>Example configurations</title>
<p>
Look at this example of a component definition:
</p>
<source>
<![CDATA[
- <component role="my.component.role" class="my.component.roleImpl"
- logger="category.subcategory"/>
+<component role="my.component.role" class="my.component.roleImpl"
+ logger="category.subcategory"/>
]]>
</source>
<p>
- And now let's have a look at a hypothetical LogKit Management configuration:
+ And now let's have a look at a hypothetical Excalibur-Logger configuration
+ using Logkit:
</p>
<source>
<![CDATA[
- <?xml version="1.0"?>
+ <?xml version="1.0"?>
- <logkit>
- <factories>
- <factory type="file"
class="org.apache.avalon.excalibur.logger.factory.FileTargetFactory"/>
- <factory type="priority-filter"
-
class="org.apache.avalon.excalibur.logger.factory.PriorityFilterTargetFactory"/>
- </factories>
+ <logkit>
+ <factories>
+ <factory type="file"
+ class="org.apache.avalon.excalibur.logger.factory.FileTargetFactory"/>
+ <factory type="priority-filter"
+
class="org.apache.avalon.excalibur.logger.factory.PriorityFilterTargetFactory"/>
+ </factories>
- <targets>
- <file id="root">
- <filename>lolo/${current-dir}/lala/${foo}/logs/main.log</filename>
- <format type="extended">
- %7.7{priority} %5.5{time} [%8.8{category}] (%{context}):
%{message}\n%{throwable}
- </format>
- <append>true</append>
- </file>
- <file id="classloader">
- <filename>logs/classloader.log</filename>
- <format type="raw"/>
- </file>
- <priority-filter id="foo" log-level="WARN">
- <file>
- <filename>logs/foo.log</filename>
- <format type="extended">%7.7{priority} %5.5{time}:
%{message}\n%{throwable}</format>
- </file>
- </priority-filter>
- </targets>
+ <targets>
+ <file id="root">
+ <filename>lolo/${current-dir}/lala/${foo}/logs/main.log</filename>
+ <format type="extended">
+%7.7{priority} %5.5{time} [%8.8{category}] (%{context}): %{message}\n%{throwable}
+ </format>
+ <append>true</append>
+ </file>
+ <file id="classloader">
+ <filename>logs/classloader.log</filename>
+ <format type="raw"/>
+ </file>
+ <priority-filter id="foo" log-level="WARN">
+ <file>
+ <filename>logs/foo.log</filename>
+ <format type="extended">
+%7.7{priority} %5.5{time}: %{message}\n%{throwable}
+ </format>
+ </file>
+ </priority-filter>
+ </targets>
- <categories>
- <category name="cocoon" log-level="INFO">
- <log-target id-ref="root"/>
+ <categories>
+ <category name="cocoon" log-level="INFO">
+ <log-target id-ref="root"/>
- <category name="classloader" log-level="DEBUG">
- <log-target id-ref="classloader"/>
- </category>
- </category>
- <category name="foo" log-level="DEBUG">
- <log-target id-ref="foo"/>
- </category>
- </categories>
- </logkit>
+ <category name="classloader" log-level="DEBUG">
+ <log-target id-ref="classloader"/>
+ </category>
+ </category>
+ <category name="foo" log-level="DEBUG">
+ <log-target id-ref="foo"/>
+ </category>
+ </categories>
+ </logkit>
]]>
</source>
<p>
- As you've seen the configuration file for the LokKit
- Management System has three sections (beside the
- root element which is <logkit>).
+ As you've seen the configuration file for excalibur-logger when used
+ with logkit has three sections (beside the root element).
</p>
<dl>
<dt><factories></dt>
<dd>
- The factories section defines the
+ The factories section defines the
<code>LogTargetFactory</code>s
- that are used to create the needed
+ that are used to create the needed
<code>LogTargets</code>. You'll
- find the factories available in the
- <code>org.apache.avalon.excalibur.logger.factory</code>
- package. You can write your own factories which
+ find the factories available in the
+ <code>org.apache.avalon.excalibur.logger.factory</code>
+ package. You can write your own factories which
only needs to implement the
<code>org.apache.avalon.excalibur.logger.LogTargetFactory</code>
- interface or you extend one of the available factories
+ interface or you extend one of the available factories
in the mentioned package.
</dd>
<dt><targets></dt>
<dd>
- The targets section defines the individual
+ The targets section defines the individual
<code>LogTargets</code>.
- The element name of a target definition corresponds
- to a type attribute of a <factory> element. You'll
- probably need to consult the javadocs of the corresponding
- factory to get familiar with the configuration
+ The element name of a target definition corresponds
+ to a type attribute of a <factory> element. You'll
+ probably need to consult the javadocs of the corresponding
+ factory to get familiar with the configuration
options available for a particular target.
</dd>
<dt><categories></dt>
<dd>
- The categories section finally assembles all together. The
- name attribute of a category gives the reference used in
- logger attribute in the components configuration files.
- The log-level attribute gives the logging priority to the
- <code>Logger</code> of that category. <category>
- elements have <log-targets> children which, you
- already guessed, defines the <code>LogTarget</code>s
- for a particular logging category. You'll also see in the
+ The categories section finally assembles all together. The
+ name attribute of a category gives the reference used in
+ logger attribute in the components configuration files.
+ The log-level attribute gives the logging priority to the
+ <code>Logger</code> of that category. <category>
+ elements have <log-targets> children which, you
+ already guessed, defines the <code>LogTarget</code>s
+ for a particular logging category. You'll also see in the
sample above that category elements can be nested to define
- sub-categories.
+ sub-categories.
</dd>
- </dl>
+ </dl>
</section>
- <section><title>Design principles and implementation details of the LogKit
Management System</title>
+ <section><title>Design principles and implementation details of
+ Excalibur-Logger</title>
<p>
The first abstraction is the <code>LogKitManager</code>:
</p>
@@ -135,11 +155,11 @@
}
</source>
<p>
- There is a implementation named <code>DefaultLogKitManager</code>
- which is the only class exposed to clients. As a convenient a
- additional interface is introduced for the
- <code>ComponentManager</code> (stolen from the role management
- system) which states that a class is willing to get a
+ There is a implementation named <code>DefaultLogKitManager</code>
+ which is the only class exposed to clients. As a convenient a
+ additional interface is introduced for the
+ <code>ComponentManager</code> (stolen from the role management
+ system) which states that a class is willing to get a
<code>LogKitManager</code>:
</p>
<source>
@@ -154,11 +174,11 @@
</p>
<p>
The <code>DefaultLogKitManager</code> is <code>Configurable</code>
- (as well as <code>Loggable</code> [the initial default logger] and
+ (as well as <code>Loggable</code> [the initial default logger] and
<code>Contextualizable</code> [to pass along for ie.
- <code>ServletOutputLogTarget</code>]) and gets a
+ <code>ServletOutputLogTarget</code>]) and gets a
<code>Configuration</code> object as expressed in the logkit
- xml syntax above. This <code>DefaultLogKitManager</code> then uses
+ xml syntax above. This <code>DefaultLogKitManager</code> then uses
a object of type
</p>
<source>
@@ -168,12 +188,12 @@
}
</source>
<p>
- The <code>DefaultLogTargetFactoryManager</code> is
+ The <code>DefaultLogTargetFactoryManager</code> is
<code>Configurable</code> (as well as <code>Loggable</code> and
- <code>Contextualizable</code>) and gets the
+ <code>Contextualizable</code>) and gets the
<code>Configuration</code> object located at the <factories>
- element. It will instanciate the concrete factories into a map
- keyed by the type attribute. So we are at the
+ element. It will instanciate the concrete factories into a map
+ keyed by the type attribute. So we are at the
<code>LogTargetFactory</code> abstraction which is:
</p>
<source>
@@ -184,25 +204,26 @@
}
</source>
<p>
- It may happen that a <code>LogTargetFactory</code> needs to
- create <code>LogTarget</code>s they don't know in advance
+ It may happen that a <code>LogTargetFactory</code> needs to
+ create <code>LogTarget</code>s they don't know in advance
and thus an additional interface is needed:
</p>
<source>
public interface LogTargetFactoryManageable
{
- void setLogTargetFactoryManager( LogTargetFactoryManager
logTargetFactoryManager );
+ void setLogTargetFactoryManager(
+ LogTargetFactoryManager logTargetFactoryManager );
}
</source>
<p>
- This eases writing factories which acts like decorators
- (<code>AsyncLogTarget</code>, <code>PriorityFilter</code>)
+ This eases writing factories which acts like decorators
+ (<code>AsyncLogTarget</code>, <code>PriorityFilter</code>)
and thus need a LogTargetFactoryManager to create the decorated
- <code>LogTargets</code> which are embeded in the configuration
+ <code>LogTargets</code> which are embeded in the configuration
of them (see <priority-filter> above).
</p>
<p>
- After initializing the <code>LogTargetFactoryManager</code> a
+ After initializing the <code>LogTargetFactoryManager</code> a
<code>LogTargetManager</code>
</p>
<source>
@@ -212,41 +233,41 @@
}
</source>
<p>
- is created. The implementation <code>DefaultLogTargetManager</code>
- is, you guess it, <code>Configurable</code> (as well as
+ is created. The implementation <code>DefaultLogTargetManager</code>
+ is, you guess it, <code>Configurable</code> (as well as
<code>Loggable</code> and <code>Contextualizable</code>). The
- <code>Configuration</code> object is the <targets> element
- in the xml syntax and is put into a map keyed by the id
- attribute of the target element. It is also
- <code>LogTargetFactoryManageable</code> tob e able to create
+ <code>Configuration</code> object is the <targets> element
+ in the xml syntax and is put into a map keyed by the id
+ attribute of the target element. It is also
+ <code>LogTargetFactoryManageable</code> tob e able to create
the <code>LogTargets</code>.
</p>
<p>
- The last step of the <code>DefaultLogKitManagers</code> configure
- method is to create the actual categories based on the categories
- elements content. It does it as the syntax will show in a
- recursive way populating the Loggers retrieved by
+ The last step of the <code>DefaultLogKitManagers</code> configure
+ method is to create the actual categories based on the categories
+ elements content. It does it as the syntax will show in a
+ recursive way populating the Loggers retrieved by
<code>Hierarchy.getDefaultHierarchy().getLoggerFor( full_category )</code>
- with the denoted <code>LogTargets</code> from the
+ with the denoted <code>LogTargets</code> from the
<code>LogTargetManager</code>.
</p>
<p>
- After that the <code>LogKitManager</code> is ready to be asked
- for <code>Logger</code>s.
+ After that the <code>LogKitManager</code> is ready to be asked
+ for <code>Logger</code>s.
</p>
- <p>
- Now Avalon's Automated Component Management System is aware of a
- "magic attributes" named logger and used like
+ <p>
+ Now ECM is aware of a
+ "magic attributes" named logger and used like
<code>logger="category"</code> on the component definition syntax.
- The classes building up Avalon's Automated Component Management System
- are made <code>LogTargetFactoryManageable</code>. If you pass along
+ The classes building up ECM
+ are made <code>LogTargetFactoryManageable</code>. If you pass along
a <code>LogKitManager</code> to the <code>ExcaliburComponentManager</code>
- the Component Management System will retrieve the denoted logger
- category specified with the logger attribute from the
- <code>LogKitManager</code> and pass it to <code>Component</code>s
+ it will retrieve the denoted logger
+ category specified with the logger attribute from the
+ <code>LogKitManager</code> and pass it to <code>Component</code>s
implementing <code>Loggable</code>.
</p>
- </section>
+ </section>
</body>
<footer>
<legal>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
