class.RDBMapper.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.RDBMapper.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/persistence/class.PersistenceMapper.php");
require_once(BASE."wcmf/lib/persistence/class.PersistenceFacade.php");
require_once(BASE."wcmf/lib/persistence/converter/class.DataConverter.php");
require_once(BASE."wcmf/lib/persistence/pdo/class.PDOConnection.php");
require_once(BASE."wcmf/lib/util/class.InifileParser.php");

/**
 * @class RDBMapper
 * @ingroup Mapper
 * @brief RDBMapper maps objects of one type to a relational database schema.
 * It defines a persistence mechanism that specialized mappers customize by overriding
 * the given template methods.
 *
 * @author   ingo herwig <ingo@wemove.com>
 */
class RDBMapper extends PersistenceMapper
{
  var $_connParams = null; // database connection parameters
  var $_conn = null;       // database connection
  var $_dbPrefix = '';     // database prefix (if given in the configuration file)

  // prepared statements
  var $_idSelectStmt = null;
  var $_idInsertStmt = null;
  var $_idUpdateStmt = null;

  /**
   * Constructor.
   * @param params Initialization data given in an assoziative array with the following keys:
   *               dbType, dbHostName, dbUserName, dbPassword, dbName OR dbConnection
   *               if dbPrefix is given it will be appended to every table string, which is
   *               usefull if different cms operate on the same database
   */
  function RDBMapper($params)
  {
    // store connection parameters to allow lazy connect
    $this->_connParams = &$params;
    $this->_dataConverter = new DataConverter();
  }
  /**
   * Select data to be stored in the session.
   * PDO throws an excetption if tried to be (un-)serialized.
   */
  function __sleep()
  {
    unset($this->_connParams['dbConnection']);
    return array('_connParams', '_dbPrefix');
  }
  /**
   * Actually connect to the database using the parameters given to the constructor.
   */
  function connect()
  {
    if (isset($this->_connParams['dbType']) && isset($this->_connParams['dbHostName']) &&
      isset($this->_connParams['dbUserName']) && isset($this->_connParams['dbPassword']) &&
      isset($this->_connParams['dbName']))
    {
      $dns = $this->_connParams['dbType'].':host='.$this->_connParams['dbHostName'].
        ((!empty($this->_connParams['dbPort'])) ? (';port='.$this->_connParams['dbPort']) : '').
        ';dbname='.$this->_connParams['dbName'];
      $charSet = isset($this->_connParams['dbCharSet']) ? $this->_connParams['dbCharSet'] : 'utf8';

      // set driver specific options
      $driverOptions = array();
      if (strtolower($this->_connParams['dbType']) == 'mysql') {
        $driverOptions[PDO::MYSQL_ATTR_INIT_COMMAND] = "SET NAMES ".$charSet;
      }
      try {
        // create new connection
        $this->_conn = new PDOConnection($dns, $this->_connParams['dbUserName'], $this->_connParams['dbPassword'], $driverOptions);
        $this->_conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
      }
      catch(PDOException $ex) {
        WCMFException::throwEx("Connection to ".$this->_connParams['dbHostName'].".".$this->_connParams['dbName']." failed: ".
          $ex->getMessage(), __FILE__, __LINE__);
      }

      // get database prefix if defined
      $this->_dbPrefix = $this->_connParams['dbPrefix'];

      // store connection for reuse
      $persistenceFacade = &PersistenceFacade::getInstance();
      $persistenceFacade->storeConnection($this->_connParams, $this->_conn);
    }
    elseif (isset($this->_connParams['dbConnection']))
    {
      // use existing connection
      $this->_conn = &$this->_connParams['dbConnection'];
    }
    else
      WCMFException::throwEx("Wrong parameters for constructor.", __FILE__, __LINE__);
  }
  /**
   * Get a new id for inserting into the database
   * @return An id value.
   */
  function getNextId()
  {
    try {
      $id = 0;
      if ($this->_idSelectStmt == null || $this->_idInsertStmt == null || $this->_idUpdateStmt == null) {
        // get the connection from the sequence mapper
        $persistenceFacade = PersistenceFacade::getInstance();
        $mapper = $persistenceFacade->getMapper("Adodbseq");
        if ($mapper instanceof RDBMapper) {
          $connection = $mapper->getConnection();
          $this->_idSelectStmt = $connection->prepare("SELECT id FROM adodbseq");
          $this->_idInsertStmt = $connection->prepare("INSERT INTO adodbseq (id) VALUES (0)");
          $this->_idUpdateStmt = $connection->prepare("UPDATE adodbseq SET id=LAST_INSERT_ID(id+1);");
        }
      }
      $this->_idSelectStmt->execute();
      $rows = $this->_idSelectStmt->fetchAll(PDO::FETCH_ASSOC);
      if (sizeof($rows) == 0) {
        $this->_idInsertStmt->execute();
        $this->_idInsertStmt->closeCursor();
        $row = array(array('id' => 0));
      }
      $id = $rows[0]['id'];
      $this->_idUpdateStmt->execute();
      $this->_idUpdateStmt->closeCursor();
      $this->_idSelectStmt->closeCursor();
      return $id;
    }
    catch (Exception $ex) {
      Log::error("The query: ".$sql."\ncaused the following exception:\n".$ex->getMessage(), __CLASS__);
      WCMFException::throwEx("Error in persistent operation. See log file for details.", __FILE__, __LINE__);
    }
  }
  /**
   * Get the name of the sequence table
   * @return The name.
   */
  function getSequenceTablename()
  {
    $persistenceFacade = &PersistenceFacade::getInstance();
    $mapper = &$persistenceFacade->getMapper('Adodbseq');
    // TODO: check if the mapper implements getTableName
    return $mapper->getTableName();
  }
  /**
   * Execute a query on the connection.
   * @param sql The sql command
   * @param isSelect True/False wether the statement is a select statement (default: false)
   * @return If isSelect is true, an array as the result of PDOStatement::fetchAll(PDO::FETCH_ASSOC),
   * the number of affected rows else
   */
  function executeSql($sql, $isSelect=false)
  {
    if ($this->_conn == null)
      $this->connect();

    if (Log::isDebugEnabled(__CLASS__)) {
      Log::debug($sql."\n".WCMFException::getStackTrace(), __CLASS__);
    }
    try {
      if ($isSelect) {
      $stmt = $this->_conn->prepare($sql);
      $stmt->execute();
      $result = $stmt->fetchAll(PDO::FETCH_ASSOC);
      $stmt->closeCursor();
      return $result;
    }
      else {
        return $this->_conn->exec($sql);
      }
    }
    catch (Exception $ex) {
      Log::error("The query: ".$sql."\ncaused the following exception:\n".$ex->getMessage(), __CLASS__);
      WCMFException::throwEx("Error in persistent operation. See log file for details.", __FILE__, __LINE__);
    }
  }
  /**
   * Execute a select query on the connection.
   * @param sql The sql command
   * @param pagingInfo An PagingInfo instance describing which page to load
   * @return An array as the result of PDOStatement::fetchAll(PDO::FETCH_ASSOC)
   */
  function select($sql, &$pagingInfo)
  {
    if ($this->_conn == null)
      $this->connect();

    try {
      if ($pagingInfo != null && $pagingInfo->getPageSize() > 0) {
        // make a count query
        $countSql = preg_replace('/^\s*SELECT\s+(DISTINCT\s+|)([^,]+)\s.+\sFROM\s/Uis', 'SELECT COUNT($1 $2) AS nRows FROM ', $sql);
        $countSql = preg_replace('/\s*ORDER BY.*$/Uis', '', $countSql);
        $result = $this->executeSql($countSql, true);
        $nRows = $result[0]['nRows'];
        // update pagingInfo
        $pagingInfo->setTotalCount($nRows);
        // set the limit on the query (NOTE: not supported by all databases)
        $limit = $pagingInfo->getPageSize();
        $offset = $pagingInfo->getIndex();
        $sql = preg_replace('/;$/', '', $sql);
        $sql .= ' LIMIT '.$limit;
        if ($offset > 0) {
          $sql .= ' OFFSET '.$offset;
        }
        $sql .= ';';
      }
      return $this->executeSql($sql, true);
    }
    catch (Exception $ex) {
      Log::error("The query: ".$sql."\ncaused the following exception:\n".$ex->getMessage(), __CLASS__);
      WCMFException::throwEx("Error in persistent operation. See log file for details.", __FILE__, __LINE__);
    }
  }
  /**
   * Check if a value is a primary key value
   * @param name The name of the value
   * @param dataType The datatype of the value
   * @return True/False
   */
  function isPkValue($name, $dataType)
  {
    $pkNames = $this->getPKNames();
    return (in_array($name, array_keys($pkNames)) && $pkNames[$name] == $dataType);
  }
  /**
   * Construct an object id from given row data
   * @param type The type of object
   * @param data An associative array with the pk column names as keys and pk values as values
   * @return The oid
   */
  function constructOID($type, $data)
  {
    $pkNames = $this->getPKNamesForType($type);
    $params = array('type' => $type, 'id' => array());
    foreach ($pkNames as $pkName)
      array_push($params['id'], $data[$pkName]);
    return PersistenceFacade::composeOID($params);

  }
  /**
   * Get the pk column names for a given type
   * @param type The type of object
   * @return An array of column names
   */
  function getPKNamesForType($type)
  {
    $persistenceFacade = &PersistenceFacade::getInstance();
    $mapper = &$persistenceFacade->getMapper($type);
    return array_keys($mapper->getPkNames());

  }
  /**
   * @see PersistenceMapper::loadImpl()
   */
  function &loadImpl($oid, $buildDepth, $buildAttribs=null, $buildTypes=null)
  {
    $persistenceFacade = &PersistenceFacade::getInstance();

    // delegate to loadObjects
    $criteria = $this->createPKCondition($oid);
    $pagingInfo = null;
    $objects = $persistenceFacade->loadObjects(PersistenceFacade::getOIDParameter($oid, 'type'), $buildDepth, $criteria, null,
                  $pagingInfo, $buildAttribs, $buildTypes);
    if (sizeof($objects) > 0)
      return $objects[0];
    else
      return null;
  }
  /**
   * @see PersistenceMapper::createImpl()
   * @note The type parameter is not used here because this class only constructs one type
   */
  function &createImpl($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__);

