Adding continuable version of functional interfaces; updating copyright headers

Author: vsilaev

net.tascalate.javaflow.extras/src/main/java/org/apache/commons/javaflow/extras/CloseableIterator.java

@@ -1,5 +1,5 @@
 /**
- * Copyright 2013-2017 Valery Silaev (http://vsilaev.com)
+ * Copyright 2013-2018 Valery Silaev (http://vsilaev.com)
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

net.tascalate.javaflow.extras/src/main/java/org/apache/commons/javaflow/extras/CoIterator.java

@@ -1,5 +1,5 @@
 /**
- * Copyright 2013-2017 Valery Silaev (http://vsilaev.com)
+ * Copyright 2013-2018 Valery Silaev (http://vsilaev.com)
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

net.tascalate.javaflow.extras/src/main/java/org/apache/commons/javaflow/extras/ContinuableBiConsumer.java

@@ -0,0 +1,69 @@
+/**
+ * Copyright 2013-2018 Valery Silaev (http://vsilaev.com)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.javaflow.extras;
+
+import java.util.Objects;
+
+import org.apache.commons.javaflow.api.continuable;
+
+/**
+ * Represents a continuable operation that accepts two input arguments and returns no
+ * result.  This is the two-arity specialization of {@link ContinuableConsumer}.
+ * Unlike most other functional interfaces, {@code ContinuableBiConsumer} is expected
+ * to operate via side-effects.
+ *
+ * <p>This is a functional interface
+ * whose functional method is {@link #accept(Object, Object)}.
+ *
+ * @param <T> the type of the first argument to the operation
+ * @param <U> the type of the second argument to the operation
+ *
+ * @see ContinuableConsumer
+ */
+@FunctionalInterface
+public interface ContinuableBiConsumer<T, U> {
+
+    /**
+     * Performs this operation on the given arguments.
+     *
+     * @param t the first input argument
+     * @param u the second input argument
+     */
+    @continuable void accept(T t, U u);
+
+    /**
+     * Returns a composed {@code ContinuableBiConsumer} that performs, in sequence, this
+     * operation followed by the {@code after} operation. If performing either
+     * operation throws an exception, it is relayed to the caller of the
+     * composed operation.  If performing this operation throws an exception,
+     * the {@code after} operation will not be performed.
+     *
+     * @param after the operation to perform after this operation
+     * @return a composed {@code ContinuableBiConsumer} that performs in sequence this
+     * operation followed by the {@code after} operation
+     * @throws NullPointerException if {@code after} is null
+     */
+    default ContinuableBiConsumer<T, U> andThen(ContinuableBiConsumer<? super T, ? super U> after) {
+        Objects.requireNonNull(after);
+        return new ContinuableBiConsumer<T, U>() {
+            @Override
+            public void accept(T t, U u) {
+                ContinuableBiConsumer.this.accept(t, u);
+                after.accept(t, u);
+            }
+        };
+    }
+}

net.tascalate.javaflow.extras/src/main/java/org/apache/commons/javaflow/extras/ContinuableBiFunction.java

@@ -0,0 +1,69 @@
+/**
+ * Copyright 2013-2018 Valery Silaev (http://vsilaev.com)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.javaflow.extras;
+
+import java.util.Objects;
+import org.apache.commons.javaflow.api.continuable;
+
+/**
+ * Represents a function that accepts two arguments and produces a result.
+ * This is the two-arity specialization of {@link ContinuableFunction}.
+ *
+ * <p>This is a functional interface
+ * whose functional method is {@link #apply(Object, Object)}.
+ *
+ * @param <T> the type of the first argument to the function
+ * @param <U> the type of the second argument to the function
+ * @param <R> the type of the result of the function
+ *
+ * @see ContinuableFunction
+ */
+@FunctionalInterface
+public interface ContinuableBiFunction<T, U, R> {
+
+    /**
+     * Applies this function to the given arguments.
+     *
+     * @param t the first function argument
+     * @param u the second function argument
+     * @return the function result
+     */
+    @continuable R apply(T t, U u);
+
+    /**
+     * Returns a composed function that first applies this function to
+     * its input, and then applies the {@code after} function to the result.
+     * If evaluation of either function throws an exception, it is relayed to
+     * the caller of the composed function.
+     *
+     * @param <V> the type of output of the {@code after} function, and of the
+     *           composed function
+     * @param after the function to apply after this function is applied
+     * @return a composed function that first applies this function and then
+     * applies the {@code after} function
+     * @throws NullPointerException if after is null
+     */
+    default <V> ContinuableBiFunction<T, U, V> andThen(ContinuableFunction<? super R, ? extends V> after) {
+        Objects.requireNonNull(after);
+        ContinuableBiFunction<T, U, R> self = this;
+        return new ContinuableBiFunction<T, U, V>() {
+            @Override
+            public V apply(T t, U u) {
+                return after.apply(self.apply(t, u));                
+            }
+        };
+    }
+}

net.tascalate.javaflow.extras/src/main/java/org/apache/commons/javaflow/extras/ContinuableBinaryOperator.java

