class.PersistentObject.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.PersistentObject.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.Storable.php");
require_once(BASE."wcmf/lib/persistence/class.PersistenceMapper.php");
require_once(BASE."wcmf/lib/persistence/class.LockManager.php");
require_once(BASE."wcmf/lib/util/class.SearchUtil.php");

/**
 * Some constants describing the state of the PersistentObject
 */
define("STATE_CLEAN",   0);
define("STATE_DIRTY",   1);
define("STATE_NEW",     2);
define("STATE_DELETED", 3);

/**
 * Some constants describing the data types
 */
define("DATATYPE_DONTCARE",    0);
define("DATATYPE_ATTRIBUTE",   1);
define("DATATYPE_ELEMENT",     2);
define("DATATYPE_IGNORE",      3); // all data items >= DATATYPE_IGNORE wont be shown in human readable node discriptions

/**
 * @class PersistentObject
 * @ingroup Persistence
 * @brief PersistentObject is the base class of all persistent objects.
 * It implements the basic persistence methods (save(), delete())
 * which will be delegated to the PersistenceMapper class that contsructed the object.
 * The PersistentObject holds the object data in an associative array of the following structure:
 * @verbatim
 * datatype1---valueName1---value
 *                          properties---propertyName1---value
 *                                       propertyName2---value
 *                                       ...
 *             valueName2---value
 *                          properties---propertyName1---value
 *                                       ...
 *             ...
 * datatype2---valueName1---value
 *                          properties---propertyName1---value
 *                                       ...
 *             ...
 * ...
 *
 * e.g.: $this->_data[DATATYPE_ATTRIBUTE]['name']['value']                 gives the value of the attribute 'name' which is of app_data_type DATATYPE_ATTRIBUTE
 *       $this->_data[DATATYPE_ATTRIBUTE]['name']['properties']['visible'] gives the value of the visibility property of the
 *                                                                         attribute 'name'
 * @endverbatim
 * @author   ingo herwig <ingo@wemove.com>
 */
class PersistentObject extends Storable
{
  var $_oid = null;                // object identifier
  var $_type = '';                 // the object type
  var $_data = array();            // associative array holding the data
  var $_properties = array();      // associative array holding the properties
  var $_state = STATE_CLEAN;       // the state of the PersistentObject
  var $_isImmutable = false;       // immutable state
  var $_changeListeners = array(); // the change listeners

