Commands
Last updated
Last updated
In this part of the documentation we will present the Command
classes that are used to changed the values of the domain objects and its usages.
When changing the values of domain objects in OSPSuite, instead of writing the values directly we are using Commands that change these objects. We do this for a few reasons. Firstly because we want to use the Commands to keep a history of changes that has happened to our data. This history also serves a regulatory purpose.
Additionally those commands give us the possibility to reverse the actions that have happened. The user can do this by selecting the command from the history and clicking undo.
When you want to create a new action that changes the data, you will need to write a new command.
The execution of a command is defined in the ExecuteWith(...) function override:
Note: If the command is defined in PK-Sim or MoBi, the context would be the context interface more specific to the project, e.g. in PK-Sim
In the body of this override we define the execution steps of the command. The context serves two purposes:
In order to be able to reverse the execution of a command we need inverse commands. Which command we use for this is specified in the GetInverseCommand(IOSPSuiteExecutionContext context)
function override part of a command. There are cases when we do not really need a new command to reverse the actions, e.g. when we have changed a value, we simply need to use the same command with different parameters to reset the values. We can find an example for that in the ChangeObservedDataMetaDataCommand. Usually though a separate new command will have to be written to reverse the actions of the original command. For example if we have added observed data to the project, in reversing the command we need to remove exactly that observed data. AddObservedDataToProjectCommand has RemoveObservedDataFromProjectCommand as its inverse - and vice versa of course.
The ICommand interface defines further properties, like the Description and ObjectType (type of object on which the command has been executed) that will also end up in the history view.
Macro Commands are a collection of separate commands. They keep the list of subcommands to which commands can be added, and the execution of a MacroCommand is the execution of each subcommand individually. Hence they do not have additional data of their own (ObjectType, Comment etc.). Clearing, restoring the execution data or getting the inverse of macro commands is the simply performing the corresponding action for each one of the subcommands.
EmptyCommand is an implementation of the Null Object Pattern. We are using it as a return object in the cases when we do not want something to happen, instead of returning null and having then to check for null all the time down the execution path.
In the OSPSuite there also exist the interface IUICommand that is NOT the same as ICommand. The UICommands actually refer to specific UI actions (buttons, context menus etc) and either get executed directly or using tasks and without being reversible or being written in history. Otherwise they also need to invoke a separate command that takes care of executing the actions on the data.