added javadoc for the businesslayer

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);
 	}
 
+
 }