  /**
   * Constructor. The object will be bound to the appripriate PersistenceMapper automatically, if the
   * the PersistenceFacade knows the type.
   * @param type The object type.
   * @param oid The object id (, optional will be calculated if not given or not valid).
   */
  function PersistentObject ($type, $oid=null)
  {
    $this->_type = $type;

    // set oid and state
    if (!(isset($oid)) || !PersistenceFacade::isValidOID($oid))
    {
      // no oid is given -> new node
      $this->setOID(PersistenceFacade::composeOID(array('type' => $type)));
      $this->setState(STATE_NEW);
    }
    else
    {
      // old node
      $this->setOID($oid);
      $this->setState(STATE_CLEAN);
    }
  }
  /**
   * Get the type of the object.
   * @return The objects type.
   */
  function getType ()
  {
    return $this->_type;
  }
  /**
   * Set the type of the object.
   * @param type The objects type.
   */
  function setType ($type)
  {
    $this->_type = $type;
  }
  /**
   * Get the base type of the object. This might differ from the type, if the object may
   * exist in different roles and has one of these roles currently. The default implementation
   ' returns the object's type.
   * @return The objects base type.
   */
  function getBaseType ()
  {
    return $this->_type;
  }
  /**
   * Get the object id of the PersistentObject.
   * @return The PersistentObject's oid.
   */
  function getOID ()
  {
    return $this->_oid;
  }
  /**
   * Get the base object id of the PersistentObject (see PersistentObject::getBaseType()).
   * @return The PersistentObject's oid.
   */
  function getBaseOID ()
  {
    return PersistenceFacade::getBaseOID($this->getOID());
  }
  /**
   * Set the object id of the PersistentObject.
   * @param oid The PersistentObject's oid.
   */
  function setOID ($oid)
  {
    $mapper = &$this->getMapper();
    if ($mapper != null)
    {
      // update the primary key columns
      $oidParts = PersistenceFacade::decomposeOID($oid);
      $pkValues = $mapper->getPkNames();
      $pkNames = array_keys($pkValues);
      for ($i=0; $i<sizeof($pkNames); $i++) {
        $this->setValue($pkNames[$i], $oidParts['id'][$i], $pkValues[$pkNames[$i]], true);
      }
    }
    // set this afterwards, because setValue may have triggered updateOID
    $this->_oid = $oid;
  }
  /**
   * Get the id of the object in the persistent storage.
   * @note This is NOT a application unique id
   * @return The id.
   */
  function getDBID ()
  {
    $id = PersistenceFacade::getOIDParameter($this->_oid, 'id');
    return $id[0];
  }
  /**
   * Set the id of the object in the persistent storage.
   * @note This is NOT a application unique id
   * @param id The id.
   */
  function setDBID ($id)
  {
    $this->setOID(PersistenceFacade::composeOID(array('type' => $this->_type, 'id' => array($id))));
  }
  /**
   * Get the PersistenceMapper of the object.
   * @return A reference to a PersistenceMapper class
   */
  function &getMapper()
  {
    $mapper = null;

    // set the mapper, if defined in PersistenceFacade
    $persistenceFacade = &PersistenceFacade::getInstance();
    if (PersistenceFacade::isKnownType($this->_type)) {
      $mapper = &$persistenceFacade->getMapper($this->_type);
    }
    return $mapper;
  }
  /**
   * Get the DataConverter used when loading/saving values.
   * @return A reference to the dataConverter instance
   */
  function &getDataConverter()
  {
    $mapper = &$this->getMapper();
    if ($mapper != null) {
      return $mapper->getDataConverter();
    }
    return null;
  }
  /**
   * Save data. This call will be delegated to the PersistenceFacade class.
   */
  function save()
  {
    if (!$this->_isImmutable)
    {
      $oldState = $this->getState();
      // call before hook method
      if ($oldState == STATE_NEW) {
        $this->beforeInsert();
      }
      elseif ($oldState == STATE_DIRTY) {
        $this->beforeUpdate();
      }
      // save the object
      $persistenceFacade = &PersistenceFacade::getInstance();
      $persistenceFacade->save($this);

      // update search index
      SearchUtil::indexInSearch($this);

      // call after hook method
      if ($oldState == STATE_NEW) {
        $this->afterInsert();
      }
      elseif ($oldState == STATE_DIRTY) {
        $this->afterUpdate();
      }
    }
    else {
      WCMFException::throwEx(Message::get("Authorization failed for action '%1%' on '%2%'.", array(ACTION_MODIFY, $this->getOID())), __FILE__, __LINE__);
    }
  }
  /**
   * Delete data. This call will be delegated to the PersistenceFacade class.
   * @param recursive True/False whether to physically delete it's children too [default: true]
   */
  function delete($recursive=true)
  {
    if (!$this->_isImmutable)
    {
      // call before hook method
      $this->beforeDelete();

      // delete the object
      $persistenceFacade = &PersistenceFacade::getInstance();
      $persistenceFacade->delete($this->getOID(), $recursive);

      // remove from index
      SearchUtil::deleteFromSearch($this);

      // call after hook method
      $this->afterDelete();
    }
    else {
      WCMFException::throwEx(Message::get("Authorization failed for action '%1%' on '%2%'.", array(ACTION_DELETE, $this->getOID())), __FILE__, __LINE__);
    }
  }
  /**
   * Get the object's state:
   * @return One of the STATE constant values:
   */
  function getState ()
  {
    return $this->_state;
  }
  /**
   * Set the state of the object to one of the STATE constants.
   * @param recursive True/False [Default: True]
   * @note PersistentObject ignores the recursive parameter, but subclasses may use it
   */
  function setState ($state, $recursive=true)
  {
    $oldState = $this->_state;
    switch ($this->_state)
    {
      // new object must stay new when it's modified
      case STATE_NEW:
        switch ($state)
        {
          case STATE_DIRTY:
            $this->_state = STATE_NEW;
            break;

          default:
            $this->_state = $state;
        }
        break;

        // deleted object must stay deleted in every case
      case STATE_DELETED:
        $this->_state = STATE_DELETED;
        break;

      default:
        $this->_state = $state;
    }
    if ($oldState != $this->_state) {
      $this->propagateStateChange($oldState, $this->_state);
    }
  }
  /**
   * Set object immutable. Sets the editable property of each value to false.
   * and disables save/delete methods.
   * @note This operation is not reversible (reload the object to get a mutable one)
   */
  function setImmutable()
  {
    // set editable attribute of all values to false
    foreach($this->getDataTypes() as $type) {
      foreach($this->getValueNames($type) as $name) {
        $this->setValueProperty($name, 'is_editable', false, $type);
      }
    }
    $this->_isImmutable = true;
  }
  /**
   * Get the lock on the object.
   * @return lock The lock as provided by LockManager::getLock() or null if not locked
   * @note If the object is locked it's set immutable. This is not reversible
   * (reload the object to get a mutable one)
   */
  function getLock ()
  {
    $lockManager = &LockManager::getInstance();
    $lock = $lockManager->getLock($this->getOID());
    if ($lock != null) {
      $this->setImmutable();
    }
    return $lock;
  }
  /**
   * Get a copy of the object (ChangeListeners and Lock are not copied)
   * @return A reference to copy.
   */
  function &duplicate ()
  {
    $class = get_class($this);
    $copy = new $class;
    $copy->_oid = $this->_oid;
    $copy->_type = $this->_type;
    $copy->_data = $this->_data;
    $copy->_properties = $this->_properties;
    $copy->_state = $this->_state;
    $copy->_isImmutable = $this->_isImmutable;

    return $copy;
  }
  /**
   * Copy all non-empty values to a given instance (ChangeListeners are triggered)
   * @param object A reference to the PersistentObject to copy the values to.
   * @param dataTypes An array of datatypes. Only values of that datatypes will be copied.
   * Empty array means all datatypes [default:empty array]
   * @param copyPkValues True/False wether primary key values should be copied if their
   * datatype is included or not [default: true]
   */
  function copyValues (&$object, $dataTypes=array(), $copyPkValues=true)
  {
    $valuesToIgnore = array();
    if (!$copyPkValues) {
      $mapper = &$this->getMapper();
      if ($mapper) {
        $valuesToIgnore = $mapper->getPkNames();
      }
    }
    $processor = new NodeProcessor('copyValueIntern', array(&$object, $dataTypes, $valuesToIgnore), $this);
    $processor->run($this, false);
  }
  /**
   * Private callback for copying values
   * @param targetnode The node to copy the value to
   * @param dataTypes An array of datatypes. Only values of that datatypes will be copied.
   * @param valuesToIgnore An associative array with the value names as keys and the types as values
   * @see NodeProcessor
   */
  function copyValueIntern (&$node, $valueName, $dataType, &$targetNode, $dataTypes, $valuesToIgnore)
  {
    if (sizeof($dataTypes) == 0 || in_array($dataType, $dataTypes))
    {
      if (!isset($valuesToIgnore[$valueName]) || $valuesToIgnore[$valueName] != $dataType) {
        $value = $node->getValue($valueName, $dataType);
        if (strlen($value) > 0) {
          $targetNode->setValue($valueName, $value, $dataType, true);
        }
      }
    }
  }
  /**
   * Clear all values. Set each value to null.
   * @param dataTypes An array of datatypes. Only values of that datatypes will be cleared.
   * Empty array means all datatypes [default:empty array]
   */
  function clearValues ($dataTypes=array())
  {
    $processor = new NodeProcessor('clearValueIntern', array($dataTypes), $this);
    $processor->run($this, false);
  }
  /**
   * Private callback for clearing values
   * @see NodeProcessor
   */
  function clearValueIntern (&$node, $valueName, $dataType, $dataTypes)
  {
    if (sizeof($dataTypes) == 0 || in_array($dataType, $dataTypes)) {
      $node->setValue($valueName, null, $dataType);
    }
  }
  /**
   * Recalculate the object id
   */
  function updateOID ()
  {
    $mapper = &$this->getMapper();
    if ($mapper != null)
    {
      $oidParts = array('type' => $this->getType(), 'id' => array());
      // collect the values of the primary keys and compose the oid from them
      $pkValues = $mapper->getPkNames();
      foreach (array_keys($pkValues) as $pkName) {
        array_push($oidParts['id'], $this->getValue($pkName, $pkValues[$pkName]));
      }
      $this->_oid = PersistenceFacade::composeOID($oidParts);
    }
  }