    $persistenceFacade = &PersistenceFacade::getInstance();

    // get attributes to load
    $attribs = null;
    if ($buildAttribs != null && isset($buildAttribs[$this->getType()]))
      $attribs = $buildAttribs[$this->getType()];

    // create the object
    $object = &$this->createObjectFromData($attribs);

    // recalculate build depth for the next generation
    if ($buildDepth != BUILDDEPTH_REQUIRED && $buildDepth != BUILDDEPTH_SINGLE && $buildDepth != BUILDDEPTH_INFINITE && $buildDepth > 0)
      $newBuildDepth = $buildDepth-1;
    else
      $newBuildDepth = $buildDepth;

    // prevent infinite recursion
    if ($buildDepth < BUILDDEPTH_MAX)
    {
      // get object definition (default values, properties)
      $objectData = $this->getObjectDefinition();

      // set dependend objects of this object
      foreach ($objectData['_children'] as $childData)
      {
        // set 'minOccurs', 'maxOccurs'
        if (!isset($childData['minOccurs']))
          $childData['minOccurs'] = 0; // default value
        if (!isset($childData['maxOccurs']))
          $childData['maxOccurs'] = 1; // default value

        if ( ($buildDepth != BUILDDEPTH_SINGLE) && (($buildDepth > 0) || ($buildDepth == BUILDDEPTH_INFINITE) ||
          (($buildDepth == BUILDDEPTH_REQUIRED) && $childData['minOccurs'] > 0 && $childData['aggregation'] == true)) )
        {
          $childObject = &$persistenceFacade->create($childData['type'], $newBuildDepth, $buildAttribs);
          $childObject->setProperty('minOccurs', $childData['minOccurs']);
          $childObject->setProperty('maxOccurs', $childData['maxOccurs']);
          $childObject->setProperty('aggregation', $childData['aggregation']);
          $childObject->setProperty('composition', $childData['composition']);
          $this->appendObject($object, $childObject);
        }
      }
    }

