Ren CallbackIterator to MappingIterator

docs/03-technical notes.md

@@ -1,17 +1,17 @@
 
 ## Iterators
 
-To avoid a possible large list of recipients are being generate ad-hoc during the
-change detection process, there are two iterators that will resolve a list of
-groups and subsequently its members on request.
+To avoid a possible large list of recipients being resolved ad-hoc during the
+change detection process, two iterators are provided to solve the list of groups and
+subsequently its members on request.
 
 The `UserLocator` is responsible for locating recipients of a notification event and
-is being resolved using a `CallbackIterator` which is then added to the `RecursiveGroupMembersIterator`
+is being resolved using a `MappingIterator` which is then added to the `RecursiveGroupMembersIterator`
 to iteratively resolve a single group and its members during a recursive processing.
 
 ```
 	// Find the groups related to changed properties
-	$groups = $iteratorFactory->newCallbackIterator(
+	$groups = $iteratorFactory->newMappingIterator(
 		$extra['properties'],
 		$notificationGroupsLocator->getNotificationsToGroupListByCallback( $subSemanticDataMatch )
 	);
@@ -29,8 +29,8 @@ to iteratively resolve a single group and its members during a recursive process
 		$recursiveGroupMemberIterator
 	);
 
-	// Create a "real" User object on request only
-	$callbackIterator = $iteratorFactory->newCallbackIterator( $recursiveIteratorIterator, function( $recipient ) {
+	// Create a "real" User object only during a request
+	$mappingIterator = $iteratorFactory->newMappingIterator( $recursiveIteratorIterator, function( $recipient ) {
 		return User::newFromName( $recipient, false );
 	} );
 ```

docs/README.md

@@ -2,7 +2,7 @@
 
 - [workflow](01-workflow.md) contains a description of the expected workflow and settings in order to receive notifications
 - [tips](02-tips.md) contains some extra description on how to use the `Notifications on` property etc.
-- [technical notes](03-technical notes.md) some technical details about the provided hooks etc.
+- [technical notes](03-technical notes.md) some technical details about available hooks etc.
 
 ## Examples
 

src/Iterator/CallbackIterator.php → src/Iterator/MappingIterator.php

@@ -13,14 +13,17 @@
  *
  * @author mwjames
  */
