001: /*
002: * This file is part of JGAP.
003: *
004: * JGAP offers a dual license model containing the LGPL as well as the MPL.
005: *
006: * For licensing information please see the file license.txt included with JGAP
007: * or have a look at the top of class org.jgap.Chromosome which representatively
008: * includes the JGAP license policy applicable for any file delivered with JGAP.
009: */
010: package org.jgap;
011:
012: import java.io.Serializable;
013:
014: /**
015: * Genes represent the discrete components of a potential solution
016: * (the Chromosome). This interface exists so that custom gene implementations
017: * can be easily plugged-in, which can add a great deal of flexibility and
018: * convenience for many applications. Note that it's very important that
019: * implementations of this interface also implement the equals() method.
020: * Without a proper implementation of equals(), some genetic operations will
021: * fail to work properly.
022: * <p>
023: * When implementing a new Gene type, extend it from {@link org.jgap.BaseGene}!
024: *
025: * @author Neil Rotstan
026: * @author Klaus Meffert
027: * @since 1.0
028: */
029: public interface Gene extends Comparable, Serializable {
030: /** String containing the CVS revision. Read out via reflection!*/
031: final static String CVS_REVISION = "$Revision: 1.25 $";
032:
033: /**
034: * Represents the delimiter that is used to separate fields in the
035: * persistent representation.
036: */
037: final static String PERSISTENT_FIELD_DELIMITER = ":";
038:
039: /**
040: * Provides an implementation-independent means for creating new Gene
041: * instances. The new instance that is created and returned should be
042: * setup with any implementation-dependent configuration that this Gene
043: * instance is setup with (aside from the actual value, of course). For
044: * example, if this Gene were setup with bounds on its value, then the
045: * Gene instance returned from this method should also be setup with
046: * those same bounds. This is important, as the JGAP core will invoke this
047: * method on each Gene in the sample Chromosome in order to create each
048: * new Gene in the same respective gene position for a new Chromosome.
049: * <p>
050: * It should be noted that nothing is guaranteed about the actual value
051: * of the returned Gene and it should therefore be considered to be
052: * undefined.
053: *
054: * @return a new Gene instance of the same type and with the same setup as
055: * this concrete Gene
056: *
057: * @since 1.0
058: */
059: Gene newGene();
060:
061: /**
062: * Sets the value of this Gene to the new given value. The actual
063: * type of the value is implementation-dependent.
064: *
065: * @param a_newValue the new value of this Gene instance
066: *
067: * @since 1.0
068: */
069:
070: void setAllele(Object a_newValue);
071:
072: /**
073: * Retrieves the value represented by this Gene. The actual type
074: * of the value is implementation-dependent.
075: *
076: * @return the value of this Gene.
077: *
078: * @since 1.0
079: */
080: Object getAllele();
081:
082: /**
083: * Retrieves a string representation of the value of this Gene instance
084: * that includes any information required to reconstruct it at a later
085: * time, such as its value and internal state. This string will be used to
086: * represent this Gene instance in XML persistence. This is an optional
087: * method but, if not implemented, XML persistence and possibly other
088: * features will not be available. An UnsupportedOperationException should
089: * be thrown if no implementation is provided.
090: *
091: * @return string representation of this Gene's current state
092: * @throws UnsupportedOperationException to indicate that no implementation
093: * is provided for this method
094: *
095: * @since 1.0
096: */
097: String getPersistentRepresentation()
098: throws UnsupportedOperationException;
099:
100: /**
101: * Sets the value and internal state of this Gene from the string
102: * representation returned by a previous invocation of the
103: * getPersistentRepresentation() method. This is an optional method but,
104: * if not implemented, XML persistence and possibly other features will not
105: * be available. An UnsupportedOperationException should be thrown if no
106: * implementation is provided.
107: *
108: * @param a_representation the string representation retrieved from a
109: * prior call to the getPersistentRepresentation() method
110: *
111: * @throws UnsupportedOperationException to indicate that no implementation
112: * is provided for this method
113: * @throws UnsupportedRepresentationException if this Gene implementation
114: * does not support the given string representation
115: *
116: * @since 1.0
117: */
118: void setValueFromPersistentRepresentation(String a_representation)
119: throws UnsupportedOperationException,
120: UnsupportedRepresentationException;
121:
122: /**
123: * Sets the value of this Gene to a random legal value for the
124: * implementation. This method exists for the benefit of mutation and other
125: * operations that simply desire to randomize the value of a gene.
126: *
127: * @param a_numberGenerator The random number generator that should be used
128: * to create any random values. It's important to use this generator to
129: * maintain the user's flexibility to configure the genetic engine to use the
130: * random number generator of their choice
131: *
132: * @since 1.0
133: */
134: void setToRandomValue(RandomGenerator a_numberGenerator);
135:
136: /**
137: * Executed by the genetic engine when this Gene instance is no
138: * longer needed and should perform any necessary resource cleanup.
139: */
140: void cleanup();
141:
142: /**
143: * @return a string representation of the gene
144: *
145: * @since 1.1 (in the interface)
146: */
147: String toString();
148:
149: /**
150: * @return the size of the gene, i.e the number of atomic elements.
151: * Always 1 for numbers
152: *
153: * @since 1.1
154: */
155: int size();
156:
157: /**
158: * Applies a mutation of a given intensity (percentage) onto the atomic
159: * element at given index (NumberGenes only have one atomic element)
160: * @param index index of atomic element, between 0 and size()-1
161: * @param a_percentage percentage of mutation (greater than -1 and smaller
162: * than 1).
163: *
164: * @since 1.1
165: */
166: void applyMutation(int index, double a_percentage);
167:
168: /**
169: * This sets the application-specific data that is attached to this Gene.
170: * Attaching application-specific data may be useful for
171: * some applications when it comes time to distinguish a Gene from another.
172: * JGAP ignores this data functionally.
173: *
174: * @param a_newData the new application-specific data to attach to this
175: * Gene
176: *
177: * @author Klaus Meffert
178: * @since 2.4
179: */
180: void setApplicationData(Object a_newData);
181:
182: /**
183: * Retrieves the application-specific data that is attached to this Gene.
184: * Attaching application-specific data may be useful for
185: * some applications when it comes time to distinguish a Gene from another.
186: * JGAP ignores this data functionally.
187: *
188: * @return the application-specific data previously attached to this Gene,
189: * or null if there is no data attached
190: *
191: * @author Klaus Meffert
192: * @since 2.4
193: */
194: Object getApplicationData();
195:
196: /**
197: * Should we also consider the application data when comparing? Default is
198: * "false" as "true" means a Gene is losing its identity when
199: * application data is set differently!
200: *
201: * @param a_doCompare true: consider application data in method compareTo
202: *
203: * @author Klaus Meffert
204: * @since 2.4
205: */
206: void setCompareApplicationData(boolean a_doCompare);
207:
208: /*
209: * @return should we also consider the application data when comparing?
210: *
211: * @author Klaus Meffert
212: * @since 2.4
213: */
214: boolean isCompareApplicationData();
215:
216: /**
217: * @return energy of the gene
218: *
219: * @author Klaus Meffert
220: * @since 2.3
221: */
222: public double getEnergy();
223:
224: /**
225: * Sets the energy of the gene
226: * @param a_energy the energy to set
227: *
228: * @author Klaus Meffert
229: * @since 2.3
230: */
231: void setEnergy(double a_energy);
232:
233: /**
234: * Sets the constraint checker to be used for this gene whenever method
235: * setAllele(Object) is called.
236: * @param a_constraintChecker the constraint checker to be set
237: *
238: * @author Klaus Meffert
239: * @since 2.6 (moved from CompositeGene, where it was since 2.0)
240: */
241: void setConstraintChecker(
242: final IGeneConstraintChecker a_constraintChecker);
243:
244: /**
245: * @return the configuration used
246: *
247: * @author Klaus Meffert
248: * @since 3.0
249: */
250: Configuration getConfiguration();
251: }
|