<?php

/**
 * Maps Location + Object ID to DomainObject, implements locate,
 * insert, update and delete
 *
 *
 * Copyright (c) 2007 Yahoo! Inc.  All rights reserved.
 * The copyrights embodied in the content of this file are licensed under the BSD
 * open source license
 *
 * @package    r3
 * @author     Bill Hails <hide@address.com>
 * @version    CVS: $Id: Mapper.php,v 1.15 2008-02-27 22:32:26 yili Exp $
 */

/**
 * requires
 */


require_once("r3/domain/Location.php");
require_once("r3/domain/DomainObject.php");
require_once("r3/util/UTF8.php");


interface r3_Mapper {
    /**
     * function locate( r3_domain_Location $l, r3_ObjectID $name)
     *
     * Returns an r3_domain_DomainObject or throws an exception if it can't find one
     *
     * @param r3_domain_Location the single location to search.
     * @param r3_util_UTF8 (string) the name to look for.
     * @return r3_domain_DomainObject the entity found.
     */
    function locate(r3_domain_Location $l, r3_util_UTF8 $name);

   /**
    * function insert( r3_domain_DomainObject $o )
    *
    * inserts the domain object. Throws r3_util_Exception on failure.
    *
    * @param r3_domain_DomainObject the object to insert.
    */
   function insert(r3_domain_DomainObject $o);

   /**
    * function update( r3_domain_DomainObject $o )
    *
    * updates the domain object record (identified by internal id)
    * cannot be used to "move" a template since the template location *is*
    * its id.
    *
    * @param r3_domain_DomainObject the object to update.
    */
   function update(r3_domain_DomainObject $o);

   /**
    * function delete( r3_domain_DomainObject $o )
    *
    * deletes the domain object recored (identified by internal id)
    *
    * @param r3_domain_DomainObject the object to delete
    */
    function delete( r3_domain_DomainObject $o );

    /**
     * creates a new temporary storage (typically a database table)
     *
     * @return string a unique name for the temporary storage
     */
     function create_temp();

     /**
      * deletes a previously created temporary location
      *
      * @param string $name as returned from create_temp
      */
     function drop_temp($name);

     /**
      * inserts a domain object into the temporary storage
      *
      * @param string $name as returned by create_temp
      * @param r3_domain_DomainObject $obj the object to insert
      * @return bool true if insert was successful
      */
     function insert_temp($name, r3_domain_DomainObject $obj);

     function clear();
}

?>