Chromosome.java
01 /*
02  * Java Genetic Algorithm Library (jenetics-3.0.0).
03  * Copyright (c) 2007-2014 Franz Wilhelmstötter
04  *
05  * Licensed under the Apache License, Version 2.0 (the "License");
06  * you may not use this file except in compliance with the License.
07  * You may obtain a copy of the License at
08  *
09  *      http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  * Author:
18  *    Franz Wilhelmstötter (franz.wilhelmstoetter@gmx.at)
19  */
20 package org.jenetics;
21 
22 import java.io.Serializable;
23 
24 import org.jenetics.util.Factory;
25 import org.jenetics.util.ISeq;
26 import org.jenetics.util.Verifiable;
27 
28 /**
29  * A chromosome consists of one or more genes. It also provides a factory
30  * method for creating new, random chromosome instances of the same type and the
31  * same constraint.
32  <p>
33  <span class="simpleTagLabel">API Note: </span>
34  * Implementations of the {@code Chromosome} interface must be <em>immutable</em>
35  * and guarantee an efficient random access ({@code O(1)}) to the genes.
36  *
37  @see <a href="http://en.wikipedia.org/wiki/Chromosome">Wikipdida: Chromosome</a>
38  *
39  @author <a href="mailto:franz.wilhelmstoetter@gmx.at">Franz Wilhelmstötter</a>
40  @since 1.0
41  @version 2.0 &mdash; <em>$Date: 2014-12-28 $</em>
42  */
43 public interface Chromosome<G extends Gene<?, G>>
44     extends
45         Verifiable,
46         Iterable<G>,
47         Factory<Chromosome<G>>,
48         Serializable
49 {
50     /**
51      * A factory method which creates a new {@link Chromosome} of specific type
52      * and the given {@code genes}.
53      *
54      @param genes the genes of the new chromosome. The given genes array is
55      *         not copied.
56      @return A new {@link Chromosome} of the same type with the given genes.
57      @throws NullPointerException if the given {@code gene}s are {@code null}.
58      @throws IllegalArgumentException if the length of the given gene sequence
59      *        is smaller than one.
60      */
61     public Chromosome<G> newInstance(final ISeq<G> genes);
62 
63     /**
64      * Return the first gene of this chromosome. Each chromosome must contain
65      * at least one gene.
66      *
67      @return the first gene of this chromosome.
68      */
69     public default G getGene() {
70         return getGene(0);
71     }
72 
73     /**
74      * Return the gene on the specified index.
75      *
76      @param index The gene index.
77      @return the wanted gene.
78      @throws IndexOutOfBoundsException if the index is out of range
79      *          (index &lt; 1 || index &gt;= length()).
80      */
81     public G getGene(final int index);
82 
83     /**
84      * Returns the length of the Chromosome. The minimal length of a
85      * chromosome is one.
86      *
87      @return Length of the Chromosome
88      */
89     public int length();
90 
91     /**
92      * Return an unmodifiable sequence of the genes of this chromosome.
93      *
94      @return an immutable gene sequence.
95      */
96     public ISeq<G> toSeq();
97 
98 }