Gene


1   /*
2    * This file is part of JGAP.
3    *
4    * JGAP offers a dual license model containing the LGPL as well as the MPL.
5    *
6    * For licencing information please see the file license.txt included with JGAP
7    * or have a look at the top of class org.jgap.Chromosome which representatively
8    * includes the JGAP license policy applicable for any file delivered with JGAP.
9    */
10  package org.jgap;
11  
12  import java.io.Serializable  ;
13  
14  /**
15   * Genes represent the discrete components of a potential solution
16   * (the Chromosome). This interface exists so that custom gene implementations
17   * can be easily plugged-in, which can add a great deal of flexibility and
18   * convenience for many applications. Note that it's very important that
19   * implementations of this interface also implement the equals() method.
20   * Without a proper implementation of equals(), some genetic operations will
21   * fail to work properly.
22   * <p>
23   * When implementing a new Gene type, extend it from {@link org.jgap.BaseGene}!
24   *
25   * @author Neil Rotstan
26   * @author Klaus Meffert
27   * @since 1.0
28   */
29  public interface Gene
30      extends Comparable  , Serializable   {
31    /** String containing the CVS revision. Read out via reflection!*/
32    final static String   CVS_REVISION = "$Revision: 1.23 $";
33  
34    /**
35     * Represents the delimiter that is used to separate fields in the
36     * persistent representation.
37     */
38    final static String   PERSISTENT_FIELD_DELIMITER = ":";
39  
40    /**
41     * Provides an implementation-independent means for creating new Gene
42     * instances. The new instance that is created and returned should be
43     * setup with any implementation-dependent configuration that this Gene
44     * instance is setup with (aside from the actual value, of course). For
45     * example, if this Gene were setup with bounds on its value, then the
46     * Gene instance returned from this method should also be setup with
47     * those same bounds. This is important, as the JGAP core will invoke this
48     * method on each Gene in the sample Chromosome in order to create each
49     * new Gene in the same respective gene position for a new Chromosome.
50     * <p>
51     * It should be noted that nothing is guaranteed about the actual value
52     * of the returned Gene and it should therefore be considered to be
53     * undefined.
54     *
55     * @return a new Gene instance of the same type and with the same setup as
56     * this concrete Gene
57     *
58     * @since 1.0
59     */
60    Gene newGene();
61  
62    /**
63     * Sets the value of this Gene to the new given value. The actual
64     * type of the value is implementation-dependent.
65     *
66     * @param a_newValue the new value of this Gene instance
67     *
68     * @since 1.0
69     */
70  
71    void setAllele(Object   a_newValue);
72  
73    /**
74     * Retrieves the value represented by this Gene. The actual type
75     * of the value is implementation-dependent.
76     *
77     * @return the value of this Gene.
78     *
79     * @since 1.0
80     */
81    Object   getAllele();
82  
83    /**
84     * Retrieves a string representation of the value of this Gene instance
85     * that includes any information required to reconstruct it at a later
86     * time, such as its value and internal state. This string will be used to
87     * represent this Gene instance in XML persistence. This is an optional
88     * method but, if not implemented, XML persistence and possibly other
89     * features will not be available. An UnsupportedOperationException should
90     * be thrown if no implementation is provided.
91     *
92     * @return string representation of this Gene's current state
93     * @throws UnsupportedOperationException to indicate that no implementation
94     * is provided for this method
95     *
96     * @since 1.0
97     */
98  
99    String   getPersistentRepresentation()
100       throws UnsupportedOperationException  ;
101 
102   /**
103    * Sets the value and internal state of this Gene from the string
104    * representation returned by a previous invocation of the
105    * getPersistentRepresentation() method. This is an optional method but,
106    * if not implemented, XML persistence and possibly other features will not
107    * be available. An UnsupportedOperationException should be thrown if no
108    * implementation is provided.
109    *
110    * @param a_representation the string representation retrieved from a
111    * prior call to the getPersistentRepresentation() method
112    *
113    * @throws UnsupportedOperationException to indicate that no implementation
114    * is provided for this method
115    * @throws UnsupportedRepresentationException if this Gene implementation
116    * does not support the given string representation
117    *
118    * @since 1.0
119    */
120 
121   void setValueFromPersistentRepresentation(String   a_representation)
122       throws UnsupportedOperationException  , UnsupportedRepresentationException;
123 
124   /**
125    * Sets the value of this Gene to a random legal value for the
126    * implementation. This method exists for the benefit of mutation and other
127    * operations that simply desire to randomize the value of a gene.
128    *
129    * @param a_numberGenerator The random number generator that should be used
130    * to create any random values. It's important to use this generator to
131    * maintain the user's flexibility to configure the genetic engine to use the
132    * random number generator of their choice
133    *
134    * @since 1.0
135    */
136   void setToRandomValue(RandomGenerator a_numberGenerator);
137 
138   /**
139    * Executed by the genetic engine when this Gene instance is no
140    * longer needed and should perform any necessary resource cleanup.
141    */
142   void cleanup();
143 
144   /**
145    * @return a string representation of the gene
146    *
147    * @since 1.1 (in the interface)
148    */
149   String   toString();
150 
151   /**
152    * @return the size of the gene, i.e the number of atomic elements.
153    * Always 1 for numbers
154    *
155    * @since 1.1
156    */
157 
158   int size();
159 
160   /**
161    * Applies a mutation of a given intensity (percentage) onto the atomic
162    * element at given index (NumberGenes only have one atomic element)
163    * @param index index of atomic element, between 0 and size()-1
164    * @param a_percentage percentage of mutation (greater than -1 and smaller
165    * than 1).
166    *
167    * @since 1.1
168    */
169   void applyMutation(int index, double a_percentage);
170 
171   /**
172    * This sets the application-specific data that is attached to this Gene.
173    * Attaching application-specific data may be useful for
174    * some applications when it comes time to distinguish a Gene from another.
175    * JGAP ignores this data functionally.
176    *
177    * @param a_newData the new application-specific data to attach to this
178    * Gene
179    *
180    * @author Klaus Meffert
181    * @since 2.4
182    */
183   void setApplicationData(Object   a_newData);
184 
185   /**
186    * Retrieves the application-specific data that is attached to this Gene.
187    * Attaching application-specific data may be useful for
188    * some applications when it comes time to distinguish a Gene from another.
189    * JGAP ignores this data functionally.
190    *
191    * @return the application-specific data previously attached to this Gene,
192    * or null if there is no data attached
193    *
194    * @author Klaus Meffert
195    * @since 2.4
196    */
197   Object   getApplicationData();
198 
199   /**
200    * Should we also consider the application data when comparing? Default is
201    * "false" as "true" means a Gene is losing its identity when
202    * application data is set differently!
203    *
204    * @param a_doCompare true: consider application data in method compareTo
205    *
206    * @author Klaus Meffert
207    * @since 2.4
208    */
209 
210   void setCompareApplicationData(boolean a_doCompare);
211 
212   /*
213    * @return should we also consider the application data when comparing?
214    *
215    * @author Klaus Meffert
216    * @since 2.4
217    */
218   boolean isCompareApplicationData();
219 
220   /**
221    * @return energy of the gene
222    *
223    * @author Klaus Meffert
224    * @since 2.3
225    */
226   public double getEnergy();
227 
228   /**
229    * Sets the energy of the gene
230    * @param a_energy the energy to set
231    *
232    * @author Klaus Meffert
233    * @since 2.3
234    */
235   void setEnergy(double a_energy);
236 
237   /**
238    * Sets the constraint checker to be used for this gene whenever method
239    * setAllele(Object) is called.
240    * @param a_constraintChecker the constraint checker to be set
241    *
242    * @author Klaus Meffert
243    * @since 2.6 (moved from CompositeGene, where it was since 2.0)
244    */
245   void setConstraintChecker(
246       final IGeneConstraintChecker a_constraintChecker);
247 
248   /**
249    * @return the configuration used
250    *
251    * @author Klaus Meffert
252    * @since 3.0
253    */
254   Configuration getConfiguration();
255 }
256
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags