Eclipse ESCET™ documentation (Incubation)

To download and install a new version of Eclipse ESCET tools (including the command line scripts) side-by-side an older version, follow these steps:

Using these instructions, it is possible to use multiple installations side by side, at the same time, regardless of whether the installations are the same release or different releases. Simply extract them to different directories and launch them as you would normally do.

To perform an in-place update of the Eclipse ESCET tools:

Eclipse stores all its settings in a so-called workspace. The workspace is simply a directory on your computer. You can choose any directory you like to serve as a workspace, as long as you have write access to that directory. It is usually best to choose an empty directory or a directory that does not yet exist as your workspace.

Typically, and by default, a directory named workspace inside your Eclipse ESCET installation directory is used. Eclipse will ask you to choose a workspace directory when you start the Eclipse ESCET IDE for the first time.

The actual settings are stored in a sub-directory of the workspace directory, called .metadata. You should avoid manually manipulating this directory. Note that because the name of the directory starts with a dot (.), depending on your operating system, file browser, and settings, the directory may be hidden.

You can easily change your workspace directory from within Eclipse, by selecting File  Switch workspace. Select one of the workspaces from the list of last used workspaces, or select Other…​ to freely select any directory on your system to use as a workspace directory.

It is possible to run multiple instances of Eclipse at the same time, but each instance must use its own workspace.

The workspace is also the default directory for new projects. However, projects don’t have to be physically located inside your workspace directory. They can be stored in any directory on your system. Whenever you create a project and store it outside of your workspace, or whenever you import an existing project from outside your workspace, it is linked to the workspace, but remains physically stored in a directory outside of the workspace.

Having projects stored outside of the workspace has some benefits. The most important benefit is that you can remove the workspace directory, without losing your files.

Eclipse is an Integrated Development Environment (IDE) with a lot of functionality. Most of the functionality is available through views. A view is a part of the Eclipse graphical user interface. Views can be thought of as 'sub-windows'. When you start Eclipse you are likely to see the Project Explorer or Package Explorer view on the left, and the Problems view at the bottom.

Eclipse, being an Integrated Development Environment (IDE), does not only allow you to edit a single file, and simulate it, but also allows you to manage your files.

Eclipse works with so-called projects. A project is a collection of files and directories. A project may be located anywhere on your system, even though by default project are created in your workspace directory.

A project is essentially a directory on your computer, with a special file named .project. This special file stores the information about your project, such as the name of the project. It is recommended to keep the name of the project as Eclipse sees it, the same as the name of the directory in which the project is stored on your hard disk.

You can see the projects that Eclipse knows about in the Project Explorer or Package Explorer <use-terminology-view,view>>.

For more information on projects, see the Working with projects, directories, and files section.

To create a new project, ensure you have either the Project Explorer or Package Explorer view visible.

Select File  New  Project…​ to open the New Project window. Alternatively, right click somewhere in the Project Explorer or Package Explorer view, and select New  Project…​, to open the same window.

In the New Project window, from the General category select Project, and click the Next > button.

In the next window, enter a project name, for example models.

By default, a project is created inside your workspace directory. If you want it at a different place (so you can remove the workspace without losing your projects), uncheck the Use default location option, and enter a Location. Make sure the location does not yet exist, for example by ending with the project name. It is recommended to always create a project in a directory that has the same name as the project.

Click the Finish button to create the project. Observe how it appears in the Project Explorer or Package Explorer view.

If you previously created a project, but it is no longer visible in your Project Explorer or Package Explorer view, you can import it. Imported projects are linked to your workspace, but remain in their original location on your hard disk (by default, they are not moved or copied to your workspace directory).

Importing existing projects is particularly useful if you removed you workspace directory and started with a fresh one, e.g. for a new installation.

To import one or more existing projects, select File  Import…​ to open the Import window. Alternatively, right click somewhere in the Project Explorer or Package Explorer view, and select Import…​ to open the same window.

In the Import window, from the General category, select Existing Projects into Workspace, and click Next >.

In the next window, in Select root directory, point it to the directory that contains the project you wish to import. The available projects in the given root directory, and all its sub-directories (recursively), are listed in the Projects list. Select the project(s) you want to import, by checking the relevant check boxes, and click Finish. Observe how the project(s) appear(s) in the Project Explorer or Package Explorer view.

To remove a project from Eclipse, ensure you have either the Project Explorer or Package Explorer view visible.

Right click the project in the Project Explorer or Package Explorer view and choose Delete. Alternatively, select it and press the Delete key on your keyboard. The Delete Resources dialog appears. To only remove the project from Eclipse, and keep the files on your hard disk, disable the Delete project contents on disk (cannot be undone) option and click the OK button. Alternatively, to remove the project from Eclipse and also remove all the files in the project from your hard disk, enable the Delete project contents on disk (cannot be undone) option and click the OK button.

