Add iterable support for race/settle. (#133)

subprojects/jdeferred-core/src/main/java/org/jdeferred/DeferredManager.java

@@ -362,206 +362,238 @@ <V1, V2, V3, V4, V5> Promise<MultipleResultsN<V1, V2, V3, V4, V5>, OneReject<Thr
 		Future<?>... futures);
 
 	/**
-	 * Creates a {@code Promise} that signals {@code done} or {@code reject} when the first runnable does so.
-	 * Wraps each {@code runnable} with {@code DeferredFutureTask}.
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when the first runnable does so.
+	 * Wraps each {@code runnable} with {@link DeferredFutureTask}.
 	 *
 	 * @param runnableV1 a task to be executed. Must not be null
 	 * @param runnableV2 a task to be executed. Must not be null
 	 * @param runnables  additional tasks to be executed. May be null
 	 *
-	 * @return a composite {@code Promise} that resolves/rejects as soon as the first of the submitted tasks is resolved/rejected.
+	 * @return a composite {@link Promise} that resolves/rejects as soon as the first of the submitted tasks is resolved/rejected.
 	 */
 	Promise<OneResult<?>, OneReject<Throwable>, Void> race(
 		Runnable runnableV1,
 		Runnable runnableV2,
 		Runnable... runnables);
 
 	/**
-	 * Creates a {@code Promise} that signals {@code done} or {@code reject} when the first callable does so.
-	 * Wraps each {@code callable} with {@code DeferredFutureTask}.
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when the first callable does so.
+	 * Wraps each {@code callable} with {@link DeferredFutureTask}.
 	 *
 	 * @param callableV1 a task to be executed. Must not be null
 	 * @param callableV2 a task to be executed. Must not be null
 	 * @param callables  additional tasks to be executed. May be null
 	 *
-	 * @return a composite {@code Promise} that resolves/rejects as soon as the first of the submitted tasks is resolved/rejected.
+	 * @return a composite {@link Promise} that resolves/rejects as soon as the first of the submitted tasks is resolved/rejected.
 	 */
 	Promise<OneResult<?>, OneReject<Throwable>, Void> race(
 		Callable<?> callableV1,
 		Callable<?> callableV2,
 		Callable<?>... callables);
 
 	/**
-	 * Creates a {@code Promise} that signals {@code done} or {@code reject} when the first runnable does so.
-	 * Wraps each {@code runnable} with {@code DeferredFutureTask}.
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when the first runnable does so.
+	 * Wraps each {@code runnable} with {@link DeferredFutureTask}.
 	 *
 	 * @param runnableV1 a task to be executed. Must not be null
 	 * @param runnableV2 a task to be executed. Must not be null
 	 * @param runnables  additional tasks to be executed. May be null
 	 *
-	 * @return a composite {@code Promise} that resolves/rejects as soon as the first of the submitted tasks is resolved/rejected.
+	 * @return a composite {@link Promise} that resolves/rejects as soon as the first of the submitted tasks is resolved/rejected.
 	 */
 	Promise<OneResult<?>, OneReject<Throwable>, Void> race(
 		DeferredRunnable<?> runnableV1,
 		DeferredRunnable<?> runnableV2,
 		DeferredRunnable<?>... runnables);
 
 	/**
-	 * Creates a {@code Promise} that signals {@code done} or {@code reject} when the first callable does so.
-	 * Wraps each {@code callable} with {@code DeferredFutureTask}.
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when the first callable does so.
+	 * Wraps each {@code callable} with {@link DeferredFutureTask}.
 	 *
 	 * @param callableV1 a task to be executed. Must not be null
 	 * @param callableV2 a task to be executed. Must not be null
 	 * @param callables  additional tasks to be executed. May be null
 	 *
-	 * @return a composite {@code Promise} that resolves/rejects as soon as the first of the submitted tasks is resolved/rejected.
+	 * @return a composite {@link Promise} that resolves/rejects as soon as the first of the submitted tasks is resolved/rejected.
 	 */
 	Promise<OneResult<?>, OneReject<Throwable>, Void> race(
 		DeferredCallable<?, ?> callableV1,
 		DeferredCallable<?, ?> callableV2,
 		DeferredCallable<?, ?>... callables);
 
 	/**
-	 * Creates a {@code Promise} that signals {@code done} or {@code reject} when the first future does so.
-	 * Wraps each {@code future} with {@code DeferredFutureTask}.
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when the first future does so.
+	 * Wraps each {@code future} with {@link DeferredFutureTask}.
 	 *
 	 * @param futureV1 a task to be executed. Must not be null
 	 * @param futureV2 a task to be executed. Must not be null
 	 * @param futures  additional tasks to be executed. May be null
 	 *
-	 * @return a composite {@code Promise} that resolves/rejects as soon as the first of the submitted tasks is resolved/rejected.
+	 * @return a composite {@link Promise} that resolves/rejects as soon as the first of the submitted tasks is resolved/rejected.
 	 */
 	Promise<OneResult<?>, OneReject<Throwable>, Void> race(
 		Future<?> futureV1,
 		Future<?> futureV2,
 		Future<?>... futures);
 
 	/**
-	 * Creates a {@code Promise} that signals {@code done} or {@code reject} when the first task does so.
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when the first task does so.
 	 *
 	 * @param taskV1 a task to be executed. Must not be null
 	 * @param taskV2 a task to be executed. Must not be null
 	 * @param tasks  additional tasks to be executed. May be null
 	 *
-	 * @return a composite {@code Promise} that resolves/rejects as soon as the first of the submitted tasks is resolved/rejected.
+	 * @return a composite {@link Promise} that resolves/rejects as soon as the first of the submitted tasks is resolved/rejected.
 	 */
 	Promise<OneResult<?>, OneReject<Throwable>, Void> race(
 		DeferredFutureTask<?, ?> taskV1,
 		DeferredFutureTask<?, ?> taskV2,
 		DeferredFutureTask<?, ?>... tasks);
 
 	/**
-	 * Creates a {@code Promise} that signals {@code done} or {@code reject} when each runnable does so.
-	 * Wraps each {@code runnable} with {@code DeferredFutureTask}.
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when each runnable does so.
+	 * Wraps each {@code runnable} with {@link DeferredFutureTask}.
 	 *
 	 * @param runnableV1 a task to be executed. Must not be null
 	 * @param runnableV2 a task to be executed. Must not be null
 	 * @param runnables  additional tasks to be executed. May be null
 	 *
-	 * @return a composite {@code Promise} that collects resolve/reject values from all tasks.
+	 * @return a composite {@link Promise} that collects resolve/reject values from all tasks.
 	 */
 	Promise<AllValues, Throwable, MasterProgress> settle(
 		Runnable runnableV1,
 		Runnable runnableV2,
 		Runnable... runnables);
 
 	/**
-	 * Creates a {@code Promise} that signals {@code done} or {@code reject} when each callable does so.
-	 * Wraps each {@code callable} with {@code DeferredFutureTask}.
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when each callable does so.
+	 * Wraps each {@code callable} with {@link DeferredFutureTask}.
 	 *
 	 * @param callableV1 a task to be executed. Must not be null
 	 * @param callableV2 a task to be executed. Must not be null
 	 * @param callables  additional tasks to be executed. May be null
 	 *
-	 * @return a composite {@code Promise} that collects resolve/reject values from all tasks.
+	 * @return a composite {@link Promise} that collects resolve/reject values from all tasks.
 	 */
 	Promise<AllValues, Throwable, MasterProgress> settle(
 		Callable<?> callableV1,
 		Callable<?> callableV2,
 		Callable<?>... callables);
 
 	/**
-	 * Creates a {@code Promise} that signals {@code done} or {@code reject} when each runnable does so.
-	 * Wraps each {@code runnable} with {@code DeferredFutureTask}.
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when each runnable does so.
+	 * Wraps each {@code runnable} with {@link DeferredFutureTask}.
 	 *
 	 * @param runnableV1 a task to be executed. Must not be null
 	 * @param runnableV2 a task to be executed. Must not be null
 	 * @param runnables  additional tasks to be executed. May be null
 	 *
-	 * @return a composite {@code Promise} that collects resolve/reject values from all tasks.
+	 * @return a composite {@link Promise} that collects resolve/reject values from all tasks.
 	 */
 	Promise<AllValues, Throwable, MasterProgress> settle(
 		DeferredRunnable<?> runnableV1,
 		DeferredRunnable<?> runnableV2,
 		DeferredRunnable<?>... runnables);
 
 	/**
-	 * Creates a {@code Promise} that signals {@code done} or {@code reject} when each callable does so.
-	 * Wraps each {@code callable} with {@code DeferredFutureTask}.
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when each callable does so.
+	 * Wraps each {@code callable} with {@link DeferredFutureTask}.
 	 *
 	 * @param callableV1 a task to be executed. Must not be null
 	 * @param callableV2 a task to be executed. Must not be null
 	 * @param callables  additional tasks to be executed. May be null
 	 *
-	 * @return a composite {@code Promise} that collects resolve/reject values from all tasks.
+	 * @return a composite {@link Promise} that collects resolve/reject values from all tasks.
 	 */
 	Promise<AllValues, Throwable, MasterProgress> settle(
 		DeferredCallable<?, ?> callableV1,
 		DeferredCallable<?, ?> callableV2,
 		DeferredCallable<?, ?>... callables);
 
 	/**
-	 * Creates a {@code Promise} that signals {@code done} or {@code reject} when each future does so.
-	 * Wraps each {@code future} with {@code DeferredFutureTask}.
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when each future does so.
+	 * Wraps each {@code future} with {@link DeferredFutureTask}.
 	 *
 	 * @param futureV1 a task to be executed. Must not be null
 	 * @param futureV2 a task to be executed. Must not be null
 	 * @param futures  additional tasks to be executed. May be null
 	 *
-	 * @return a composite {@code Promise} that collects resolve/reject values from all tasks.
+	 * @return a composite {@link Promise} that collects resolve/reject values from all tasks.
 	 */
 	Promise<AllValues, Throwable, MasterProgress> settle(
 		Future<?> futureV1,
 		Future<?> futureV2,
 		Future<?>... futures);
 
 	/**
-	 * Creates a {@code Promise} that signals {@code done} or {@code reject} when each task does so.
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when each task does so.
 	 *
 	 * @param taskV1 a task to be executed. Must not be null
 	 * @param taskV2 a task to be executed. Must not be null
 	 * @param tasks  additional tasks to be executed. May be null
 	 *
-	 * @return a composite {@code Promise} that collects resolve/reject values from all tasks.
+	 * @return a composite {@link Promise} that collects resolve/reject values from all tasks.
 	 */
 	Promise<AllValues, Throwable, MasterProgress> settle(
 		DeferredFutureTask<?, ?> taskV1,
 		DeferredFutureTask<?, ?> taskV2,
 		DeferredFutureTask<?, ?>... tasks);
 
 	/**
-	 * Creates a {@code Promise} that signals {@code done} or {@code reject} when each promise does so.
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when each promise does so.
 	 *
 	 * @param promiseV1 a promise. Must not be null
 	 * @param promiseV2 a promise. Must not be null
 	 * @param promises  additional promises. May be null
 	 *
-	 * @return a composite {@code Promise} that collects resolve/reject values from all promises.
+	 * @return a composite {@link Promise} that collects resolve/reject values from all promises.
 	 */
 	Promise<AllValues, Throwable, MasterProgress> settle(
 		Promise<?, ?, ?> promiseV1,
 		Promise<?, ?, ?> promiseV2,
 		Promise<?, ?, ?>... promises);
 
 	/**
-	 * Accept an iterable of variety of different object types, and converted into corresponding Promise. E.g.,
+	 * Accept an iterable of a variety of different object types, and convert it into corresponding Promise. E.g.,
 	 * if an item is a {@link Callable}, it'll call {@link #when(Callable)} to convert that into a Promise.
+	 * <p>
+	 * If the item is of an unknown type, it'll throw an {@link IllegalArgumentException}.
 	 *
-	 * If the item is an unknown type, it'll throw an {@link IllegalArgumentException}
+	 * @param iterable the source of tasks. Must be non-null and not empty. Every item must be convertible to {@link Promise}
+	 *
+	 * @return a composite {@link Promise} that rejects as soon as the first of the submitted tasks is rejected or contains
+	 * the resolution of all given tasks.
 	 *
-	 * @param iterable
 	 * @throws IllegalArgumentException if any item in iterable cannot be converted to a {@link Promise}
-	 * @return
 	 */
 	Promise<MultipleResults, OneReject<?>, MasterProgress> when(Iterable<?> iterable);
