/*
 * Copyright 2015-2017 the original author or authors.
 *
 * All rights reserved. This program and the accompanying materials are
 * made available under the terms of the Eclipse Public License v1.0 which
 * accompanies this distribution and is available at
 *
 * http://www.eclipse.org/legal/epl-v10.html
 */

package org.junit.jupiter.api.extension;

import static org.junit.platform.commons.meta.API.Usage.Experimental;

import java.util.Iterator;
import java.util.stream.Stream;

import org.junit.platform.commons.meta.API;

/**
 * {@code TestTemplateInvocationContextProvider} defines the API for
 * {@link Extension Extensions} that wish to provide one or multiple contexts
 * for the invocation of a
 * {@link org.junit.jupiter.api.TestTemplate @TestTemplate} method.
 *
 * <p>This extension point makes it possible to execute a test template in
 * different contexts, e.g. with different parameters, by preparing the test
 * class instance differently, or multiple times without modifying the context.
 *
 * <p>This interface defines two methods: {@link #supports} and
 * {@link #provide}. The former is called by the framework to determine whether
 * this extension wants to act on a test template that is about to be executed.
 * If so, the latter is called and must return an {@link Iterator} of
 * {@link TestTemplateInvocationContext} instances. Otherwise, this provider is
 * ignored for the execution of the current test template.
 *
 * <p>A provider that has returned {@code true} from its {@link #supports}
 * method is called <em>active</em>. When multiple providers are active for a
 * test template method, the {@code Iterators} returned by their
 * {@link #provide} methods will be chained, i.e. the test template method will
 * be invoked using the contexts of all active providers.
 *
 * <p>Implementations must provide a no-args constructor.
 *
 * @see org.junit.jupiter.api.TestTemplate
 * @see TestTemplateInvocationContext
 * @since 5.0
 */
@API(Experimental)
public interface TestTemplateInvocationContextProvider extends Extension {

	/**
	 * Determine if this provider supports providing invocation contexts for the
	 * test template method represented by the supplied {@code context}.
	 *
	 * @param context the container extension context for the test template
	 * method about to be invoked; never {@code null}
	 * @return {@code true} if this provider can provide invocation contexts
	 * @see #provide
	 * @see ContainerExtensionContext
	 */
	boolean supports(ContainerExtensionContext context);

	/**
	 * Provide {@linkplain TestTemplateInvocationContext invocation contexts}
	 * for the test template method represented by the supplied {@code context}.
	 *
	 * <p>This method is only called by the framework if {@link #supports} has
	 * previously returned {@code true} for the same
	 * {@link ContainerExtensionContext}. Thus, it must not return an empty
	 * {@code Stream}.
	 *
	 * <p>The returned {@code Stream} will be properly closed by calling
	 * {@link Stream#close()}, making it safe to use a resource such as
	 * {@link java.nio.file.Files#lines(java.nio.file.Path) Files.lines()}.
	 *
	 * @param context the container extension context for the test template
	 * method about to be invoked; never {@code null}
	 * @return a Stream of TestTemplateInvocationContext instances for the
	 * invocation of the test template method; never {@code null} or empty
	 * @see #supports
	 * @see ContainerExtensionContext
	 */
	Stream<TestTemplateInvocationContext> provide(ContainerExtensionContext context);

}

@@ -424,35 +424,8 @@
 l;%0A%0A
-import java.util.Iterator;%0A
 impo
@@ -452,16 +452,16 @@
 Stream;%0A
+
 %0Aimport 
@@ -847,14 +847,29 @@
 exts
-, e.g.
+ &mdash; for example,
  wit
@@ -894,16 +894,19 @@
 ters, by
+%0A *
  prepari
@@ -916,19 +916,16 @@
 the test
-%0A *
  class i
@@ -970,16 +970,19 @@
  without
+%0A *
  modifyi
@@ -1276,17 +1276,16 @@
 rn a
-n
  %7B@link 
 Iter
@@ -1280,24 +1280,22 @@
  %7B@link 
-Iterator
+Stream
 %7D of%0A * 
@@ -1626,16 +1626,14 @@
 ode 
-Iterator
+Stream
 s%7D r
@@ -1648,19 +1648,16 @@
 by their
-%0A *
  %7B@link 
@@ -1665,16 +1665,19 @@
 provide%7D
+%0A *
  methods
@@ -1698,12 +1698,11 @@
 ed, 
-i.e.
+and
  the
@@ -1727,19 +1727,16 @@
 hod will
-%0A *
  be invo
@@ -1744,16 +1744,19 @@
 ed using
+%0A *
  the con
@@ -3255,18 +3255,33 @@
 n a 
+%7B@code 
 Stream
+%7D
  of 
+%7B@code 
 Test
@@ -3305,16 +3305,21 @@
 nContext
+%7D%0A%09 *
  instanc
@@ -3328,20 +3328,16 @@
  for the
-%0A%09 *
  invocat
@@ -3387,16 +3387,20 @@
 de null%7D
+%0A%09 *
  or empt

Fix JavaDoc for TestTemplateInvocationContextProvider