/*
 * Java Genetic Algorithm Library (@__identifier__@).
 * Copyright (c) @__year__@ Franz Wilhelmstötter
 *
 * 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.
 *
 * Author:
 *    Franz Wilhelmstötter (franz.wilhelmstoetter@gmail.com)
 */
package io.jenetics.util;

import static java.util.Objects.requireNonNull;

import java.util.Set;
import java.util.function.BiConsumer;
import java.util.function.BinaryOperator;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.stream.Collector;

/**
 * This interface lets you accumulate elements of type {@code T} to a result of
 * type {@code R}. It can be seen as a continuous {@link Collector}. In contrast
 * to a {@link Collector} an {@code Accumulator} can deliver intermediate results
 * while accumulating. Due to the similarities between the {@link Collector}
 * class, an {@code Accumulator} can be created from any {@link Collector}
 * implementation ({@link #of(Collector)}).
 *
 * <pre>{@code
 * final Accumulator<Integer, List<Integer>> accu =
 *     Accumulator.of(Collectors.toList());
 *
 * final ISeq<List<Integer>> result = IntStream.range(0, 10).boxed()
 *     .peek(accu)
 *     .map(i -> accu.result())
 *     .collect(ISeq.toISeq());
 *
 * result.forEach(System.out::println);
 * }</pre>
 * The code above gives you the following output.
 * <pre>
 * [0]
 * [0,1]
 * [0,1,2]
 * [0,1,2,3]
 * [0,1,2,3,4]
 * [0,1,2,3,4,5]
 * [0,1,2,3,4,5,6]
 * [0,1,2,3,4,5,6,7]
 * [0,1,2,3,4,5,6,7,8]
 * [0,1,2,3,4,5,6,7,8,9]
 * </pre>
 *
 * @apiNote
 * In contrast to the {@link Collector} interface, the {@code Accumulator} is
 * not mergeable.
 * The <em>accumulator</em> is not thread-safe and can't be used for parallel
 * streams.
 *
 * @param <T> the type of input elements to the accumulate operation
 * @param <A> the accumulator type
 * @param <R> the result type of the accumulated operation
 *
 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
 * @version !__version__!
 * @since !__version__!
 */
public interface Accumulator<T, A extends Accumulator<T, A, R>, R>
	extends Consumer<T>, Collector<T, A, R>
{

	/**
	 * Return a <em>copy</em>  of the current result of the accumulated elements.
	 * The accumulated elements are not changed by this method.
	 *
	 * @return the current result of the accumulated elements
	 */
	R result();

	/**
	 * Combines {@code this} accumulator with the {@code other} one.
	 *
	 * @param other the other accumulator
	 * @return the combined accumulator
	 * @throws UnsupportedOperationException unless it's overridden by the
	 *         implementation
	 */
	default A combine(final A other) {
		throw new UnsupportedOperationException(
			"No implementation for combining accumulators."
		);
	}

	@Override
	default BiConsumer<A, T> accumulator() {
		return A::accept;
	}

	@Override
	default BinaryOperator<A> combiner() {
		return A::combine;
	}

	@Override
	default Function<A, R> finisher() {
		return A::result;
	}

	@Override
	default Set<Characteristics> characteristics() {
		return Set.of();
	}

	/**
	 * Returns a synchronized (thread-safe) accumulator backed by {@code this}
	 * accumulator. The given {@code lock} is used as synchronization object.
	 *
	 * @param lock the <em>lock</em> used for synchronization
	 * @return a synchronized (thread-safe) accumulator backed by {@code this}
	 * 	       accumulator
	 * @throws NullPointerException if the given {@code lock} is {@code null}
	 */
	default Accumulator<T, ?, R> synced(final Object lock) {
		requireNonNull(lock);

		@SuppressWarnings("unchecked")
		final A self = (A)this;
		return this instanceof SynchronizedAccumulator
			? this
			: new SynchronizedAccumulator<>(self, lock);
	}

	/**
	 * Returns a synchronized (thread-safe) accumulator backed by {@code this}
	 * accumulator. {@code this} accumulator is used as synchronization object.
	 *
	 * @return a synchronized (thread-safe) accumulator backed by {@code this}
	 * 	       accumulator
	 */
	default Accumulator<T, ?, R> synced() {
		return synced(this);
	}

	/**
	 * Create a new accumulator from the given {@code collector}.
	 *
	 * <pre>{@code
	 * final Accumulator<Integer, ISeq<Integer>> accu =
	 *     Accumulator.of(ISeq.toISeq());
	 * }</pre>
	 *
	 * @param collector the collector which is used for accumulation and creation
	 *        the result value.
	 * @param <T> the type of input elements to the reduction operation
	 * @param <R> the result type of the reduction operation
	 * @return a new accumulator which is backed by the given {@code collector}
	 * @throws NullPointerException if the given {@code collector} is {@code null}
	 */
	static <T, R> Accumulator<T, ?, R> of(final Collector<T, ?, R> collector) {
		return new CollectorAccumulator<>(collector);
	}

}


@@ -1130,57 +1130,8 @@
 R%7D. 
-It can be seen as a continuous %7B@link Collector%7D.
  In 
@@ -1138,19 +1138,16 @@
 contrast
-%0A *
  to a %7B@
@@ -1180,24 +1180,27 @@
 Accumulator%7D
+%0A *
  can deliver
@@ -1220,19 +1220,16 @@
  results
-%0A *
  while a
@@ -1245,83 +1245,12 @@
 ng. 
-Due to the similarities between the %7B@link Collector%7D%0A * class, an %7B@code A
+An a
 ccum
@@ -1259,16 +1259,18 @@
 ator
-%7D
  can be
+%0A *
  cre
@@ -1304,26 +1304,17 @@
 tor%7D
-%0A * implementation
+ with the
  (%7B@
@@ -1334,16 +1334,23 @@
 ector)%7D)
+ method
 .%0A *%0A * 
@@ -1390,16 +1390,19 @@
 Integer,
+ ?,
  List%3CIn
@@ -2008,19 +2008,16 @@
 rgeable.
-%0A *
  The %3Cem
@@ -2066,24 +2066,27 @@
 an't be used
+%0A *
  for paralle
@@ -2086,19 +2086,16 @@
 parallel
-%0A *
  streams
@@ -4550,16 +4550,19 @@
 Integer,
+ ?,
  ISeq%3CIn

Improve Javadoc.