@@ -0,0 +1,80 @@
+/**
+ * Copyright 2013-2018 Valery Silaev (http://vsilaev.com)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.javaflow.extras;
+
+import java.util.Comparator;
+import java.util.Objects;
+
+
+/**
+ * Represents an continuable operation upon two operands of the same type, producing a result
+ * of the same type as the operands.  This is a specialization of
+ * {@link ContinuableBiFunction} for the case where the operands and the result are all of
+ * the same type.
+ *
+ * <p>This is a functional interface
+ * whose functional method is {@link #apply(Object, Object)}.
+ *
+ * @param <T> the type of the operands and result of the operator
+ *
+ * @see ContinuableBiFunction
+ * @see ContinuableUnaryOperator
+ */
+@FunctionalInterface
+public interface ContinuableBinaryOperator<T> extends ContinuableBiFunction<T,T,T> {
+    /**
+     * Returns a {@link ContinuableBinaryOperator} which returns the lesser of two elements
+     * according to the specified {@code Comparator}.
+     *
+     * @param <T> the type of the input arguments of the comparator
+     * @param comparator a {@code Comparator} for comparing the two values
+     * @return a {@code ContinuableBinaryOperator} which returns the lesser of its operands,
+     *         according to the supplied {@code Comparator}
+     * @throws NullPointerException if the argument is null
+     */
+    public static <T> ContinuableBinaryOperator<T> minBy(Comparator<? super T> comparator) {
+        Objects.requireNonNull(comparator);
+        return new ContinuableBinaryOperator<T>() {
+            @Override
+            public T apply(T a, T b) {
+                return comparator.compare(a, b) <= 0 ? a : b;
+            }
+            
+        };
+
+    }
+
+    /**
+     * Returns a {@link ContinuableBinaryOperator} which returns the greater of two elements
+     * according to the specified {@code Comparator}.
+     *
+     * @param <T> the type of the input arguments of the comparator
+     * @param comparator a {@code Comparator} for comparing the two values
+     * @return a {@code ContinuableBinaryOperator} which returns the greater of its operands,
+     *         according to the supplied {@code Comparator}
+     * @throws NullPointerException if the argument is null
+     */
+    public static <T> ContinuableBinaryOperator<T> maxBy(Comparator<? super T> comparator) {
+        Objects.requireNonNull(comparator);
+        return new ContinuableBinaryOperator<T>() {
+            @Override
+            public T apply(T a, T b) {
+                return comparator.compare(a, b) >= 0 ? a : b;
+            }
+            
+        };
+    }
+}

net.tascalate.javaflow.extras/src/main/java/org/apache/commons/javaflow/extras/ContinuableConsumer.java

@@ -1,5 +1,5 @@
 /**
- * Copyright 2013-2017 Valery Silaev (http://vsilaev.com)
+ * Copyright 2013-2018 Valery Silaev (http://vsilaev.com)
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -54,7 +54,7 @@ public interface ContinuableConsumer<T> {
     default ContinuableConsumer<T> andThen(ContinuableConsumer<? super T> after) {
         Objects.requireNonNull(after);
         return new ContinuableConsumer<T>() {
-            public @continuable void accept(T t) {
+            public void accept(T t) {
                 ContinuableConsumer.this.accept(t);
                 after.accept(t);
             }

net.tascalate.javaflow.extras/src/main/java/org/apache/commons/javaflow/extras/ContinuableFunction.java

@@ -0,0 +1,109 @@
+/**
+ * Copyright 2013-2018 Valery Silaev (http://vsilaev.com)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.javaflow.extras;
+
+import java.util.Objects;
+
+import org.apache.commons.javaflow.api.continuable;
+
+/**
+ * Represents a continuable function that accepts one argument and produces a result.
+ *
+ * <p>This is a functional interface
+ * whose functional method is {@link #apply(Object)}.
+ *
+ * @param <T> the type of the input to the function
+ * @param <R> the type of the result of the function
+ *
+ */
+@FunctionalInterface
+public interface ContinuableFunction<T, R> {
+
+    /**
+     * Applies this function to the given argument.
+     *
+     * @param t the function argument
+     * @return the function result
+     */
+    @continuable R apply(T t);
+
+    /**
+     * Returns a composed function that first applies the {@code before}
+     * function to its input, and then applies this function to the result.
+     * If evaluation of either function throws an exception, it is relayed to
+     * the caller of the composed function.
+     *
+     * @param <V> the type of input to the {@code before} function, and to the
+     *           composed function
+     * @param before the function to apply before this function is applied
+     * @return a composed function that first applies the {@code before}
+     * function and then applies this function
+     * @throws NullPointerException if before is null
+     *
+     * @see #andThen(ContinuableFunction)
+     */
+    default <V> ContinuableFunction<V, R> compose(ContinuableFunction<? super V, ? extends T> before) {
+        Objects.requireNonNull(before);
+        ContinuableFunction<T, R> self = this;
+        return new ContinuableFunction<V, R>() {
+            @Override
+            public R apply(V v) {
+                return self.apply(before.apply(v));                
+            }
+        };
+    }
+
+    /**
+     * Returns a composed function that first applies this function to
+     * its input, and then applies the {@code after} function to the result.
+     * If evaluation of either function throws an exception, it is relayed to
+     * the caller of the composed function.
+     *
+     * @param <V> the type of output of the {@code after} function, and of the
+     *           composed function
+     * @param after the function to apply after this function is applied
+     * @return a composed function that first applies this function and then
+     * applies the {@code after} function
+     * @throws NullPointerException if after is null
+     *
+     * @see #compose(ContinuableFunction)
+     */
+    default <V> ContinuableFunction<T, V> andThen(ContinuableFunction<? super R, ? extends V> after) {
+        Objects.requireNonNull(after);
+        ContinuableFunction<T, R> self = this;
+        return new ContinuableFunction<T, V>() {
+            @Override
+            public V apply(T v) {
+                return after.apply(self.apply(v));                
+            }
+        };
+    }
+
+    /**
+     * Returns a function that always returns its input argument.
+     *
+     * @param <T> the type of the input and output objects to the function
+     * @return a function that always returns its input argument
+     */
+    static <T> ContinuableFunction<T, T> identity() {
+        return new ContinuableFunction<T, T>() {
+            @Override
+            public T apply(T v) {
+                return v;                
+            }
+        };
+    }
+}