class.PersistenceFacadeImpl.php

Go to the documentation of this file.

<?php
/**
 * wCMF - wemove Content Management Framework
 * Copyright (C) 2005-2014 wemove digital solutions GmbH
 *
 * Licensed under the terms of any of the following licenses
 * at your choice:
 *
 * - GNU Lesser General Public License (LGPL)
 *   http://www.gnu.org/licenses/lgpl.html
 * - Eclipse Public License (EPL)
 *   http://www.eclipse.org/org/documents/epl-v10.php
 *
 * See the license.txt file distributed with this work for
 * additional information.
 *
 * $Id: class.PersistenceFacade.php 1079 2009-09-08 15:21:33Z iherwig $
 */
require_once(BASE."wcmf/lib/core/class.WCMFException.php");
require_once(BASE."wcmf/lib/util/class.Log.php");
require_once(BASE."wcmf/lib/util/class.InifileParser.php");
require_once(BASE."wcmf/lib/output/class.OutputStrategy.php");
require_once(BASE."wcmf/lib/persistence/class.PersistenceMapper.php");
require_once(BASE."wcmf/lib/persistence/class.ObjectQuery.php");
require_once(BASE."wcmf/lib/persistence/class.StringQuery.php");
require_once(BASE."wcmf/lib/persistence/class.PagingInfo.php");
require_once(BASE."wcmf/lib/persistence/class.ChangeListener.php");

/**
 * @class PersistenceFacadeImpl
 * @ingroup Persistence
 * @brief PersistenceFacadeImpl delegates persistence operations to the type-specific PersistenceMappers.
 *
 * @note The OID parameter must provide enough information to select the appropriate mapper.
 *       This may be achived by different strategies, e.g. coding the object type into the
 *       OID or having a global registry which maps OIDs to objects. wCMF uses the first method.
 *       The OID is a string in order to make it easier to serialize it in HTML forms. The following
 *       notation is used: type:id1:id2:... where type is the object type and id1, id2, .. are the
 *       values of the primary key columns (in case of simple keys only one). PersistenceFacade provides
 *       methods to handle OIDs (composeOID(), decomposeOID(), ...)
 *
 *
 * @author      ingo herwig <ingo@wemove.com>
 */
class PersistenceFacadeImpl extends ChangeListener
{
  var $_mapperObjects = array();
  var $_createdOIDs = array();
  var $_dbConnections = array();
  var $_cache = array();
  var $_logging = false;
  var $_logStrategy = null;
  var $_isReadOnly = false;
  var $_isCaching = false;
  var $_inTransaction = false;

