diff options
author | Bernhard Posselt <nukeawhale@gmail.com> | 2013-06-04 22:45:19 +0200 |
---|---|---|
committer | Bernhard Posselt <nukeawhale@gmail.com> | 2013-06-04 22:45:19 +0200 |
commit | 80a62c0383730204d92b6690481f0e45de677d70 (patch) | |
tree | 6d014b7df8c5833b8084a42a398489e851b5e130 /businesslayer | |
parent | 991f8e0c51810d7ed89a7c73383fdbf2541c0637 (diff) |
added javadoc for the businesslayer
Diffstat (limited to 'businesslayer')
-rw-r--r-- | businesslayer/businesslayer.php | 17 | ||||
-rw-r--r-- | businesslayer/feedbusinesslayer.php | 48 | ||||
-rw-r--r-- | businesslayer/folderbusinesslayer.php | 31 | ||||
-rw-r--r-- | businesslayer/itembusinesslayer.php | 80 |
4 files changed, 145 insertions, 31 deletions
diff --git a/businesslayer/businesslayer.php b/businesslayer/businesslayer.php index 4ce6f1625..54b64d6a2 100644 --- a/businesslayer/businesslayer.php +++ b/businesslayer/businesslayer.php @@ -40,12 +40,27 @@ abstract class BusinessLayer { } + /** + * Delete an entity + * @param int $id the id of the entity + * @param string $userId the name of the user for security reasons + * @throws DoesNotExistException if the entity does not exist + * @throws MultipleObjectsReturnedException if more than one entity exists + */ public function delete($id, $userId){ $entity = $this->find($id, $userId); $this->mapper->delete($entity); } + /** + * Finds an entity by id + * @param int $id the id of the entity + * @param string $userId the name of the user for security reasons + * @throws DoesNotExistException if the entity does not exist + * @throws MultipleObjectsReturnedException if more than one entity exists + * @return Entity the entity + */ public function find($id, $userId){ try { return $this->mapper->find($id, $userId); @@ -56,4 +71,4 @@ abstract class BusinessLayer { } } -}
\ No newline at end of file +} diff --git a/businesslayer/feedbusinesslayer.php b/businesslayer/feedbusinesslayer.php index 53e0862a9..c0d0fdf21 100644 --- a/businesslayer/feedbusinesslayer.php +++ b/businesslayer/feedbusinesslayer.php @@ -59,15 +59,24 @@ class FeedBusinessLayer extends BusinessLayer { $this->autoPurgeMinimumInterval = $autoPurgeMinimumInterval; } - + /** + * Finds all feeds of a user + * @param string $userId the name of the user + * @return array of feeds + */ public function findAll($userId){ return $this->mapper->findAllFromUser($userId); } /** + * Creates a new feed + * @param string $feedUrl the url to the feed + * @param int $folderId the folder where it should be put into, 0 for root folder + * @param string $userId for which user the feed should be created * @throws BusinessLayerExistsException if the feed exists already * @throws BusinessLayerException if the url points to an invalid feed + * @return Feed the newly created feed */ public function create($feedUrl, $folderId, $userId){ // first try if the feed exists already @@ -76,10 +85,10 @@ class FeedBusinessLayer extends BusinessLayer { throw new BusinessLayerExistsException( $this->api->getTrans()->t('Can not add feed: Exists already')); } catch(DoesNotExistException $ex){} - + try { list($feed, $items) = $this->feedFetcher->fetch($feedUrl); - + // insert feed $feed->setFolderId($folderId); $feed->setUserId($userId); @@ -106,7 +115,7 @@ class FeedBusinessLayer extends BusinessLayer { // set unread count $feed->setUnreadCount($unreadCount); - + return $feed; } catch(FetcherException $ex){ $this->api->log($ex->getMessage()); @@ -117,8 +126,11 @@ class FeedBusinessLayer extends BusinessLayer { } - // FIXME: this method is not covered by any tests + /** + * Runs all the feed updates + */ public function updateAll(){ + // TODO: this method is not covered by any tests $feeds = $this->mapper->findAll(); foreach($feeds as $feed){ try { @@ -131,7 +143,11 @@ class FeedBusinessLayer extends BusinessLayer { /** + * Updates a single feed + * @param int $feedId the id of the feed that should be updated + * @param string $userId the id of the user * @throws BusinessLayerException if the feed does not exist + * @return Feed the updated feed entity */ public function update($feedId, $userId){ try { @@ -145,7 +161,7 @@ class FeedBusinessLayer extends BusinessLayer { list($feed, $items) = $this->feedFetcher->fetch( $existingFeed->getUrl()); - // insert items in reverse order because the first one is usually + // insert items in reverse order because the first one is usually // the newest item for($i=count($items)-1; $i>=0; $i--){ $item = $items[$i]; @@ -156,12 +172,12 @@ class FeedBusinessLayer extends BusinessLayer { $item->getGuidHash(), $feedId, $userId); // in case of an update the existing item has to be deleted - // if the pub_date changed because we sort by id on the + // if the pub_date changed because we sort by id on the // client side since this is the only reliable way to do it // to not get weird behaviour if((int)$existing->getPubDate() !== (int)$item->getPubDate()){ - // because the item is being replaced we need to keep + // because the item is being replaced we need to keep // status flags but we want the new entry to be unread $item->setStatus($existing->getStatus()); $item->setUnread(); @@ -181,9 +197,9 @@ class FeedBusinessLayer extends BusinessLayer { ': Not found or bad source'); $this->api->log($ex->getMessage()); } - + return $this->mapper->find($feedId, $userId); - + } catch (DoesNotExistException $ex){ throw new BusinessLayerException('Feed does not exist'); } @@ -191,6 +207,10 @@ class FeedBusinessLayer extends BusinessLayer { /** + * Moves a feed into a different folder + * @param int $feedId the id of the feed that should be moved + * @param int $folderId the id of the folder where the feed should be moved to + * @param string $userId the name of the user whose feed should be moved * @throws BusinessLayerException if the feed does not exist */ public function move($feedId, $folderId, $userId){ @@ -241,6 +261,8 @@ class FeedBusinessLayer extends BusinessLayer { /** * Use this to mark a feed as deleted. That way it can be undeleted + * @param int $feedId the id of the feed that should be deleted + * @param string $userId the name of the user for security reasons * @throws BusinessLayerException when feed does not exist */ public function markDeleted($feedId, $userId) { @@ -252,6 +274,8 @@ class FeedBusinessLayer extends BusinessLayer { /** * Use this to undo a feed deletion + * @param int $feedId the id of the feed that should be restored + * @param string $userId the name of the user for security reasons * @throws BusinessLayerException when feed does not exist */ public function unmarkDeleted($feedId, $userId) { @@ -265,7 +289,7 @@ class FeedBusinessLayer extends BusinessLayer { * Deletes all deleted feeds * @param string $userId if given it purges only feeds of that user * @param boolean $useInterval defaults to true, if true it only purges - * entries in a given interval to give the user a chance to undo the + * entries in a given interval to give the user a chance to undo the * deletion */ public function purgeDeleted($userId=null, $useInterval=true) { @@ -276,7 +300,7 @@ class FeedBusinessLayer extends BusinessLayer { $deleteOlderThan = $now - $this->autoPurgeMinimumInterval; } - $toDelete = $this->mapper->getToDelete($deleteOlderThan, $userId); + $toDelete = $this->mapper->getToDelete($deleteOlderThan, $userId); foreach ($toDelete as $feed) { $this->mapper->delete($feed); diff --git a/businesslayer/folderbusinesslayer.php b/businesslayer/folderbusinesslayer.php index 662b04b01..f5afe24ad 100644 --- a/businesslayer/folderbusinesslayer.php +++ b/businesslayer/folderbusinesslayer.php @@ -48,7 +48,11 @@ class FolderBusinessLayer extends BusinessLayer { $this->autoPurgeMinimumInterval = $autoPurgeMinimumInterval; } - + /** + * Returns all folders of a user + * @param string $userId the name of the user + * @return array of folders + */ public function findAll($userId) { return $this->mapper->findAllFromUser($userId); } @@ -63,8 +67,14 @@ class FolderBusinessLayer extends BusinessLayer { } } + /** + * Creates a new folder + * @param string $folderName the name of the folder + * @param string $userId the name of the user for whom it should be created + * @param int $parentId the parent folder id, deprecated we dont nest folders * @throws BusinessLayerExistsException if name exists already + * @return Folder the newly created folder */ public function create($folderName, $userId, $parentId=0) { $this->allowNoNameTwice($folderName, $userId); @@ -88,20 +98,27 @@ class FolderBusinessLayer extends BusinessLayer { /** + * Renames a folder + * @param int $folderId the id of the folder that should be deleted + * @param string $folderName the new name of the folder + * @param string $userId the name of the user for security reasons * @throws BusinessLayerExistsException if name exists already * @throws BusinessLayerException if the folder does not exist + * @return Folder the updated folder */ public function rename($folderId, $folderName, $userId){ $this->allowNoNameTwice($folderName, $userId); $folder = $this->find($folderId, $userId); $folder->setName($folderName); - $this->mapper->update($folder); + return $this->mapper->update($folder); } /** * Use this to mark a folder as deleted. That way it can be undeleted + * @param int $folderId the id of the folder that should be deleted + * @param string $userId the name of the user for security reasons * @throws BusinessLayerException when folder does not exist */ public function markDeleted($folderId, $userId) { @@ -112,7 +129,9 @@ class FolderBusinessLayer extends BusinessLayer { /** - * Use this to undo a folder deletion + * Use this to restore a folder + * @param int $folderId the id of the folder that should be restored + * @param string $userId the name of the user for security reasons * @throws BusinessLayerException when folder does not exist */ public function unmarkDeleted($folderId, $userId) { @@ -126,18 +145,18 @@ class FolderBusinessLayer extends BusinessLayer { * Deletes all deleted folders * @param string $userId if given it purges only folders of that user * @param boolean $useInterval defaults to true, if true it only purges - * entries in a given interval to give the user a chance to undo the + * entries in a given interval to give the user a chance to undo the * deletion */ public function purgeDeleted($userId=null, $useInterval=true) { $deleteOlderThan = null; - + if ($useInterval) { $now = $this->timeFactory->getTime(); $deleteOlderThan = $now - $this->autoPurgeMinimumInterval; } - $toDelete = $this->mapper->getToDelete($deleteOlderThan, $userId); + $toDelete = $this->mapper->getToDelete($deleteOlderThan, $userId); foreach ($toDelete as $folder) { $this->mapper->delete($folder); diff --git a/businesslayer/itembusinesslayer.php b/businesslayer/itembusinesslayer.php index 03b4c1498..065e0de30 100644 --- a/businesslayer/itembusinesslayer.php +++ b/businesslayer/itembusinesslayer.php @@ -49,21 +49,30 @@ class ItemBusinessLayer extends BusinessLayer { } + /** + * Returns all new items + * @param int $id the id of the feed, 0 for starred or all items + * @param FeedType $type the type of the feed + * @param int $updatedSince a timestamp with the last modification date + * returns only items with a >= modified timestamp + * @param boolean $showAll if unread items should also be returned + * @param string $userId the name of the user + * @return array of items + */ public function findAllNew($id, $type, $updatedSince, $showAll, $userId){ - $status = $this->statusFlag->typeToStatus($type, $showAll); - + switch($type){ case FeedType::FEED: - $items = $this->mapper->findAllNewFeed($id, $updatedSince, + $items = $this->mapper->findAllNewFeed($id, $updatedSince, $status, $userId); break; case FeedType::FOLDER: - $items = $this->mapper->findAllNewFolder($id, $updatedSince, + $items = $this->mapper->findAllNewFolder($id, $updatedSince, $status, $userId); break; default: - $items = $this->mapper->findAllNew($updatedSince, $status, + $items = $this->mapper->findAllNew($updatedSince, $status, $userId); } @@ -71,21 +80,30 @@ class ItemBusinessLayer extends BusinessLayer { } - public function findAll($id, $type, $limit, $offset, - $showAll, $userId){ + /** + * Returns all items + * @param int $id the id of the feed, 0 for starred or all items + * @param FeedType $type the type of the feed + * @param int $limit how many items should be returned + * @param int $offset only items lower than this id are returned, 0 for no offset + * @param boolean $showAll if unread items should also be returned + * @param string $userId the name of the user + * @return array of items + */ + public function findAll($id, $type, $limit, $offset, $showAll, $userId){ $status = $this->statusFlag->typeToStatus($type, $showAll); switch($type){ case FeedType::FEED: - $items = $this->mapper->findAllFeed($id, $limit, $offset, + $items = $this->mapper->findAllFeed($id, $limit, $offset, $status, $userId); break; case FeedType::FOLDER: - $items = $this->mapper->findAllFolder($id, $limit, $offset, + $items = $this->mapper->findAllFolder($id, $limit, $offset, $status, $userId); break; default: - $items = $this->mapper->findAll($limit, $offset, $status, + $items = $this->mapper->findAll($limit, $offset, $status, $userId); } @@ -94,6 +112,11 @@ class ItemBusinessLayer extends BusinessLayer { /** + * Star or unstar an item + * @param int $feedId the id of the item's feed that should be starred + * @param string $guidHash the guidHash of the item that should be starred + * @param boolean $isStarred if true the item will be marked as starred, if false unstar + * @param $userId the name of the user for security reasons * @throws BusinessLayerException if the item does not exist */ public function star($feedId, $guidHash, $isStarred, $userId){ @@ -113,13 +136,17 @@ class ItemBusinessLayer extends BusinessLayer { /** + * Read or unread an item + * @param int $itemId the id of the item that should be read + * @param boolean $isRead if true the item will be marked as read, if false unread + * @param $userId the name of the user for security reasons * @throws BusinessLayerException if the item does not exist */ public function read($itemId, $isRead, $userId){ $item = $this->find($itemId, $userId); $item->setLastModified($this->timeFactory->getTime()); if($isRead){ - $item->setRead(); + $item->setRead(); } else { $item->setUnread(); } @@ -127,23 +154,43 @@ class ItemBusinessLayer extends BusinessLayer { } + /** + * Set all items read + * @param int $highestItemId all items below that are marked read. This is used + * to prevent marking items as read that the users hasnt seen yet + * @param string $userId the name of the user + */ public function readAll($highestItemId, $userId){ $this->mapper->readAll($highestItemId, $userId); } + /** + * Set a folder read + * @param int $folderId the id of the folder that should be marked read + * @param int $highestItemId all items below that are marked read. This is used + * to prevent marking items as read that the users hasnt seen yet + * @param string $userId the name of the user + */ public function readFolder($folderId, $highestItemId, $userId){ $this->mapper->readFolder($folderId, $highestItemId, $userId); } + /** + * Set a feed read + * @param int $feedId the id of the feed that should be marked read + * @param int $highestItemId all items below that are marked read. This is used + * to prevent marking items as read that the users hasnt seen yet + * @param string $userId the name of the user + */ public function readFeed($feedId, $highestItemId, $userId){ $this->mapper->readFeed($feedId, $highestItemId, $userId); } /** - * This method deletes all unread feeds that are not starred and over the + * This method deletes all unread feeds that are not starred and over the * count of $this->autoPurgeCount starting by the oldest. This is to clean * up the database so that old entries dont spam your db. As criteria for * old, the id is taken @@ -154,7 +201,10 @@ class ItemBusinessLayer extends BusinessLayer { /** + * Returns the newest itemd id, use this for marking feeds read + * @param string $userId the name of the user * @throws BusinessLayerException if there is no newest item + * @return int */ public function getNewestItemId($userId) { try { @@ -165,8 +215,14 @@ class ItemBusinessLayer extends BusinessLayer { } + /** + * Returns the starred count + * @param string $userId the name of the user + * @return int the count + */ public function starredCount($userId){ return $this->mapper->starredCount($userId); } + } |