+
+	/**
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when the first task does so.
+	 * If an item is a {@link Callable}, it'll call {@link #when(Callable)} to convert that into a Promise.
+	 * <p>
+	 * If the item is of an unknown type, it'll throw an {@link IllegalArgumentException}.
+	 * <strong>WARNING: </strong>does not accept items of type {@code Promise}.
+	 *
+	 * @param iterable the source of tasks. Must be non-null and not empty. Every item must be convertible to {@link Promise}
+	 *
+	 * @return a composite {@link Promise} that resolves/rejects as soon as the first of the submitted tasks is resolved/rejected.
+	 *
+	 * @throws IllegalArgumentException if any item in iterable cannot be converted to a {@link Promise}
+	 */
+	Promise<OneResult<?>, OneReject<Throwable>, Void> race(Iterable<?> iterable);
+
+	/**
+	 * Creates a {@link Promise} that signals {@code done} or {@code reject} when each task does so.
+	 * If an item is a {@link Callable}, it'll call {@link #when(Callable)} to convert that into a Promise.
+	 * <p>
+	 * If the item is of an unknown type, it'll throw an {@link IllegalArgumentException}.
+	 *
+	 * @param iterable the source of tasks. Must be non-null and not empty. Every item must be convertible to {@link Promise}
+	 *
+	 * @return a composite {@link Promise} that collects resolve/reject values from all promises.
+	 *
+	 * @throws IllegalArgumentException if any item in iterable cannot be converted to a {@link Promise}
+	 */
+	Promise<AllValues, Throwable, MasterProgress> settle(Iterable<?> iterable);
 }