From: Michael J. Rubinsky Date: Wed, 31 Mar 2010 21:57:09 +0000 (-0400) Subject: Clean up Connector objects: X-Git-Url: https://git.internetallee.de/?a=commitdiff_plain;h=bd313a46a7ff0ae1af22f7be495c841b6118e1ee;p=horde.git Clean up Connector objects: phpdoc, ws, variablenames, remove obsolete parameters, class constants etc... --- diff --git a/framework/ActiveSync/lib/Horde/ActiveSync.php b/framework/ActiveSync/lib/Horde/ActiveSync.php index dd6599157..08e8ae818 100644 --- a/framework/ActiveSync/lib/Horde/ActiveSync.php +++ b/framework/ActiveSync/lib/Horde/ActiveSync.php @@ -437,9 +437,6 @@ define("SYNC_FOLDER_TYPE_UNKNOWN", 18); define("SYNC_FOLDER_TYPE_RECIPIENT_CACHE", 19); define("SYNC_FOLDER_TYPE_DUMMY", "__dummy.Folder.Id__"); -define("SYNC_CONFLICT_OVERWRITE_SERVER", 0); -define("SYNC_CONFLICT_OVERWRITE_PIM", 1); - define("SYNC_TRUNCATION_HEADERS", 0); define("SYNC_TRUNCATION_512B", 1); define("SYNC_TRUNCATION_1K", 2); @@ -856,6 +853,10 @@ class Horde_ActiveSync ) ); + /* Constants */ + const CONFLICT_OVERWRITE_SERVER = 0; + const CONFLICT_OVERWRITE_PIM = 1; + /** * Provisioning support * diff --git a/framework/ActiveSync/lib/Horde/ActiveSync/Connector/Exporter.php b/framework/ActiveSync/lib/Horde/ActiveSync/Connector/Exporter.php index 89e77caba..ec64d9e56 100644 --- a/framework/ActiveSync/lib/Horde/ActiveSync/Connector/Exporter.php +++ b/framework/ActiveSync/lib/Horde/ActiveSync/Connector/Exporter.php @@ -1,5 +1,14 @@ + * @package Horde_ActiveSync + */ +/** * File : streamimporter.php * Project : Z-Push * Descr : Stream import classes @@ -10,60 +19,97 @@ * This file is distributed under GPL v2. * Consult LICENSE file for details */ - -/** - * - * - */ class Horde_ActiveSync_Connector_Exporter { + /** + * The wbxml encoder + * + * @var Horde_ActiveSync_Wbxml_Encoder + */ protected $_encoder; - protected $_type; - protected $_seenObjects; - + + /** + * The collection class for what we are exporting + * + * @var string + */ + protected $_class; + + /** + * Local cache of object ids we have already dealt with. + * + * @var array + */ + protected $_seenObjects = array(); + + /** + * Array of object ids that have changed. + * Used when exporting folder structure changes since they are not streamed + * from this object. + * + * @var array + */ public $changed = array(); + + /** + * Array of folder ids that have been deleted on the server. + * + * @var array + */ public $deleted = array(); + + /** + * Tracks the total number of folder changes + * + * @var integer + */ public $count = 0; /** * Const'r * - * @param Horde_ActiveSync_Wbxml_Encoder $encoder - * @param string $class The collection class + * @param Horde_ActiveSync_Wbxml_Encoder $encoder The encoder + * @param string $class The collection class * * @return Horde_ActiveSync_Connector_Exporter */ public function __construct($encoder = null, $class = null) { $this->_encoder = $encoder; - $this->_type = $class; - $this->_seenObjects = array(); + $this->_class = $class; } /** + * Send a message change over the wbxml stream * - * @param $id - * @param $message - * @return unknown_type + * @param string $id Thenuid of the message + * @param Horde_ActiveSync_Message_Base $message The message object + * + * @return boolean */ public function messageChange($id, $message) { - if ($message->getClass() != $this->_type) { - return true; // ignore other types + /* Just ignore any messages that are not from this collection */ + if ($message->getClass() != $this->_class) { + return true; } - // prevent sending the same object twice in one request + /* Prevent sending the same object twice in one request */ if (in_array($id, $this->_seenObjects)) { return true; } + /* Remember this message */ $this->_seenObjects[] = $id; + + /* Specify if this is an ADD or a MODIFY change? */ if ($message->flags === false || $message->flags === SYNC_NEWMESSAGE) { $this->_encoder->startTag(SYNC_ADD); } else { $this->_encoder->startTag(SYNC_MODIFY); } + /* Send the message */ $this->_encoder->startTag(SYNC_SERVERENTRYID); $this->_encoder->content($id); $this->_encoder->endTag(); @@ -76,9 +122,11 @@ class Horde_ActiveSync_Connector_Exporter } /** + * Stream a message deletion to the PIM * - * @param $id - * @return unknown_type + * @param string $id The uid of the message we are deleting. + * + * @return boolean */ public function messageDeletion($id) { @@ -92,16 +140,21 @@ class Horde_ActiveSync_Connector_Exporter } /** + * Change a message's READ flag. + * + * @param string $id The uid + * @param integer $flags The flag * - * @param $id - * @param $flags - * @return unknown_type + * @return boolean */ public function messageReadFlag($id, $flags) { - if ($this->_type != "syncmail") { + /* This only applies to mail folders */ + if ($this->_class != "syncmail") { return true; } + + /* Encode and stream */ $this->_encoder->startTag(SYNC_MODIFY); $this->_encoder->startTag(SYNC_SERVERENTRYID); $this->_encoder->content($id); @@ -117,9 +170,11 @@ class Horde_ActiveSync_Connector_Exporter } /** + * Move a message to a different folder. + * @TODO + * @param Horde_ActiveSync_Message_Base $message The message * - * @param $message - * @return unknown_type + * @return boolean */ function messageMove($message) { @@ -127,9 +182,11 @@ class Horde_ActiveSync_Connector_Exporter } /** + * Add a folder change to the cache. (used during FolderSync Requests). + * + * @param Horde_ActiveSync_Message_Folder $folder * - * @param $folder - * @return + * @return boolean */ public function FolderChange($folder) { @@ -140,9 +197,11 @@ class Horde_ActiveSync_Connector_Exporter } /** + * Add a folder deletion to the cache (used during FolderSync Requests). * - * @param $id - * @return + * @param string $id The folder id + * + * @return boolean */ public function FolderDeletion($id) { diff --git a/framework/ActiveSync/lib/Horde/ActiveSync/Connector/Importer.php b/framework/ActiveSync/lib/Horde/ActiveSync/Connector/Importer.php index 15212e9ad..f3c9a23e5 100644 --- a/framework/ActiveSync/lib/Horde/ActiveSync/Connector/Importer.php +++ b/framework/ActiveSync/lib/Horde/ActiveSync/Connector/Importer.php @@ -1,30 +1,42 @@ + * @package Horde_ActiveSync + */ +/** + * File : streamimporter.php + * Project : Z-Push + * Descr : Stream import classes + * + * Created : 01.10.2007 + * + * � Zarafa Deutschland GmbH, www.zarafaserver.de + * This file is distributed under GPL v2. + * Consult LICENSE file for details */ class Horde_ActiveSync_Connector_Importer { /** + * State machine * - * @var Horde_ActiveSync_StateMachine_Base + * @var Horde_ActiveSync_State_Base */ - protected $_stateMachine; + protected $_state; /** + * The backend driver for communicating with the server we are syncing with. * * @var Horde_ActiveSync_Driver_Base */ protected $_backend; /** - * Sync key for current request * - * @var string - */ - protected $_syncKey; - - /** * @TODO * @var */ @@ -43,30 +55,38 @@ class Horde_ActiveSync_Connector_Importer * Const'r * * @param Horde_ActiveSync_Driver_Base $backend - * @param Horde_ActiveSync_StateMachine_Base $stateMachine - * @param $syncKey - * @param $flags */ public function __construct(Horde_ActiveSync_Driver_Base $backend) { $this->_backend = $backend; } - public function init(Horde_ActiveSync_State_Base &$stateMachine, - $folderId, $syncKey, $flags = 0) + /** + * Initialize the exporter for this collection + * + * @param Horde_ActiveSync_State_Base $state The state machine + * @param string $folderId The collection's id + * @param integer $flags Any flags + */ + public function init(Horde_ActiveSync_State_Base &$state, $folderId, $flags = 0) { - $this->_stateMachine = &$stateMachine; - $this->_syncKey = $syncKey; + $this->_state = &$state; $this->_flags = $flags; $this->_folderId = $folderId; } + /** + * Setter for a logger instance + * + * @param Horde_Log_Logger $logger The logger + */ public function setLogger($logger) { $this->_logger = $logger; } /** + * Import a message change from the wbxml stream * * @param mixed $id A server message id or * false if a new message @@ -76,68 +96,73 @@ class Horde_ActiveSync_Connector_Importer */ public function ImportMessageChange($id, $message) { - //do nothing if it is in a dummy folder + /* do nothing if it is in a dummy folder */ if ($this->_folderId == SYNC_FOLDER_TYPE_DUMMY) { return false; } + /* Changing an existing object */ if ($id) { - // See if there's a conflict + /* Check for conflicts */ $conflict = $this->_isConflict('change', $this->_folderId, $id); - // Update client state if this is an update + /* Update client state */ $change = array(); $change['id'] = $id; $change['mod'] = 0; // dummy, will be updated later if the change succeeds $change['parent'] = $this->_folderId; $change['flags'] = (isset($message->read)) ? $message->read : 0; - $this->_stateMachine->updateState('change', $change); + $this->_state->updateState('change', $change); - if ($conflict && $this->_flags == SYNC_CONFLICT_OVERWRITE_PIM) { + /* If this is a conflict, see if the server wins */ + if ($conflict && $this->_flags == Horde_ActiveSync::CONFLICT_OVERWRITE_PIM) { return true; } } + /* Tell the backend about the change */ $stat = $this->_backend->ChangeMessage($this->_folderId, $id, $message); - // @TODO: Isn't this an error? if (!is_array($stat)) { return $stat; } - // Record the state of the message - $this->_stateMachine->updateState('change', $stat); + /* Record the state of the message */ + $this->_state->updateState('change', $stat); return $stat['id']; } /** - * Import a deletion. This may conflict if the local object has been + * Import a message deletion. This may conflict if the local object has been * modified. * - * @param string $id Server message id + * @param string $id Server message uid + * + * @return boolean */ public function ImportMessageDeletion($id) { - //do nothing if it is in a dummy folder + /* Do nothing if it is in a dummy folder */ if ($this->_folderId == SYNC_FOLDER_TYPE_DUMMY) { return true; } - // See if there's a conflict + /* Check for conflict */ $conflict = $this->_isConflict('delete', $this->_folderId, $id); - // Update client state + /* Update client state */ $change = array(); $change['id'] = $id; - $this->_stateMachine->updateState('delete', $change); + $this->_state->updateState('delete', $change); - // If there is a conflict, and the server 'wins', then return OK without - // performing the change this will cause the exporter to 'see' the - // overriding item as a change, and send it back to the PIM - if ($conflict && $this->_flags == SYNC_CONFLICT_OVERWRITE_PIM) { + /* If server wins the conflict, don't import change - it will be + * detected on next sync and sent back to PIM (since we updated the PIM + * state). */ + if ($conflict && $this->_flags == Horde_ActiveSync::CONFLICT_OVERWRITE_PIM) { return true; } + /* Tell backend about the deletion */ $this->_backend->DeleteMessage($this->_folderId, $id); return true; @@ -151,27 +176,32 @@ class Horde_ActiveSync_Connector_Importer */ public function ImportMessageReadFlag($id, $flags) { - //do nothing if it is a dummy folder + /* Do nothing if it is a dummy folder */ if ($this->_folderId == SYNC_FOLDER_TYPE_DUMMY) { return true; } - // Update client state + /* Update client state */ $change = array(); $change['id'] = $id; $change['flags'] = $flags; - $this->_stateMachine->updateState('flags', $change); + $this->_state->updateState('flags', $change); + + /* Tell backend */ $this->_backend->SetReadFlag($this->_folderId, $id, $flags); return true; } /** - * Not supported/todo? + * Perform a message move initiated on the PIM. + * + * @TODO * - * @param $id - * @param $newfolder - * @return + * @param string $id The message id + * @param $newfolder + * + * @return boolean */ public function ImportMessageMove($id, $newfolder) { @@ -179,16 +209,18 @@ class Horde_ActiveSync_Connector_Importer } /** + * Import a folder change from the wbxml stream + * + * @param string $id The folder id + * @param string $parent The parent folder id? + * @param string $displayname The folder display name + * @param $type The collection type? * - * @param $id - * @param $parent - * @param $displayname - * @param $type - * @return unknown_type + * @return boolean */ public function ImportFolderChange($id, $parent, $displayname, $type) { - //do nothing if it is a dummy folder + /* do nothing if it is a dummy folder */ if ($parent == SYNC_FOLDER_TYPE_DUMMY) { return false; } @@ -199,27 +231,29 @@ class Horde_ActiveSync_Connector_Importer $change['mod'] = $displayname; $change['parent'] = $parent; $change['flags'] = 0; - $this->_stateMachine->updateState('change', $change); + $this->_state->updateState('change', $change); } - // @TODO: ChangeFolder did not exist in ZPush's code?? + /* Tell the backend */ $stat = $this->_backend->ChangeFolder($parent, $id, $displayname, $type); if ($stat) { - $this->_stateMachine->updateState('change', $stat); + $this->_state->updateState('change', $stat); } return $stat['id']; } /** + * Imports a folder deletion from the PIM + * + * @param string $id The folder id + * @param string $parent The folder id of the parent folder * - * @param $id - * @param $parent - * @return unknown_type + * @return boolean */ public function ImportFolderDeletion($id, $parent) { - //do nothing if it is a dummy folder + /* Do nothing if it is a dummy folder */ if ($parent == SYNC_FOLDER_TYPE_DUMMY) { return false; } @@ -227,14 +261,14 @@ class Horde_ActiveSync_Connector_Importer $change = array(); $change['id'] = $id; - $this->_stateMachine->updateState('delete', $change); + $this->_state->updateState('delete', $change); $this->_backend->DeleteFolder($parent, $id); return true; } /** - * Returns TRUE if the given ID conflicts with the given operation. + * Check if this change conflicts with server changes * This is only true in the following situations: * * Changed here and changed there @@ -243,20 +277,26 @@ class Horde_ActiveSync_Connector_Importer * * Any other combination of operations can be done * (e.g. change flags & move or move & delete) + * + * @param string $type The type of change('change', 'delete' etc...) + * @param string $folderid The id of the folder this change is from. + * @param string $id The uid for the changed message. + * + * @return boolean */ protected function _isConflict($type, $folderid, $id) { $stat = $this->_backend->StatMessage($folderid, $id); if (!$stat) { - // Message is gone + /* Message is gone, if type is change, this is a conflict */ if ($type == 'change') { return true; } else { - return false; // all other remote changes still result in a delete (no conflict) + return false; } } - return $this->_stateMachine->isConflict($stat, $type); + return $this->_state->isConflict($stat, $type); } } diff --git a/framework/ActiveSync/lib/Horde/ActiveSync/Connector/NullImporter.php b/framework/ActiveSync/lib/Horde/ActiveSync/Connector/NullImporter.php index 2d8f1d3e2..9378f9b1c 100644 --- a/framework/ActiveSync/lib/Horde/ActiveSync/Connector/NullImporter.php +++ b/framework/ActiveSync/lib/Horde/ActiveSync/Connector/NullImporter.php @@ -1,6 +1,14 @@ + * @package Horde_ActiveSync */ class Horde_ActiveSync_Connector_NullImporter { diff --git a/framework/ActiveSync/lib/Horde/ActiveSync/Driver/Horde.php b/framework/ActiveSync/lib/Horde/ActiveSync/Driver/Horde.php index bf513a412..74b57c198 100644 --- a/framework/ActiveSync/lib/Horde/ActiveSync/Driver/Horde.php +++ b/framework/ActiveSync/lib/Horde/ActiveSync/Driver/Horde.php @@ -443,7 +443,7 @@ class Horde_ActiveSync_Driver_Horde extends Horde_ActiveSync_Driver_Base * * @param string $folderid The folder id * @param string $id The message id - * @param mixed $hint ?? + * @param mixed $hint @TODO: Figure out what, exactly, this does :) * * @return message stat hash */ diff --git a/framework/ActiveSync/lib/Horde/ActiveSync/Request/FolderSync.php b/framework/ActiveSync/lib/Horde/ActiveSync/Request/FolderSync.php index 92ad9f845..be91f7a8f 100644 --- a/framework/ActiveSync/lib/Horde/ActiveSync/Request/FolderSync.php +++ b/framework/ActiveSync/lib/Horde/ActiveSync/Request/FolderSync.php @@ -21,6 +21,14 @@ class Horde_ActiveSync_Request_FolderSync extends Horde_ActiveSync_Request_Base const STATUS_KEYMISM = 9; const STATUS_PROTOERR = 10; + /** + * Handle the request. + * + * @param Horde_ActiveSync $activeSync The activesync server object + * @param string $devId The device id + * + * @return boolean + */ public function handle(Horde_ActiveSync $activeSync, $devId) { parent::handle($activeSync, $devId); @@ -99,7 +107,7 @@ class Horde_ActiveSync_Request_FolderSync extends Horde_ActiveSync_Request_Base /* Configure importer with last state */ $importer = $this->_driver->getImporter(); - $importer->init($state, false, $synckey); + $importer->init($state, false); while (1) { $folder = new Horde_ActiveSync_Message_Folder(array('logger' => $this->_logger)); @@ -140,12 +148,8 @@ class Horde_ActiveSync_Request_FolderSync extends Horde_ActiveSync_Request_Base /* Start sending server -> PIM changes */ $this->_logger->debug('[Horde_ActiveSync::handleFolderSync] Preparing to send changes to PIM'); - // The $importer caches all imports in-memory, so we can send a change - // count before sending the actual data. As the amount of data done in - // this operation is rather low, this is not memory problem. Note that - // this is not done when sync'ing messages - we let the exporter write - // directly to WBXML. - // TODO: Combine all these import caches into a single Class + // The $connector just caches all folder changes in-memory, so we can + // count before sending the actual data. $connector = new Horde_ActiveSync_Connector_Exporter(); $sync = $this->_driver->GetSyncObject(); $sync->init($state, $connector, array('synckey' => $synckey)); diff --git a/framework/ActiveSync/lib/Horde/ActiveSync/Request/Sync.php b/framework/ActiveSync/lib/Horde/ActiveSync/Request/Sync.php index 0e0883fc6..52e965864 100644 --- a/framework/ActiveSync/lib/Horde/ActiveSync/Request/Sync.php +++ b/framework/ActiveSync/lib/Horde/ActiveSync/Request/Sync.php @@ -201,14 +201,14 @@ class Horde_ActiveSync_Request_Sync extends Horde_ActiveSync_Request_Base /* compatibility mode - set default conflict behavior if no * conflict resolution algorithm is set */ if (!isset($collection['conflict'])) { - $collection['conflict'] = SYNC_CONFLICT_OVERWRITE_PIM; + $collection['conflict'] = Horde_ActiveSync::CONFLICT_OVERWRITE_PIM; } } if ($this->_decoder->getElementStartTag(SYNC_COMMANDS)) { /* Configure importer with last state */ $importer = $this->_driver->getImporter(); - $importer->init($state, $collection['id'], $collection['synckey'], $collection['conflict']); + $importer->init($state, $collection['id'], $collection['conflict']); $nchanges = 0; while (1) { // MODIFY or REMOVE or ADD or FETCH