<?php // vim:ts=4:sw=4:noet
/*====================================================================== 
Copyright (C) 2006-2009, Walter Doekes
This file is part of KjwLib-php45.
 
KjwLib-php45 is free software: you can redistribute it and/or modify 
it under the terms of the GNU General Public License as published by 
the Free Software Foundation, either version 3 of the License, or 
(at your option) any later version. 

KjwLib-php45 is distributed in the hope that it will be useful, 
but WITHOUT ANY WARRANTY; without even the implied warranty of 
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
GNU General Public License for more details. 

You should have received a copy of the GNU General Public License 
along with KjwLib-php45.  If not, see <http://www.gnu.org/licenses/>. 
======================================================================*/

require_once(dirname(__FILE__) . '/KjwLib.php');

static $kjw_object_count = 0;

/**
 * Everyone inherits from KjwObject.
 */
class KjwObject {
	var $_kjwobject_id = -1;			/**< The object identifier. So we can differentiate between objects. */
	var $_kjwobject_last_error;			/**< A last error message, if any. */
	
	/**
	 * The KjwObject.
	 */
	function __construct() {
		global $kjw_object_count;
		++$kjw_object_count;
		static $kjwobject_id = 0;
		$this->_kjwobject_id = ++$kjwobject_id;
		$this->_kjwobject_last_error = null;

		if (KJW_DEBUG)
			$this->trace("Creating " . $this->id() . ", total objects now = $kjw_object_count.", 'MEMORY');
	}

	/**
	 * Destructor performing cleanup.
	 * Don't rely on this being called ever. The user must call it by hand.
	 */
	function destroy() {
		global $kjw_object_count;
		--$kjw_object_count;
		if (KJW_DEBUG)
			$this->trace("Destroying " . $this->id() . ", total objects left = $kjw_object_count.", 'MEMORY');
	}
	
	/**
	 * Returns a string with a unique object id.
	 *
	 * @return The string "KjwObject(#N)" where N is a number.
	 */
	function id() {
		return 'KjwObject(#' . $this->_kjwobject_id . ')::' . get_class($this);
	}

	/**
	 * Set an error. XXX do we use this?
	 *
	 * @param $errorMessage The error message to be stored.
	 */
	function setError($errorMessage) {
		assert('is_string($errorMessage)');
		$this->trace("(transient) $errorMessage", 'ERROR');
		if ($this->_kjwobject_last_error === null)
			$this->_kjwobject_last_error = $errorMessage;
	}

	/**
	 * Get last error.
	 *
	 * @return The last stored error as string, or null if there was no error.
	 */
	function getError() {
		return $this->_kjwobject_last_error;
	}

	/**
	 * Die with an "Not implemented!" message. With this hack we can define
	 * abstract classes in PHP4.
	 */
	function notImplemented() {
		$this->croak('Library Component Error', 'Abstract method not implemented!');
	}

	/**
	 * Print a message to the resource pointed to by KJW_STDLOG.
	 *
	 * @param $msg The message to print.
	 * @param $level The message importance level (e.g. WARNING).
	 */
	function trace($msg, $level = 'DEBUG') {
		kjw_trace($msg, $level, $this->id());
	}

	/**
	 * See kjw_croak().
	 */
	function croak($shortMsg, $detailedMsg, $backtraceShift = 1) {
		kjw_croak($this->id(), $shortMsg, $detailedMsg, $backtraceShift);
	}
}