1: <?php
  2: /**
  3:  * A simple structural handler for a tree of objects.
  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:  * The interface definition for the handlers dealing with the Kolab Server
 16:  * object tree structure.
 17:  *
 18:  * Copyright 2009-2012 Horde LLC (http://www.horde.org/)
 19:  *
 20:  * See the enclosed file COPYING for license information (LGPL). If you
 21:  * did not receive this file, see http://www.horde.org/licenses/lgpl21.
 22:  *
 23:  * @category Kolab
 24:  * @package  Kolab_Server
 25:  * @author   Gunnar Wrobel <wrobel@pardus.de>
 26:  * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
 27:  * @link     http://pear.horde.org/index.php?package=Kolab_Server
 28:  */
 29: interface Horde_Kolab_Server_Structure_Interface
 30: {
 31:     /**
 32:      * Finds object data matching a given set of criteria.
 33:      *
 34:      * @param Horde_Kolab_Server_Query_Element $criteria The criteria for the search.
 35:      * @param array                            $params   Additional search parameters.
 36:      *
 37:      * @return Horde_Kolab_Server_Result The result object.
 38:      *
 39:      * @throws Horde_Kolab_Server_Exception
 40:      */
 41:     public function find(
 42:         Horde_Kolab_Server_Query_Element_Interface $criteria,
 43:         array $params = array()
 44:     );
 45: 
 46:     /**
 47:      * Finds all object data below a parent matching a given set of criteria.
 48:      *
 49:      * @param Horde_Kolab_Server_Query_Element $criteria The criteria for the search.
 50:      * @param string                           $parent   The parent to search below.
 51:      * @param array                            $params   Additional search parameters.
 52:      *
 53:      * @return Horde_Kolab_Server_Result The result object.
 54:      *
 55:      * @throws Horde_Kolab_Server_Exception
 56:      */
 57:     public function findBelow(
 58:         Horde_Kolab_Server_Query_Element_Interface $criteria,
 59:         $parent,
 60:         array $params = array()
 61:     );
 62: 
 63:     /**
 64:      * Set the composite server reference for this object.
 65:      *
 66:      * @param Horde_Kolab_Server_Composite $composite A link to the composite
 67:      *                                                server handler.
 68:      *
 69:      * @return NULL
 70:      */
 71:     public function setComposite(
 72:         Horde_Kolab_Server_Composite $composite
 73:     );
 74: 
 75:     /**
 76:      * Returns the set of objects supported by this structure.
 77:      *
 78:      * @return array An array of supported objects.
 79:      */
 80:     public function getSupportedObjects();
 81: 
 82:     /**
 83:      * Returns the set of search operations supported by this object type.
 84:      *
 85:      * @return array An array of supported search operations.
 86:      */
 87:     public function getSearchOperations();
 88: 
 89:     /**
 90:      * Maps the external attribute name to its internal counterpart.
 91:      *
 92:      * @param string $external The external attribute name.
 93:      *
 94:      * @return string The internal attribute name.
 95:      */
 96:     public function mapExternalToInternalAttribute($external);
 97: 
 98:     /**
 99:      * Return the external attributes supported by the given object class.
100:      *
101:      * @param Horde_Kolab_Server_Object $object Determine the external
102:      *                                          attributes for this class.
103:      *
104:      * @return array The supported attributes.
105:      *
106:      * @throws Horde_Kolab_Server_Exception If the schema analysis fails.
107:      */
108:     public function getExternalAttributes($object);
109: 
110:     /**
111:      * Return the internal attributes supported by the given object class.
112:      *
113:      * @param Horde_Kolab_Server_Object $object Determine the internal
114:      *                                          attributes for this class.
115:      *
116:      * @return array The supported attributes.
117:      *
118:      * @throws Horde_Kolab_Server_Exception If the schema analysis fails.
119:      */
120:     public function getInternalAttributes($object);
121: 
122:     public function getExternalAttribute(
123:         $name,
124:         Horde_Kolab_Server_Object_Interface $object
125:     );
126: 
127:     /**
128:      * Determine the type of an object by its tree position and other
129:      * parameters.
130:      *
131:      * @param string $guid The GUID of the object to examine.
132:      *
133:      * @return string The class name of the corresponding object type.
134:      *
135:      * @throws Horde_Kolab_Server_Exception If the object type is unknown.
136:      */
137:     public function determineType($guid);
138: 
139:     /**
140:      * Generates a UID for the given information.
141:      *
142:      * @param string $type The class name of the object to create.
143:      * @param string $id   The id of the object.
144:      * @param array  $info Any additional information about the object to create.
145:      *
146:      * @return string The GUID.
147:      *
148:      * @throws Horde_Kolab_Server_Exception If the given type is unknown.
149:      */
150:     public function generateServerGuid($type, $id, array $info);
151: }
152: