/*
 * 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@gmx.at)
 */
package org.jenetics.engine;

import static java.util.Objects.requireNonNull;

import java.util.function.Function;

import org.jenetics.Gene;
import org.jenetics.Genotype;
import org.jenetics.util.Factory;

/**
 * A problem {@code Codec} contains the information about how to encode a given
 * argument type into a {@code Genotype}. It also lets convert the encoded
 * {@code Genotype} back to the argument type. The engine creation and the
 * implementation of the fitness function can be heavily simplified by using
 * a {@code Codec} class. The example given in the {@link Engine} documentation
 * can be simplified as follows:
 *
 * <pre>{@code
 * public class RealFunction {
 *     // The conversion from the 'Genotype' to the argument type of the fitness
 *     // function is performed by the given 'Codec'. You can concentrate on the
 *     // implementation, because you are not bothered with the conversion code.
 *     private static double eval(final double x) {
 *         return cos(0.5 + sin(x)) * cos(x);
 *     }
 *
 *     public static void main(final String[] args) {
 *         final Engine<DoubleGene, Double> engine = Engine
 *              // Create an Engine.Builder with the "pure" fitness function
 *              // and the appropriate Codec.
 *             .build(RealFunction::eval, codecs.ofScalar(DoubleRange.of(0, 2*PI)))
 *             .build();
 *         ...
 *     }
 * }
 * }</pre>
 *
 * @see codecs
 * @see Engine
 * @see Engine.Builder
 *
 * @param <T> the argument type of a given problem
 * @param <G> the {@code Gene} type used for encoding the argument type {@code T}
 *
 * @author <a href="mailto:franz.wilhelmstoetter@gmx.at">Franz Wilhelmstötter</a>
 * @version 3.2
 * @since 3.2
 */
public interface Codec<T, G extends Gene<?, G>> {

	/**
	 * Return the genotype factory for creating genotypes with the right
	 * encoding for the given problem. The genotype created with this factory
	 * must work together with the {@link #decoder()} function, which transforms
	 * the genotype into an object of the problem domain.
	 *
	 * <pre>{@code
	 * final Codec<SomeObject, DoubleGene> codec = ...
	 * final Genotype<DoubleGene> gt = codec.encoding().newInstance();
	 * final SomeObject arg = codec.decoder().apply(gt);
	 * }</pre>
	 *
	 * @see #decoder()
	 *
	 * @return the genotype (factory) representation of the problem domain
	 */
	public Factory<Genotype<G>> encoding();

	/**
	 * Return the <em>decoder</em> function which transforms the genotype back
	 * to the original problem domain representation.
	 *
	 * @see #encoding()
	 *
	 * @return genotype decoder
	 */
	public Function<Genotype<G>, T> decoder();


	/**
	 * Create a new {@code Codec} object with the given {@code encoding} and
	 * {@code decoder} function.
	 *
	 * @param encoding the genotype factory used for creating new
	 *        {@code Genotypes}.
	 * @param decoder decoder function, which converts a {@code Genotype} to a
	 *        value in the problem domain.
	 * @param <G> the {@code Gene} type
	 * @param <T> the fitness function argument type in the problem domain
	 * @return a new {@code Codec} object with the given parameters.
	 * @throws NullPointerException if one of the arguments is {@code null}.
	 */
	public static <G extends Gene<?, G>, T> Codec<T, G> of(
		final Factory<Genotype<G>> encoding,
		final Function<Genotype<G>, T> decoder
	) {
		requireNonNull(encoding);
		requireNonNull(decoder);

		return new Codec<T, G>() {
			@Override
			public Factory<Genotype<G>> encoding() {
				return encoding;
			}

			@Override
			public Function<Genotype<G>, T> decoder() {
				return decoder;
			}
		};
	}

}

@@ -2152,24 +2152,348 @@
  %7D%3C/pre%3E%0A *%0A
+ * The %7B@code Codec%7D needed for the above usage example, will look like this:%0A * %3Cpre%3E%7B@code%0A * final DoubleRange domain = DoubleRange.of(0, 2*PI);%0A * final Codec%3CDouble, DoubleGene%3E codec = Codec.of(%0A *     Genotype.of(DoubleChromosome.of(domain)),%0A *     gt -%3E gt.getChromosome().getGene().getAllele()%0A * );%0A * %7D%3C/pre%3E%0A *%0A
  * @see code

Add Javadoc.