  /**
   * Persistence hook methods.
   * Subclasses may override this to implement special application requirements.
   * The default implementations do nothing.
   */
  /**
   * This method is called once after creation of this object. At this time it
   * is not known in the store.
   */
  function afterCreate() {}
  /**
   * This method is called once before inserting the newly created object into the store.
   */
  function beforeInsert() {}
  /**
   * This method is called once after inserting the newly created object into the store.
   */
  function afterInsert() {}
  /**
   * This method is called always after loading the object from the store.
   */
  function afterLoad() {}
  /**
   * This method is called always before updating the modified object in the store.
   */
  function beforeUpdate() {}
  /**
   * This method is called always after updating the modified object in the store.
   */
  function afterUpdate() {}
  /**
   * This method is called once before deleting the object from the store.
   */
  function beforeDelete() {}
  /**
   * This method is called once after deleting the object from the store.
   */
  function afterDelete() {}

  /**
   * Values and Properties
   */

  /**
   * Check if the node has a given item.
   * @param name The name of the item to query.
   * @param type The type of the item as defined in the subclass [optional]
   *        (if type is omitted the first item value of any type that matches will be returned)
   * @return True/False wether the item exists or not.
   */
  function hasValue($name, $type=null)
  {
    return in_array($name, $this->getValueNames($type));
  }
  /**
   * Get the value of a named item.
   * @param name The name of the item to query.
   * @param type The type of the item as defined in the subclass [optional]
   *        (if type is omitted the first item value of any type that matches will be returned)
   * @return The value of the item / null if it doesn't exits.
   */
  function getValue($name, $type=null)
  {
    if ($type != null)
    {
      if (is_array($this->_data[$type]) && isset($this->_data[$type][$name])) {
        return $this->_data[$type][$name]['value'];
      }
      else {
        return null;
      }
    }
    else
    {
      foreach($this->_data as $curDataArray) {
        if (isset($curDataArray[$name])) {
          return $curDataArray[$name]['value'];
        }
      }
    }
    return null;
  }
  /**
   * Remove a named item.
   * @param name The name of the item to remove.
   * @param type The type of the item as defined in the subclass [optional]
   *        (if type is omitted the first item value of any type that matches will be returned)
   */
  function removeValue($name, $type=null)
  {
    if ($type != null)
    {
      if (is_array($this->_data[$type]) && array_key_exists($name, $this->_data[$type])) {
        unset($this->_data[$type][$name]);
      }
    }
    else
    {
      foreach(array_keys($this->_data) as $type) {
        if (is_array($this->_data[$type]) && array_key_exists($name, $this->_data[$type])) {
          unset($this->_data[$type][$name]);
        }
      }
    }
  }
  /**
   * Get the unconverted value of a named item.
   * @param name The name of the item to query.
   * @param type The type of the item as defined in the subclass [optional]
   *        (if type is omitted the first item value of any type that matches will be returned)
   * @return The unconverted value of the item / null if it doesn't exits.
   */
  function getUnconvertedValue($name, $type=null)
  {
    $value = $this->getValue($name, $type);
    $dataConverter = $this->getDataConverter();
    if (is_object($dataConverter) && $value != null) {
      $value = $dataConverter->convertApplicationToStorage($value, $this->getValueProperty($name, 'db_data_type', $type), $name);
    }
    return $value;
  }
  /**
   * Get the converted value of a named item.
   * @param name The name of the item to query.
   * @param type The type of the item as defined in the subclass [optional]
   *        (if type is omitted the first item value of any type that matches will be returned)
   * @return The converted value of the item / null if it doesn't exits.
   * @note The result is normally equal to that of PersistentObject::getValue() except, when the value is unconverted
   */
  function getConvertedValue($name, $type=null)
  {
    $value = $this->getValue($name, $type);
    $dataConverter = $this->getDataConverter();
    if (is_object($dataConverter) && $value != null) {
      $value = $dataConverter->convertStorageToApplication($value, $this->getValueProperty($name, 'db_data_type', $type), $name);
    }
    return $value;
  }
  /**
   * Get the type of a named item.
   * @param name The name of the item to query.
   * @return An array containig the types of the value (in most cases this array will have length 1).
   */
  function getValueTypes($name)
  {
    $types = array();
    foreach(array_keys($this->_data) as $type) {
      if (in_array($name, array_keys($this->_data[$type]))) {
        array_push($types, $type);
      }
    }
    return $types;
  }
  /**
   * Validate all values
   * @return Empty string if validation succeeded, an error string else. The default implementation returns the result of
   *        PersistentObject::validateValueAgainstRestrictions().
   */
  function validateValues ()
  {
    $result = '';
    $processor = new NodeProcessor('validateValueIntern', array(&$result), $this);
    $processor->run($this, false);
    return $result;
  }
  /**
   * Private callback for validating values
   * @param errorMsg A string to append error messages to
   * @see NodeProcessor
   */
  function validateValueIntern (&$node, $valueName, $dataType, &$errorMsg)
  {
    $error = $node->validateValue($valueName, $value, $dataType);
    if (strlen($error) > 0) {
      $errorMsg .= $error."\n";
    }
  }
  /**
   * Check if data may be set. The method is also called, when setting a value.
   * Controller may call this method before setting data and saving the object.
   * @param name The name of the item to set.
   * @param value The value of the item.
   * @param type The type of the item as defined in the subclass [optional]
   *        (if type is omitted the first item of any type that matches will be validated)
   * @return Empty string if validation succeeded, an error string else. The default implementation returns the result of
   *        PersistentObject::validateValueAgainstRestrictions().
   * @note Subclasses will override this method to implement special application requirements.
   */
  function validateValue($name, $value, $type=null)
  {
    return $this->validateValueAgainstRestrictions($name, $value, $type);
  }
  /**
   * Check a value's value against the restrictions set on it. This method uses the
   * 'restrictions_match' and 'restrictions_not_match' value properties.
   * @param name The name of the item to set.
   * @param value The value of the item.
   * @param type The type of the item as defined in the subclass [optional]
   *        (if type is omitted the first item of any type that matches will be checked)
   * @return Empty string if validation succeeded, an error string else.
   */
  function validateValueAgainstRestrictions($name, $value, $type=null)
  {
    $valueProperties = $this->getValueProperties($name, $type);
    $restrictionsMatch = $valueProperties['restrictions_match'];
    $restrictionsNotMatch = $valueProperties['restrictions_not_match'];
    if (($restrictionsMatch == '' || preg_match("/".$restrictionsMatch."/m", $value)) &&
        ($restrictionsNotMatch == '' || !preg_match("/".$restrictionsNotMatch."/m", $value))) {
      return '';
    }
    // construct the error message
    $errorMessage = Message::get("Wrong value for %1% (%2%). ", array($name, $value));

    // use configured message if existing
    if (strlen($valueProperties['restrictions_description']) > 0) {
      $errorMessage .= Message::get($valueProperties['restrictions_description']);
    }
    else
    {
      // construct default message
      if (strlen($restrictionsMatch) > 0) {
        $errorMessage .= Message::get("The value must match %1%.", array($restrictionsMatch));
      }
      if (strlen($restrictionsNotMatch) > 0) {
        $errorMessage .= Message::get("The value must NOT match %1%.", array($restrictionsNotMatch));
      }
    }
    return $errorMessage;
  }
  /**
   * Set the value of a named item if it exists.
   * @param name The name of the item to set.
   * @param value The value of the item.
   * @param type The type of the item as defined in the subclass [optional]
   *        (if type is omitted the first item of any type that matches will be modified)
   * @param forceSet Set the value even if it is already set and validation would fail (used to notify listeners) [default: false]
   * @return true if operation succeeds / false else
   */
  function setValue($name, $value, $type=null, $forceSet=false)
  {
    if (!$forceSet)
    {
      $validationResult = $this->validateValue($name, $value, $type);
      if (strlen($validationResult) > 0) {
        WCMFException::throwEx("Invalid value (".$value.") for ".$this->getOID().".".$name.": ".$validationResult, __FILE__, __LINE__);
      }
    }
    $oldValue = $this->getValue($name, $type);
    if ($type != null && strlen($type) > 0)
    {
      // construct type array if it doesn't exist
      if (!isset($this->_data[$type]))
      {
        $this->_data[$type] = array();
      }
      // construct name array if it doesn't exist
      if (!isset($this->_data[$type][$name]))
      {
        $this->_data[$type][$name] = array();
      }
      // set value
      if ($this->_data[$type][$name]['value'] !== $value || $forceSet)
      {
        $this->_data[$type][$name]['value'] = $value;
        PersistentObject::setState(STATE_DIRTY);
        $mapper = &$this->getMapper();
        if ($mapper != null && in_array($name, array_keys($mapper->getPKNames()))) {
          $this->updateOID();
        }
        $this->propagateValueChange($name, $type, $oldValue, $value);
        return true;
      }
    }
    else
    {
      foreach(array_keys($this->_data) as $key)
      {
        if (array_key_exists($name, $this->_data[$key]))
        {
          if ($this->_data[$key][$name] != $value || $forceSet)
          {
            $this->_data[$key][$name]['value'] = $value;
            PersistentObject::setState(STATE_DIRTY);
            $mapper = &$this->getMapper();
            if ($mapper != null && in_array($name, array_keys($mapper->getPKNames()))) {
              $this->updateOID();
            }
            $this->propagateValueChange($name, $key, $oldValue, $value);
          }
          return true;
        }
      }
    }
    return false;
  }
  /**
   * Get the properties of a named item.
   * @param name The name of the item to query.
   * @param type The type of the item as defined in the subclass [optional]
   *        (if type is omitted the first item value of any type that matches will be returned)
   * @return An associative array holding the properties of the item / null if it doesn't exits.
   */
  function getValueProperties ($name, $type=null)
  {
    if ($type != null)
    {
      if (isset($this->_data[$type][$name]['properties'])) {
        return $this->_data[$type][$name]['properties'];
      }
      else {
        return null;
      }
    }
    else
    {
      foreach($this->_data as $curDataArray)
      {
        if (isset($curDataArray[$name])) {
          return $curDataArray[$name]['properties'];
        }
      }
    }
    return null;
  }
  /**
   * Set the properties of a named item.
   * @param name The name of the item to set its properties.
   * @param properties An associative array holding the properties of the item.
   * @param type The type of the item as defined in the subclass [optional]
   *        (if type is omitted the first item of any type that matches will be modified)
   * @return true/false whether the value was set.
   */
  function setValueProperties ($name, $properties, $type=null)
  {
    if ($type != null)
    {
      // return false if type array doesn't exist
      if (!isset($type, $this->_data)) {
        return false;
      }
      // set properties if value exists
      if (isset($name, $this->_data[$type]))
      {
        $this->_data[$type][$name]['properties'] = $properties;
        PersistentObject::setState(STATE_DIRTY);
        return true;
      }
    }
    else
    {
      foreach(array_keys($this->_data) as $key)
      {
        if (isset($name, $this->_data[$key]))
        {
          $this->_data[$key][$name]['properties'] = $properties;
          PersistentObject::setState(STATE_DIRTY);
          return true;
        }
      }
    }
    return false;
  }
  /**
   * Get the value of one property of a named item.
   * @param name The name of the item to set its properties.
   * @param property The name of the property to set.
   * @param type The type of the item as defined in the subclass [optional]
   *        (if type is omitted the first item of any type that matches will be modified)
   * @return The value property/null if not found.
   */
  function getValueProperty ($name, $property, $type=null)
  {
    $properties = $this->getValueProperties($name, $type);
    if ($properties != null) {
      return $properties[$property];
    }
    return false;
  }
  /**
   * Set the value of one property of a named item.
   * @param name The name of the item to set its properties.
   * @param property The name of the property to set.
   * @param value The value to set on the property.
   * @param type The type of the item as defined in the subclass [optional]
   *        (if type is omitted the first item of any type that matches will be modified)
   * @return true/false whether the value was set.
   */
  function setValueProperty ($name, $property, $value, $type=null)
  {
    $properties = $this->getValueProperties($name, $type);
    if ($properties != null)
    {
      $properties[$property] = $value;
      return $this->setValueProperties($name, $properties, $type);
    }
    return false;
  }
  /**
   * Get the names of all items.
   * @param type The type of the item as defined in the subclass [optional]
   *        (if type is omitted all names will be returned)
   * @return array of all item names.
   */
  function getValueNames ($type=null)
  {
    $names = array();
    if ($type == null)
    {
      foreach(array_keys($this->_data) as $key) {
        $names = array_merge($names, array_keys($this->_data[$key]));
      }
    }
    else
    {
      if (isset($this->_data[$type])) {
        $names = array_keys($this->_data[$type]);
      }
    }
    return $names;
  }
  /**
   * Get all datatypes.
   * @return array of all datatypes.
   */
  function getDataTypes ()
  {
    return array_keys($this->_data);
  }
  /**
   * Get the value of a named property in the object.
   * @param name The name of the property to query.
   * @return The value of the property / null if it doesn't exits.
   */
  function getProperty ($name)
  {
    if (isset($this->_properties[$name])) {
      return $this->_properties[$name];
    }
    else {
      return null;
    }
  }
  /**
   * Set the value of a named property in the object.
   * @param name The name of the property to set.
   * @param value The value of the property to set.
   */
  function setProperty ($name, $value)
  {
    $oldValue = $this->getProperty($name);
    $this->_properties[$name] = $value;
    $this->propagatePropertyChange($name, $oldValue, $value);
  }
  /**
   * Get the names of all properties in the object.
   * @return An array consisting the names.
   */
  function getPropertyNames ()
  {
    return array_keys($this->_properties);
  }