-class CallbackIterator extends IteratorIterator {
+class MappingIterator extends IteratorIterator {
 
+	/**
+	 * @var callable
+	 */
 	private $callback;
 
 	/**
 	 * @since 1.0
 	 *
-	 * @param Iterator $iterator
+	 * @param Iterator|array $iterator
 	 * @param callable  $callback
 	 */
 	public function __construct( $iterator, callable $callback ) {

src/IteratorFactory.php

@@ -3,11 +3,10 @@
 namespace SMW\Notifications;
 
 use SMW\Store;
-use SMW\Notifications\Iterator\CallbackIterator;
+use SMW\Notifications\Iterator\MappingIterator;
 use SMW\Notifications\Iterator\CallbackRecursiveIterator;
 use SMW\Notifications\Iterator\RecursiveGroupMembersIterator;
 use SMW\Notifications\Iterator\ChildlessRecursiveIterator;
-use Closure;
 use Iterator;
 use RecursiveIterator;
 use RecursiveIteratorIterator;
@@ -24,12 +23,12 @@ class IteratorFactory {
 	 * @since 1.0
 	 *
 	 * @param array|Iterator $iterator
-	 * @param Closure $callback
+	 * @param callable $callback
 	 *
-	 * @return CallbackIterator
+	 * @return MappingIterator
 	 */
-	public function newCallbackIterator( $iterator, Closure $callback ) {
-		return new CallbackIterator( $iterator, $callback );
+	public function newMappingIterator( $iterator, callable $callback ) {
+		return new MappingIterator( $iterator, $callback );
 	}
 
 	/**

src/ValueChange/UserLocator.php

@@ -16,8 +16,8 @@
 class UserLocator {
 
 	/**
-	 * Find out which for the properties/values that changed belongs to which
-	 * group and is assigned/matchable possible users.
+	 * Find out for which of the properties that have changed the assigned group
+	 * and for each group do locate its members(users).
 	 *
 	 * @see EchoUserLocator::locateArticleCreator
 	 * @since 1.0
@@ -35,22 +35,22 @@ public static function doLocateEventSubscribers( EchoEvent $event ) {
 			return array();
 		}
 
-		$type = $event->getType();
 		$store = ApplicationFactory::getInstance()->getStore( '\SMW\SQLStore\SQLStore' );
+		$iteratorFactory = new IteratorFactory();
 
 		$notificationGroupsLocator = new NotificationGroupsLocator(
 			$store
 		);
 
-		$iteratorFactory = new IteratorFactory();
 		$subSemanticDataMatch = isset( $extra['subSemanticDataMatch'] ) ? $extra['subSemanticDataMatch'] : array();
+		$type = $event->getType();
 
 		if ( $type === ChangeNotifications::SPECIFICATION_CHANGE ) {
 			$groups = $notificationGroupsLocator->getSpecialGroupOnSpecificationChange();
 		} else {
 			// Find groups assigned to properties on a "lazy" request during the
 			// iteration process
-			$groups = $iteratorFactory->newCallbackIterator(
+			$groups = $iteratorFactory->newMappingIterator(
 				$extra['properties'],
 				$notificationGroupsLocator->getNotificationsToGroupListByCallback( $subSemanticDataMatch )
 			);
@@ -83,14 +83,14 @@ public static function doLocateEventSubscribers( EchoEvent $event ) {
 		wfDebugLog( 'smw', 'Agent ' . $agentName );
 
 		// Access the user only on request by the iterator
-		$callbackIterator = $iteratorFactory->newCallbackIterator( $recursiveIteratorIterator, function( $recipient ) {
+		$mappingIterator = $iteratorFactory->newMappingIterator( $recursiveIteratorIterator, function( $recipient ) {
 			wfDebugLog( 'smw', 'User ' . $recipient );
 			return User::newFromName( $recipient, false );
 		} );
 
 		wfDebugLog( 'smw', __METHOD__ . ' procTime (sec): ' . round( ( microtime( true ) - $start ), 7 ) );
 
-		return $callbackIterator;
+		return $mappingIterator;
 	}
 
 }

tests/phpunit/Unit/Iterator/MappingIteratorTest.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace SMW\Notifications\Iterator\Tests;
+
+use SMW\Notifications\Iterator\MappingIterator;
+use ArrayIterator;
+
+/**
+ * @covers \SMW\Notifications\Iterator\MappingIterator
+ * @group semantic-notifications
+ *
+ * @license GNU GPL v2+
+ * @since 1.0
+ *
+ * @author mwjames
+ */
+class MappingIteratorTest extends \PHPUnit_Framework_TestCase {
+
+	public function testCanConstruct() {
+
+		$this->assertInstanceOf(
+			MappingIterator::class,
+			new MappingIterator( array(), function() {} )
+		);
+	}
+
+	public function testInvalidConstructorArgumentThrowsException() {
+
+		$this->setExpectedException( 'RuntimeException' );
+		$instance = new MappingIterator( 2, function() {} );
+	}
+
+	public function testdoIterateOnArray() {
+
+		$expected = array(
+			1 , 42
+		);
+
+		$mappingIterator = new MappingIterator( $expected, function( $counter ) {
+			return $counter;
+		} );
+
+		foreach ( $mappingIterator as $key => $value ) {
+			$this->assertEquals(
+				$expected[$key],
+				$value
+			);
+		}
+	}
+
+	public function testdoIterateOnArrayIterator() {
+
+		$expected = array(
+			1001 , 42
+		);
+
+		$mappingIterator = new MappingIterator( new ArrayIterator( $expected ), function( $counter ) {
+			return $counter;
+		} );
+
+		foreach ( $mappingIterator as $key => $value ) {
+			$this->assertEquals(
+				$expected[$key],
+				$value
+			);
+		}
+	}
+
+}

tests/phpunit/Unit/IteratorFactoryTest.php

@@ -4,7 +4,7 @@
 
 use RecursiveIterator;
 use SMW\Notifications\IteratorFactory;
-use SMW\Notifications\Iterator\CallbackIterator;
+use SMW\Notifications\Iterator\MappingIterator;
 use SMW\Notifications\Iterator\RecursiveGroupMembersIterator;
 use SMW\Notifications\Iterator\ChildlessRecursiveIterator;
 use RecursiveIteratorIterator;
@@ -21,13 +21,13 @@
  */
 class IteratorFactoryTest extends \PHPUnit_Framework_TestCase {
 
-	public function testCanConstructCallbackIterator() {
+	public function testCanConstructMappingIterator() {
 
 		$instance = new IteratorFactory();
 
 		$this->assertInstanceOf(
-			CallbackIterator::class,
-			$instance->newCallbackIterator( [], function() {} )
+			MappingIterator::class,
+			$instance->newMappingIterator( [], function() {} )
 		);
 	}