Wait for Eclipse to complete the removal operation.

You can structure large collections of files, by putting them into different directories (also called folders). Directories can only be created in projects, or in other directories.

Select the project or directory in which you want to create a new directory (by left clicking its name in the Project Explorer or Package Explorer view, and create a new directory by selecting File  New  Folder. Alternatively, right click on the project or directory instead, and from the popup menu select New  Folder.

In the New Folder window, enter the Folder name, and click Finish.

Select the project or directory in which you want to create a new file (by left clicking its name in the Project Explorer or Package Explorer view), and create a new file by selecting File  New  File. Alternatively, right click on the project or directory instead, and from the popup menu select New  File.

In the New File window, enter the File name, and click Finish. Make sure to give the file the correct file extension. E.g. CIF files should end with .cif.

An editor for the new file opens, and you can start editing it.

To rename a file, directory, or project, select it by left clicking its name in the Project Explorer or Package Explorer view, and then select File  Rename…​. Alternatively, right click on the file, directory, or project instead, and from the popup menu select Refactor  Rename…​. A second alternative is to select the file, directory, or project, and then press the F2 key.

In the Rename Resource window, enter the New name, and click OK.

Often, it is convenient to be able to manage files not from inside Eclipse, but from outside Eclipse, for instance in a file explorer provided by your operating system. The Properties view can be used to find out where the files, directories, and projects that are in Eclipse, are located on your hard disk. With the Properties view visible, select a file, directory, or project in the Project Explorer or Package Explorer view. In the Property column of the Properties view, look for location. The corresponding Value indicates where the file, directory, or project is located on your hard disk. Note that you can right click the location and choose Copy to copy the location to the clipboard.

As an alternative to the Properties view, you can also use the Properties window. Right click a file, directory, or project in the Project Explorer or Package Explorer view and choose Properties. In the window that shows, select Resource on the left, if it is not already selected. Then, on the right, look for the Location.

To directly open the directory that contains a file, directory, or project in your system’s file explorer, right click the file, directory, or project in the Project Explorer or Package Explorer view and choose Show In  System Explorer.

Don’t forget to refresh your projects in Eclipse after manipulating them outside Eclipse.

Whenever changes are made to files or directories from outside Eclipse, and those files or directories are also in one of the projects inside Eclipse, the changes are not always automatically reflected in the Project Explorer or Package Explorer view. To ensure that the current state of the files and directories are properly reflected in Eclipse, a refresh is required. To refresh a file, directory, or project, right click it, and choose Refresh. Any files and directories that no longer exist will disappear from Eclipse. Any new files and directories created outside Eclipse will appear in Eclipse as well.

When working with files, you may occasionally encounter large files. Opening large files in Eclipse can cause serious performance problems. You can use the Properties view to check the size of a file. With the Properties view visible, select a file in the Project Explorer or Package Explorer view. In the Property column of the Properties view, look for size. The corresponding Value indicates the size of the file.

As an alternative to the Properties view, you can also use the Properties window. Right click a file in the Project Explorer or Package Explorer view and choose Properties. In the window that shows, select Resource on the left, if it is not already selected. Then, on the right, look for the Size.

To edit a file, double click it in the Project explorer or Package explorer view.

Whenever you open a text file, change it, or the editor receives the focus, the file is checked for errors. If there are errors (or warnings), they are displayed in the editor as shown below.

Note that you can hover over an error in the source code itself to find out what the problem is. Alternatively, you can hover over the error marker in the margin of the editor, or look at the Problems view. Also, if a file has an error or a warning, an overlay icon is shown in the Project Explorer and Package Explorer views, for that file, the directories that contain it, and the project that contains it.

If you have a file without errors, you can execute certain commands on it. The various Eclipse ESCET tools add commands to Eclipse. For instance, CIF models can be simulated using a simulation command.

To execute a command on a file, right click the file in the Project Explorer or Package Explorer view, and select the command. Alternatively, if you have the file open in an editor, right click the editor, and select the command.

The commands that are available are determined by the file extension of the file. That is, only the commands applicable for a certain file are shown.

Besides simulation, other commands may be available, depending on the modeling language and tools you use. Consult the specific documentation for each tool for more details.

The Applications view can be opened by selecting Window  Show view  Applications, assuming the ESCET perspective is enabled.

The view shows a list of running applications. If an application starts another application, it is shown as a child, forming a tree structure. Each item of the tree shows a single application. In the example screenshot above, there are four running applications. The first application is a ToolDef interpreter, which is running a second application, a CIF simulator. The third application is also a ToolDef interpreter, which is running a fourth application, also a CIF simulator.

To the left of each item, the status of the application is indicated. The following statuses are available:

When an application is started, it get a Starting state. Once the options have been processed from the command line and the option dialog (if requested), the actual application code is executed, and the status changes to Running. If the application is not terminated at the request of the user, the application will be done with its execution after some time. If execution finished without problems, it then reaches status Finished. If execution failed for some reason, it reaches status Failed instead. If the execution crashed due to internal problems, the application reaches status Crashed. If however the user terminates the application, the status is first changed to Terminating. Once the application has successfully been terminated, the status changes to Terminated.

You can also view these statuses and their corresponding icons from within the IDE, by opening the Application Status Legend dialog, which is available via the view’s drop-down button popup menu:

The Applications view supports terminating running applications. There are several ways to terminate an application using the Applications view.

When terminating an application (with a Starting or Running state), the application will get a Terminating state. Applications occasionally poll for termination requests. Therefore, it may take a while for the application to actually process the termination request. Once it has been processed, the application will have terminated, and the status changes to Terminated as well.

Applications can’t process a termination request while a modal dialog (such as the option dialog) is open, or when input is requested from the console. They will terminate as soon as possible, after the dialog is closed, or the user has provided input via the console.

The following buttons related to termination are available in the Applications view’s toolbar:

The Applications view can get a bit crowded, if already terminated applications are not removed from the list. To keep only relevant applications, the Applications view supports removing items from the list.

Only applications which have finished execution can be removed. That is, the root of the tree of applications needs to have a Terminated, Finished, Failed, or Crashed status, for the tree to be allowed to be removed. This prevents removing applications that are still running, which would make it impossible to terminate them, or observe their status.

The following buttons related to removal are available in the Applications view’s toolbar:

When one application starts another application, they are listed in a tree, with the parent containing the child. When running a single application, it may be of interest to see which child applications are being executed by the parent application. However, when executing multiple applications, this may quickly crowd the view. It may then be better to keep all root items collapsed, only showing the status of the root applications. This provides an overview over those multiple applications.

The following buttons related to expansion are available in the Applications view’s toolbar:

The Applications view can also be used observe the status of running applications, and to terminate them.

The Eclipse Console view maintains the console output for all running and finished applications. To look at the applications that you executed, click the small arrow next to the Display Selected Console icon () of the Console view’s toolbar. A list of executed applications will appear, that looks something like this:

In this case, of the four applications that have been started, the second and fourth are still running. The console for the fourth application is currently displayed, as indicated by the selection indicator on the left. Clicking on any of the other applications will activate the console for that application, allowing it to be terminated, thus freeing resources for other applications.

The application that is currently active in the console can be terminated at any time, by using the Terminate button (), located at the upper right corner of the console. Note however that if the console does not have the focus, this button may not be visible. If the button is not visible, click somewhere in the console to make the button appear. If even then the button is still not available, it may still appear if you Maximize the console. Also note that the button has no effect while the application interactively asks for input from the console. However, once the console input is provided, and ENTER is pressed, the termination request will be processed.

This section explains a 'quick and dirty' solution that gives Eclipse more memory, resolving the most common performance problems and out-of-memory errors.

Find the eclipse.ini file. By default, it is located in your Eclipse ESCET installation directory, except for macOS, where instead it is in the Eclipse.app/Contents/MacOS directory inside the Eclipse ESCET installation directory. Modify the last line (usually -Xmx4g). Replace it by the following to change the maximum available memory from 4 GiB to 8 GiB:

Restart the Eclipse ESCET IDE or command line script to apply the new settings. If the instructions given here don’t fix your problem, or if the IDE or script will no longer start after you changed these settings, you should read the remainder of this page.

Before going into the actual settings, this section provides a little background on managed memory and garbage collection, to make it easier to understand the following sections. The information here is highly simplified, in order not to complicate matters too much.

The Eclipse ESCET IDE and command line scripts run on Java, a computer programming language. The Java Virtual Machine (JVM) manages all memory used by Eclipse, as well as the Eclipse ESCET tools. This page focuses on the Oracle JVM, as that is the JVM that we recommend. JVMs from other vendors may behave differently, and may have different settings. Also, new versions of the JVM often change/tweak their garbage collector, settings, defaults, etc. As such, the information on this page should be used to guide you, but may not be completely accurate.

The JVM keeps track of all data that is maintained by the Eclipse ESCET tools, and releases (frees) the memory once it is no longer needed, so that it can be used to store other data. The JVM frees memory by means of a process called garbage collection (GC). Garbage collection is a complex process, but generally it consists of locking the memory to avoid modification during garbage collection, finding the data that is no longer used (mark the garbage), and then freeing the memory associated with that data (sweep the marked garbage).

In order to understand the memory related settings, some understanding of Java’s memory architecture is essential. The following figure provides an overview of Java’s memory architecture, and the different types of memory that are used:

The operating system (OS) has memory available, either as physical RAM, or as virtual memory. When Java is executed, the Java program (java executable on Linux and macOS, java.exe on Windows), becomes one of the running processes. The process uses a part of the operating system’s memory to store its data. This memory is called the Java process heap. The Java process heap is divided into two parts, the Java object heap and 'Everything else'. The Java object heap contains all data actually used by the running Java program, which in our case is the Eclipse ESCET IDE and/or Eclipse ESCET command line scripts. The 'Everything else' part contains various data, mostly used by the JVM internally.

Java uses a generational garbage collector. New data, called objects in Java, are created in the young generation, or more specifically, in its allocation space (also called eden space). When the young generation becomes full, the garbage collector will remove all garbage (no longer used data) using a minor collection, which removes garbage from the young generation. The garbage collector uses the survivor spaces to store the surviving objects. Objects that survive a few minor collections are moved to the old generation, which stores the longer living objects, as well as the larger objects that don’t fit in the young generation, which is usually much smaller than the old generation. When the old generation becomes full, the garbage collector performs a major collection removing garbage from the entire Java object heap, which is much more work, and thus much more costly than a minor collection.

The 'Everything else' part of the Java process heap contains various data used internally by the JVM. This includes the 'Metaspace' with all the Java code of Eclipse and our own plugins, the values of constants, etc. It also includes the native code, the highly optimized code generated for the specific architecture of your machine, that can actually be executed on your processor. Furthermore, it includes the stacks of all the threads that are running in parallel. There is also a part that contains the data maintained by the garbage collector itself, for administrative purposes. The 'Everything else' part contains various other types of data, that are irrelevant for the current discussion.

If Java runs out of available memory, our applications running in Eclipse will terminate with an 'out of memory' error message. In such cases, increasing the available memory will likely solve the problem. However, even if you don’t run out of memory, increasing the amount of memory that is available to Java can significantly improve Java’s performance.

The garbage collector performs a minor collection when the young generation becomes 'full'. Here, 'full' doesn’t necessarily mean 100%, as Java by default tries to keep the heap about 40% to 70% filled. Increasing the size of the young generation makes it possible to allocate more new objects before the young generation becomes 'full'. During garbage collection, program execution may become halted, to ensure that memory doesn’t change during the collection process. The longer one can go without garbage collection, the less halting, and thus the greater the performance of the program.

If an application uses a lot of data that lives for longer periods of time, the old generation may become mostly filled with data. It then becomes harder and harder for the garbage collector to move objects from the young generation to the old generation. This may be caused by fragmentation, due to some objects from the old generation being removed by the garbage collector. In such cases, if the gaps are too small to hold the new objects, the old generation may need to be compacted, a form of defragmentation. After compaction, the single larger gap hopefully has more than enough free space to contain the new objects. The compaction process is expensive, as a lot of objects need to moved. If the situation gets really bad, Java may need to spend more time performing expensive garbage collection operations than it spends time on actually executing the program you’re running. By increasing the size of the old generation to more than the application needs, a lot more free space is available, reducing the need for frequent compaction, thus significantly increasing the performance of the application.

These are just some of the reasons why increasing the amount of available memory can improve program execution times, even though enough memory was already available to complete the given task. In general, the more memory Java has, the better it performs.

The JVM has way too many options to list here, but the settings listed in this section are of particular practical relevance. Most of the settings affect memory sizes. Each setting is described using a name, a command line syntax (between parentheses), and a description. The command line syntax is used to specify the setting, as explained in the Changing memory settings section.

The <size> part of the command line syntax is to be replaced by an actual size, in bytes. The size can be postfixed with a k or K for kibibytes, an m or M for mebibytes, or a g or G for gibibytes. For instance, 32k is 32 kibibytes, which is equal to 32768, which is 32,768 bytes.

The <n> part of the command line syntax is to be replaced by an integer number. The values that are allowed are option specific.

The + part of the command line syntax indicates that the corresponding feature is to be enabled. Replace the + by a - to disable the feature instead of enabling it.

There are several ways to supply the command line arguments for the settings to Java. The easiest way to do it, when using Eclipse, is to modify the eclipse.ini file. By default, it is located in your Eclipse ESCET installation directory, except for macOS, where instead it is in the Eclipse.app/Contents/MacOS directory inside the Eclipse ESCET installation directory.

Each of the settings you want to change should be added to the eclipse.ini text file, in the command line syntax. Each setting must be put on a line by itself. Furthermore, all these JVM settings must be put after the line that contains -vmargs. Settings on lines before the -vmargs line are the settings for the launcher that starts Eclipse, and should not be changed.

Note that the default eclipse.ini file supplied with Eclipse may already contain some of the settings. If so, don’t add the setting again. Instead, change the value of the existing setting. The settings that are present by default, as well as their values, may change from release to release.

After modifying eclipse.ini, restart the Eclipse ESCET IDE or command line script for the changes to take effect.

In general, giving Java extra memory only makes it perform better. As such, increasing the maximum Java object heap size (-Xmx), is generally a good idea, if you have enough free memory.

If you actually run out of memory, Java will emit a java.lang.OutOfMemoryError, with a message to indicate the type of memory that was insufficient. Below the most common out of memory error message are listed, with possible solutions:

Giving the JVM too much memory (especially via the -Xmx setting), can make the JVM fail to start, or crash shortly after starting. This problem mostly applies to 32-bit JVMs. The JVM needs to reserve a contiguous region of memory, or rather a contiguous region of the address space. On 32-bit JVMs, at most 4 GB of space can be addressed, of which a part is already in use by the operating system, drivers, and other applications. Thus, requesting too much memory, even if it is available, may cause problems, if no contiguous region of address space of that size is available when starting the JVM. If you request too much memory, you may get a Invalid maximum heap size: -Xmx****m The specified size exceeds the maximum representable size. Could not create the Java virtual machine. or Error occurred during initialization of VM Could not reserve enough space for object heap error when starting the JVM. For 64-bit JVMs, the address space is practically infinite, and this should not be a problem.

In Eclipse, it is possible to observe the amount of Java object heap space that is being used. In Eclipse, open the Preferences dialog, via Window  Preferences. Select the General category on the left, if not already selected. On the right, make sure the Show heap status option is checked, and click OK to close the dialog.

The heap status should now be displayed in the bottom right corner of the Eclipse window:

This example shows that the Java object heap (not the Java process heap) is currently 147 MB in size. Of that 147 MB, 62 MB are in use. The entire graph (the gray background) indicates the total heap size (147 MB), while the yellow part indicates the used part of the heap (62 MB).

Clicking on the garbage can icon, to the right of the heap status, will trigger a major collection cycle of the garbage collector.

By right clicking on the heap status, and enabling the Show Max Heap option, the heap status shows more information:

The text still shows the amount of used heap memory (74 MB) out of the total size of the current heap (147 MB). The scale of the background colors however, is different. The entire graph (the gray background) now indicates the maximum heap size. The orange part indicates the current heap size. The yellow part still indicates the part of the heap that is in use. If the used part of the memory gets past the red bar, it will become red as well, to indicate that you are approaching the maximum allowed Java object heap size, and may need to increase it (-Xmx setting).

Hover over the heap status to get the same information in a tooltip.

The Java Development Kit (JDK) includes a program called JVisualVM. JVisualVM can be used to monitoring, troubleshoot, and profile running Java applications.

To start JVisualVM:

If your JDK does not contain JVisualVM, you can download it from the VisualVM website.

After you start JVisualVM for the first time, you’ll see some dialogs. Just go through the steps until you get to the actual application.

In JVisualVM, you’ll see the currently running Java applications, for the local system:

Sometimes JVisualVM can identify the Java applications, sometimes it can’t. This may also depend on you operating system, and the version of JVisualVM. Find the application you want to know more about and double click it. A new tab opens on the right. The new tab has various tabs of its own:

The Monitor tab can be used to determine which type of memory should be increased. The Sampler tab can be used to profile an application, and figure out where bottlenecks are. This information can be used by the developers of the application to improve the performance of the application, by removing those bottlenecks.

Via Tools  Plugins you can access the Plugins window, where you manage the plugins. Various plugins are available. The Visual GC plugin is of particular interest. After installing it, restart JVisualVM, or close the tabs of the JVMs you’re monitoring and open them again. You’ll get an extra tab for monitored JVMs, the Visual GC tab. This tab is somewhat similar to the Monitor tab, but shows more detailed information about the garbage collector, its various generations, etc.

It is often a good idea to first discuss new ideas and features with the rest of the project developers, i.e. the project committers and the project community. Discussions can take place on the project’s 'dev' list, especially for radical new ideas and new features that have not been discussed before.

If the project committers and the community agree that it is a good idea to have the new feature, an issue should be created in the issue tracker. For improvements where extensive discussion is not expected, as well as for obvious bugs, an issue can be created directly, without first discussing it on the 'dev' list. The discussion can also continue in the issue itself, once the issue is created.

When creating an issue, take the following into account:

For every software version a GitLab milestone is created, to track its scope and progress. First the scope is discussed and agreed upon. Then, a GitLab milestone is created, the relevant issues are created if not yet present, and the issues are associated with the milestone. The issues can then be picked up to be addressed.

A single GitLab milestone is used per software version. Each software version has one or more milestone releases, followed by one or more release candidates, and is completed by a final release.

See also:

The process to work on issues is as follows:

The Eclipse ESCET project roughly follows the GitFlow branching model. The master branch is thus for released content only, and the current development status is captured in the develop branch.

If possible, we approach the somewhat heavy GitFlow branching model in a practical way, reducing overhead.

When creating and working with branches, consider the following:

As is standard for Git commits, the first line of the commit message must be a short summary, and must not exceed 72 characters.

For the Eclipse ESCET project, this line must start with the issue number, to allow GitLab to link commits to issues. For instance: #1 commit summary. In case a commit relates to multiple issues, list each of them, e.g. #1 #2 commit summary. Merge commits are exempt from this rule.

Furthermore, all commits must adhere to the requirements as defined by the Eclipse Foundation:

If you are not an Eclipse ESCET project committer, with write access to our Git repository, see the information on contributing to the Eclipse ESCET project. Don’t forget to sign-off your Git commits.

Once the work on an issue is done and pushed to a branch, it must be reviewed before it is merged back. Reviews are done via merge requests. The process is as follows:

If you are not an Eclipse ESCET project committer, with write access to our Git repository, see the information on contributing to the Eclipse ESCET project.

In the Eclipse ESCET source code repository (Git repository), three layers are distinguished:

This document describes the structure of the top and middle layers. For the bottom layer, standard Eclipse and Maven/Tycho tools are used, which are described elsewhere.

The three layers are not further distinguished in the repository. Instead, different parts are stored in different sub-directories from the root.

Each language has its own subdirectory in the root, /cif and /chi for the CIF and Chi modeling languages, /tooldef for the ToolDef language, and /setext for the SeText language.

Within a language directory, a directory exists for each part of the code (often equivalent to a plugin), with the same name as the plugin. The pattern of a plugin name is org.eclipse.escet.<language>.<plugin-name> where the plugin-name in different directories has the same meaning. A non-exhaustive list:

Other plugin names are often tools with the same name.

The common code between all languages is stored in the /common directory, again with full name of the plugin as sub-directory names. These plugins contain:

Within Java programs, members can be defined with the static modifier. Since multiple instances of an application may be running simultaneously, within a single instance of the IDE, one should avoid using static variables that contain information that is specific to a single instance of the application. For instance, assume an application that maintains an integer counter, used to generate unique identifiers. If defined in a class as follows:

and incremented when needed, the first instance of the application will run just fine. Variable count starts at zero, and is incremented over and over again. When a second instance of the application starts however, the static variable keeps its value, as the new application is started within the same Eclipse instance, and thus within the same JVM. The count won’t start from zero, thus leading to different results for the application.

The conclusion is that one should be careful to avoid static variables that hold information specific to an application instance.

Applications often have settings, and they are generally passed as command line arguments. GUI applications however, often use a dialog to configure the options instead. To allow applications within the application framework to work in both scenarios, all applications should use the option framework.

See also the option framework section.

Command line applications generally obtain input from stdin, and write output to stdout and/or stderr streams. For applications running within the IDE, those streams are connected to the Eclipse application (IDE) as a whole, and not to the applications running within the IDE. To provide a uniform I/O interface, the application framework includes an I/O framework.

See also the I/O framework section.

The Eclipse IDE uses the Standard Widget Toolkit (SWT) for its graphical user interface (GUI). To be compatible with the Eclipse IDE, all GUI applications should use SWT as well. In order for GUI applications to work seamlessly within the Eclipse IDE as well as stand-alone, the application framework automatically registers the main SWT display thread for stand-alone applications, and uses the Eclipse SWT display thread when running within the Eclipse IDE. This reduces the burden of having to register the main SWT display threads, but also avoids blocking and other thread related issues.

Using the GUI option, the GUI can be enabled or disabled. If disabled, headless execution mode is used, which disables creation of a SWT display thread, and thus disables all GUI functionality, including the option dialog.

Within Java, the System.exit method can be used to immediately terminate an application, by terminating the JVM. For applications running within the Eclipse IDE, this not only terminates the application, but the IDE as well. As such, the System.exit method should never be used in applications that are intended to be executed within the IDE.

Stand-alone applications can typically be started from a the command line terminal window. Pressing Ctrl+C at such a command line terminal window terminates the currently running application (on Unix-based systems, this generates a SIGINT). Applications running within the Eclipse IDE however, don’t run in an actual command line terminal. Instead, they run within the IDE, and the stdin, stdout, and stderr streams are coupled to the Eclipse console view. The Eclipse console view does not support termination using the Ctrl+C key combination. Instead, Ctrl+C is used to copy console output to the clipboard. To remedy this situation, application framework applications running within Eclipse get a Terminate button with their console within the IDE, to allow for easy termination.

Furthermore, the application framework allows termination requests via the AppEnv.terminate method. Application framework applications and threads should regularly call the AppEnv.isTerminationRequested method to see whether they should terminate.

See also the termination features of the Applications view.

Exceptions are Java feature that allows applications to report error conditions. Exceptions can generally be divided into two categories: internal errors, and end-user errors. Internal errors should generally not happen, and make the application crash. The application framework provides crash reports for end users to report crashes due to internal errors. The application framework also provides exception classes for end-user errors, to provide nice error messages, instead of stack traces.

See also the exception framework section.

Java uses system properties (System.getProperty method etc). Those properties are global to the entire JVM, meaning they are shared between applications running within the Eclipse IDE. The application framework provides functionality to maintain system properties on a per application basis, turning them into application properties. All application framework applications should use the getProp* and setProp* methods in the AppEnv class instead of the property related methods in the System class. This ensures that the application properties are used instead of the global system properties.

One of the standard system properties in Java is the user.dir property, which refers to the current working directory, or more precisely, the directory from which the JVM was started. Java doesn’t allow changing the current working directory. The application framework however, maintains the current working directory on a per application basis. Changing the current working directory is also supported. Application framework applications should use the methods in the org.eclipse.escet.common.app.framework.Paths class to get and set the current working directory, to resolve relative paths, etc. These methods also allow both Windows (\) and Unix (/) separators to be used in paths, on all platforms, transparently.

Furthermore, within the Eclipse IDE, the concept of a workspace is introduced. In order to allow importing of resources from other projects etc, it may be nice to allow end users to specify platform paths (plug-in paths or workspace paths). Eclipse Modeling Framework (EMF) URIs, besides local file system paths, provide functionality for platform URIs as well. EMF URIs can for instance be used to load models that are instances of an Ecore. The Paths class mentioned above features methods to create such EMF URIs, from various sources. Those methods also feature smart handling of platform:/auto/... paths, an addition to platform URIs, added by the application framework. Such URIs are first resolved in the workspace, and if they can’t be found there, they are resolved in the plug-ins. This allows for easier debugging, as the workspace always overrides the plug-ins.

All exceptions that should be presented to the end user are considered end-user exceptions. These messages should be written in terms that the end user should be able to understand. For end-user exceptions, the exception framework does not display stack traces (at least not by default). All end-user exceptions must implement the org.eclipse.escet.common.app.framework.exceptions.EndUserException interface, and may inherit from the org.eclipse.escet.common.app.framework.exceptions.ApplicationException class. All applications that use the application framework must satisfy these requirements when the error message is to be presented to end users. It is recommended to reuse existing application framework exceptions whenever possible.

All exceptions that are not to be presented to end users are considered to be internal exceptions. Internal exceptions crash the application and are always considered to be bugs. The application framework generates crash reports for internal errors, so that end users can easily report them. Also, stack traces are not shown on the console. They are however present in the crash report, along with among others information about the system, the Java version used, the application that crashed (name, version, etc), and if the OSGi framework is running, the available plug-ins etc.

Java supports the concept of chained exceptions. The end-user exceptions of the application framework support this as well. If an uncaught end-user exception needs to be presented to the end user, the message of the exception is printed to the console, prefixed with the ERROR: text. All the causes of the exception are printed as well, each on a line of their own. Those messages are prefixed with the CAUSE: text. For exceptions that provide an end-user readable message, only that message is printed after the CAUSE: text. For other exceptions, the simple name of the exception class, enclosed in parentheses, is printed between the CAUSE: text and the exception message. All end-user exceptions (the ones inheriting from the org.eclipse.escet.common.app.framework.exceptions.ApplicationException class), as well as all other exceptions explicitly designed as such (by implementing the org.eclipse.escet.common.app.framework.exceptions.EndUserException interface) are considered to provide readable messages. For other exceptions, it is assumed that they don’t. This includes all exceptions provided by Java itself.

Developers can enable the development mode option (DevModeOption class) to always get stack traces for all internal exceptions (thus for crashes, but not for end-user exceptions), instead of crash reports. For more information, see the option framework section.

The development mode option is ideal for automated tests, where a stack trace on stderr is much more ideal than a crash report.

The I/O framework works with output components. All output that the application generates, is given to the output components. Each output component can decide for itself what to do with that output. All applications include at least a StreamOutputComponent, that redirects stream output to the console. For stand-alone applications, this means redirection to stdout and stderr. For application running within the Eclipse IDE, this means redirection to a Console view.

Applications that only need to provide error, warning, normal, and debug textual output, the default output component interface (IOutputComponent) suffices. Applications that want to provide additional (typed) output, should create a derived interface that inherits from IOutputComponent, and extends the interface with additional callback methods. For an example of this, see the org.eclipse.escet.cif.simulator.output.SimulatorOutputComponent interface.

The OutputComponentBase class can be used as a base class for output components. It implements the full IOutputComponent interface, but does nothing with the output that is generated by the application. Derived classes can easily override one or more methods to process output.

Each instance of an application has its own output provider. The output provider keeps track of the output components that are registered, and allows sending of output to the output components through static methods.

If an application uses the default IOutputComponent as its output interface, an instance of OutputProvider<IOutputComponent> can be used. This will suffice for most applications. If an extended output component interface is defined, the OutputProvider class should be extended to provide additional static methods. For an example of this, see the org.eclipse.escet.cif.simulator.output.SimulatorOutputComponent class.

For details on how and where to create an instance of the output provider for an application, see the section on how to implement your own application.

Command line applications generally write output to stdout and/or stderr streams. For applications running within the Eclipse IDE, those streams are connected to the Eclipse IDE as a whole, and not to the applications running within Eclipse. The I/O framework solves this issue, by providing a uniform I/O interface.

The org.eclipse.escet.common.app.framework.output.OutputProvider<T> class provides several static methods that can be used to generate output. Several forms of output are supported by default:

One of the default options of the application framework is the output mode option (OutputModeOption class). It can be used to control what output gets forwarded to the output components. For performance reasons, it may be useful to query whether certain output gets forwarded. The OutputProvider class provides the dowarn, doout, and dodbg methods for this.

It should now be clear that application should never access System.out and System.err directly. Instead, they should use the output provider.

There is no equivalent to the OutputProvider for stdin. Instead, use the AppEnv.getStreams() method to obtain the streams for the current application. The AppEnv.getStreams().IN streams can be used to read data from the stdin stream associated with the current application.

The I/O framework buffers all input and output streams by default, and also automatically performs line based flushing for output and error streams.

All options of applications that use the application framework, should be specified as application framework options. Each option is a derived class of the org.eclipse.escet.common.app.framework.options.Option<T> class. The generic type parameter <T> indicates that options are strongly typed with respect to their values.

The option framework requires all options to work via the command line, but options can also support the option dialog. It is recommended for all options to support the option dialog. The option framework process options as follows:

Options can be ordered into categories. Categories can be combined into a hierarchical structure. This allows the option dialog to show options per category, and allows the command line help message to show command line option help per category. In both cases, this adds structure to the possibly large amount of options, and makes it easier for end users to find the option they are looking for.

For every option, there may be at most one instance. Therefore, never use the constructors of options directly. Instead use the following:

to get an instance of an option.

Applications don’t have access to the command line arguments. The option framework automatically process the command line arguments based on the options registered for the application. Applications always retrieve the values of options through static methods defined in the option classes.

Options are usually set via command line arguments, or via the option dialog. It is however also possible to set option values at run-time:

If possible, options should not depend on the order in which they are parsed. If the value of one option depends on the value of another option, use the post-processing hook to achieve consistency.

All options have a long form (--option), optionally with a value (--option=VALUE). They can also have short form (-o), optionally with a value (-oVALUE or -o VALUE). All arguments that do not start with a dash symbol (-) are considered to be the 'remaining arguments'. It is possible to register one option that processes those remaining arguments. Such special options have * as long option name.

Simply derive from the Option class, and study its API to implement your own options. You can also look at existing options for best practices. Furthermore, the option framework provides several options that can be used in applications:

The application framework provides several options that must be registered for every application:

See also the section on how to implement your own application.

Some things to consider when implementing the runInternal method:

All data stored for the application is wrapped in the AppEnvData class, and stored by the AppEnv class, on a per-thread basis. If your application uses multiple threads, you need to register each thread with the application framework. Use the AppEnv.registerThread method for this. This method requires the current application environment data as parameter, which may be obtained by using the AppEnv.getData method. To avoid managed memory leaks, always unregister threads once they are no longer used, by using the AppEnv.unregisterThread method.

If unit tests use methods that depend on the application being registered, then the unit test will need to register an application. Examples of method using the application framework are methods that use options, or produce output via the application framework. Especially for unit tests, the AppEnv.registerSimple method can be used to register a dummy application. This method uses a default application environment, without an actual application, registers a default stream output provider, sets the output mode to errors and warnings only (no normal or debug output), and disables development mode. It can be used in a unit test class as follows:

If any options are used, they will need to be available as well. For instance, one could add the following to the oneTimeSetUp method, or at the start of the actual unit test method:

As noted above, only a single application can be registered for a single thread. To start one application from another application, simply run the second application in a fresh thread. In the new thread, do the following:

After the child application thread finishes, make sure you:

To make it easier to follow this approach, the ChildAppStarter.exec methods can be used.