Package com.amalgamasimulation.desktop.ui.studies

Class StudyPart

java.lang.Object
com.amalgamasimulation.desktop.ui.studies.StudyPart
public abstract class StudyPart extends Object
Base class for study parts in desktop applications.

Each study consists of experiments. An experiment can be launched either locally or remotely.

To enable local launching, create a StudyPart child class and implement all abstract methods.

To enable remote launching, add 'desktop.studies.remote' bundle to your project dependencies and override remoteRunHelper() and checkLicenseForRemoteExecution() methods (see their javadocs for details).

  • Field Details

    • toolBar

      protected org.eclipse.swt.widgets.ToolBar toolBar

    • runRemotelyButton

      protected org.eclipse.swt.widgets.ToolItem runRemotelyButton

  • Constructor Details

    • StudyPart

      public StudyPart()

  • Method Details

    • resultBackgroundColor

      protected Accumulator<Color> resultBackgroundColor(DistributionStatistics distributionStatistics, ResultPath resultPath)

    • studies

      protected abstract List<PossibleStudy> studies(StudyStep selectedStudyStep)
      What is the full list of studies that are potentially applicable for the selected study step of the concrete simulation application?

      The applicability of every specific study will be additionally checked for the selected study step by calling PossibleStudy.isApplicable(StudyStep) method. The list of applicable studies appears when a user opens a context menu of the specific study step.

      Parameters:
      selectedStudyStep - the study step at which the user is asking the list of potentially applicable studies for
      Returns:
      list of PossibleStudy objects that describe studies potentially applicable to the given study step

    • reports

      protected abstract List<Report> reports(StudyStep selectedStudyStep)
      What reports are available for the selected study step?

      This method should return a list of Report instances that are relevant to the given StudyStep. Reports typically provide summarized or detailed views of simulation results, often presented as HTML pages, charts, or tables.

      The returned reports will be made available in the context menu of the selected study step within the study steps tree, allowing the user to open and view them.

      Parameters:
      selectedStudyStep - the study step for which available reports are being queried
      Returns:
      a list of Report instances applicable to the selected study step; return an empty list if no reports are available

    • customizeStudyStepsTree

      protected abstract void customizeStudyStepsTree(EditableTree<StudyStep> studyStepsTree)
      How to customize the study steps tree view for the specific simulation application?

      This method allows a simulation application to customize the structure and behavior of the study steps tree shown in the UI. The tree displays a hierarchy of study steps such as scenarios, modified scenarios, replications, and applied studies.

      Use this hook to add custom columns, change the presentation or editing behavior, or enhance interaction with the tree (e.g., context menus, icons, validation, etc.). It is invoked during the construction of the part and should operate on the provided EditableTree instance.

      Example customizations might include:

      • Adding new columns to display domain-specific metadata.
      • Adding context menu items specific to the simulation application's logic.
      • Changing the way tree nodes are displayed or sorted.
      Parameters:
      studyStepsTree - the editable tree component representing the study steps, provided for the simulation application to customize.

    • createLocalRun

      protected abstract Run<?> createLocalRun(org.eclipse.emf.ecore.EObject scenario, int seed)
      How to create an instance of local run for the given scenario and random number seed?

      At some point of time, a user might want to run some simulation experiment locally on the current machine. In order to do so, a new instance of Run will be created by calling this method overridden in the concrete simulation application.

      Parameters:
      scenario - the scenario for which the run must be created
      seed - the random number seed for which the run must be created
      Returns:
      A new instance of Run, most likely an instance of LocalRun

    • remoteRunHelper

      protected IRemoteRunHelper remoteRunHelper()
      Returns a helper object to enable and handle remote execution.

      Default method implementation returns DefaultRemoteRunHelper - this implementation does not support remote experiment execution.

      To enable remote experiment execution:

      1. Add 'desktop.studies.remote' bundle to the list of dependencies of your application bundle.
      2. Write the following implementation of `remoteRunHelper()` in your StudyPart child class:
      
 @Override
 protected IRemoteRunHelper remoteRunHelper() {
 	return new RemoteRunHelper<>(
            appInfo.supportsRemoteRun(), 
            appInfo.getProductID(), 
            appInfo.getClientSuffix(), 
            appInfo.getVersion(), 
            ComputerIDProvider.getComputerID(), 
            this::trySaveScenario);
 }
      Here,
      - appInfo is the application-specific instance of DesktopAppInfo;
      - trySaveScenario(EObject, String) is the method that can save application-specific scenario object to a file.

    • checkLicenseForRemoteExecution

      protected boolean checkLicenseForRemoteExecution()
      Does the current license support remote execution of simulation runs?

      This method is called after the user has pressed 'Run on server', but immediately before sending the data to the server.
      In this method, user's license for the product can be checked to have the remote execution feature. Also, a confirmation from the user may be requested, the user may be warned about the consequences of running a remote simulation, etc.

      The default implementation returns false.

      To enable remote experiment execution:

      1. Add 'desktop.studies.remote', 'licensemanager', and 'desktop.utils' bundles to the list of dependencies of your application bundle.
      2. Write the following implementation of this method in your StudyPart child class:
      
 @Override
 protected boolean checkLicenseForRemoteExecution() {
 return License.requestPermissionForRemoteStudyExecutionIfTrial(appInfo, messageManager);		
 }
      Returns:
      true if the remote calculations are allowed by the license and the used has agreed, false otherwise

    • studyStepTitle

      protected String studyStepTitle(StudyStep studyStep)
      What heading text to display for each study step?

      The text to be shown for the given study step in the first column of the part's study steps tree view. For example, it can be a scenario name or a description of scenario modification.

      Parameters:
      studyStep - study step for which to determine the step.
      Returns:
      text to be shown

    • tryLoadScenario

      protected abstract org.eclipse.emf.ecore.EObject tryLoadScenario(String filePath)
      How to load a scenario from the file path specified by a user?

      A user might want to add a scenario as one of the study steps. To do so, a user will be shown the standard operating system's dialog and, if the specified path is valid, this method will be called to actually load the scenario from the file and return the loaded scenario as the result of this method.

      If loading attempt is failed due to any reason, the null must be returned. This null will be further handled correctly by this class.

      Parameters:
      filePath - path to the file being loaded
      Returns:
      An instance of the scenario loaded from the specified file, or null of loading failed

    • trySaveScenario

      protected abstract boolean trySaveScenario(org.eclipse.emf.ecore.EObject scenario, String filePath)
      How to save the given scenario into the file at the given path?

      The study part allows users to save any loaded or modified scenario into a separate file. When a user activates this command, this method is called. It must be overridden by the concrete simulation application. The method must return true if saving ended successfully, and false otherwise.

      Parameters:
      scenario - scenario
      filePath - path to the file to which the scenario must be saved
      Returns:
      true if saving ended successfully, and false otherwise

    • getRecentlyOpenedFilesManager

      protected abstract com.amalgamasimulation.desktop.utils.RecentlyOpenedFilesManager getRecentlyOpenedFilesManager()

    • visibleTableColumns

      protected abstract List<ResultPath> visibleTableColumns()
      Which elements of the simulation Result must be shown in columns of the part's main tree view?

      Simulation Result contains elements with key indicators like "total cost", "equipment utilization", etc. These are specific to each concrete simulation application, so must be defined in the overridden method. Each element is described by its path inside the results - a ResultPath instance. This method must return a list of such paths defining the elements to be shown and their order.

      Returns:
      List of ResultPath pointing to result elements to be shown in the columns of the part's main tree view

    • showReport

      protected abstract void showReport(Report report)
      How to show the report when a users wants to open it?

      Studies provide reports that typically contain summary of the study's results in some user-friendly form, most often an HTML page. The list of reports provided by a study is defined by Study.reports() method. This method is called when a user chooses to show one of such reports.

      Parameters:
      report - report to be shown

    • showReport

      protected void showReport(StudySession.ReportType reportType, StudyStep step)
      How to show the report when a users wants to open it?

      Studies provide reports that typically contain summary of the study's results in some user-friendly form, most often an HTML page. The list of reports provided by a study is defined by Study.reports() method. This method is called when a user chooses to show one of such reports.

      Parameters:
      reportType - report type to be shown
      step - study step

    • localizedResultPathTitle

      protected String localizedResultPathTitle(ResultPath path)
      What text label to show for the given result element?

      For every result element, a text label must be shown, probably in local language. This methods allows to specify such text.

      Parameters:
      path - ResultPath pointing to the result element for which the text label is provided
      Returns:
      Text label to show for the given result element

    • replaceStudyStep

      public void replaceStudyStep(StudyStep existingStudyStep, StudyStep newStudyStep)

    • customizeToolBar

      protected void customizeToolBar(org.eclipse.swt.widgets.ToolBar toolBar)
      How to customize the toolbar for the specific simulation application?

      This method allows the simulation application to extend or modify the default toolbar shown in the study part's UI. It is called during initialization, after the standard toolbar items (such as run, stop, add scenario, etc.) have been added.

      Override this method to add application-specific commands, toggle buttons, separators, or other SWT ToolItems. You can also attach listeners, icons, and tooltips specific to your domain or simulation behavior.

      Example use cases include:

      • Adding buttons to launch domain-specific analysis tools or dialogs.
      • Adding export/import features specific to custom formats.
      • Adding toggles or filters that affect study step behavior or display.
      Parameters:
      toolBar - the ToolBar instance to which additional controls can be added.

    • customizeContextMenu

      protected void customizeContextMenu(org.eclipse.swt.widgets.Menu menu, StudyStep studyStep)

    • localizedResultPathDescription

      protected String localizedResultPathDescription(ResultPath path)

    • studySerializer

      protected abstract StudySerializer studySerializer()
      What specific instance of StudySerializer must be used to save and open studies in the concrete simulation application?

      This inherited instance of StudySerializer must know how to serialize studies and modifications specific to the concrete simulation application. If this method returns null, then the default study serializer will be used.

      Returns:
      Instance of StudySerializer specific to the concrete simulation application

    • createStudySession

      protected abstract StudySession createStudySession(Study study)
      How to create a study session from a Study object?

    • createStudySession

      protected abstract StudySession createStudySession(String studyName)
      How to create a study session using the name of the root study?

    • updateTree

      protected void updateTree()

    • studySession

      public StudySession studySession()

    • rootStudy

      public Study rootStudy()

    • setStudyFilePath

      public void setStudyFilePath(String studyFilePath)

    • savePersist

      @Persist public void savePersist()

    • newStudyName

      public static String newStudyName(org.eclipse.e4.ui.workbench.modeling.EPartService partService)