class.PersistenceMapper.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.PersistenceMapper.php 1462 2014-02-04 23:52:27Z 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.Message.php");
require_once(BASE."wcmf/lib/security/class.RightsManager.php");
require_once(BASE."wcmf/lib/persistence/class.LockManager.php");
require_once(BASE."wcmf/lib/persistence/class.PersistenceFacade.php");

/**
 * @class PersistenceMapper
 * @ingroup Persistence
 * @brief PersistenceMapper is the base class for all mapper classes.
 *
 * @author      ingo herwig <ingo@wemove.com>
 */
class PersistenceMapper
{
  var $_dataConverter = null; // a DataConverter object that converts data before writing and after reading from storage
  var $_type = '';            // mapper type
  var $_logging = false;
  var $_logStrategy = null;

  /**
   * Get the mapper type.
   * @return Mapper type.
   */
  function getType()
  {
    return $this->_type;
  }
  /**
   * Get the names of the primary key values.
   * @return An associative array with the value names as keys and the types as values (see PersistentObject::getValue).
   */
  function getPkNames()
  {
    WCMFException::throwEx("getPkNames() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Set the DataConverter that should be used on load() and save().
   * @param dataConverter The DataConverter object.
   */
  function setDataConverter($dataConverter)
  {
    $this->_dataConverter = $dataConverter;
  }
  /**
   * Get the DataConverter that is used on load() and save().
   * @return The DataConverter object.
   */
  function getDataConverter()
  {
    return $this->_dataConverter;
  }
  /**
   * 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;
    $this->_logging = true;
  }
  /**
   * Disable logging.
   */
  function disableLogging()
  {
    $this->_logging = false;
  }
  /**
   * Check if the PersistenceMapper is logging.
   * @return True/False whether the PersistenceMapper is logging.
   */
  function isLogging()
  {
    return $this->_logging;
  }
  /**
   * Log action if logging is enabled.
   * @note Subclasses must call this method in save/delete method in appropriate place.
   * @param obj The object on which the action is performed on.
   */
  function logAction(&$obj)
  {
    if ($this->isLogging())
      $this->_logStrategy->writeObject($obj);
  }
  /**
   * 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 (!$this->checkAuthorization($oid, ACTION_READ))
    {
            $this->authorizationFailedError($oid, ACTION_READ);
      return;
    }

    if (!$this->isValidOID($oid))
      return null;

    // load object
    $object = &$this->loadImpl($oid, $buildDepth, $buildAttribs, $buildTypes);
    if ($object != null)
    {
      // set immutable if not authorized for modification
      if (!$this->checkAuthorization($oid, ACTION_MODIFY))
        $object->setImmutable();

      $this->initialize($object);

      // call custom initialization
      $object->afterLoad();
    }
    return $object;
  }
  /**
   * 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)
  {
    // Don't check rights here, because object creation may be needed
    // for internal purposes. That newly created objects may not be saved
    // to the storage is asured by the save method.
    $object = &$this->createImpl($type, $buildDepth, $buildAttribs);

    $this->initialize($object);

    // call custom initialization
    $object->afterCreate();

    return $object;
  }
  /**
   * Save an Object to the persistent storage.
   * @param object A reference to the object to safe
   * @return True/False depending on success of operation
   */
  function save(&$object)
  {
    if ( ($object->getState() == STATE_DIRTY) && !$this->checkAuthorization($object->getOID(), ACTION_MODIFY) )
    {
            $this->authorizationFailedError($object->getOID(), ACTION_MODIFY);
      return;
    }
    else if ( ($object->getState() == STATE_NEW) && !$this->checkAuthorization($object->getOID(), ACTION_CREATE) )
    {
            $this->authorizationFailedError($object->getOID(), ACTION_CREATE);
      return;
    }

    // modify object
    return $this->saveImpl($object);
  }
  /**
   * Delete an Object from the persistent storage.
   * @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->checkAuthorization($oid, ACTION_DELETE))
    {
            $this->authorizationFailedError($oid, ACTION_DELETE);
      return;
    }

    if (!$this->isValidOID($oid))
      return false;

    // delete oid
    $result = $this->deleteImpl($oid, $recursive);
    if ($result === true)
    {
      // release any locks on the object
      $lockManager = &LockManager::getInstance();
      $lockManager->releaseLocks($oid);
    }
    return $result;
  }
  /**
   * Check authorization on an type/OID and a given action.
   * @param oid The object id of the Object to authorize (its type will be checked too)
   * @param action Action to authorize
   * @return True/False depending on success of authorization
   */
  function checkAuthorization($oid, $action)
  {
    $rightsManager = &RightsManager::getInstance();
    if (!$rightsManager->authorize($oid, '', $action))
      return false;
    else
      return true;
  }
  function authorizationFailedError($oid, $action)
  {
    // when reading only log the error to avoid errors on the display
    $msg = Message::get("Authorization failed for action '%1%' on '%2%'.", array($action, $oid));
    if ($action == ACTION_READ)
      Log::error($msg."\n".WCMFException::getStackTrace(), __CLASS__);
    else
      WCMFException::throwEx($msg, __FILE__, __LINE__);
  }
  /**
   * Initialize the object after creation/loading and before handing it over to the application.
   * @note Subclasses may override this to implement special requirements (e.g. install listeners).
   * Remember to always call parent::initialize().
   * @param object A reference to the object
   */
  function initialize(&$object)
  {
  }
  /**
   * Validate a given OID.
   * @note Subclasses must implement this method
   * @param oid The OID of the object.
   * @return An True/False whether the OID is valid
   */
  function isValidOID($oid)
  {
    WCMFException::throwEx("isValidOID() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * @see PersistenceFacade::load()
   * @note Subclasses must implement the loading of an object from the storage in this method
   * @note Precondition: Object rights have been checked already
   *
   */
  function &loadImpl($oid, $buildDepth, $buildAttribs=null, $buildTypes=null)
  {
    WCMFException::throwEx("loadImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * @see PersistenceFacade::create()
   * @note Subclasses must implement the creation of an object in this method
   * @note Precondition: Object rights have been checked already
   */
  function &createImpl($type, $buildDepth, $buildAttribs=null)
  {
    WCMFException::throwEx("createImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * @see PersistenceFacade::save()
   * @note Subclasses must implement the modification of an object in the storage in this method
   * @note Precondition: Object rights have been checked already
   */
  function saveImpl(&$object)
  {
    WCMFException::throwEx("saveImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * @see PersistenceFacade::delete()
   * @note Subclasses must implement the deletion of an object from the storage in this method
   * @note Precondition: Object rights have been checked already
   */
  function deleteImpl($oid, $recursive=true)
  {
    WCMFException::throwEx("deleteImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * @see PersistenceFacade::getOIDs()
   * @note Subclasses must implement the retrieval of object ids from the storage in this method
   */
  function getOIDs($type, $criteria=null, $orderby=null, &$pagingInfo)
  {
    WCMFException::throwEx("getOIDs() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * @see PersistenceFacade::loadObjects()
   * @note Subclasses must implement the retrieval of objects from the storage in this method
   */
  function loadObjects($type, $buildDepth, $criteria=null, $orderby=null, &$pagingInfo, $buildAttribs=null, $buildTypes=null)
  {
    WCMFException::throwEx("loadObjects() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Get the names of the attributes to order by, when retrieving the oids.
   * ASC (ascending), DESC (descending) may be added to defined the order direction for each attribute.
   * @return An array of attribute names
   */
  function getOrderBy()
  {
    WCMFException::throwEx("getOrderBy() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * @see PersistenceFacade::startTransaction()
   * @note The default implementation does nothing. Subclasses may override this method if required
   */
  function startTransaction()
  {
  }
  /**
   * @see PersistenceFacade::commitTransaction()
   * @note The default implementation does nothing. Subclasses may override this method if required
   */
  function commitTransaction()
  {
  }
  /**
   * @see PersistenceFacade::rollbackTransaction()
   * @note The default implementation does nothing. Subclasses may override this method if required
   */
  function rollbackTransaction()
  {
  }
}
?>