1: <?php
2: /**
3: * The base class representing Kolab objects stored in the server
4: * database.
5: *
6: * PHP version 5
7: *
8: * @category Kolab
9: * @package Kolab_Server
10: * @author Gunnar Wrobel <wrobel@pardus.de>
11: * @license http://www.horde.org/licenses/lgpl21 LGPL 2.1
12: * @link http://pear.horde.org/index.php?package=Kolab_Server
13: */
14:
15: /**
16: * This class provides methods to deal with Kolab objects stored in
17: * the Kolab db.
18: *
19: * Copyright 2008-2012 Horde LLC (http://www.horde.org/)
20: *
21: * See the enclosed file COPYING for license information (LGPL). If you
22: * did not receive this file, see http://www.horde.org/licenses/lgpl21.
23: *
24: * @category Kolab
25: * @package Kolab_Server
26: * @author Gunnar Wrobel <wrobel@pardus.de>
27: * @license http://www.horde.org/licenses/lgpl21 LGPL 2.1
28: * @link http://pear.horde.org/index.php?package=Kolab_Server
29: */
30: abstract class Horde_Kolab_Server_Object_Base
31: implements Horde_Kolab_Server_Object_Interface
32: {
33: /**
34: * Link to the Kolab server.
35: *
36: * @var Horde_Kolab_Server_Composite
37: */
38: private $_composite;
39:
40: /**
41: * GUID of this object on the Kolab server.
42: *
43: * @var string
44: */
45: protected $guid;
46:
47: /**
48: * Initialize the Kolab Object. Provide either the GUID
49: *
50: * @param Horde_Kolab_Server_Composite $composite The link to the Kolab server.
51: * @param string $guid GUID of the object.
52: */
53: public function __construct(
54: Horde_Kolab_Server_Composite $composite,
55: $guid = null
56: ) {
57: $this->_composite = $composite;
58: $this->guid = $guid;
59: }
60:
61: /**
62: * Get the GUID of this object
63: *
64: * @return string the GUID of this object
65: */
66: public function getGuid()
67: {
68: if ($this->guid === null) {
69: throw new Horde_Kolab_Server_Exception(
70: 'Uninitialized object is missing GUID!'
71: );
72: }
73: return $this->guid;
74: }
75:
76: /**
77: * Get the external attributes supported by this object.
78: *
79: * @return array The external attributes supported by this object. This is a
80: * list of abbreviated attribute class names.
81: */
82: public function getExternalAttributes()
83: {
84: return $this->_composite->structure->getExternalAttributes($this);
85: }
86:
87: /**
88: * Get the internal attributes supported by this object.
89: *
90: * @return array The internal attributes supported by this object.
91: */
92: public function getInternalAttributes()
93: {
94: return $this->_composite->structure->getInternalAttributes($this);
95: }
96:
97: /**
98: * Does the object exist?
99: *
100: * @return boolean True if the object exists, false otherwise.
101: */
102: public function exists()
103: {
104: try {
105: $this->readInternal();
106: return true;
107: } catch (Horde_Kolab_Server_Exception $e) {
108: return false;
109: }
110: }
111:
112: /**
113: * Read the object data.
114: *
115: * @return array The read data.
116: */
117: public function readInternal()
118: {
119: return $this->_composite->server->readAttributes(
120: $this->getGuid(), $this->getInternalAttributes()
121: );
122: }
123:
124: /**
125: * Get the specified internal attributes.
126: *
127: * @param array $attributes The internal attribute.
128: *
129: * @return array The value(s) of these attribute
130: */
131: public function getInternal(array $attributes)
132: {
133: $result = $this->readInternal();
134:
135: $values = array();
136: foreach ($attributes as $attribute) {
137:
138: if (!isset($result[$attribute])) {
139: throw new Horde_Kolab_Server_Exception_Novalue(
140: sprintf(
141: "No value for attribute \"%s\"!",
142: $attribute
143: )
144: );
145: }
146: $values[$attribute] = $result[$attribute];
147: }
148: return $values;
149: }
150:
151: /**
152: * Get the specified attribute of this object.
153: *
154: * @param string $attr The attribute to read.
155: *
156: * @return mixed The value of this attribute.
157: */
158: public function getExternal($attr)
159: {
160: if (!in_array($attr, $this->getExternalAttributes())) {
161: throw new Horde_Kolab_Server_Exception(
162: sprintf("Attribute \"%s\" not supported!", $attr)
163: );
164: }
165: $attribute = $this->_composite->structure->getExternalAttribute(
166: $attr, $this
167: );
168: return $attribute->value();
169: }
170:
171: /**
172: * Saves object information. This may either create a new entry or modify an
173: * existing entry.
174: *
175: * Please note that fields with multiple allowed values require the callee
176: * to provide the full set of values for the field. Any old values that are
177: * not resubmitted will be considered to be deleted.
178: *
179: * @param array $info The information about the object.
180: *
181: * @return NULL
182: *
183: * @throws Horde_Kolab_Server_Exception If saving the data failed.
184: */
185: public function save(array $info)
186: {
187: /** Handle all class specific transformations of the provided data */
188: $this->prepareObjectInformation($info);
189:
190: $internal = $this->getNewInternal($info);
191:
192: $guid = $this->_composite->structure->generateServerGuid(
193: get_class($this), $this->generateId($internal), $internal
194: );
195:
196: if ($this->exists()) {
197: if ($guid != $this->guid) {
198: $this->_composite->server->rename($this->guid, $guid);
199: $this->guid = $guid;
200: }
201: $result = $this->_composite->server->save($this, $internal);
202: } else {
203: $this->guid = $guid;
204: $this->_composite->server->add($this, $internal);
205: }
206: }
207:
208: /**
209: * Transform the given data array into the new internal dataset.
210: *
211: * @param array $info The information about the object.
212: *
213: * @return NULL
214: *
215: * @throws Horde_Kolab_Server_Exception If transforming the data failed.
216: */
217: protected function getNewInternal($info)
218: {
219: $internal = array();
220: foreach ($info as $external => $value) {
221: $attribute = $this->_composite->structure->getExternalAttribute(
222: $external, $this
223: );
224: $internal = array_merge($internal, $attribute->update($info));
225: }
226: return $internal;
227: }
228:
229: /**
230: * Delete this object.
231: *
232: * @return NULL
233: *
234: * @throws Horde_Kolab_Server_Exception If deleting the object failed.
235: */
236: public function delete()
237: {
238: $this->_composite->server->delete($this->getGuid());
239: }
240: }
241: