avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From leosim...@apache.org
Subject cvs commit: avalon-excalibur/logger/src/xdocs index.xml
Date Fri, 21 Feb 2003 21:19:59 GMT
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 &lt;logkit&gt;).
  +        As you've seen the configuration file for excalibur-logger when used
  +        with logkit has three sections (beside the root element).
         </p>
         <dl>
           <dt>&lt;factories&gt;</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>&lt;targets&gt;</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 &lt;factory&gt; 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 &lt;factory&gt; 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>&lt;categories&gt;</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. &lt;category&gt; 
  -          elements have &lt;log-targets&gt; 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. &lt;category&gt;
  +          elements have &lt;log-targets&gt; 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 &lt;factories&gt;
  -        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 &lt;priority-filter&gt; 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 &lt;targets&gt; 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 &lt;targets&gt; 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: cvs-unsubscribe@avalon.apache.org
For additional commands, e-mail: cvs-help@avalon.apache.org


Mime
View raw message