  /**
   * Prevent anything to be stored in the session
   */
  function __sleep() {}
  /**
   * Load an object from the database.
   * @param oid OID of the object to construct
   * @param buildDepth One of the BUILDDEPTH constants or a number describing the number of generations to build (except BUILDDEPTH_REQUIRED)
   * @param buildAttribs An assoziative array listing the attributes to load (default: null loads all attributes)
   *        (keys: the types, values: an array of attributes of the type to load)
   *        Use this to load only a subset of attributes
   * @param buildTypes An array listing the (sub-)types to include
   * @return A reference to the object, null if oid does not exist or a given condition prevents loading.
   */
  function &load($oid, $buildDepth, $buildAttribs=null, $buildTypes=null)
  {
    if ($buildDepth < 0 && !in_array($buildDepth, array(BUILDDEPTH_INFINITE, BUILDDEPTH_SINGLE)))
        WCMFException::throwEx("Build depth not supported: $buildDepth", __FILE__, __LINE__);

    $obj = null;

    // lookup the object in the cache
    if ($this->_isCaching)
    {
      $cacheKey = $this->getCacheKey($oid, $buildDepth, $buildAttribs, $buildTypes);
      if (isset($this->_cache[$cacheKey]))
      {
        $obj = &$this->_cache[$cacheKey];
      }
    }

    // if not cached, load
    if ($obj == null)
    {
      $oidParts = PersistenceFacade::decomposeOID($oid);
      $mapper = &$this->getMapper($oidParts['type']);
      if ($mapper != null)
        $obj = &$mapper->load($oid, $buildDepth, $buildAttribs, $buildTypes);

      if ($obj != null)
      {
        // prepare the object (readonly/locked)
        if ($this->_isReadOnly)
          $obj->setImmutable();

        // cache the object
        if ($this->_isCaching)
        {
          $cacheKey = $this->getCacheKey($oid, $buildDepth, $buildAttribs, $buildTypes);
          $this->_cache[$cacheKey] = &$obj;
        }
      }
    }
    return $obj;
  }
  /**
   * Construct the template of an Object of a given type.
   * @param type The type of object to build
   * @param buildDepth One of the BUILDDEPTH constants or a number describing the number of generations to build
   * @param buildAttribs An assoziative array listing the attributes to create (default: null creates all attributes)
   *        (keys: the types, values: an array of attributes of the type to create)
   *        Use this to create only a subset of attributes
   * @return A reference to the object.
   */
  function &create($type, $buildDepth, $buildAttribs=null)
  {
    if ($buildDepth < 0 && !in_array($buildDepth, array(BUILDDEPTH_INFINITE, BUILDDEPTH_SINGLE, BUILDDEPTH_REQUIRED)))
        WCMFException::throwEx("Build depth not supported: $buildDepth", __FILE__, __LINE__);

    $obj = null;
    $mapper = &$this->getMapper($type);
    if ($mapper != null)
    {
      $obj = &$mapper->create($type, $buildDepth, $buildAttribs);

      // register as change listener to track the created oid, after save
      $obj->addChangeListener($this);
    }

    return $obj;
  }
  /**
   * Save an object to the database (inserted if it is new).
   * @param object A reference to the object to save
   * @return True/False depending on success of operation
   */
  function save(&$object)
  {
    if ($this->_isReadOnly)
      return true;

    $result = false;
    $mapper = &$object->getMapper();
    if ($mapper != null)
      $result = $mapper->save($object);
    return $result;
  }
  /**
   * Delete an object from the database (together with all of its children).
   * @param oid The object id of the object to delete
   * @param recursive True/False whether to physically delete it's children too [default: true]
   * @return True/False depending on success of operation
   */
  function delete($oid, $recursive=true)
  {
    if ($this->_isReadOnly)
      return true;

    $result = false;
    $oidParts = PersistenceFacade::decomposeOID($oid);
    $mapper = &$this->getMapper($oidParts['type']);
    if ($mapper != null)
      $result = $mapper->delete($oid, $recursive);
    return $result;
  }
  /**
   * Get the object ids of newly created objects of a given type.
   * @param type The type of the object
   * @return An array containing the objects ids
   */
  function getCreatedOIDs($type)
  {
    if (!isset($this->_createdOIDs[$type]))
      return $this->_createdOIDs[$type];
    return array();
  }
  /**
   * Get the object id of the last created object of a given type.
   * @param type The type of the object
   * @return The object id or null
   */
  function getLastCreatedOID($type)
  {
    if (isset($this->_createdOIDs[$type]) && sizeof($this->_createdOIDs[$type]) > 0)
      return $this->_createdOIDs[$type][sizeof($this->_createdOIDs[$type])-1];
    return null;
  }
  /**
   * Get the object ids of objects matching a given criteria. If a PagingInfo instance is passed it will be used and updated.
   * @param type The type of the object
   * @param criteria An assoziative array holding name value pairs of attributes for selecting objects or a single string
   *        representing a (mapper specific) query condition (maybe null). [default: null]
   * @param orderby An array holding names of attributes to order by (maybe null). [default: null]
   * @param pagingInfo A reference PagingInfo instance (optional, default null does not work in PHP4).
   * @return An array containing the objects ids
   */
  function getOIDs($type, $criteria=null, $orderby=null, &$pagingInfo)
  {
    $result = array();
    $mapper = &$this->getMapper($type);
    if ($mapper != null)
      $result = $mapper->getOIDs($type, $criteria, $orderby, $pagingInfo);
    return $result;
  }
  /**
   * @deprecated use getOIDs() instead
   */
  function getOIDsEx($type, $where=null, $orderby=null, &$pagingInfo)
  {
    Log::error("use of deprecated method getOIDsEx. use getOIDs() instead.\n".WCMFException::getStackTrace(), __CLASS__);
  }
  /**
   * Get the first object id of objects matching a given condition. If a PagingInfo instance is passed it will be used and updated.
   * @param type The type of the object
   * @param criteria An assoziative array holding name value pairs of attributes for selecting objects or a single string
   *        representing a (mapper specific) query condition (maybe null). [default: null]
   * @param orderby An array holding names of attributes to ORDER by (maybe null). [default: null]
   * @param pagingInfo A reference PagingInfo instance (optional, default null does not work in PHP4).
   * @return An object id or null
   */
  function getFirstOID($type, $criteria=null, $orderby=null, &$pagingInfo)
  {
    $oids = $this->getOIDs($type, $criteria, $orderby, $pagingInfo);
    if (sizeof($oids) > 0)
      return $oids[0];
    else
      return null;
  }
  /**
   * @deprecated use getFirstOID() instead
   */
  function getFirstOIDEx($type, $where=null, $orderby=null, &$pagingInfo)
  {
    Log::error("use of deprecated method getFirstOIDEx. use getFirstOID() instead.\n".WCMFException::getStackTrace(), __CLASS__);
  }
  /**
   * Load the objects matching a given condition. If a PagingInfo instance is passed it will be used and updated.
   * @param type The type of the object
   * @param buildDepth One of the BUILDDEPTH constants or a number describing the number of generations to build (except BUILDDEPTH_REQUIRED)
   * @param criteria An assoziative array holding name value pairs of attributes for selecting objects or a single string
   *        representing a (mapper specific) query condition (maybe null). [default: null]
   * @param orderby An array holding names of attributes to ORDER by (maybe null). [default: null]
   * @param pagingInfo A reference PagingInfo instance (optional, default null does not work in PHP4).
   * @param buildAttribs An assoziative array listing the attributes to load (default: null loads all attributes)
   *        (keys: the types, values: an array of attributes of the type to load)
   *        Use this to load only a subset of attributes
   * @param buildTypes An array listing the (sub-)types to include
   * @return An array containing the objects
   */
  function loadObjects($type, $buildDepth, $criteria=null, $orderby=null, &$pagingInfo, $buildAttribs=null, $buildTypes=null)
  {
    $result = array();
    $mapper = &$this->getMapper($type);
    if ($mapper != null)
      $result = $mapper->loadObjects($type, $buildDepth, $criteria, $orderby, $pagingInfo, $buildAttribs, $buildTypes);
    return $result;
  }
  /**
   * Load the first object matching a given condition. If a PagingInfo instance is passed it will be used and updated.
   * @param type The type of the object
   * @param buildDepth One of the BUILDDEPTH constants or a number describing the number of generations to build (except BUILDDEPTH_REQUIRED)
   * @param criteria An assoziative array holding name value pairs of attributes for selecting objects or a single string
   *        representing a (mapper specific) query condition (maybe null). [default: null]
   * @param orderby An array holding names of attributes to ORDER by (maybe null). [default: null]
   * @param pagingInfo A reference PagingInfo instance (optional, default null does not work in PHP4).
   * @param buildAttribs An assoziative array listing the attributes to load (default: null loads all attributes)
   *        (keys: the types, values: an array of attributes of the type to load)
   *        Use this to load only a subset of attributes
   * @param buildTypes An array listing the (sub-)types to include
   * @return A reference to the object or null
   */
  function &loadFirstObject($type, $buildDepth, $criteria=null, $orderby=null, &$pagingInfo, $buildAttribs=null, $buildTypes=null)
  {
    $objects = $this->loadObjects($type, $buildDepth, $criteria, $orderby, $pagingInfo, $buildAttribs, $buildTypes);
    if (sizeof($objects) > 0)
      return $objects[0];
    else
      return null;
  }
  /**
   * Start a transaction. Used for PersistenceMapper classes that need to explicitely start and commit transactions.
   * If this method is called, the startTransaction() method of every used PersistenceMapper will be called - until
   * commitTransaction() is called.
   * @note There is only ONE transaction active at a time. Repeated calls of this method will leave the initial
   * transaction active until commitTransaction() ore rollbackTransaction() is called.
   */
  function startTransaction()
  {
    if (!$this->_inTransaction)
    {
      // log action
      if ($this->isLogging())
        Log::debug("Start Transaction", __CLASS__);

      // end transaction for every mapper
      $mapperEntries = array_keys($this->_mapperObjects);
      for ($i=0; $i<sizeof($mapperEntries); $i++)
        $this->_mapperObjects[$mapperEntries[$i]]->startTransaction();

      $this->_inTransaction = true;
    }
  }
  /**
   * Commit the started transaction. Used for PersistenceMapper classes that need to explicitely start and commit transactions.
   * If this method is called, the commitTransaction() method of every used PersistenceMapper will be called.
   * @note There is only ONE transaction active at a time. Repeated calls of this method will do nothing until
   * a new transaction was started by calling startTransaction().
   */
  function commitTransaction()
  {
    if ($this->_inTransaction)
    {
      // log action
      if ($this->isLogging())
        Log::debug("Commit Transaction", __CLASS__);

      // commit transaction for every mapper
      $mapperEntries = array_keys($this->_mapperObjects);
      for ($i=0; $i<sizeof($mapperEntries); $i++)
        $this->_mapperObjects[$mapperEntries[$i]]->commitTransaction();

      $this->_inTransaction = false;
    }
  }
  /**
   * Rollback the started transaction. Used for PersistenceMapper classes that need to explicitely start and commit transactions.
   * If this method is called, the rollbackTransaction() method of every used PersistenceMapper will be called.
   * @note There is only ONE transaction active at a time. Repeated calls of this method will do nothing until
   * a new transaction was started by calling startTransaction(). Rollbacks have to be supported by the data storage.
   */
  function rollbackTransaction()
  {
    if ($this->_inTransaction)
    {
      if ($this->isLogging())
        Log::debug("Rollback Transaction", __CLASS__);

      // rollback transaction for every mapper
      $mapperEntries = array_keys($this->_mapperObjects);
      for ($i=0; $i<sizeof($mapperEntries); $i++)
        $this->_mapperObjects[$mapperEntries[$i]]->rollbackTransaction();

      $this->_inTransaction = false;
    }
  }
  /**
   * Get the PersistenceMapper for a given type. If no mapper for this type is defined the mapper for type '*' will be returned
   * @param type The type of the object to get the PersistenceMapper for
   * @return A reference to the PersistenceMapper, null on error
   */
  function &getMapper($type)
  {
    $mapper = null;
    // find type-specific mapper
    if (!isset($this->_mapperObjects[$type]))
    {
      // first use
      // find mapper in configfile
      $parser = &InifileParser::getInstance();
      if (($mapperClass = $parser->getValue($type, 'typemapping')) === false)
      {
        if (($mapperClass = $parser->getValue('*', 'typemapping')) === false)
        {
          WCMFException::throwEx("No PersistenceMapper found in configfile for type '".$type."' in section 'typemapping'", __FILE__, __LINE__);
          return null;
        }
      }
      // find mapper class file
      $classFile = $this->getClassFile($parser, $mapperClass);
      // find mapper params
      $initParams = null;
      if (($initSection = $parser->getValue($mapperClass, 'initparams')) !== false)
      {
        if (($initParams = $parser->getSection($initSection)) === false)
        {
          WCMFException::throwEx("No '".$initSection."' section given in configfile.", __FILE__, __LINE__);
          return null;
        }
      }

      // if connection is already opened reuse it
      $connectionKey = join(':', array_values($initParams));
      if (isset($this->_dbConnections[$connectionKey]))
        $initParams = array('dbConnection' => &$this->_dbConnections[$connectionKey]);

      // see if class is already instantiated and reuse it if possible
      $isAlreadyInUse = false;
      $mapperObjects = array_values($this->_mapperObjects);
      for ($i=0; $i<sizeof($mapperObjects); $i++)
      {
        if (strtolower(get_class($mapperObjects[$i])) == strtolower($mapperClass))
        {
          $this->_mapperObjects[$type] = &$mapperObjects[$i];
          $isAlreadyInUse = true;
          break;
        }
      }

      // instantiate class if needed
      if (!$isAlreadyInUse)
      {
        if (file_exists(BASE.$classFile))
        {
          require_once(BASE.$classFile);
          if ($initParams)
            $mapperObj = new $mapperClass($initParams);
          else
            $mapperObj = new $mapperClass;
          $this->_mapperObjects[$type] = &$mapperObj;
        }
        else
        {
          WCMFException::throwEx("Definition of PersistanceMapper ".$mapperClass." in '".$classFile."' not found.", __FILE__, __LINE__);
          return null;
        }

        // lookup converter
        if (($converterClass = $parser->getValue($type, 'converter')) !== false ||
            ($converterClass = $parser->getValue('*', 'converter')) !== false)
        {
          $classFile = $this->getClassFile($parser, $converterClass);
          if ($classFile != null)
          {
            // instatiate class
            if (file_exists(BASE.$classFile))
            {
              require_once(BASE.$classFile);
              $converterObj = new $converterClass;
              $mapperObj->setDataConverter($converterObj);
            }
            else
            {
              WCMFException::throwEx("Definition of DataConverter ".$converterClass." in '".$classFile."' not found.", __FILE__, __LINE__);
              return null;
            }
          }
        }
      }
    }

    if (isset($this->_mapperObjects[$type]))
      $mapper = &$this->_mapperObjects[$type];
    else
      $mapper = &$this->_mapperObjects['*'];

    return $mapper;
  }
  /**
   * Get the class file name from the classmapping section of ini file
   * @param parser The ini file parser
   * @param className The class name
   * @return The class file name
   */
  function getClassFile($parser, $className)
  {
    if (($classFile = $parser->getValue($className, 'classmapping')) === false)
    {
      WCMFException::throwEx($parser->getErrorMsg(), __FILE__, __LINE__);
      return null;
    }
    return $classFile;
  }
  /**
   * Explicitly set a PersistentMapper for a type
   * @param type The type to set the mapper for
   * @param mapper A reference to the mapper
   */
  function setMapper($type, &$mapper)
  {
    $this->_mapperObjects[$type] = &$mapper;
  }
  /**
   * Store a connection for reuse
   * @param initParams The initParams used to initialize the conenction
   * @param connection A reference to the connection to save
   */
  function storeConnection($initParams, &$connection)
  {
    if ($connection != null)
    {
      $connectionKey = join(':', array_values($initParams));
      $this->_dbConnections[$connectionKey] = &$connection;
    }
  }
  /**
   * Set state to readonly. If set to true, PersistenceFacade will return only immutable
   * objects and save/delete methods are disabled.
   * @param isReadOnly True/False whether objects should be readonly or not
   */
  function setReadOnly($isReadOnly)
  {
    $this->_isReadOnly = $isReadOnly;
  }
  /**
   * Enable logging using a given OutputStrategy to log insert/update/delete actions to a file.
   * @param logStrategy The OutputStrategy to use.
   */
  function enableLogging($logStrategy)
  {
    $this->_logStrategy = $logStrategy;
    $mapperObjs = array_values($this->_mapperObjects);
    for($i=0, $count=sizeof($mapperObjs); $i<$count; $i++) {
      $mapperObjs[$i]->enableLogging($this->_logStrategy);
    }
    $this->_logging = true;
  }
  /**
   * Disable logging.
   */
  function disableLogging()
  {
    $mapperObjs = array_values($this->_mapperObjects);
    for($i=0, $count=sizeof($mapperObjs); $i<$count; $i++) {
      $mapperObjs[$i]->disableLogging();
    }
    $this->_logging = false;
  }
  /**
   * Check if the PersistenceMapper is logging.
   * @return True/False whether the PersistenceMapper is logging.
   */
  function isLogging()
  {
    return $this->_logging;
  }
  /**
   * Set state to caching. If set to true, PersistenceFacade will cache all loaded objects
   * and returns cached instances when calling the PersistenceFacade::load method.
   * @param isCaching True/False whether objects should be chached or not
   */
  function setCaching($isCaching)
  {
    $this->_isCaching = $isCaching;
  }
  /**
   * Clear the object cache
   */
  function clearCache()
  {
    $this->_cache = array();
  }
  /**
   * Get cache key from the given parameters
   * @param oid OID of the object
   * @param buildDepth One of the BUILDDEPTH constants
   * @param buildAttribs An assoziative array (@see PersistenceFacade::load)
   * @param buildTypes An array (@see PersistenceFacade::load)
   * @return The cache key string
   */
  function getCacheKey($oid, $buildDepth, $buildAttribs, $buildTypes)
  {
    $key = $oid.':'.$buildDepth.':';
    foreach($buildAttribs as $type => $attribs)
      $key .= $type.'='.join(',', $attribs).':';
    $key .= join(',', $buildTypes);
    return $key;
  }

  /**
   * ChangeListener interface implementation
   */

  /**
   * @see ChangeListener::getId()
   */
  function getId()
  {
    return __CLASS__;
  }
  /**
   * @see ChangeListener::valueChanged()
   */
  function valueChanged(&$object, $name, $type, $oldValue, $newValue) {}
  /**
   * @see ChangeListener::propertyChanged()
   */
  function propertyChanged(&$object, $name, $oldValue, $newValue) {}
  /**
   * @see ChangeListener::stateChanged()
   */
  function stateChanged(&$object, $oldValue, $newValue)
  {
    // store the object id in the internal registry if the object was saved after creation
    if ($oldValue == STATE_NEW && $newValue == STATE_CLEAN)
    {
      $type = $object->getType();
      if (!isset($this->_createdOIDs[$type]))
        $this->_createdOIDs[$type] = array();
      array_push($this->_createdOIDs[$type], $object->getOID());
    }
  }
}
?>