    return $object;
  }
  /**
   * @see PersistenceMapper::saveImpl()
   */
  function saveImpl(&$object)
  {
    if ($this->_conn == null)
      $this->connect();

    // prepare object data
    // convert all values (except for primary key values)
    $appValues = array();
    foreach ($object->getDataTypes() as $type)
    {
      foreach ($object->getValueNames($type) as $valueName) {
        if (!$this->isPkValue($valueName, $type))
        {
          if (!isset($appValues[$type])) {
            $appValues[$type] = array();
          }
          $properties = $object->getValueProperties($valueName, $type);
          $value = $object->getValue($valueName, $type);
          $appValues[$type][$valueName] = $value;
          $convertedValue = $this->_dataConverter->convertApplicationToStorage($value, $properties['db_data_type'], $valueName);
          $object->setValue($valueName, $convertedValue, $type, true);
        }
      }
    }

    $persistenceFacade = &PersistenceFacade::getInstance();
    if ($object->getState() == STATE_NEW)
    {
      // insert new object
      $this->prepareInsert($object);
      $sqlArray = $this->getInsertSQL($object);
      foreach($sqlArray as $sqlStr)
        $this->executeSql($sqlStr);

      // log action
      $this->logAction($object);
    }
    else if ($object->getState() == STATE_DIRTY)
    {
      // save existing object
      // precondition: the object exists in the database

      // log action
      $this->logAction($object);

      // save object
      $sqlArray = $this->getUpdateSQL($object);
      foreach($sqlArray as $sqlStr)
        $this->executeSql($sqlStr);
    }

    // set converted values back to application values
    foreach ($object->getDataTypes() as $type)
    {
      foreach ($object->getValueNames($type) as $valueName) {
        if (!$this->isPkValue($valueName, $type)) {
          $object->setValue($valueName, $appValues[$type][$valueName], $type);
        }
      }
    }

    $object->setState(STATE_CLEAN, false);
    // postcondition: the object is saved to the db
    //                the object state is STATE_CLEAN
    //                attributes are only inserted if their values differ from ''
    return true;
  }
  /**
   * @see PersistenceMapper::deleteImpl()
   */
  function deleteImpl($oid, $recursive=true)
  {
    if ($this->_conn == null)
      $this->connect();

    $persistenceFacade = &PersistenceFacade::getInstance();

    // log action
    if ($this->isLogging())
    {
      $obj = &$persistenceFacade->load($oid, BUILDDEPTH_SINGLE);
      if ($obj)
        $this->logAction($obj);
    }

    // delete object
    $sqlArray = $this->getDeleteSQL($oid);
    foreach($sqlArray as $sqlStr)
      $this->executeSql($sqlStr);

    // delete children
    if ($recursive)
    {
      // make sure that we only delete the composition children...
      $sqlArray = $this->getChildrenSelectSQL($oid, true);
      foreach($sqlArray as $childType => $criteria)
      {
        $attribs = $this->getPkNamesForType($childType);
        $childoids = $persistenceFacade->getOIDs($childType, $criteria);
        foreach($childoids as $childoid)
          $persistenceFacade->delete($childoid, $recursive);
      }
      // ...for the others we have to break the foreign key relation
      $sqlArray = $this->getChildrenDisassociateSQL($oid, true);
      foreach($sqlArray as $sqlStr)
        $this->executeSql($sqlStr);
    }
    // postcondition: the object and all dependend objects are deleted from db
    return true;
  }
  /**
   * Get the database connection.
   * @return A reference to the ADONewConnection object
   */
  function &getConnection()
  {
    if ($this->_conn == null)
      $this->connect();

    return $this->_conn;
  }
  /**
   * @see PersistenceMapper::getOIDs()
   * @note The type parameter is not used here because this class only constructs one type
   */
  function getOIDs($type, $criteria=null, $orderby=null, &$pagingInfo)
  {
    $oids = array();

    // create query (load only pk columns and no children oids)
    $type = $this->getType();
    $data = $this->loadObjects($type, BUILDDEPTH_SINGLE, $criteria, $orderby, $pagingInfo, array($type => array()), array($type), false, true);

    // collect oids
    for ($i=0, $count=sizeof($data); $i<$count; $i++) {
      $objectData['_data'] = $data[$i];
      $oid = $this->constructOID($this->getType(), $objectData['_data']);
      array_push($oids, $oid);
    }

    return $oids;
  }
  /**
   * @see PersistenceFacade::loadObjects()
   * @note The additional parameter selectChildOIDs indicates wether to load the oids of the children or not and is
   * used internally only
   */
  function loadObjects($type, $buildDepth, $criteria=null, $orderby=null, &$pagingInfo, $buildAttribs=null, $buildTypes=null, $selectChildOIDs=true, $omitObjects=false)
  {
    if ($buildDepth < 0 && !in_array($buildDepth, array(BUILDDEPTH_INFINITE, BUILDDEPTH_SINGLE)))
      WCMFException::throwEx("Build depth not supported: $buildDepth", __FILE__, __LINE__);

    if ($this->_conn == null)
      $this->connect();

    $objects = array();

    // check buildTypes
    if (is_array($buildTypes) && !in_array($type, $buildTypes))
      return $objects;

    // get attributes to load
    $attribs = null;
    if ($buildAttribs != null && isset($buildAttribs[$this->getType()]))
      $attribs = $buildAttribs[$this->getType()];

    // create condition
    $attribCondStr = "";
    if ($criteria != null)
    {
      // criteria is an array
      if (is_array($criteria))
      {
        foreach($criteria as $name => $value)
          $attribCondStr .= $name."=".$this->_conn->quote($value)." AND ";
        $attribCondStr = substr($attribCondStr, 0, strlen($attribCondStr)-strlen(" AND "));
      }
      else
        $attribCondStr = $criteria;
    }

    // create order
    $orderbyStr = "";
    if ($orderby != null)
      $orderbyStr = join(', ', $orderby);

    // create query
    $data = array();
    $sqlStr = $this->getSelectSQL($attribCondStr, $orderbyStr, $attribs);
    $data = $this->select($sqlStr, $pagingInfo);
    if (sizeof($data) == 0)
      return $objects;

    if ($omitObjects) {
      return $data;
    }

    $numObjects = sizeof($data);
    for ($i=0; $i<$numObjects; $i++)
    {
      // create the object
      $object = &$this->createObjectFromData($attribs, $data[$i]);

      // append child data (childoids or real children depending on the buildDepth)
      if ($selectChildOIDs)
        $this->appendChildData($object, $buildDepth, $buildAttribs, $buildTypes);

      $object->setState(STATE_CLEAN, false);
      $objects[] = &$object;
    }
    return $objects;
  }
  /**
   * Create an object of the mapper's type with the given attributes from the given data
   * @param attribs An array of attributes to create
   * @param data The '_data' array contained in the array returned by getObjectDefinition @see RDBMapper::applyDataOnLoad()
   * @return A reference to the object
   */
  function &createObjectFromData($attribs, $data=null)
  {
    // determin if we are loading or creating
    $createFromLoadedData = false;
    if (is_array($data))
      $createFromLoadedData = true;

    // get object definition (default values, properties)
    $objectData = $this->getObjectDefinition();

    // initialize data and oid
    if ($createFromLoadedData)
    {
      // fill the given data into the definition
      $objectData['_data'] = $data;
      $oid = $this->constructOID($this->getType(), $objectData['_data']);
    }
    else
      $oid = null;

    // construct object
    $object = &$this->createObject($oid);

    // set object properties
    foreach($objectData['_properties'] as $property)
      $object->setProperty($property['name'], $property['value']);

    // apply data to the created object
    if ($createFromLoadedData)
      $this->applyDataOnLoad($object, $objectData, $attribs);
    else
      $this->applyDataOnCreate($object, $objectData, $attribs);

    return $object;
  }
  /**
   * Append the child data to an object. If the buildDepth does not determine to load a
   * child generation, only the oids of the children will be loaded.
   * @param object A reference to the object to append the children to
   * @param buildDepth @see PersistenceFacade::loadObjects()
   * @param buildAttribs @see PersistenceFacade::loadObjects()
   * @param buildTypes @see PersistenceFacade::loadObjects()
   */
  function appendChildData(&$object, $buildDepth, $buildAttribs=null, $buildTypes=null)
  {
    $persistenceFacade = &PersistenceFacade::getInstance();

    // recalculate build depth for the next generation
    if ($buildDepth != BUILDDEPTH_SINGLE && $buildDepth != BUILDDEPTH_INFINITE && $buildDepth > 0)
      $newBuildDepth = $buildDepth-1;
    else
      $newBuildDepth = $buildDepth;

    // get dependend objects of this object
    $childoids = array();
    $sqlArray = $this->getChildrenSelectSQL($object->getOID());
    foreach($sqlArray as $childType => $childCriteria)
    {
      $childoids = array_merge($childoids, $persistenceFacade->getOIDs($childType, $childCriteria));

      // load dependend objects if build depth is not satisfied already
      if (($buildDepth != BUILDDEPTH_SINGLE) && ($buildDepth > 0 || $buildDepth == BUILDDEPTH_INFINITE))
      {
        $childPagingInfo = null;
        $children = $persistenceFacade->loadObjects($childType, $newBuildDepth, $childCriteria, null, $childPagingInfo, $buildAttribs, $buildTypes);
        for ($j=0; $j<sizeof($children); $j++)
          $this->appendObject($object, $children[$j]);
      }
      $object->setProperty('childoids', $childoids);
    }
  }
  /**
   * @see PersistenceMapper::startTransaction()
   */
  function startTransaction()
  {
    if ($this->_conn == null)
      $this->connect();

    $this->_conn->beginTransaction();
  }
  /**
   * @see PersistenceMapper::commitTransaction()
   */
  function commitTransaction()
  {
    if ($this->_conn == null)
      $this->connect();

    $this->_conn->commit();
  }
  /**
   * @see PersistenceMapper::rollbackTransaction()
   * @note Rollbacks have to be supported by the database.
   */
  function rollbackTransaction()
  {
    if ($this->_conn == null)
      $this->connect();

    $this->_conn->rollBack();
  }

  /**
   * TEMPLATE METHODS
   * Subclasses must implement this method to define their object type.
   */

  /**
   * Factory method for the supported object type.
   * @note Subclasses must implement this method to define their object type.
   * @param oid The object id (maybe null)
   * @return A reference to the created object.
   */
  function &createObject($oid=null)
  {
    WCMFException::throwEx("createObject() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Add a dependend object (child) to an object.
   * @note Subclasses must implement this method to define their object type.
   * @param object The object to add to.
   * @param dependendObject The object to add.
   */
  function appendObject(&$object, &$dependendObject)
  {
    WCMFException::throwEx("appendObject() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Apply the loaded object data to the object.
   * @note Subclasses must implement this method to define their object type.
   * @param object A reference to the object created with createObject method to which the data should be applied
   * @param objectData The array returned by the getObjectDefinition method with the '_data' array filled with
   *                   the rows returned by execution of the database select statement (given by getSelectSQL). These
   *                   rows hold the loaded data.
   * @param attribs The build attributes for the type of object (given in the buildAttribs parameter of the loadImpl method)
   */
  function applyDataOnLoad(&$object, $objectData, $attribs)
  {
    WCMFException::throwEx("applyDataOnLoad() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Apply the default data to the object.
   * @note Subclasses must implement this method to define their object type.
   * @param object A reference to the object created with createObject method to which the data should be applied
   * @param objectData The array returned by the getObjectDefinition method. The default data are extracted from this.
   * @param attribs The build attributes for the type of object (given in the buildAttribs parameter of the loadImpl method).
   */
  function applyDataOnCreate(&$object, $objectData, $attribs)
  {
    WCMFException::throwEx("applyDataOnCreate() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Set the object primary key values for inserting the object to the database.
   * @note Subclasses must implement this method to define their object type.
   * @param object A reference to the object to insert.
   * @note The object does not have the final object id set. If a new id value for a primary key column is needed
   * for the insert statement, use RDBMapper::getNextId().
   */
  function prepareInsert(&$object)
  {
    WCMFException::throwEx("prepareInsert() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Get the object type this mapper supports.
   * @note Subclasses must implement this method to define their object type.
   * @return The name of the supported object type.
   */
  function getType()
  {
    WCMFException::throwEx("getType() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Get the object type definition.
   * @note Subclasses must implement this method to define their object type.
   * @return An assoziative array with unchangeable keys '_properties', '_datadef', '_children', '_data' plus application specific keys.
   * The predefined keys hold the following structures:
   *
   * - @em _properties: An array of assoziative arrays with the keys 'name', 'value' for every property
   *          (e.g. array('name' => 'display_value', 'value' => 'name'))
   * - @em _datadef: The structure of this key must be defined in the subclasses!
   * - @em _parents: An array of assoziative arrays with the key 'type' for every parent
   *          (e.g. array('type' => 'author'))
   * - @em _children: An array of assoziative arrays with the keys 'type', 'minOccurs', 'maxOccurs', 'aggregation', 'composition' for every child
   *          (e.g. array('type' => 'textblock', 'minOccurs' => 0, 'maxOccurs' => 'unbounded', 'aggregation' => true, 'composition' => false))
   * - @em _data: An assoziative array where the keys are the data item names defined in the @em _datadef array
   *          (e.g. array('title' => 'Hello User!'))
   *          @note The @em _data array will be overridden with data provided by the db select. No need for definition at this point!
   */
  function getObjectDefinition()
  {
    WCMFException::throwEx("getObjectDefinition() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Get the SQL command to select object data from the database.
   * @note Subclasses must implement this method to define their object type.
   * @param condStr The condition string (without 'WHERE').
   * @param orderStr The order string (without 'ORDER BY') (default: null uses default order).
   * @param attribs An array listing the attributes to load (default: null loads all attributes).
   * @param asArray True to get an associative array with keys 'attributeStr', 'tableStr', 'conditionStr', 'orderStr'
   *        and the appropriate query parts as value. [default: false]
   * @return A SQL command that selects all object data that match the condition or an array with the query parts.
   * Additionally columns 'ptype0' ('ptype1', ...) and 'pid0' ('pid1', ...) that define the objects parent are expected.
   * @note The names of the data item columns MUST match the data item names provided in the '_datadef' array from RDBMapper::getObjectDefinition()
   *       Use alias names if not! The selected data will be put into the '_data' array of the object definition.
   */
  function getSelectSQL($condStr, $orderStr=null, $attribs=null, $asArray=false)
  {
    WCMFException::throwEx("getSelectSQL() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Get the SQL commands to select the objects children from the database.
   * @note Subclasses must implement this method to define their object type.
   * @param oid The object id of the object to load the children for.
   * @param compositionOnly True/False indicates wether to only select composition children or all [default: false].
   * @return An associative array with the children types as keys and the corresponding SQL conditions to be used as criteria parameter
   *       in PersistenceFacade::loadObjects().
   * @note We need to return an array because MySql doesn't support unions prior to version 4
   */
  function getChildrenSelectSQL($oid, $compositionOnly=false)
  {
    WCMFException::throwEx("getChildrenSelectSQL() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Get the SQL command to disassociate the objects children from the object (e.g. setting the foreign key to null).
   * @note Subclasses must implement this method to define their object type.
   * @param oid The object id of the object to disassociate the children from.
   * @param sharedOnly True/False indicates wether to only disassociate shared children or all [default: false].
   * @return An array of SQL commands that disassociate all object children.
   */
  function getChildrenDisassociateSQL($oid, $sharedOnly=false)
  {
    WCMFException::throwEx("getChildrenDisassociateSQL() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Get the SQL command to insert a object into the database.
   * @note Subclasses must implement this method to define their object type.
   * @param object A reference to the object to insert.
   * @return An array of SQL commands that insert a new object.
   */
  function getInsertSQL(&$object)
  {
    WCMFException::throwEx("getInsertSQL() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Get the SQL command to update a object in the database.
   * @note Subclasses must implement this method to define their object type.
   * @param object A reference to the object to update.
   * @return An array of SQL commands that update an existing object.
   */
  function getUpdateSQL(&$object)
  {
    WCMFException::throwEx("getUpdateSQL() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Get the SQL command to delete a object from the database.
   * @note Subclasses must implement this method to define their object type.
   * @param oid The object id of the object to delete.
   * @return An array of SQL commands that delete an existing object.
   */
  function getDeleteSQL($oid)
  {
    WCMFException::throwEx("getDeleteSQL() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
  /**
   * Create a condition string for the primary key values of the form id1=val1, id2=val2, ...
   * @note Subclasses must implement this method to define their object type.
   * @param oid The object id that defines the primary key values
   * @return The string
   */
  function createPKCondition($oid)
  {
    WCMFException::throwEx("createPKCondition() must be implemented by derived class: ".get_class($this), __FILE__, __LINE__);
  }
}
?>