<?php
/**
 * This file is part of the Logger library and defines a generic {@link Logger}
 * abstract class.
 * 
 * @author Sylvain Lequeux
 * @author Francois Daoust <fd@w3.org>
 * @package Logger
 * @version $Revision: 1.6 $
 * @license http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231.html W3C Software Notice and License
 * @copyright Copyright (c) 2009, W3C (MIT, ERCIM, Keio)
 */


/**
 * The Logger class is an abstract class that is intended to be used
 * in libraries that do no want to impose a particular logging format
 * and/or way of recording log messages.
 * 
 * The class also defines a couple of logs management functions to
 * retrieve and suppress logs.
 * 
 * All methods must be implemented in concrete subclasses.
 * 
 * @author Sylvain Lequeux
 * @author Francois Daoust <fd@w3.org>
 * @package Logger
 * @version $Revision: 1.6 $
 * @license http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231.html W3C Software Notice and License
 * @copyright Copyright (c) 2009, W3C (MIT, ERCIM, Keio)
 */
abstract class Logger{
	/**
	 * @var array(string) The set of levels to log (avoid 'all' value).
	 */
	protected $levels;
	
	/**
	 * Logs a message at the given level.
	 * 
	 * @param string $message_content The message to log.
	 * @param string $level Identifies the level 
	 */
	abstract public function add_message($message_content, $level='warning');
	
	/**
	 * Retrieves all messages logged at the requested level. 
	 * 
	 * @param string $level_value The level you are interested in. All the
	 *                            messages should be returned when value is 'all'.
	 *                            Default value is 'all'.
	 * @return array(Message) A set of messages.
	 */
	abstract public function retrieve_messages($level_value='all');
	
	/**
	 * Purges the logs of all the messages that are at the requested leve.
	 * 
	 * @param string $level_value The level to purge. All the messages are
	 *                            suppressed when value is 'all'.
	 *                            Default value is 'all'. 
	 */
	abstract public function clear_messages($level_value='all');
}


?>