avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hamm...@apache.org
Subject cvs commit: jakarta-avalon-excalibur/logger/src/xdocs index.xml
Date Fri, 05 Apr 2002 05:33:24 GMT
hammant     02/04/04 21:33:24

  Modified:    logger/src/xdocs index.xml
  Log:
  Contents of xdocs moved to new location
  
  Revision  Changes    Path
  1.3       +253 -20   jakarta-avalon-excalibur/logger/src/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/logger/src/xdocs/index.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- index.xml	4 Apr 2002 20:18:55 -0000	1.2
  +++ index.xml	5 Apr 2002 05:33:24 -0000	1.3
  @@ -1,24 +1,257 @@
   <?xml version="1.0"?>
   
   <document>
  -    <header>
  -        <title>Excalibur - TestCase Utilities</title>
  -        <authors>
  -            <person name="Peter Donald" email="peter@apache.org"/>
  -            <person name="Leif Mortenson" email="leif@tanukisoftware.com"/>
  -        </authors>
  -    </header>
  -    <body>
  -        <s1 title="Introduction">
  -            <p>
  -            This project contains utilities which can be used to write Excalibur Test Cases.
  -            </p>
  -        </s1>
  -    </body>
  -    <footer>
  -        <legal>
  -          Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
  -          $Revision: 1.2 $ $Date: 2002/04/04 20:18:55 $
  -        </legal>
  -    </footer>
  +  <header>
  +    <title>Excalibur - Logger</title>
  +      <authors>
  +      <person name="Giacomo Pati" email="giacomo@apache.org"/>
  +      </authors>
  +  </header>
  +  <body>
  +    <s1 title="Introduction">
  +      <p>
  +        Find Avalon Excalibur's LogKit 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 
  +        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>).
  +      </p>
  +    </s1>
  +    <s1 title="Example configurations">
  +      <p>
  +        Look at this example of a component definition:
  +      </p>
  +      <source>
  +        <![CDATA[
  +          <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:
  +      </p>
  +      <source>
  +        <![CDATA[
  +          <?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>
  +
  +            <targets>
  +              <file id="root">
  +                <filename>lolo/${current-dir}/lala/${foo}/logs/main.log</filename>
  +                <format type="exteded">
  +                  %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"/>
  +
  +                <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;).
  +      </p>
  +      <dl>
  +        <dt>&lt;factories&gt;</dt>
  +        <dd>
  +          The factories section defines the 
  +          <code>LogTargetFactory</code>s
  +          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 
  +          only needs to implement the
  +          <code>org.apache.avalon.excalibur.logger.LogTargetFactory</code>
  +          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 
  +          <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 
  +          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 
  +          sample above that category elements can be nested to define
  +          sub-categories. 
  +        </dd>
  +      </dl>   
  +    </s1>
  +    <s1 title="Design principles and implementation details of the LogKit Management
System">
  +      <p>
  +        The first abstraction is the <code>LogKitManager</code>:
  +      </p>
  +      <source>
  +        public interface LogKitManager
  +        {
  +            Logger getLogger( String categoryName );
  +        }
  +      </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 
  +        <code>LogKitManager</code>:
  +      </p>
  +      <source>
  +        public interface LogKitManageable
  +        {
  +            void setLogKitManager( LogKitManager logmanager );
  +        }
  +      </source>
  +      <p>
  +        This method has to be called before the configure method but after the
  +        contextualize method.
  +      </p>
  +      <p>
  +        The <code>DefaultLogKitManager</code> is <code>Configurable</code>
  +        (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>Configuration</code> object as expressed in the logkit
  +        xml syntax above. This <code>DefaultLogKitManager</code> then uses

  +        a object of type
  +      </p>
  +      <source>
  +        public interface LogTargetFactoryManager
  +        {
  +            LogTargetFactory getLogTargetFactory( String factoryName );
  +        }
  +      </source>
  +      <p>
  +        The <code>DefaultLogTargetFactoryManager</code> is 
  +        <code>Configurable</code> (as well as <code>Loggable</code>
and
  +        <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 
  +        <code>LogTargetFactory</code> abstraction which is:
  +      </p>
  +      <source>
  +        public interface LogTargetFactory
  +        {
  +            LogTarget createTarget( Configuration configuration )
  +                throws ConfigurationException;
  +        }
  +      </source>
  +      <p>
  +        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
);
  +        }
  +      </source>
  +      <p>
  +        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 
  +        of them (see &lt;priority-filter&gt; above).
  +      </p>
  +      <p>
  +        After initializing the <code>LogTargetFactoryManager</code> a 
  +        <code>LogTargetManager</code>
  +      </p>
  +      <source>
  +        public interface LogTargetManager
  +        {
  +            LogTarget getLogTarget( String targetId );
  +        }
  +      </source>
  +      <p>
  +        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 
  +        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 
  +        <code>Hierarchy.getDefaultHierarchy().getLoggerFor( full_category )</code>
  +        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. 
  +      </p>
  +      <p> 
  +        Now Avalon's Automated Component Management System 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

  +        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

  +        implementing <code>Loggable</code>.
  +      </p>
  +    </s1>    
  +  </body>
  +  <footer>
  +    <legal>
  +      Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
  +      $Revision: 1.3 $ $Date: 2002/04/05 05:33:24 $
  +    </legal>
  +  </footer>
   </document>
  
  
  

--
To unsubscribe, e-mail:   <mailto:avalon-cvs-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@jakarta.apache.org>


Mime
View raw message