Table of Contents
Model Architecture
This page presents the main classes a model should implement.
Note: If you have models written with the old design, you may go directly to the last section to adapt them to the new architecture. You may also see the Fast Checklist.
New Architecture Fast CheckList (for developpers)
All files renames, moves, addition and removals must be done with SVN. xxx is the module prefix (e.g. 'Mount' for mountain).
Refactoring (rename / move classes, rename methods…) in Eclipse with an SVN plugin installed is the preferred way to process this check list.
- Initial parameters
- rename xxxSettings into xxxInitialParameters
- xxxInitialParameters extends AbstractSettings implements InitialParameters
- add @Override public void buildInitScene (GModel m) throws Exception { → build the initScene
- add @Override public GScene getInitScene () { → return the initScene
- Initial dialog
- rename the initial dialog class into xxxInitialDialog
- xxxInitialDialog extends InitialDialog (DOES NOT implement InitialParameters)
- constructor public xxxInitialDialog (GModel m) {
- remove refs to the relay, remove buildInitScene () and getInitScene ()
- okAction () → after having checked the parameters:
- xxxInitialParameters p = model.getSettings ()
- set all parameters in p
- p.buildInitScene (model)
- setInitialParameters (p)
- Evolution parameters
- create xxxEvolutionParameters → in the model package
- xxxEvolutionParameters implements EvolutionParameters
- it contains the context for the evolution (including at least the target criterium, e.g. 10 years)
- Evolution dialog
- rename the evolution dialog class into xxxEvolutionDialog
- xxxEvolutionDialog extends EvolutionDialog (DOES NOT implement EvolutionParameters)
- constructor public xxxEvolutionDialog (Step s) {
- remove refs to the relay
- okAction () → after having checked the parameters:
- xxxEvolutionParameters p = new xxxEvolutionParameters ()
- set all parameters in p
- setEvolutionParameters (p)
- Model class
- in constructor: setSettings (new xxxInitialParameters ());
- @Override public Step initializeModel (InitialParameters p) throws Exception { → adapt here code from xxxRelay, return last Step
- @Override public Step processEvolution (Step step, EvolutionParameters p) { → adapt here code from xxxRelay, return last Step
- adapt @Override processPostIntervention (GScene newScene, GScene prevScene) if needed
- Remove gui.xxxRelay class and script relay package if any
Capsis new model architecture
Since november 2009, Capsis supports a new model architecture. This new architecture intends to :
- Reduce the number of necessary classes.
- Simplify the implementation of the model
- Support automatic graphical user interface
- Support automation to replay a scenario and do some variation on the parameters
The main differences with the previous architecture are:
- Relay classes are optional : there is a default implementation
- Settings and initial parameters are merged into a single class
- Script mode is supported by default
- Parameter classes and gui classes are separated
<note> To see an example, open the template model </note>
Model classes
in the model directory
TplModel.java
This is the main model class. It contains the model entry points.
- Initilization method
- Evolution method
- Post intervention method
- The constructor intantiate the settings object.
- The model class do not open directly the GUI. This is done in by the GUI classes (see below).
public class TplModel extends GModel { /** Constructor with no parameters */ public TplModel () throws Exception { super (); // Create settings (initial parameters) setSettings(new TplInitialParameters()); } /** Model initialisation. */ @Override public void initializeModel (InitialParameters p) { GScene initStand = p.getInitScene (); // do other initialization } /** Evolution function */ @Override public Step processEvolution (Step stp, EvolutionParameters p) throws Exception { Step newStp = null; // to be returned at the end int age = ((TplEvolutionParameters) p).getAge (); // do evolution return newStp; } /** Post intervention processing */ @Override public void processPostIntervention (GScene newStand, GScene oldStand) {} }
TplInitialParameters.java
The initial parameter class contains all the data needed to start the model.
The InitialParameters class should be able to build the initial scene. It provides 2 methods :
getInitScene()
: return the build initial scenebuildInitScene()
: load or build the initial scene
The buildInitScene()
method should be used directly in the initial dialog to ensure that the scene can be correctly build before closing the dialog. In the other cases, Capsis call this method directly (in AutoDialog or C4Script).
public class TplInitialParameters extends AbstractSettings implements InitialParameters { public Double param = 2.2; public int param2; public String filename; public enum MyEnum { VAL1, VAL2, VAL3; } public MyEnum e; ... @Ignore transient private TplStand initStand; public TplInitialParameters () {}; public TplInitialParameters (String fileName) { filename = fileName; } @Override public GScene getInitScene () { return initStand; } /** Load initial scene */ @Override public void buildInitScene(GModel model) throws Exception { // ensure model has correct settings model.setSettings (this); // load scene from the file ... } }
TplEvolutionParameters.java
The evolution parameters class. It contains the data needed to do an evolution.
public class TplEvolutionParameters implements EvolutionParameters { private int age; public TplEvolutionParameters (int age) { this.age = age; // Set some other parameters here... } public int getAge () { return age; }
Other classes
- TplStand.java : contains the stand data and the associated method
- TplTree.java : if the model uses individual trees
- … : all the classes you need to implement your model
Note : use one concept and only one by class (cohesion, low coupling)
Gui classes
in the gui directory
Gui classes provides the Graphical interfaces for the initial dialog and the evolution dialog.
They can be generated automatically : see Auto UI. In this case, you DON'T need to implement the GUI classes.
If automatic UI do not fit to the need, specific dialogs can be implemented. The name of the class is predefined by convention.
TplInitialDialog.java
The initialisation dialog.
In the template
example, the initial dialog is automatically generated. So we don't need to implement this class.
If you need to implement it, the class should inherit from InitialDialog
.
public class TplInitialDialog extends InitialDialog { private GModel model; private JTextField fldFileName; private JButton browse; private JButton ok; private JButton cancel; public TplInitialDialog (GModel mod) { super (); model = mod; createUI (); show (); } ... /** ok button */ private void okAction () { // classic checks... filename = fldFileName.getText (); try { // Get existing settings InitialParameters ip = (InitialParameters) mod.getSettings(); // !! IMPORTANT : dialog result setInitialParameters(ip); // Set values ((TplInitialParameters) ip).filename = filename; // build scene ip.buildInitScene(mod); } catch (Exception exc) { Log.println (Log.ERROR, "Error", exc.toString (), exc); // show a message box ... return; } setValidDialog (true); } public void actionPerformed (ActionEvent evt) { if (evt.getSource ().equals (ok)) { okAction (); } else if (evt.getSource ().equals (cancel)) { setValidDialog (false); } } /** Inits the GUI */ private void createUI () { ... } }
TplEvolutionDialog.java
The evolution dialog.
public class TplEvolutionDialog extends EvolutionDialog { private int age; private JTextField zonAge; private JButton ok; private JButton cancel; /** Constructor with Step */ public TplEvolutionDialog (Step fromStep) { super (); createUI (); setVisible (true); } /** ok */ private void okAction () { // do some checks... // !!IMPORTANT!! set dialog result setEvolutionParameters( new TplEvolutionParameters(age) ); // close dialog setValidDialog (true); } /** Listener */ public void actionPerformed (ActionEvent evt) { if (evt.getSource ().equals (ok)) { okAction (); } else if (evt.getSource ().equals (cancel)) { setValidDialog (false); } } /** Initialize the GUI. */ private void createUI () { // Create the GUI... }
Script classes
Script classes are not needed anymore. If the model follow the previous recommandation, the script mode is supported by default.
Convert an old architecture module to the new architecture
If you need to convert your existing module into the new architecture in order to use for instance the automation framework, please read the following documentation.
In the following, replace X by the model prefix.
Rename XSettings.java to XInitialParameters.java
in the model directory
The initial parameters class should contains all the data necessary to do the initialisation.
The XInitialParameters class should implement the interface InitialParameters
and the associated functions
//... Other parameters @Ignore private TplStand initStand; // constructor @Override public void buildInitScene(GModel mod) throws Exception { // ensure model has correct parameters mod.setSettings (this); // load initStand = (TplStand) ((TplModel) mod).loadInitStand (standInventory); } @Override public GScene getInitScene() { // ... return initStand; }
See Model classes
You should rename (or move) the file with smartSVN or with your SVN client.
Create XEvolutionParameters.java
in the model directory
The class should implement the interface : EvolutionParameters
The evolution parameters class should contains all the data necessary to do the evolution.
See Model classes
Don't forget to add the java file to SVN with smartSVN or with your SVN client.
Add entry point functions in XModel.java
In the new architecture, The relay class has been removed. The model entry points are in the class XModel.java.
Add the following functions and fill them with the corresponding code found in the XRelay.java file.
/** Model initialisation. */ @Override public void initializeModel (InitialParameters p) { GScene initStand = p.getInitScene (); // ... do initialisation } /** process Evolution */ @Override public Step processEvolution (Step stp, EvolutionParameters p) throws Exception { Step newStp = null; // to be returned at the end // do evolution ... return newStp; } /** Post intervention processing */ @Override public void processPostIntervention (GScene newStand, GScene oldStand) {}
Adapt Model constructor
in the model directory
The constructor of the XModel should be adapted : instantiate a XInitialParameters instead of a XSettings class
/** Constructor */ public TplModel () throws Exception { super (); //... setSettings(new TplInitialParameters()); }
Note : the model class should use the GModel settings
field and not its own field.
Rename XDInitStand.java to XInitialDialog.java
in the gui directory
- The new class should inherits from
InitialDialog
- It does NOT implements the
InitialParameters
interface - The constructor should take one parameter : the model
public MaddInitialDialog (GModel model) { super (); mod = model; //... }
- Remove the reference to the Relay
- Remove unused field
- Remove the
getInitScene
and thebuildInitScene
methods. - In the ok handler :
- Check the parameters
- Get the
InitialParameters
(settings) object from the model : model.getSettings() - Set the value of the parameters in this settings object
- call the
buildInitScene
function - Set the return value of the dialog with
setInitialParameters( ip );
You should rename (or move) the file with smartSVN or with your SVN client.
Rename XDGrowthParameters.java to XEvolutionDialog.java
in the gui directory
- The new class should inherits from
EvolutionDialog
- It does NOT implements the
EvolutionParameters
interface - The constructor should take a single parameter
Step stp
public TplEvolutionDialog (Step stp) { super (); stand = (TplStand) stp.getScene(); // only if needed createUI (); pack (); show (); }
- Remove the reference to the Relay
- In the ok handler :
- Check the parameters
- Create a new
XEvolutionParameters
object with the correct values - Set the return value of the dialog with
setEvolutionParameters( ep );
You should rename (or move) the file with smartSVN or with your SVN client.
Remove XRelay.java
in the gui directory
The relay is not used anymore. It is replaced by functions in the Model class. If your model does some computation in the relay class, you should move them in the model class.
Remove the file gui/XRelay.java with SmartSVN or with your own SVN client.
Remove script directory
The script directory is not necessary since it is integrated in the model class. If the script classes do some particular computation, you should move them in the model
class.
Remove the directory with SmartSVN or with your own SVN client.