[FLINK-4271] [DataStream API] Extends JavaDocs for 'apply(...)' and 'with(...)' functions.

flink-streaming-java/src/main/java/org/apache/flink/streaming/api/datastream/CoGroupedStreams.java

@@ -224,6 +224,10 @@ public class CoGroupedStreams<T1, T2> {
 		/**
 		 * Completes the co-group operation with the user function that is executed
 		 * for windowed groups.
+		 * 
+		 * <p>Note: This method's return type does not support setting an operator-specific parallelism.
+		 * Due to binary backwards compatibility, this cannot be altered. Use the {@link #with(CoGroupFunction)}
+		 * method to set an operator-specific parallelism.
 		 */
 		public <T> DataStream<T> apply(CoGroupFunction<T1, T2, T> function) {
 
@@ -244,12 +248,13 @@ public class CoGroupedStreams<T1, T2> {
 		 * Completes the co-group operation with the user function that is executed
 		 * for windowed groups.
 		 *
-		 * <p>
-		 *     Note: This is a temporary workaround while the {@link #apply(CoGroupFunction)} method has the wrong return type.
-		 * </p>
-		 * @deprecated This method will be replaced by {@link #apply(CoGroupFunction)} in Flink 2.0.
-		 * So use the {@link #apply(CoGroupFunction)} in the future.
-         */
+		 * <p><b>Note:</b> This is a temporary workaround while the {@link #apply(CoGroupFunction)}
+		 * method has the wrong return type and hence does not allow one to set an operator-specific
+		 * parallelism
+		 * 
+		 * @deprecated This method will be removed once the {@link #apply(CoGroupFunction)} method is fixed
+		 *             in the next major version of Flink (2.0).
+		 */
 		@PublicEvolving
 		@Deprecated
 		public <T> SingleOutputStreamOperator<T> with(CoGroupFunction<T1, T2, T> function) {
@@ -259,6 +264,10 @@ public class CoGroupedStreams<T1, T2> {
 		/**
 		 * Completes the co-group operation with the user function that is executed
 		 * for windowed groups.
+		 * 
+		 * <p>Note: This method's return type does not support setting an operator-specific parallelism.
+		 * Due to binary backwards compatibility, this cannot be altered. Use the
+		 * {@link #with(CoGroupFunction, TypeInformation)} method to set an operator-specific parallelism.
 		 */
 		public <T> DataStream<T> apply(CoGroupFunction<T1, T2, T> function, TypeInformation<T> resultType) {
 			//clean the closure
@@ -297,11 +306,12 @@ public class CoGroupedStreams<T1, T2> {
 		 * Completes the co-group operation with the user function that is executed
 		 * for windowed groups.
 		 *
-		 * <p>
-		 *     Note: This is a temporary workaround while the {@link #apply(CoGroupFunction, TypeInformation)} method has the wrong return type.
-		 * </p>
-		 * @deprecated This method will be replaced by {@link #apply(CoGroupFunction, TypeInformation)} in Flink 2.0.
-		 * So use the {@link #apply(CoGroupFunction, TypeInformation)} in the future.
+		 * <p><b>Note:</b> This is a temporary workaround while the {@link #apply(CoGroupFunction, TypeInformation)}
+		 * method has the wrong return type and hence does not allow one to set an operator-specific
+		 * parallelism
+		 *
+		 * @deprecated This method will be removed once the {@link #apply(CoGroupFunction, TypeInformation)}
+		 *             method is fixed in the next major version of Flink (2.0).
 		 */
 		@PublicEvolving
 		@Deprecated

flink-streaming-java/src/main/java/org/apache/flink/streaming/api/datastream/JoinedStreams.java

@@ -219,6 +219,10 @@ public class JoinedStreams<T1, T2> {
 		/**
 		 * Completes the join operation with the user function that is executed
 		 * for each combination of elements with the same key in a window.
+		 * 
+		 * <p>Note: This method's return type does not support setting an operator-specific parallelism.
+		 * Due to binary backwards compatibility, this cannot be altered. Use the {@link #with(JoinFunction)}
+		 * method to set an operator-specific parallelism.
 		 */
 		public <T> DataStream<T> apply(JoinFunction<T1, T2, T> function) {
 			TypeInformation<T> resultType = TypeExtractor.getBinaryOperatorReturnType(
@@ -238,11 +242,12 @@ public class JoinedStreams<T1, T2> {
 		 * Completes the join operation with the user function that is executed
 		 * for each combination of elements with the same key in a window.
 		 *
-		 * <p>
-		 *     Note: This is a temporary workaround while the {@link #apply(JoinFunction)} method has the wrong return type.
-		 * </p>
-		 * @deprecated This method will be replaced by {@link #apply(JoinFunction)} in Flink 2.0.
-		 * So use the {@link #apply(JoinFunction)} in the future.
+		 * <p><b>Note:</b> This is a temporary workaround while the {@link #apply(JoinFunction)}
+		 * method has the wrong return type and hence does not allow one to set an operator-specific
+		 * parallelism
+		 * 
+		 * @deprecated This method will be removed once the {@link #apply(JoinFunction)} method is fixed
+		 *             in the next major version of Flink (2.0).
 		 */
 		@PublicEvolving
 		@Deprecated
@@ -253,6 +258,10 @@ public class JoinedStreams<T1, T2> {
 		/**
 		 * Completes the join operation with the user function that is executed
 		 * for each combination of elements with the same key in a window.
+		 * 
+		 * <p>Note: This method's return type does not support setting an operator-specific parallelism.
+		 * Due to binary backwards compatibility, this cannot be altered. Use the
+		 * {@link #with(JoinFunction, TypeInformation)}, method to set an operator-specific parallelism.
 		 */
 		public <T> DataStream<T> apply(FlatJoinFunction<T1, T2, T> function, TypeInformation<T> resultType) {
 			//clean the closure
@@ -273,9 +282,10 @@ public class JoinedStreams<T1, T2> {
 		 * Completes the join operation with the user function that is executed
 		 * for each combination of elements with the same key in a window.
 		 *
-		 * <p>
-		 *     Note: This is a temporary workaround while the {@link #apply(FlatJoinFunction, TypeInformation)} method has the wrong return type.
-		 * </p>
+		 * <p><b>Note:</b> This is a temporary workaround while the {@link #apply(JoinFunction, TypeInformation)}
+		 * method has the wrong return type and hence does not allow one to set an operator-specific
+		 * parallelism
+		 *
 		 * @deprecated This method will be replaced by {@link #apply(FlatJoinFunction, TypeInformation)} in Flink 2.0.
 		 * So use the {@link #apply(FlatJoinFunction, TypeInformation)} in the future.
 		 */
@@ -288,6 +298,10 @@ public class JoinedStreams<T1, T2> {
 		/**
 		 * Completes the join operation with the user function that is executed
 		 * for each combination of elements with the same key in a window.
+		 * 
+		 * <p>Note: This method's return type does not support setting an operator-specific parallelism.
+		 * Due to binary backwards compatibility, this cannot be altered. Use the
+		 * {@link #with(FlatJoinFunction)}, method to set an operator-specific parallelism.
 		 */
 		public <T> DataStream<T> apply(FlatJoinFunction<T1, T2, T> function) {
 			TypeInformation<T> resultType = TypeExtractor.getBinaryOperatorReturnType(
@@ -307,11 +321,12 @@ public class JoinedStreams<T1, T2> {
 		 * Completes the join operation with the user function that is executed
 		 * for each combination of elements with the same key in a window.
 		 *
-		 * <p>
-		 *     Note: This is a temporary workaround while the {@link #apply(FlatJoinFunction)} method has the wrong return type.
-		 * </p>
-		 * @deprecated This method will be replaced by {@link #apply(FlatJoinFunction)} in Flink 2.0.
-		 * So use the {@link #apply(FlatJoinFunction)} in the future.
+		 * <p><b>Note:</b> This is a temporary workaround while the {@link #apply(FlatJoinFunction)}
+		 * method has the wrong return type and hence does not allow one to set an operator-specific
+		 * parallelism.
+		 * 
+		 * @deprecated This method will be removed once the {@link #apply(FlatJoinFunction)}
+		 *             method is fixed in the next major version of Flink (2.0).
 		 */
 		@PublicEvolving
 		@Deprecated
@@ -322,6 +337,10 @@ public class JoinedStreams<T1, T2> {
 		/**
 		 * Completes the join operation with the user function that is executed
 		 * for each combination of elements with the same key in a window.
+		 * 
+		 * <p>Note: This method's return type does not support setting an operator-specific parallelism.
+		 * Due to binary backwards compatibility, this cannot be altered. Use the
+		 * {@link #with(JoinFunction, TypeInformation)}, method to set an operator-specific parallelism.
 		 */
 		public <T> DataStream<T> apply(JoinFunction<T1, T2, T> function, TypeInformation<T> resultType) {
 			//clean the closure
@@ -341,11 +360,12 @@ public class JoinedStreams<T1, T2> {
 		 * Completes the join operation with the user function that is executed
 		 * for each combination of elements with the same key in a window.
 		 *
-		 * <p>
-		 *     Note: This is a temporary workaround while the {@link #apply(JoinFunction, TypeInformation)} method has the wrong return type.
-		 * </p>
-		 * @deprecated This method will be replaced by {@link #apply(JoinFunction, TypeInformation)} in Flink 2.0.
-		 * So use the {@link #apply(JoinFunction, TypeInformation)} in the future.
+		 * <p><b>Note:</b> This is a temporary workaround while the {@link #apply(FlatJoinFunction, TypeInformation)}
+		 * method has the wrong return type and hence does not allow one to set an operator-specific
+		 * parallelism
+		 * 
+		 * @deprecated This method will be removed once the {@link #apply(JoinFunction, TypeInformation)}
+		 *             method is fixed in the next major version of Flink (2.0).
 		 */
 		@PublicEvolving
 		@Deprecated