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.

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.

1. 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
2. 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)
3. 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)
4. 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)
5. 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
6. Remove gui.xxxRelay class and script relay package if any

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>

in the model directory

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) {}
}

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 scene
• buildInitScene() : 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 ...
	}
}

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; }

• 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)

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.

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 () {
             ...
	}
}	
 

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 are not needed anymore. If the model follow the previous recommandation, the script mode is supported by default.

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.

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.

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.

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) {}

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.

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 the buildInitScene 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.

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.

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.

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.