Excalibur - TestCase Utilities

Return-Path: Delivered-To: apmail-jakarta-avalon-cvs-archive@apache.org Received: (qmail 51425 invoked from network); 5 Apr 2002 05:33:28 -0000 Received: from unknown (HELO nagoya.betaversion.org) (192.18.49.131) by daedalus.apache.org with SMTP; 5 Apr 2002 05:33:28 -0000 Received: (qmail 21506 invoked by uid 97); 5 Apr 2002 05:33:37 -0000 Delivered-To: qmlist-jakarta-archive-avalon-cvs@jakarta.apache.org Received: (qmail 21490 invoked by uid 97); 5 Apr 2002 05:33:37 -0000 Mailing-List: contact avalon-cvs-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Avalon CVS List" Reply-To: "Avalon Developers List" Delivered-To: mailing list avalon-cvs@jakarta.apache.org Received: (qmail 21477 invoked by uid 97); 5 Apr 2002 05:33:37 -0000 Date: 5 Apr 2002 05:33:24 -0000 Message-ID: <20020405053324.51861.qmail@icarus.apache.org> From: hammant@apache.org To: jakarta-avalon-excalibur-cvs@apache.org Subject: cvs commit: jakarta-avalon-excalibur/logger/src/xdocs index.xml X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N 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 @@ -

- Excalibur - TestCase Utilities - - - - -

- - -

- This project contains utilities which can be used to write Excalibur Test Cases. -

- - - +

+ Excalibur - Logger + + + +

+ + +

+ Find Avalon Excalibur's LogKit Management System in the + org.apache.avalon.excalibur.logger 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 Component (given the + Component is Loggable). +

+ + +

+ Look at this example of a component definition: +

+ + + ]]> + +

+ And now let's have a look at a hypothetical LogKit Management configuration: +

+ + + + + + + + + + + + lolo/${current-dir}/lala/${foo}/logs/main.log + + %7.7{priority} %5.5{time} [%8.8{category}] (%{context}): %{message}\n%{throwable} + + true + + + logs/classloader.log + + + + + logs/foo.log + %7.7{priority} %5.5{time}: %{message}\n%{throwable} + + + + + + + + + + + + + + + + + + ]]> + +

+ As you've seen the configuration file for the LokKit + Management System has three sections (beside the + root element which is <logkit>). +

<factories>: + The factories section defines the + LogTargetFactorys + that are used to create the needed + LogTargets. You'll + find the factories available in the + org.apache.avalon.excalibur.logger.factory + package. You can write your own factories which + only needs to implement the + org.apache.avalon.excalibur.logger.LogTargetFactory + interface or you extend one of the available factories + in the mentioned package. +
<targets>: + The targets section defines the individual + LogTargets. + 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. +
<categories>: + 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 + Logger of that category. <category> + elements have <log-targets> children which, you + already guessed, defines the LogTargets + for a particular logging category. You'll also see in the + sample above that category elements can be nested to define + sub-categories. +

+ + +

+ The first abstraction is the LogKitManager: +

+ + public interface LogKitManager + { + Logger getLogger( String categoryName ); + } + +

+ There is a implementation named DefaultLogKitManager + which is the only class exposed to clients. As a convenient a + additional interface is introduced for the + ComponentManager (stolen from the role management + system) which states that a class is willing to get a + LogKitManager: +

+ + public interface LogKitManageable + { + void setLogKitManager( LogKitManager logmanager ); + } + +

+ This method has to be called before the configure method but after the + contextualize method. +

+ The DefaultLogKitManager is Configurable + (as well as Loggable [the initial default logger] and + Contextualizable [to pass along for ie. + ServletOutputLogTarget]) and gets a + Configuration object as expressed in the logkit + xml syntax above. This DefaultLogKitManager then uses + a object of type +

+ + public interface LogTargetFactoryManager + { + LogTargetFactory getLogTargetFactory( String factoryName ); + } + +

+ The DefaultLogTargetFactoryManager is + Configurable (as well as Loggable and + Contextualizable) and gets the + Configuration 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 + LogTargetFactory abstraction which is: +

+ + public interface LogTargetFactory + { + LogTarget createTarget( Configuration configuration ) + throws ConfigurationException; + } + +

+ It may happen that a LogTargetFactory needs to + create LogTargets they don't know in advance + and thus an additional interface is needed: +

+ + public interface LogTargetFactoryManageable + { + void setLogTargetFactoryManager( LogTargetFactoryManager logTargetFactoryManager ); + } + +

+ This eases writing factories which acts like decorators + (AsyncLogTarget, PriorityFilter) + and thus need a LogTargetFactoryManager to create the decorated + LogTargets which are embeded in the configuration + of them (see <priority-filter> above). +

+ After initializing the LogTargetFactoryManager a + LogTargetManager +

+ + public interface LogTargetManager + { + LogTarget getLogTarget( String targetId ); + } + +

+ is created. The implementation DefaultLogTargetManager + is, you guess it, Configurable (as well as + Loggable and Contextualizable). The + Configuration 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 + LogTargetFactoryManageable tob e able to create + the LogTargets. +

+ The last step of the DefaultLogKitManagers 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 + Hierarchy.getDefaultHierarchy().getLoggerFor( full_category ) + with the denoted LogTargets from the + LogTargetManager. +

+ After that the LogKitManager is ready to be asked + for Loggers. +

+ Now Avalon's Automated Component Management System is aware of a + "magic attributes" named logger and used like + logger="category" on the component definition syntax. + The classes building up Avalon's Automated Component Management System + are made LogTargetFactoryManageable. If you pass along + a LogKitManager to the ExcaliburComponentManager + the Component Management System will retrieve the denoted logger + category specified with the logger attribute from the + LogKitManager and pass it to Components + implementing Loggable. +

+ + + -- To unsubscribe, e-mail: For additional commands, e-mail: