1: <?php
  2: /**
  3:  * A library for accessing the Kolab user database.
  4:  *
  5:  * PHP version 5
  6:  *
  7:  * @category Kolab
  8:  * @package  Kolab_Server
  9:  * @author   Gunnar Wrobel <wrobel@pardus.de>
 10:  * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
 11:  * @link     http://pear.horde.org/index.php?package=Kolab_Server
 12:  */
 13: 
 14: /**
 15:  * Interface for a server object list.
 16:  *
 17:  * Copyright 2008-2012 Horde LLC (http://www.horde.org/)
 18:  *
 19:  * See the enclosed file COPYING for license information (LGPL). If you
 20:  * did not receive this file, see http://www.horde.org/licenses/lgpl21.
 21:  *
 22:  * @category Kolab
 23:  * @package  Kolab_Server
 24:  * @author   Gunnar Wrobel <wrobel@pardus.de>
 25:  * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
 26:  * @link     http://pear.horde.org/index.php?package=Kolab_Server
 27:  */
 28: interface Horde_Kolab_Server_Objects_Interface
 29: {
 30:     /**
 31:      * Set the composite server reference for this object.
 32:      *
 33:      * @param Horde_Kolab_Server_Composite $composite A link to the composite
 34:      *                                                server handler.
 35:      */
 36:     public function setComposite(
 37:         Horde_Kolab_Server_Composite $composite
 38:     );
 39: 
 40:     /**
 41:      * Add a Kolab object.
 42:      *
 43:      * @param array $info The object to store.
 44:      *
 45:      * @return Kolab_Object The newly created Kolab object.
 46:      *
 47:      * @throws Horde_Kolab_Server_Exception If the type of the object to add has
 48:      *                                      been left undefined or the object
 49:      *                                      already exists.
 50:      */
 51:     public function add(array $info);
 52: 
 53:     /**
 54:      * Fetch a Kolab object.
 55:      *
 56:      * This method will not retrieve any data from the server
 57:      * immediately. Instead it will simply generate a new instance for the
 58:      * desired object.
 59:      *
 60:      * The server data will only be accessed once you start reading the object
 61:      * data.
 62:      *
 63:      * This method can also be used in order to fetch non-existing objects that
 64:      * will be saved later. This is however not recommended and you should
 65:      * rather use the add($info) method for that.
 66:      *
 67:      * If you do not provide the object type the server will try to determine it
 68:      * automatically based on the uid. As this requires reading data from the
 69:      * server it is recommended to specify the object type whenever it is known.
 70:      *
 71:      * If you do not specify a uid the object corresponding to the user bound to
 72:      * the server will be returned.
 73:      *
 74:      * @param string $uid  The UID of the object to fetch.
 75:      * @param string $type The type of the object to fetch.
 76:      *
 77:      * @return Kolab_Object The corresponding Kolab object.
 78:      *
 79:      * @throws Horde_Kolab_Server_Exception
 80:      */
 81:     public function fetch($uid = null, $type = null);
 82: 
 83:     /**
 84:      * List all objects of a specific type
 85:      *
 86:      * @param string $type   The type of the objects to be listed
 87:      * @param array  $params Additional parameters.
 88:      *
 89:      * @return array An array of Kolab objects.
 90:      *
 91:      * @throws Horde_Kolab_Server_Exception
 92:      */
 93:     public function listObjects($type, $params = null);
 94: 
 95:     /**
 96:      * Generate a hash representation for a list of objects.
 97:      *
 98:      * The approach taken here is somewhat slow as the server data gets fetched
 99:      * into objects first which are then converted to hashes again. Since a
100:      * server search will usually deliver the result as a hash the intermediate
101:      * object conversion is inefficient.
102:      *
103:      * But as the object classes are able to treat the attributes returned from
104:      * the server with custom parsing, this is currently the preferred
105:      * method. Especially for large result sets it would be better if this
106:      * method would call a static object class function that operate on the
107:      * result array returned from the server without using objects.
108:      *
109:      * @param string $type   The type of the objects to be listed
110:      * @param array  $params Additional parameters.
111:      *
112:      * @return array An array of Kolab objects.
113:      *
114:      * @throws Horde_Kolab_Server_Exception
115:      *
116:      * @todo The LDAP driver needs a more efficient version of this call as it
117:      *       is not required to generate objects before returning data as a
118:      *       hash. It can be derived directly from the LDAP result.
119:      */
120:     public function listHash($type, $params = null);
121: 
122: }