1 package net.bmahe.genetics4j.core.chromosomes.factory;
2
3 import net.bmahe.genetics4j.core.chromosomes.Chromosome;
4 import net.bmahe.genetics4j.core.spec.chromosome.ChromosomeSpec;
5
6 /**
7 * Factory interface for creating chromosome instances based on specifications.
8 *
9 * <p>ChromosomeFactory implements the Factory pattern to decouple chromosome creation from the specific implementation
10 * details. Each factory is responsible for creating chromosomes of a specific type (bit, integer, double, etc.) based
11 * on the provided specifications.
12 *
13 * <p>The factory pattern provides several benefits:
14 * <ul>
15 * <li><strong>Type safety</strong>: Compile-time guarantees about chromosome types</li>
16 * <li><strong>Extensibility</strong>: Easy addition of new chromosome types</li>
17 * <li><strong>Configuration-driven</strong>: Chromosome creation based on specifications</li>
18 * <li><strong>Encapsulation</strong>: Hides complex chromosome initialization logic</li>
19 * </ul>
20 *
21 * <p>Factory implementations typically handle:
22 * <ul>
23 * <li><strong>Random initialization</strong>: Creating chromosomes with random values within constraints</li>
24 * <li><strong>Constraint validation</strong>: Ensuring generated chromosomes meet specification requirements</li>
25 * <li><strong>Value range handling</strong>: Respecting minimum/maximum bounds for numeric types</li>
26 * <li><strong>Size management</strong>: Creating chromosomes with the correct number of alleles</li>
27 * </ul>
28 *
29 * <p>The framework provides concrete factories for common chromosome types:
30 * <ul>
31 * <li>{@link BitChromosomeFactory}: Creates binary string chromosomes</li>
32 * <li>{@link IntChromosomeFactory}: Creates integer array chromosomes</li>
33 * <li>{@link DoubleChromosomeFactory}: Creates double-precision floating-point chromosomes</li>
34 * <li>{@link FloatChromosomeFactory}: Creates single-precision floating-point chromosomes</li>
35 * </ul>
36 *
37 * <p>Factory selection is typically handled automatically by {@link ChromosomeFactoryProvider} which maintains a
38 * registry of available factories and selects the appropriate one based on the chromosome specification type.
39 *
40 * <p>Example custom factory implementation:
41 *
42 * <pre>
43 * {
44 * @code
45 * public class CustomChromosomeFactory implements ChromosomeFactory<CustomChromosome> {
46 *
47 * @Override
48 * public boolean canHandle(ChromosomeSpec chromosomeSpec) {
49 * return chromosomeSpec instanceof CustomChromosomeSpec;
50 * }
51 *
52 * @Override
53 * public CustomChromosome generate(ChromosomeSpec chromosomeSpec) {
54 * CustomChromosomeSpec spec = (CustomChromosomeSpec) chromosomeSpec;
55 * // Create chromosome based on specification
56 * return new CustomChromosome(spec.getParameters());
57 * }
58 * }
59 * }
60 * </pre>
61 *
62 * @param <T> the type of chromosome this factory creates
63 * @see ChromosomeSpec
64 * @see ChromosomeFactoryProvider
65 * @see net.bmahe.genetics4j.core.chromosomes.Chromosome
66 */
67 public interface ChromosomeFactory<T extends Chromosome> {
68
69 /**
70 * Determines if this factory can create chromosomes for the given specification.
71 *
72 * <p>This method implements the type-checking logic that allows the factory system to automatically select the
73 * appropriate factory for each chromosome specification. Implementations typically check if the specification is of
74 * the expected type.
75 *
76 * <p>The method should be:
77 * <ul>
78 * <li><strong>Fast</strong>: Called frequently during factory selection</li>
79 * <li><strong>Accurate</strong>: Return true only if generation will succeed</li>
80 * <li><strong>Safe</strong>: Handle null and unexpected specification types gracefully</li>
81 * </ul>
82 *
83 * @param chromosomeSpec the chromosome specification to evaluate
84 * @return {@code true} if this factory can generate chromosomes for the given specification, {@code false} otherwise
85 * @throws IllegalArgumentException if chromosomeSpec is null (optional, implementation-dependent)
86 */
87 boolean canHandle(final ChromosomeSpec chromosomeSpec);
88
89 /**
90 * Creates a new chromosome instance based on the provided specification.
91 *
92 * <p>This method implements the core factory logic, creating and initializing a new chromosome according to the
93 * parameters defined in the specification. The generated chromosome should be ready for use in genetic operations.
94 *
95 * <p>The generation process typically involves:
96 * <ul>
97 * <li>Extracting parameters from the specification (size, bounds, constraints)</li>
98 * <li>Generating random values within the specified constraints</li>
99 * <li>Creating and initializing the chromosome instance</li>
100 * <li>Validating that the result meets all requirements</li>
101 * </ul>
102 *
103 * <p>Implementation requirements:
104 * <ul>
105 * <li><strong>Specification compatibility</strong>: Only call after {@link #canHandle} returns true</li>
106 * <li><strong>Randomization</strong>: Use appropriate random number generation for initialization</li>
107 * <li><strong>Constraint compliance</strong>: Ensure generated values respect specification bounds</li>
108 * <li><strong>Thread safety</strong>: Support concurrent calls in multi-threaded environments</li>
109 * </ul>
110 *
111 * @param chromosomeSpec the specification defining the chromosome to create
112 * @return a newly created chromosome instance conforming to the specification
113 * @throws IllegalArgumentException if the specification is null, invalid, or not supported by this factory
114 * @throws RuntimeException if chromosome generation fails due to constraint conflicts or other errors
115 */
116 T generate(final ChromosomeSpec chromosomeSpec);
117 }