Author: Raymond Bosman Date: 2006-01-13 10:00:23 +0100 (Fri, 13 Jan 2006) New Revision: 1808
Log: # Documented the new parts of EventLog. Added: packages/EventLog/trunk/src/interfaces/mapper.php Modified: packages/EventLog/trunk/src/log.php packages/EventLog/trunk/src/log_autoload.php packages/EventLog/trunk/src/mapper/filter_rule.php packages/EventLog/trunk/src/mapper/filterset.php Added: packages/EventLog/trunk/src/interfaces/mapper.php =================================================================== --- packages/EventLog/trunk/src/interfaces/mapper.php 2006-01-13 08:51:09 UTC (rev 1807) +++ packages/EventLog/trunk/src/interfaces/mapper.php 2006-01-13 09:00:23 UTC (rev 1808) @@ -0,0 +1,29 @@ +<?php +/** + * File containing the ezcLogMapper interface. + * + * @package EventLog + * @version //autogentag// + * @copyright Copyright (C) 2005, 2006 eZ systems as. All rights reserved. + * @license http://ez.no/licenses/new_bsd New BSD License + */ + +/** + * The ezcLogMapper provides a public interface to implement a mapper. + * + * @package EventLog + * @version //autogentag// + */ +interface ezcLogMapper +{ + /** + * Returns the containers (results) that are mapped to this $severity, $source, and $category. + * + * @param int $severity + * @param string $source + * @param string $category + * @return mixed + */ + public function get( $severity, $source, $category ); +} +?> Property changes on: packages/EventLog/trunk/src/interfaces/mapper.php ___________________________________________________________________ Name: svn:eol-style + native Modified: packages/EventLog/trunk/src/log.php =================================================================== --- packages/EventLog/trunk/src/log.php 2006-01-13 08:51:09 UTC (rev 1807) +++ packages/EventLog/trunk/src/log.php 2006-01-13 09:00:23 UTC (rev 1808) @@ -18,8 +18,8 @@ * * Extra writers can be added by implementing the the [EMAIL PROTECTED] ezcLogWriter} interface. * - * Use the [EMAIL PROTECTED] map()} method to attach an additional writer to the ezcLog - * class. This method filters incoming log messages with the [EMAIL PROTECTED] ezcLogFilter}. + * Use the [EMAIL PROTECTED] getMapper()} method to get an instance of the ezcLogMapper. + * The ezcLogMapper classes specifies incoming log messages with the [EMAIL PROTECTED] ezcLogFilter}. * Log messages that are accepted, match with the filter, are sent to the * [EMAIL PROTECTED] ezcLogWriter}. * @@ -30,7 +30,7 @@ * $filter->severity = ezcLog::INFO | ezcLog::NOTICE | ezcLog::WARNING | ezcLog::ERROR | ezcLog::FATAL; * * $log = ezcLog::getInstance(); - * $log->map( $filter, new ezcLogWriterUnixFile( "/tmp/logs/", "error.log" ) ); + * $log->getMapper()->appendRule( new ezcFilterRule( $filter, new ezcLogWriterUnixFile( "/tmp/logs/", "error.log" ), true ) ); * </code> * * The log messages with the severity: INFO, NOTICE, WARNING, ERROR, and FATAL will @@ -43,24 +43,13 @@ * $filter->severity = ezcLog::SUCCESS_AUDIT | ezcLog::FAILED_AUDIT; * * $log = ezcLog::getInstance(); - * $log->map( $filter, new ezcLogWriterDatabase( "audits" ) ); + * $log->getMapper()->appendRule( new ezcFilterRule( $filter, new ezcLogWriterDatabase( "audits" ), true ) ); * </code> * * The audit trails will be stored in the table "audits". See [EMAIL PROTECTED] ezcLogWriterDatabase} - * for creating the appropriate tables and setting up the database. + * for creating the appropriate tables and setting up the database. See the [EMAIL PROTECTED] ezcLogFilter} + * for more details. * - * It is also possible to exclude messages from going to a specific writer. - * This is done via the [EMAIL PROTECTED] unmap()} method. The following example shows - * how all messages, except for the DEBUG severity, are written to a file: - * <code> - * $fileWriter = ezcLogWriterUnixFile( "/tmp/logs/", "all.log" ); - * $filter = new ezcLogFilter(); - * $ezcLog::getInstance()->map( $filter, $fileWriter ); // All severities. - * - * $filter->severity = ezcLog::DEBUG; - * ezcLog::getInstance()->unmap( $filter, $fileWriter ); // Remove DEBUG severity. - * </code> - * * Use the [EMAIL PROTECTED] log()} method to log messages at the specified writers. This * method expects a: * - Message, contains a single log message. @@ -306,11 +295,25 @@ $this->setDefaults(); } - public function setMapper( $mapper ) + /** + * Sets the given ezcLogMapper $mapper as the log message to writer map. + * + * By default the ezcLogFilterSet is the default writer map. The default + * ezcLogMapper can be replaced with this method. + * + * @param ezcLogMapper $mapper + * @return void + */ + public function setMapper( ezcLogMapper $mapper ) { $this->writers = $mapper; } + /** + * Returns an instance of the current ezcLogMapper. + * + * return ezcLogMapper + */ public function getMapper() { return $this->writers; @@ -430,76 +433,6 @@ } /** - * Attaches the writer $writer with the filter $logFilter to this ezcLog. - * - * The log filter $logFilter describes which severities, categories, and - * sources are accepted by the writer $writer. Those messages that - * match are send to the writer. - * - * Multiple logFilters with their writer can be attached to the ezcLog class. - * Every log message will be sent to the writer for which the log filter matches. - * - * Available writers are: - * - [EMAIL PROTECTED] ezcLogWriterUnixFile Unix File} writer - * - [EMAIL PROTECTED] ezcLogWriterDatabase Database} writer - * - * Extra writers can be added by implementing the the [EMAIL PROTECTED] ezcLogWriter} interface. - * - * The following example maps the Unix file writer to all the log messages that - * are from the category "template", source "content_module" and severities - * WARNING, ERROR, or FATAL. - * <code> - * $f = new ezclogFilter(); - * $f->severity = ezcLog::WARNING | ezcLog::ERROR | ezcLog::FATAL; - * $f->source = "template"; - * $f->category = "content_module"; - * - * $w = new ezcLogWriterUnixFile("/tmp/logs/content_module/", "template.log" ); - * - * $ezcLog::getInstance()->map( $f, $w ); - * </code> - * - * See also [EMAIL PROTECTED] unmap()} - * - * @param ezcLogFilter $logFilter - * @param ezcLogWriter $writer - * @return void - */ -// public function map( ezcLogFilter $logFilter, ezcLogWriter $writer ) -// { -// $this->writers->map( $logFilter->severity, $logFilter->source, $logFilter->category, $writer ); -// } - - /** - * Detaches the writer $writer for specific log messages, specified by the log filter $logFilter. - * - * The log filter $logFilter describes which severities, categories, and - * sources are no longer accepted by the writer $writer. - * - * See the [EMAIL PROTECTED] map()} method for information about attaching a filter. - * - * The following example shows how to log all messages, except the debug message: - * <code> - * $fileWriter = ezcLogWriterUnixFile( "/tmp/logs/", "all.log" ); - * $filter = new ezcLogFilter(); - * $ezcLog::getInstance()->map( $filter, $fileWriter ); // All severities. - * - * $filter->severity = ezcLog::DEBUG; - * ezcLog::getInstance()->unmap( $filter, $fileWriter ); // Remove DEBUG severity. - * </code> - * - * See also [EMAIL PROTECTED] map()} - * - * @param ezcLogFilter $logFilter - * @param ezcLogWriter $writer - * @return void - */ -// public function unmap( ezcLogFilter $logFilter, ezcLogWriter $writer ) -// { -// $this->writers->unmap( $logFilter->severity, $logFilter->source, $logFilter->category, $writer ); -// } - - /** * Sets the attributes $attributes for a group of severities $severityMask. * * The severities are specified with a bit mask. These attributes will be Modified: packages/EventLog/trunk/src/log_autoload.php =================================================================== --- packages/EventLog/trunk/src/log_autoload.php 2006-01-13 08:51:09 UTC (rev 1807) +++ packages/EventLog/trunk/src/log_autoload.php 2006-01-13 09:00:23 UTC (rev 1808) @@ -1,6 +1,6 @@ <?php /** - * Autoloader definition for the Translation component. + * Autoloader definition for the EventLog component. * * @copyright Copyright (C) 2005, 2006 eZ systems as. All rights reserved. * @license http://ez.no/licenses/new_bsd New BSD License @@ -11,22 +11,24 @@ return array( 'ezcLog' => 'EventLog/log.php', - 'ezcLogFilterSet' => 'EventLog/mapper/filterset.php', + 'ezcLogContext' => 'EventLog/context.php', 'ezcLogMessage' => 'EventLog/log_message.php', + 'ezcLogWriter' => 'EventLog/interfaces/writer.php', + 'ezcLogMapper' => 'EventLog/interfaces/mapper.php', + + 'ezcLogFilter' => 'EventLog/structs/log_filter.php', + + 'ezcLogFilterSet' => 'EventLog/mapper/filterset.php', + 'ezcLogFilterRule' => 'EventLog/mapper/filter_rule.php', + 'ezcLogWriterFile' => 'EventLog/writers/writer_file.php', 'ezcLogWriterUnixFile' => 'EventLog/writers/writer_unix_file.php', 'ezcLogWriterDatabase' => 'EventLog/writers/writer_database.php', - 'ezcLogFilter' => 'EventLog/structs/log_filter.php', + 'ezcLogFileException' => 'EventLog/exceptions/file_exception.php', - 'ezcLogFilterRule' => 'EventLog/mapper/filter_rule.php', - - 'ezcLogMapper'=> 'EventLog/interfaces/mapper.php', - 'ezcLogWriterException'=> 'EventLog/exceptions/writer_exception.php' - - ); ?> Modified: packages/EventLog/trunk/src/mapper/filter_rule.php =================================================================== --- packages/EventLog/trunk/src/mapper/filter_rule.php 2006-01-13 08:51:09 UTC (rev 1807) +++ packages/EventLog/trunk/src/mapper/filter_rule.php 2006-01-13 09:00:23 UTC (rev 1808) @@ -10,6 +10,7 @@ */ /** + * The ezcLogFilterRule is a rule that is added to the ezcLogFilterSet. * * @package EventLog * @version //autogentag// @@ -18,22 +19,68 @@ class ezcLogFilterRule { /** + * The matching part of the ezcLogFilterRule + * * @var ezcLogFilter */ private $filter; + /** + * Should continue to the next filter if this rule matches? + * + * @var bool + */ private $continueProcessing; - private $writers; + /** + * The container that contains the result. + * + * @var array(mixed) + */ + private $container; + /** + * True if it matches all severities, otherwise false. + * + * @var bool + */ + private $severityStar = false; - private $severityStar = false; + /** + * True if it matches all sources, otherwise false. + * + * @var bool + */ private $sourceStar = false; - private $categoryStar = false; + /** + * True if it matches all categories, otherwise false. + * + * @var bool + */ + private $categoryStar = false; + + /** + * Internal structure for faster lookup. + * + * @var array(string=>mixed) + */ private $structure; - public function __construct( ezcLogFilter $filter, $writers, $continueProcessing ) + /** + * Creates an ezcLogFilterRule. + * + * The ezcLogFilter $filter is the matching part of this filter rule. See [EMAIL PROTECTED] get()}. + * The $container contains the value bound to the $filter, the result. + * If the filter matches, the boolean $continueProcessing indicates whether the next + * filter is processed. + * + * @param ezcLogFilter $filter + * @param mixed $container + * @param bool $continueProcessing + * @return void + */ + public function __construct( ezcLogFilter $filter, $container, $continueProcessing ) { $this->filter = clone( $filter ); @@ -55,11 +102,17 @@ } $this->continueProcessing = $continueProcessing; - $this->writers = ( is_array( $writers ) ? $writers : array( $writers ) ); + $this->container = ( is_array( $container ) ? $container : array( $container ) ); $this->createStructure(); } + /** + * Creates an internal structure, to quickly lookup the combination of severity, source, and + * categories. + * + * @return void + */ protected function createStructure() { $severities = $this->getMaskArray( $this->filter->severity ); @@ -82,6 +135,14 @@ } } + /** + * Returns true when the given $severity, $source, and $category matches with this filter rule. + * + * @param int $severity + * @param string $source + * @param string $category + * @return bool + */ public function isMatch( $severity, $source, $category ) { if( $this->severityStar ) @@ -103,11 +164,22 @@ return ( isset( $this->structure[ $key ] ) && $this->structure[ $key ] ); } - public function getWriters() + /** + * Returns the container, containing the result. + * + * @return mixed + */ + public function getContainer() { - return $this->writers; + return $this->container; } + /** + * Returns true if, after matching, should proceeded to the next filter rule. + * + * @return bool + */ + public function shouldContinueProcessing() { return $this->continueProcessing; Modified: packages/EventLog/trunk/src/mapper/filterset.php =================================================================== --- packages/EventLog/trunk/src/mapper/filterset.php 2006-01-13 08:51:09 UTC (rev 1807) +++ packages/EventLog/trunk/src/mapper/filterset.php 2006-01-13 09:00:23 UTC (rev 1808) @@ -10,7 +10,7 @@ */ /** - * Mapping of a mixed variable to an eventType, eventSource and eventCategory. + * Mapping of an eventType, eventSource and eventCategory to a mixed variable using a filter set. * * @package EventLog * @version //autogentag// @@ -18,28 +18,61 @@ */ class ezcLogFilterSet implements ezcLogMapper { + /** + * Rules of the filter set. + * + * var array(ezcLogFilterRule) + */ private $rules = array(); + /** + * Hash table that caches the [EMAIL PROTECTED] get()} queries to their results. + * + * var array(string=>mixed) + */ private $cache = array(); + /** + * Appends a rule to the end of the filter set. + * + * @param ezcLogFilter $filter + * @return void + */ public function appendRule( $filter ) { $this->rules[] = $filter; - $this->refreshCache(); + $this->clearCache(); } + /** + * Deletes the the last rule from the filter set. + * + * Returns false if the filter set is empty, otherwise true. + * + * @return bool + */ public function deleteLastRule() { if( sizeof( $this->rules ) > 0 ) { array_pop( $this->rules ); - $this->refreshCache(); + $this->clearCache(); return true; } return false; } + + /** + * Returns the variable assigned to the combination of a severity $severity, source $source, + * and category $category. + * + * @param int $severity + * @param string $source + * @param string $category + * @return mixed + */ public function get( $severity, $source, $category ) { // It is likely that the same type of log messages are written after each other. @@ -55,7 +88,7 @@ { if( $rule->isMatch( $severity, $source, $category ) ) { - $total = array_merge( $total, $rule->getWriters() ); + $total = array_merge( $total, $rule->getContainer() ); if( !$rule->shouldContinueProcessing() ) { @@ -69,11 +102,14 @@ return $total; } - protected function refreshCache() + /** + * Clears the cache. + * + * return void + */ + protected function clearCache() { $this->cache = array(); } - - } ?> -- svn-components mailing list [email protected] http://lists.ez.no/mailman/listinfo/svn-components