  /**
   * ChangeListener Support
   */

  /**
   * Add a change listener (Must be of type ChangeListener).
   * @param listener The ChangeListener.
   */
  function addChangeListener (&$listener)
  {
    $this->_changeListeners[sizeof($this->_changeListeners)] = &$listener;
  }
  /**
   * Remove a change listener (Must be of type ChangeListener).
   * @param listener The ChangeListener.
   */
  function removeChangeListener (&$listener)
  {
    for ($i=0, $count=sizeof($this->_changeListeners); $i<$count; $i++) {
      if ($this->_changeListeners[$i]->getId() == $listener->getId()) {
        unset($this->_changeListeners[$i]);
      }
    }
  }
  /**
   * Notify ChangeListeners of value changes.
   * @param name The name of the item that has changed.
   * @param type The type of the item that has changed.
   * @param oldValue The old value of the item that has changed
   * @param newValue The new value of the item that has changed
   */
  function propagateValueChange ($name, $type, $oldValue, $newValue)
  {
    for ($i=0, $count=sizeof($this->_changeListeners); $i<$count; $i++) {
      if(method_exists($this->_changeListeners[$i], 'valueChanged')) {
        $this->_changeListeners[$i]->valueChanged($this, $name, $type, $oldValue, $newValue);
      }
    }
  }
  /**
   * Notify ChangeListeners of property changes.
   * @param name The name of the item that has changed.
   * @param oldValue The old value of the item that has changed
   * @param newValue The new value of the item that has changed
   */
  function propagatePropertyChange ($name, $oldValue, $newValue)
  {
    for ($i=0, $count=sizeof($this->_changeListeners); $i<$count; $i++) {
      if(method_exists($this->_changeListeners[$i], 'propertyChanged')) {
        $this->_changeListeners[$i]->propertyChanged($this, $name, $oldValue, $newValue);
      }
    }
  }
  /**
   * Notify ChangeListeners of state changes.
   * @param oldValue The old value of the item that has changed
   * @param newValue The new value of the item that has changed
   */
  function propagateStateChange ($oldValue, $newValue)
  {
    for ($i=0, $count=sizeof($this->_changeListeners); $i<$count; $i++) {
      if(method_exists($this->_changeListeners[$i], 'stateChanged')) {
        $this->_changeListeners[$i]->stateChanged($this, $oldValue, $newValue);
      }
    }
  }

