KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jgap > 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 JavaDoc;
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 JavaDoc, Serializable JavaDoc {
31   /** String containing the CVS revision. Read out via reflection!*/
32   final static String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getPersistentRepresentation()
100       throws UnsupportedOperationException JavaDoc;
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 JavaDoc a_representation)
122       throws UnsupportedOperationException JavaDoc, 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 JavaDoc 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 JavaDoc 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 JavaDoc 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
Popular Tags