issue #36

Author: gecampbell

lib/collection.inc

@@ -30,7 +30,10 @@ class Collection extends Base {
 		$itemclass,
 		$itemlist=array(),
 		$pointer=0,
-		$sortkey;
+		$sortkey,
+		$next_page_class,
+		$next_page_callback,
+		$next_page_url;
 
 	/**
 	 * A Collection is an array of objects
@@ -44,6 +47,7 @@ class Collection extends Base {
 		$this->service = $service;
 		$this->debug('Collection:service=%s, class=%s, array=%s',
 			get_class($service), $itemclass, print_r($arr,TRUE));
+		$this->next_page_class = $itemclass;
 		$p = strrpos($itemclass, '\\');
 		if ($p !== FALSE)
 		    $this->itemclass = substr($itemclass, $p+1);
@@ -171,6 +175,51 @@ class Collection extends Base {
 				unset($this->itemlist[$index]);
 		}
 	}
+	
+	/**
+	 * returns the Collection object for the next page of results, or
+	 * FALSE if there are no more pages
+	 *
+	 * Generally, the structure for a multi-page collection will look like
+	 * this:
+	 *
+	 *		$coll = $obj->Collection();
+	 *		do {
+	 *			while($item = $coll->Next()) {
+	 *				// do something with the item
+	 *			|
+	 *		} while ($coll = $coll->NextPage());
+	 *
+	 * @api
+	 * @return Collection if there are more pages of results, otherwise FALSE
+	 */
+	public function NextPage() {
+		if (isset($this->next_page_url)) {
+			return call_user_func(
+				$this->next_page_callback, 
+				$this->next_page_class,
+				$this->next_page_url);
+		}
+		return FALSE;
+	}
+	
+	/**
+	 * for paginated collection, sets the callback function and URL for
+	 * the next page
+	 *
+	 * The callback function should have the signature:
+	 *		function Whatever($class, $url, $parent)
+	 * and the `$url` should be the URL of the next page of results
+	 *
+	 * @param callable $callback the name of the function (or array of 
+	 *		object, function name)
+	 * @param string $url the URL of the next page of results
+	 * @return void
+	 */
+	public function SetNextPageCallback($callback, $url) {
+		$this->next_page_callback = $callback;
+		$this->next_page_url = $url;
+	}
 
 	/********** PRIVATE METHODS **********/
 

lib/dbservice.inc

@@ -81,6 +81,7 @@ class DbService extends Nova {
 	 * @return Collection
 	 */
 	public function InstanceList($params=array()) {
-		return $this->Collection('\OpenCloud\DbService\Instance');
+		return $this->Collection(
+			'\OpenCloud\DbService\Instance', NULL, NULL, $params);
 	}
 }

lib/service.inc

@@ -174,22 +174,47 @@ abstract class Service extends Base {
 		$obj = json_decode($response->HttpBody());
 		if ($this->CheckJsonError())
 			return FALSE;
+			
+		// see if there is a "next" link
+		if (isset($obj->links)) {
+			if (is_array($obj->links)) {
+				foreach($obj->links as $link) {
+					if (isset($link->rel) && ($link->rel=='next')) {
+						if (isset($link->href))
+							$next_page_url = $link->href;
+						else
+							throw new \OpenCloud\DomainError(
+								_('unexpected [links] found with no [href]'));
+					}
+				}
+			}
+		}
 
 		// and say goodbye
 		if (!$collection)
-			return new Collection($parent, $class, $obj);
+			$coll_obj = new Collection($parent, $class, $obj);
 		elseif (isset($obj->$collection)) {
 			if (!$element)
-				return new Collection($parent, $class, $obj->$collection);
+				$coll_obj = new Collection($parent, $class, $obj->$collection);
 			else { // handle element levels
 				$arr = array();
 				foreach($obj->$collection as $index => $item)
 					$arr[] = $item->$element;
-				return new Collection($parent, $class, $arr);
+				$coll_obj = new Collection($parent, $class, $arr);
 			}
 		}
 		else
-			return new Collection($parent, $class, array());
+			$coll_obj = new Collection($parent, $class, array());
+		
+		// if there's a $next_page_url, then we need to establish a
+		// callback method
+		if (isset($next_page_url)) {
+			$coll_obj->SetNextPageCallback(
+				array($this, 'Collection'), 
+				$next_page_url);
+		}
+		
+		return $coll_obj;
 	}
 
 	/**

samples/database/create.php

@@ -24,7 +24,7 @@
 $instance = $dbservice->Instance();
 $instance->flavor = $dbservice->Flavor(1);
 $instance->volume->size = 3;
-$instance->Create(array('name'=>'MySQL'));
+$instance->Create(array('name'=>'TestInstance'.time()));
 $instance->WaitFor('ACTIVE', 300, 'showstatus');
 
 // create a database

samples/database/list.php

@@ -20,17 +20,22 @@
 $dbservice = $connection->DbService('cloudDatabases', 'DFW');
 
 // delete all the instances created by the create.php script
-$inlist = $dbservice->InstanceList();
-while($instance = $inlist->Next()) {
-    printf("Instance: %s (%s)\n", $instance->id, $instance->Name());
-    $dblist = $instance->DatabaseList();
-    while($db = $dblist->Next()) {
-        printf("  Database: %s\n", $db->name);
-    }
-    $userlist = $instance->UserList();
-    while($user = $userlist->Next()) {
-        printf("  User: %s\n", $user->name);
-        foreach($user->databases as $db)
-            printf("    Database for user; %s\n", $db->name);
-    }
-}
+$inlist = $dbservice->InstanceList(array('limit'=>2));
+$pageno = 0;
+do {
+	printf("Page #%d of results...\n", ++$pageno);
+	while($instance = $inlist->Next()) {
+		printf("Instance: %s (%s)\n", $instance->id, $instance->Name());
+		$dblist = $instance->DatabaseList();
+		while($db = $dblist->Next()) {
+			printf("  Database: %s\n", $db->name);
+		}
+		$userlist = $instance->UserList();
+		while($user = $userlist->Next()) {
+			printf("  User: %s\n", $user->name);
+			foreach($user->databases as $db)
+				printf("    Database for user; %s\n", $db->name);
+		}
+	}
+	$inlist = $inlist->NextPage();
+} while ($inlist);

tests/CollectionTest.php

@@ -102,4 +102,22 @@ public function testSelect() {
 		// this should cause an error
 		$coll->Select(function(){ return 5;});
 	}
+	public function testNextPage() {
+		$coll = $this->my;
+		$coll->SetNextPageCallback(
+			array($this,'_callback'), 
+			'http://something');
+		$this->assertEquals(
+			'CollectionTest',
+			get_class($coll->NextPage()));
+		$this->assertEquals(
+			FALSE,
+			$coll->NextPage());
+	}
+	public function _callback($class, $url) {
+		// stub function used by SetNextPageCallback
+	}
+	public function testSetNextPageCallback() {
+		// not needed; exercised by testNextPage(), above
+	}
 }