Did more commenting, implemented reflection and statistics

8 files changed, 551 insertions, 0 deletions

diff --git a/src/jcgp/backend/parameters/BooleanParameter.java b/src/jcgp/backend/parameters/BooleanParameter.java
new file mode 100644
index 0000000..f0abe50
--- /dev/null
+++ b/src/jcgp/backend/parameters/BooleanParameter.java
@@ -0,0 +1,79 @@
+package jcgp.backend.parameters;
+
+import javafx.beans.property.SimpleBooleanProperty;
+
+/**
+ * Parameter subclass for the boolean type. Most of the
+ * functionality is already implemented in {@code Parameter}, 
+ * leaving only construction and type definition to the
+ * subclasses.
+ * <br><br>
+ * This class contains three constructors, two of which are public.
+ * One assumes the parameter is not critical and only takes a name
+ * and initial value, while the other allows the critical flag
+ * to be set as well. The third constructor is protected and allows
+ * the monitor flag to be set as well, allowing subclasses of this class
+ * to be used as monitors. See {@link BooleanMonitor} for an example
+ * of this usage.
+ * <br><br>
+ * The validate method is overridden here and left blank since not all
+ * parameters actually require validation, but where validation is
+ * required this method can be anonymously overridden on an instance-to-instance
+ * basis.
+ * 
+ * @author Eduardo Pedroni
+ *
+ */
+public class BooleanParameter extends Parameter<Boolean> {
+	
+	/**
+	 * Creates a new instance of this class, assuming the parameter
+	 * is not critical.
+	 * 
+	 * @param value the initial value for this parameter.
+	 * @param name the name of this parameter, for GUI display.
+	 */
+	public BooleanParameter(boolean value, String name) {
+		super(name, false, false);
+		this.valueProperty = new SimpleBooleanProperty(value);
+	}
+	
+	/**
+	 * Creates a new instance of this class.
+	 * 
+	 * @param value the initial value for this parameter.
+	 * @param name the name of this parameter, for GUI display.
+	 * @param critical true if the parameter is critical.
+	 */
+	public BooleanParameter(boolean value, String name, boolean critical) {
+		super(name, false, critical);
+		this.valueProperty = new SimpleBooleanProperty(value);
+	}
+	
+	/**
+	 * For use by subclasses only, this constructor allows the monitor flag to be set.
+	 * 
+	 * @param value the initial value for this parameter.
+	 * @param name the name of this parameter, for GUI display.
+	 * @param monitor true if the parameter is a monitor.
+	 * @param critical true if the parameter is critical.
+	 */
+	protected BooleanParameter(boolean value, String name, boolean monitor, boolean critical) {
+		super(name, monitor, critical);
+		this.valueProperty = new SimpleBooleanProperty(value);
+	}
+	
+	@Override
+	public Boolean get() {
+		return super.get().booleanValue();
+	}
+
+	@Override
+	public void validate(Boolean newValue) {
+		/*
+		 *  Blank by default.
+		 *  Instances should override this as necessary.
+		 *  
+		 */
+	}
+}
diff --git a/src/jcgp/backend/parameters/DoubleParameter.java b/src/jcgp/backend/parameters/DoubleParameter.java
new file mode 100644
index 0000000..14b3151
--- /dev/null
+++ b/src/jcgp/backend/parameters/DoubleParameter.java
@@ -0,0 +1,79 @@
+package jcgp.backend.parameters;
+
+import javafx.beans.property.SimpleDoubleProperty;
+
+/**
+ * Parameter subclass for the double type. Most of the
+ * functionality is already implemented in {@code Parameter}, 
+ * leaving only construction and type definition to the
+ * subclasses.
+ * <br><br>
+ * This class contains three constructors, two of which are public.
+ * One assumes the parameter is not critical and only takes a name
+ * and initial value, while the other allows the critical flag
+ * to be set as well. The third constructor is protected and allows
+ * the monitor flag to be set as well, allowing subclasses of this class
+ * to be used as monitors. See {@link DoubleMonitor} for an example
+ * of this usage.
+ * <br><br>
+ * The validate method is overridden here and left blank since not all
+ * parameters actually require validation, but where validation is
+ * required this method can be anonymously overridden on an instance-to-instance
+ * basis.
+ * 
+ * @author Eduardo Pedroni
+ *
+ */
+public class DoubleParameter extends Parameter<Number> {
+	
+	/**
+	 * Creates a new instance of this class, assuming the parameter
+	 * is not critical.
+	 * 
+	 * @param value the initial value for this parameter.
+	 * @param name the name of this parameter, for GUI display.
+	 */
+	public DoubleParameter(double value, String name) {
+		super(name, false, false);
+		this.valueProperty = new SimpleDoubleProperty(value);
+	}
+	
+	/**
+	 * Creates a new instance of this class.
+	 * 
+	 * @param value the initial value for this parameter.
+	 * @param name the name of this parameter, for GUI display.
+	 * @param critical true if the parameter is critical.
+	 */
+	public DoubleParameter(double value, String name, boolean critical) {
+		super(name, false, critical);
+		this.valueProperty = new SimpleDoubleProperty(value);
+	}
+	
+	/**
+	 * For use by subclasses only, this constructor allows the monitor flag to be set.
+	 * 
+	 * @param value the initial value for this parameter.
+	 * @param name the name of this parameter, for GUI display.
+	 * @param monitor true if the parameter is a monitor.
+	 * @param critical true if the parameter is critical.
+	 */
+	protected DoubleParameter(double value, String name, boolean monitor, boolean critical) {
+		super(name, monitor, critical);
+		this.valueProperty = new SimpleDoubleProperty(value);
+	}
+
+	@Override
+	public Double get() {
+		return super.get().doubleValue();
+	}
+
+	@Override
+	public void validate(Number newValue) {
+		/*
+		 *  Blank by default.
+		 *  Instances should override this as necessary.
+		 *  
+		 */
+	}
+}
diff --git a/src/jcgp/backend/parameters/IntegerParameter.java b/src/jcgp/backend/parameters/IntegerParameter.java
new file mode 100644
index 0000000..d0d7328
--- /dev/null
+++ b/src/jcgp/backend/parameters/IntegerParameter.java
@@ -0,0 +1,79 @@
+package jcgp.backend.parameters;
+
+import javafx.beans.property.SimpleIntegerProperty;
+
+/**
+ * Parameter subclass for the double type. Most of the
+ * functionality is already implemented in {@code Parameter}, 
+ * leaving only construction and type definition to the
+ * subclasses.
+ * <br><br>
+ * This class contains three constructors, two of which are public.
+ * One assumes the parameter is not critical and only takes a name
+ * and initial value, while the other allows the critical flag
+ * to be set as well. The third constructor is protected and allows
+ * the monitor flag to be set as well, allowing subclasses of this class
+ * to be used as monitors. See {@link IntegerMonitor} for an example
+ * of this usage.
+ * <br><br>
+ * The validate method is overridden here and left blank since not all
+ * parameters actually require validation, but where validation is
+ * required this method can be anonymously overridden on an instance-to-instance
+ * basis.
+ * 
+ * @author Eduardo Pedroni
+ *
+ */
+public class IntegerParameter extends Parameter<Number> {
+	
+	/**
+	 * Creates a new instance of this class, assuming the parameter
+	 * is not critical.
+	 * 
+	 * @param value the initial value for this parameter.
+	 * @param name the name of this parameter, for GUI display.
+	 */
+	public IntegerParameter(int value, String name) {
+		super(name, false, false);
+		this.valueProperty = new SimpleIntegerProperty(value);
+	}
+	
+	/**
+	 * Creates a new instance of this class.
+	 * 
+	 * @param value the initial value for this parameter.
+	 * @param name the name of this parameter, for GUI display.
+	 * @param critical true if the parameter is critical.
+	 */
+	public IntegerParameter(int value, String name, boolean critical) {
+		super(name, false, critical);
+		this.valueProperty = new SimpleIntegerProperty(value);
+	}
+	
+	/**
+	 * For use by subclasses only, this constructor allows the monitor flag to be set.
+	 * 
+	 * @param value the initial value for this parameter.
+	 * @param name the name of this parameter, for GUI display.
+	 * @param monitor true if the parameter is a monitor.
+	 * @param critical true if the parameter is critical.
+	 */
+	protected IntegerParameter(int value, String name, boolean monitor, boolean critical) {
+		super(name, monitor, critical);
+		this.valueProperty = new SimpleIntegerProperty(value);
+	}
+
+	@Override
+	public Integer get() {
+		return super.get().intValue();
+	}
+
+	@Override
+	public void validate(Number newValue) {
+		/*
+		 *  Blank by default.
+		 *  Instances should override this as necessary.
+		 *  
+		 */
+	}
+}
diff --git a/src/jcgp/backend/parameters/Parameter.java b/src/jcgp/backend/parameters/Parameter.java
new file mode 100644
index 0000000..c04dee9
--- /dev/null
+++ b/src/jcgp/backend/parameters/Parameter.java
@@ -0,0 +1,128 @@
+package jcgp.backend.parameters;
+
+import javafx.beans.property.Property;
+import javafx.beans.property.ReadOnlyProperty;
+
+/**
+ * Specifies an abstract model of a module parameter.
+ * <br><br>
+ * Parameters are values which control the operation of modules.
+ * They can be freely modified and accessed by the module in which
+ * they are declared. Additionally, the module may choose to expose
+ * some of its parameters to a user interface, so that information
+ * is displayed. If that is the case, the parameter can be made
+ * read-only by setting the monitor flag (it becomes a parameter
+ * monitor). In addition, settings the critical flag indicates to
+ * the experiment that any changes to the parameter should result in
+ * an experiment-wide reset.
+ * <br><br>
+ * {@code Parameter} is abstract. A typical implementation defines
+ * the data type T and initialises the {@code valueProperty} field
+ * with a suitable type. For the sake of clarity, it may not be ideal 
+ * for a subclass constructor to expose an argument for the monitor
+ * field. Instead, a different class should be created which constructs
+ * the parameter as a monitor, so that the distinction between a regular
+ * parameter and a parameter monitor is more apparent. The boolean, integer
+ * and double implementations of parameter (and their associated monitors)
+ * implement this pattern, refer to them for more details. 
+ * <br><br>
+ * The {@code status} field holds the current status of the parameter, 
+ * which should change whenever the parameter value changes.
+ * In order for this to happen, {@code validate()} is called whenever
+ * the parameter status should be updated. This being the case, it should
+ * be overridden on an instance-to-instance basis, as each parameter 
+ * will likely have different validity criteria. The type of status is
+ * {@link ParameterStatus}, an enum type defining all valid states.
+ * 
+ * @see Module, ParameterStatus
+ * @author Eduardo Pedroni
+ * @param <T> the data type stored in the parameter.
+ */
+public abstract class Parameter<T> {
+	
+	private boolean monitor, critical;
+	protected ParameterStatus status = ParameterStatus.VALID;
+	protected String name;
+	protected Property<T> valueProperty;
+	
+	/**
+	 * For internal use only. This creates a new instance of the class
+	 * requiring a name, monitor and critical information. It should be
+	 * invoked using {@code super()} by any implementing constructors.
+	 * 
+	 * @param name the name of the parameter, to be used by GUIs (if in use).
+	 * @param monitor true if the parameter is a monitor, meaning it is not editable via the GUI (if in use).
+	 * @param critical true if any changes to this parameter should cause an experiment-wide reset.
+	 */
+	protected Parameter(String name, boolean monitor, boolean critical) {
+		this.name = name;
+		this.monitor = monitor;
+		this.critical = critical;
+	}
+	
+	/**
+	 * @return true if the parameter is a monitor.
+	 */
+	public boolean isMonitor() {
+		return monitor;
+	}
+	
+	/**
+	 * @return true if the parameter is critical.
+	 */
+	public boolean isCritical() {
+		return critical;
+	}
+	
+	/**
+	 * @return the current status of the parameter.
+	 */
+	public ParameterStatus getStatus() {
+		return status;
+	}
+		
+	/**
+	 * This method is intended for bindings only. Changes to the parameter
+	 * value should be made using {@code set()}.
+	 * 
+	 * @return the property which holds the parameter value.
+	 */
+	public ReadOnlyProperty<T> valueProperty() {
+		return valueProperty;
+	}
+	
+	/**
+	 * @return the parameter's current value.
+	 */
+	public T get() {
+		return valueProperty.getValue();
+	}
+	
+	/**
+	 * Sets the parameter to the specified value, if the property
+	 * is not bound.
+	 * 
+	 * @param newValue the new value for the parameter.
+	 */
+	public void set(T newValue) {
+		if (!valueProperty.isBound()) {
+			valueProperty.setValue(newValue);
+		}
+	}
+	
+	/**
+	 * This is a callback method which gets called whenever changes
+	 * to parameters (not only its own instance) are made. This method
+	 * is intended to set the {@code status} field according to the
+	 * new value, so that the user can be informed if any parameters
+	 * are currently set to invalid values.
+	 * 
+	 * @param newValue the new value.
+	 */
+	public abstract void validate(T newValue);
+	
+	@Override
+	public String toString() {
+		return name;
+	}
+}
diff --git a/src/jcgp/backend/parameters/ParameterStatus.java b/src/jcgp/backend/parameters/ParameterStatus.java
new file mode 100644
index 0000000..4041cad
--- /dev/null
+++ b/src/jcgp/backend/parameters/ParameterStatus.java
@@ -0,0 +1,53 @@
+package jcgp.backend.parameters;
+
+/**
+ * Enum type containing all possible states for parameters.
+ * <br>
+ * <ul>
+ * <li>INVALID: the new parameter value is not valid,
+ * and the experiment will not be allowed to run.</li>
+ * <li>WARNING: the new parameter value is technically valid,
+ * though it might lead to undesirable behaviour.</li>
+ * <li>WARNING_RESET: the new parameter value is technically valid
+ * but will require a reset.</li>
+ * <li>VALID: the new value is valid.</li>
+ * <br><br>
+ * The above definitions are final in the sense that they outline
+ * how parameters are treated by the program depending on their 
+ * status (e.g. if any parameters are set to WARNING_RESET, a reset 
+ * will automatically be performed when the experiment is run).
+ * <br>
+ * In addition to the status itself, this class includes a field
+ * to contain details about the current status. If a GUI is in use, 
+ * the contents of the field should be displayed to the user, as well
+ * as some visual indication of the status itself. Both the status
+ * and the message should be updated by each parameter when {@code validate()}
+ * is called.
+ * 
+ * @see Parameter
+ * @author Eduardo Pedroni
+ *
+ */
+public enum ParameterStatus {
+	INVALID, WARNING, WARNING_RESET, VALID;
+
+	private String details;
+
+	/**
+	 * Sets a new string containing details about the current status.
+	 * This should be displayed by the GUI, if one is in use.
+	 * 
+	 * @param details an explanation of the current status.
+	 */
+	public void setDetails(String details) {
+		this.details = details;
+	}
+
+	/**
+	 * @return the string containing details about the current status.
+	 */
+	public String getDetails() {
+		return details;
+	}
+
+}
diff --git a/src/jcgp/backend/parameters/monitors/BooleanMonitor.java b/src/jcgp/backend/parameters/monitors/BooleanMonitor.java
new file mode 100644
index 0000000..c7ccaf0
--- /dev/null
+++ b/src/jcgp/backend/parameters/monitors/BooleanMonitor.java
@@ -0,0 +1,44 @@
+package jcgp.backend.parameters.monitors;
+
+import jcgp.backend.parameters.BooleanParameter;
+
+/**
+ * This is a special type of {@code BooleanParameter} which 
+ * cannot be modified in the GUI (if the GUI is in use).
+ * 
+ * @author Eduardo Pedroni
+ *
+ */
+public class BooleanMonitor extends BooleanParameter {
+	
+	/**
+	 * Creates a new instance of this class, assuming the monitor
+	 * is not critical.
+	 * 
+	 * @param value the initial value for this monitor.
+	 * @param name the name of this monitor, for GUI display.
+	 */
+	public BooleanMonitor(boolean value, String name) {
+		super(value, name, true, false);
+	}
+	
+	/**
+	 * Creates a new instance of this class.
+	 * 
+	 * @param value the initial value for this monitor.
+	 * @param name the name of this monitor, for GUI display.
+	 * @param critical true if the monitor is critical.
+	 */
+	public BooleanMonitor(boolean value, String name, boolean critical) {
+		super(value, name, true, critical);
+	}
+
+	@Override
+	public void validate(Boolean newValue) {
+		/*
+		 *  Blank by default.
+		 *  Instances should override this as necessary.
+		 *  
+		 */
+	}
+}
diff --git a/src/jcgp/backend/parameters/monitors/DoubleMonitor.java b/src/jcgp/backend/parameters/monitors/DoubleMonitor.java
new file mode 100644
index 0000000..36b0e22
--- /dev/null
+++ b/src/jcgp/backend/parameters/monitors/DoubleMonitor.java
@@ -0,0 +1,45 @@
+package jcgp.backend.parameters.monitors;
+
+import jcgp.backend.parameters.DoubleParameter;
+
+/**
+ * This is a special type of {@code DoubleParameter} which 
+ * cannot be modified in the GUI (if the GUI is in use).
+ * 
+ * @author Eduardo Pedroni
+ *
+ */
+public class DoubleMonitor extends DoubleParameter {
+	
+	/**
+	 * Creates a new instance of this class, assuming the monitor
+	 * is not critical.
+	 * 
+	 * @param value the initial value for this monitor.
+	 * @param name the name of this monitor, for GUI display.
+	 */
+	public DoubleMonitor(double value, String name) {
+		super(value, name, true, false);
+	}
+	
+	/**
+	 * Creates a new instance of this class.
+	 * 
+	 * @param value the initial value for this monitor.
+	 * @param name the name of this monitor, for GUI display.
+	 * @param critical true if the monitor is critical.
+	 */
+	public DoubleMonitor(double value, String name, boolean critical) {
+		super(value, name, true, critical);
+	}
+
+	@Override
+	public void validate(Number newValue) {
+		/*
+		 *  Blank by default.
+		 *  Instances should override this as necessary.
+		 *  
+		 */
+	}
+
+}
diff --git a/src/jcgp/backend/parameters/monitors/IntegerMonitor.java b/src/jcgp/backend/parameters/monitors/IntegerMonitor.java
new file mode 100644
index 0000000..5c1a83e
--- /dev/null
+++ b/src/jcgp/backend/parameters/monitors/IntegerMonitor.java
@@ -0,0 +1,44 @@
+package jcgp.backend.parameters.monitors;
+
+import jcgp.backend.parameters.IntegerParameter;
+
+/**
+ * This is a special type of {@code IntegerParameter} which 
+ * cannot be modified in the GUI (if the GUI is in use).
+ * 
+ * @author Eduardo Pedroni
+ *
+ */
+public class IntegerMonitor extends IntegerParameter {
+	
+	/**
+	 * Creates a new instance of this class, assuming the monitor
+	 * is not critical.
+	 * 
+	 * @param value the initial value for this monitor.
+	 * @param name the name of this monitor, for GUI display.
+	 */
+	public IntegerMonitor(int value, String name) {
+		super(value, name, true, false);
+	}
+	
+	/**
+	 * Creates a new instance of this class.
+	 * 
+	 * @param value the initial value for this monitor.
+	 * @param name the name of this monitor, for GUI display.
+	 * @param critical true if the monitor is critical.
+	 */
+	public IntegerMonitor(int value, String name, boolean critical) {
+		super(value, name, true, critical);
+	}
+
+	@Override
+	public void validate(Number newValue) {
+		/*
+		 *  Blank by default.
+		 *  Instances should override this as necessary.
+		 *  
+		 */
+	}
+}