class.LockManager.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.LockManager.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.Message.php");
require_once(BASE."wcmf/lib/util/class.InifileParser.php");
require_once(BASE."wcmf/lib/util/class.SessionData.php");
require_once(BASE."wcmf/lib/persistence/class.PersistenceFacade.php");
require_once(BASE."wcmf/lib/persistence/class.NullLockManager.php");
require_once(BASE."wcmf/lib/persistence/class.Lock.php");
require_once(BASE."wcmf/lib/security/class.RightsManager.php");
require_once(BASE."wcmf/lib/util/class.ObjectFactory.php");

/**
 * @class LockManager
 * @ingroup Persistence
 * @brief LockManager is used to handle lock requests on objects.
 *
 * This class defines abstract methods that subclasses must implement to support
 * different lock storages.
 *
 * @author      ingo herwig <ingo@wemove.com>
 */
class LockManager
{
  /**
   * Returns an instance of the class.
   * @return A reference to the only instance of the Singleton object
   */  
  function &getInstance()
  {
    static $instance = null;

    $parser = &InifileParser::getInstance();
    $locking = $parser->getValue('locking', 'cms');
    if ($locking)
    {
      if (!is_object($instance) )
      {
        // if the application runs in anonymous mode, locking is not supported
        $anonymous = $parser->getValue('anonymous', 'cms');
        if ($anonymous)
        {
          require_once(BASE."wcmf/lib/persistence/class.NullLockManager.php");
          $instance = new NullLockManager();
        }
        else
        {
          $objectFactory = &ObjectFactory::getInstance();
          $instance = &$objectFactory->createInstanceFromConfig('implementation', 'LockManager');
          if ($instance === null)
            WCMFException::throwEx($objectFactory->getErrorMsg(), __FILE__, __LINE__);
        }
      }
      return $instance;
    }
    else
    {
      return new NullLockManager();
    }
  }
  /**
   * Lock a persistent object if it is not locked already and the current user 
   * is allowed to modify it. 
   * @note static method
   * @param object The object to lock
   * @param name The display name of the object
   * @return A message describing the problem if locking is not possible
   *         because another user holds the lock
   */
  function handleLocking(&$object, $name)
  {
    $lockMsg = "";

    if (strtolower(get_class($object)) == 'persistentobject' || is_a($object, 'PersistentObject'))
    {
      $lockManager = &LockManager::getInstance();
      $rightsManager = &RightsManager::getInstance();
      // check if we can edit the object
      if ($rightsManager->authorize($object->getOID(), '', ACTION_MODIFY))
      {
        // if object is locked by another user we retrieve the lock to show a message
        $lock = $object->getLock();
        if ($lock != null)
          $lockMsg .= $lockManager->getLockMessage($lock, $name).'<br />';
        else
        {
          // try to lock object
          $lockManager->aquireLock($object->getOID());
        }
      }
    }
    return $lockMsg;
  }
  /**
   * Aquire a lock on an OID for the current user.
   * @param oid object id of the object to lock.
   * @return True if successfull/False in case of an invalid oid or a Lock instance in case of an existing lock.
   */
  function aquireLock($oid)
  {
    if (!PersistenceFacade::isValidOID($oid)) 
      return false;
      
    $lock = $this->getLock($oid);
    if ($lock === null)
    {    
      $session = &SessionData::getInstance();
      $authUser = $this->getUser();
      if ($authUser != null)
      {
        $lock = new Lock($oid, $authUser->getOID(), $authUser->getLogin(), $session->getID());
        $this->aquireLockImpl($authUser->getOID(), $session->getID(), $oid, $lock->getCreated());
      }
    }
        return $lock;
  }
  /**
   * Release a lock on an OID for the current user.
   * @param oid object id of the object to release.
   */
  function releaseLock($oid)
  {
    if (!PersistenceFacade::isValidOID($oid)) 
      return false;
      
    $session = &SessionData::getInstance();
    $authUser = $this->getUser();
    if ($authUser != null)
      $this->releaseLockImpl($authUser->getOID(), $session->getID(), $oid);
  }
  /**
   * Release all locks on an OID regardless of the user.
   * @param oid object id of the object to release.
   */
  function releaseLocks($oid)
  {
    if (!PersistenceFacade::isValidOID($oid)) 
      return false;
      
    $this->releaseLockImpl(null, null, $oid);
  }
  /**
   * Release all lock for the current user.
   */
  function releaseAllLocks()
  {      
    $session = &SessionData::getInstance();
    $authUser = $this->getUser();
    if ($authUser != null)
      $this->releaseAllLocksImpl($authUser->getOID(), $session->getID());
  }
  /**
   * Get the default lock message for a lock.
   * @param lock The Lock instance to construct the message for.
   * @param objectText The display text for the locked object.
   * @return The lock message of the form 'objectText is locked by user 'admin' since 12:12:36<br />'.
   */
  function getLockMessage($lock, $objectText)
  {
    if ($objectText == '')
      $objectText = $lock->getOID();
    $msg = Message::get("%1% is locked by user '%2%' since %3%. ", array($objectText, $lock->getLogin(), strftime("%X", strtotime($lock->getCreated()))));
    //$msg .= '<a href="javascript:submitAction(\'unlock\')">'.Message::get("Click here to unlock the object").'.</a>';
    return $msg;
  }
  /**
   * Get lock data for an OID. This method may also be used to check for an lock.
   * @note The method uses the php parameter 'session.gc_maxlifetime' to determine if a lock belongs to an expired session. 
   * A lock with a creation date older than 'session.gc_maxlifetime' seconds is regarded to belong to an expired 
   * session which results in the removal of all locks attached to that session.
   * @param oid object id of the object to get the lock data for.
   * @return A Lock instance or null if no lock exists/or in case of an invalid oid.
   */
  function getLock($oid)
  {
    if (!PersistenceFacade::isValidOID($oid)) 
      return null;
     
    $lock = $this->getLockImpl($oid);

    // remove lock if session is expired
    if ($lock != null)
    {
      $lifeTimeInSeconds = (mktime() - strtotime($lock->getCreated()));
      if ($lifeTimeInSeconds > ini_get("session.gc_maxlifetime"))
      {
        $this->releaseLockImpl($lock->getUserOID(), $lock->getSessionID(), null);
        $lock = null;
      }
    }    
    return $lock; 
  }
  /**
   * Get the currently logged in user.
   * @return An instance of AuthUser.
   */
  function &getUser()
  {
    $rightsManager = &RightsManager::getInstance();
    return $rightsManager->getAuthUser();
  }
  /**
   * Aquire a lock on an OID for a given user.
   * @param useroid The oid of the user.
   * @param sessid The id of the session of the user.
   * @param oid object id of the object to lock.
   * @param lockDate date of the lock.
   */
  function aquireLockImpl($useroid, $sessid, $oid, $lockDate)
  {
    WCMFException::throwEx("aquireLockImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Release a lock on an OID for a given user or all locks for that user or all locks for the OID.
   * The behaviour depends on the given parameters. A null means that this parameter should be ignored
   * @param useroid The oid of the user or null to ignore the userid.
   * @param sessid The id of the session of the user or null to ignore the session id.
   * @param oid object id of the object to release or null top ignore the oid.
   */
  function releaseLockImpl($useroid, $sessid, $oid)
  {
    WCMFException::throwEx("releaseLockImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Release all lock for a given user.
   * @param useroid The oid of the user.
   * @param sessid The id of the session of the user.
   */
  function releaseAllLocksImpl($useroid, $sessid)
  {      
    WCMFException::throwEx("releaseAllLocks() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Get lock data for an OID. This method may also be used to check for an lock.
   * @param oid object id of the object to get the lock data for.
   * @return A Lock instance or null if no lock exists/or in case of an invalid oid.
   */
  function getLockImpl($oid)
  {
    WCMFException::throwEx("getLockImpl() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
}
?>