1: <?php
2: /**
3: * A log decorator for the data handlers.
4: *
5: * PHP version 5
6: *
7: * @category Kolab
8: * @package Kolab_Storage
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_Storage
12: */
13:
14: /**
15: * A log decorator for the data handlers.
16: *
17: * Copyright 2011-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: * @since Horde_Kolab_Storage 1.1.0
23: *
24: * @category Kolab
25: * @package Kolab_Storage
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_Storage
29: */
30: class Horde_Kolab_Storage_Data_Decorator_Log
31: implements Horde_Kolab_Storage_Data, Horde_Kolab_Storage_Data_Query
32: {
33: /**
34: * Decorated data handler.
35: *
36: * @var Horde_Kolab_Storage_Data
37: */
38: private $_data;
39:
40: /**
41: * A log handler.
42: *
43: * @var mixed
44: */
45: private $_logger;
46:
47: /**
48: * Constructor.
49: *
50: * @param Horde_Kolab_Storage_Data $data The original data handler.
51: * @param mixed $logger The log handler. This instance
52: * must provide the debug() and
53: * info() methods.
54: */
55: public function __construct(Horde_Kolab_Storage_Data $data,
56: $logger)
57: {
58: $this->_data = $data;
59: $this->_logger = $logger;
60: }
61:
62: /**
63: * Return the folder path for this data handler.
64: *
65: * @since Horde_Kolab_Storage 1.1.0
66: *
67: * @return string The folder path.
68: */
69: public function getPath()
70: {
71: return $this->_data->getPath();
72: }
73:
74: /**
75: * Return the ID of the current user.
76: *
77: * @since Horde_Kolab_Storage 1.1.0
78: *
79: * @return string The current user.
80: */
81: public function getAuth()
82: {
83: return $this->_data->getAuth();
84: }
85:
86: /**
87: * Return the ID of this data handler.
88: *
89: * @return string The ID.
90: */
91: public function getId()
92: {
93: return $this->_data->getId();
94: }
95:
96: /**
97: * Return the ID parameters for this data handler.
98: *
99: * @return array The ID parameters.
100: */
101: public function getIdParameters()
102: {
103: return $this->_data->getIdParameters();
104: }
105:
106: /**
107: * Return the data type represented by this object.
108: *
109: * @return string The type of data this instance handles.
110: */
111: public function getType()
112: {
113: return $this->_data->getType();
114: }
115:
116: /**
117: * Return the data version.
118: *
119: * @return string The data version.
120: */
121: public function getVersion()
122: {
123: return $this->_data->getVersion();
124: }
125:
126: /**
127: * Report the status of this folder.
128: *
129: * @return Horde_Kolab_Storage_Folder_Stamp The stamp that can be used for
130: * detecting folder changes.
131: */
132: public function getStamp()
133: {
134: return $this->_data->getStamp();
135: }
136:
137: /**
138: * Create a new object.
139: *
140: * @param array &$object The array that holds the object data.
141: * @param boolean $raw True if the data to be stored has been provided in
142: * raw format.
143: *
144: * @return string The ID of the new object or true in case the backend does
145: * not support this return value.
146: *
147: * @throws Horde_Kolab_Storage_Exception In case an error occured while
148: * saving the data.
149: */
150: public function create(&$object, $raw = false)
151: {
152: $this->_logger->info(
153: sprintf('Creating new data object in %s.', $this->_data->getPath())
154: );
155: $result = $this->_data->create($object, $raw);
156: $this->_logger->info(
157: sprintf(
158: 'Created data object %s in %s [backend: %s].',
159: $object['uid'],
160: $this->_data->getPath(),
161: $result
162: )
163: );
164: return $result;
165: }
166:
167: /**
168: * Modify an existing object.
169: *
170: * @param array $object The array that holds the updated object data.
171: * @param boolean $raw True if the data to be stored has been provided in
172: * raw format.
173: *
174: * @return NULL
175: *
176: * @throws Horde_Kolab_Storage_Exception In case an error occured while
177: * saving the data.
178: */
179: public function modify($object, $raw = false)
180: {
181: $this->_logger->info(
182: sprintf(
183: 'Modifying data object %s in %s.',
184: $object['uid'],
185: $this->_data->getPath()
186: )
187: );
188: $this->_data->modify($object, $raw);
189: $this->_logger->info(
190: sprintf(
191: 'Modified data object %s in %s.',
192: $object['uid'],
193: $this->_data->getPath()
194: )
195: );
196: }
197:
198: /**
199: * Retrieves the objects for the given UIDs.
200: *
201: * @param array $uids The message UIDs.
202: *
203: * @return array An array of objects.
204: */
205: public function fetch($uids)
206: {
207: $this->_logger->debug(
208: sprintf(
209: 'Fetching data objects %s in %s.',
210: join(',', $uids),
211: $this->_data->getPath()
212: )
213: );
214: return $this->_data->fetch($uids);
215: }
216:
217: /**
218: * Retrieves the complete message for the given UID.
219: *
220: * @param string $uid The message UID.
221: *
222: * @return array The message encapsuled as an array that contains a
223: * Horde_Mime_Headers and a Horde_Mime_Part object.
224: */
225: public function fetchComplete($uid)
226: {
227: $this->_logger->debug(
228: sprintf(
229: 'Fetching complete message id %s in %s.',
230: $uid,
231: $this->_data->getPath()
232: )
233: );
234: return $this->_data->fetchComplete($uid);
235: }
236:
237: /**
238: * Return the backend ID for the given object ID.
239: *
240: * @param string $object_uid The object ID.
241: *
242: * @return string The backend ID for the object.
243: */
244: public function getBackendId($object_id)
245: {
246: $result = $this->_data->getBackendId($object_id);
247: $this->_logger->debug(
248: sprintf(
249: 'Backend id for object %s is %s in %s.',
250: $object_id,
251: $result,
252: $this->_data->getPath()
253: )
254: );
255: return $result;
256: }
257:
258: /**
259: * Generate a unique object ID.
260: *
261: * @return string The unique ID.
262: */
263: public function generateUid()
264: {
265: $result = $this->_data->generateUid();
266: $this->_logger->debug(
267: sprintf(
268: 'Generated new uid %s for %s.',
269: $result,
270: $this->_data->getPath()
271: )
272: );
273: return $result;
274: }
275:
276: /**
277: * Check if the given object ID exists.
278: *
279: * @param string $object_id The object ID.
280: *
281: * @return boolean True if the ID was found, false otherwise.
282: */
283: public function objectIdExists($object_id)
284: {
285: return $this->_data->objectIdExists($object_id);
286: }
287:
288: /**
289: * Return the specified object.
290: *
291: * @param string $object_id The object id.
292: *
293: * @return array The object data as an array.
294: */
295: public function getObject($object_id)
296: {
297: return $this->_data->getObject($object_id);
298: }
299:
300: /**
301: * Return the specified attachment.
302: *
303: * @param string $attachment_id The attachment id.
304: *
305: * @return resource An open stream to the attachment data.
306: */
307: public function getAttachment($attachment_id)
308: {
309: return $this->_data->getAttachment($attachment_id);
310: }
311:
312: /**
313: * Retrieve all object ids in the current folder.
314: *
315: * @return array The object ids.
316: */
317: public function getObjectIds()
318: {
319: $result = $this->_data->getObjectIds();
320: if (count($result < 20)) {
321: $ids = '[' . join(', ', $result) . ']';
322: } else {
323: $ids = '[too many to list]';
324: }
325: $this->_logger->debug(
326: sprintf(
327: '%s has %s objects %s.',
328: $this->_data->getPath(),
329: count($result),
330: $ids
331: )
332: );
333: return $result;
334: }
335:
336: /**
337: * Retrieve all objects in the current folder.
338: *
339: * @return array An array of all objects.
340: */
341: public function getObjects()
342: {
343: $result = $this->_data->getObjects();
344: if (count($result < 20)) {
345: $ids = '[' . join(', ', array_keys($result)) . ']';
346: } else {
347: $ids = '[too many to list]';
348: }
349: $this->_logger->debug(
350: sprintf(
351: '%s has %s objects %s.',
352: $this->_data->getPath(),
353: count($result),
354: $ids
355: )
356: );
357: return $result;
358: }
359:
360: /**
361: * Retrieve all objects in the current folder by backend id.
362: *
363: * @since Horde_Kolab_Storage 1.1.0
364: *
365: * @return array An array of all objects.
366: */
367: public function getObjectsByBackendId()
368: {
369: $result = $this->_data->getObjectsByBackendId();
370: if (count($result < 20)) {
371: $ids = '[backend ids: ' . join(', ', array_keys($result)) . ']';
372: } else {
373: $ids = '[too many to list]';
374: }
375: $this->_logger->debug(
376: sprintf(
377: '%s has %s objects %s.',
378: $this->_data->getPath(),
379: count($result),
380: $ids
381: )
382: );
383: return $result;
384: }
385:
386: /**
387: * Retrieve an object in the current folder by backend id.
388: *
389: * @since Horde_Kolab_Storage 1.1.0
390: *
391: * @param string $uid Backend id of the object to be returned.
392: *
393: * @return array An array of all objects.
394: */
395: public function getObjectByBackendId($uid)
396: {
397: return $this->_data->getObjectByBackendId($uid);
398: }
399:
400: /**
401: * Return the mapping of object IDs to backend IDs.
402: *
403: * @since Horde_Kolab_Storage 1.1.0
404: *
405: * @return array The object to backend mapping.
406: */
407: public function getObjectToBackend()
408: {
409: return $this->_data->getObjectToBackend();
410: }
411:
412: /**
413: * Retrieve the list of object duplicates.
414: *
415: * @since Horde_Kolab_Storage 1.1.0
416: *
417: * @return array The list of duplicates.
418: */
419: public function getDuplicates()
420: {
421: return $this->_data->getDuplicates();
422: }
423:
424: /**
425: * Retrieve the list of object errors.
426: *
427: * @since Horde_Kolab_Storage 1.1.0
428: *
429: * @return array The list of errors.
430: */
431: public function getErrors()
432: {
433: return $this->_data->getErrors();
434: }
435:
436: /**
437: * Move the specified message from the current folder into a new
438: * folder.
439: *
440: * @param string $object_id ID of the message to be moved.
441: * @param string $new_folder Target folder.
442: *
443: * @return NULL
444: */
445: public function move($object_id, $new_folder)
446: {
447: $this->_logger->info(
448: sprintf(
449: 'Moving data object %s in %s to %s.',
450: $object_id,
451: $this->_data->getPath(),
452: $new_folder
453: )
454: );
455: $this->_data->move($object_ids, $new_folder);
456: $this->_logger->info(
457: sprintf(
458: 'Moved data object %s in %s to %s.',
459: $object_id,
460: $this->_data->getPath(),
461: $new_folder
462: )
463: );
464: }
465:
466: /**
467: * Delete the specified objects from this data set.
468: *
469: * @param array|string $object_ids Id(s) of the object to be deleted.
470: *
471: * @return NULL
472: */
473: public function delete($object_ids)
474: {
475: if (is_array($object_ids)) {
476: $ids = join(', ', $object_ids);
477: } else {
478: $ids = $object_ids;
479: }
480: $this->_logger->info(
481: sprintf(
482: 'Deleting data object(s) %s in %s.',
483: $ids,
484: $this->_data->getPath()
485: )
486: );
487: $this->_data->delete($object_ids);
488: $this->_logger->info(
489: sprintf(
490: 'Deleted data object(s) %s in %s.',
491: $ids,
492: $this->_data->getPath()
493: )
494: );
495: }
496:
497: /**
498: * Delete all objects from this data set.
499: *
500: * @return NULL
501: */
502: public function deleteAll()
503: {
504: $this->_logger->info(
505: sprintf(
506: 'Deleting all data objects in %s.',
507: $this->_data->getPath()
508: )
509: );
510: $this->_data->deleteAll();
511: $this->_logger->info(
512: sprintf(
513: 'Deleted all data objects in %s.',
514: $this->_data->getPath()
515: )
516: );
517: }
518:
519: /**
520: * Delete the specified messages from this folder.
521: *
522: * @since Horde_Kolab_Storage 1.1.0
523: *
524: * @param array|string $uids Backend id(s) of the message to be deleted.
525: *
526: * @return NULL
527: */
528: public function deleteBackendIds($uids)
529: {
530: if (is_array($uids)) {
531: $ids = join(', ', $uids);
532: } else {
533: $ids = $uids;
534: }
535: $this->_logger->info(
536: sprintf(
537: 'Deleting backend data object(s) %s in %s.',
538: $ids,
539: $this->_data->getPath()
540: )
541: );
542: $this->_data->deleteBackendIds($uids);
543: $this->_logger->info(
544: sprintf(
545: 'Deleted backend data object(s) %s in %s.',
546: $ids,
547: $this->_data->getPath()
548: )
549: );
550: }
551:
552: /**
553: * Synchronize the list information with the information from the backend.
554: *
555: * @param array $params Additional parameters.
556: *
557: * @return NULL
558: */
559: public function synchronize($params = array())
560: {
561: $this->_data->synchronize();
562: $this->_logger->debug(
563: sprintf(
564: 'Synchronized data cache for %s.',
565: $this->_data->getPath()
566: )
567: );
568: }
569:
570: /**
571: * Register a query to be updated if the underlying data changes.
572: *
573: * @param string $name The query name.
574: * @param Horde_Kolab_Storage_Query $query The query to register.
575: *
576: * @return NULL
577: */
578: public function registerQuery($name, Horde_Kolab_Storage_Query $query)
579: {
580: $this->_data->registerQuery($name, $query);
581: }
582:
583: /**
584: * Return a registered query.
585: *
586: * @param string $name The query name.
587: *
588: * @return Horde_Kolab_Storage_Query The requested query.
589: *
590: * @throws Horde_Kolab_Storage_Exception In case the requested query does
591: * not exist.
592: */
593: public function getQuery($name = null)
594: {
595: return $this->_data->getQuery($name);
596: }
597: }