  /**
   * Output
   */

  /**
   * Get the name of the type used for display.
   * @return The name.
   * @note Sublasses will override this for special application requirements
   */
  function getObjectDisplayName()
  {
    return Message::get($this->getType());
  }
  /**
   * Get the description of the type.
   * @return The description.
   * @note Sublasses will override this for special application requirements
   */
  function getObjectDescription()
  {
    return Message::get($this->getType());
  }
  /**
   * Get the value of the object used for display.
   * @return The value.
   * @note Sublasses will override this for special application requirements
   */
  function getDisplayValue()
  {
    return $this->toString();
  }
  /**
   * Get the name of a value used for display.
   * @param name The name of the value.
   * @param type The type of the value (not used by the default implementation) [default: null]
   * @return The name of the value.
   * @note Sublasses will override this for special application requirements
   */
  function getValueDisplayName($name, $type=null)
  {
    return Message::get($name);
  }
  /**
   * Get the description of a value.
   * @param name The name of the value.
   * @param type The type of the value (not used by the default implementation) [default: null]
   * @return The description of the value.
   * @note Sublasses will override this for special application requirements
   */
  function getValueDescription($name, $type=null)
  {
    return Message::get($name);
  }
  /**
   * Get a string representation of the PersistentObject.
   * @param verbose True to get a verbose output [default: false]
   * @return The string representation of the PersistentObject.
   */
  function toString ($verbose=false)
  {
    $str = 'type:'.$this->getType().', ';
    $mapper = &$this->getMapper();
    if ($mapper != null)
    $str .= 'mapper:'.get_class($mapper).', ';
    $str .= 'oid:'.$this->getOID().' ';
    $str .= 'state:'.$this->getState().' ';
    $str .= 'PROPERTIES ';
    foreach($this->getPropertyNames() as $name)
    {
      $value = $this->getProperty($name);
      if (is_array($value)) {
        $str .= $name.':'.join(',', $value).' ';
      }
      else {
        $str .= $name.':'.$value.' ';
      }
    }
    $str .= "\n";
    $str .= 'VALUES ';
    $dataTypes = $this->getDataTypes();
    foreach($dataTypes as $type)
    {
      $str .= $type.'->{';
      $valueNames = $this->getValueNames($type);
      foreach($valueNames as $name)
      {
        $str .= $name.':'.$this->getValue($name, $type).' ';
        if ($verbose)
        {
          $valueProperties = $this->getValueProperties($name, $type);
          if (sizeOf($valueProperties) > 0)
          {
            $str .= '[';
            foreach($valueProperties as $key => $value) {
              $str .= $key.':'.$value.' ';
            }
            $str = substr($str, 0, strlen($str)-1);
            $str .= '] ';
          }
        }
      }
      $str = substr($str, 0, -1).'} ';
    }
    $str = substr($str, 0, -1);
    $str .= "\n";
    return $str;
  }
  /**
   * Check if the instance object is contained in the search index
   * @return True/False wether the object is contained or not
   */
  public function isIndexInSearch()
  {
    return (boolean) $this->getProperty('is_searchable') && $this->getType() == $this->getBaseType();
  }
}
?>