IDE Customization Guide

Template processing uses the FreeMarker library (http://freemarker.org) and all template syntax supported by FreeMarker can be used. In particular, variable references of the syntax ${varName} will be replaced with the variable value.

The FreeMarker language also offers constructs that make it a full programming language: variable assignments, conditionals, loops, switch statement, functions, macros, expression evaluation, built-in operators, etc., as well as access to fields and methods of classes defined in Java. This means that any algorithm can be expressed in the FreeMarker language, and if that is not enough, one can directly access Java classes using FreeMarker’s Bean Wrapper.

Templates can use several sources for input. They can:

Custom wizard pages are defined in XSWT (http://xswt.sourceforge.net). XSWT is an XML based language that allows the definition of SWT (the widget set used by Eclipse) widget hierarchies, without the need to write any code in Java. XSWT also maps widget properties to XML attributes so the visual appearance of the wizard pages can be easily tweaked. It is also possible to invoke methods on the generated widgets and use the SWT layout containers, allowing further customizations. Each .xswt file in the template directory defines a separate wizard page which can be shown either conditionally or unconditionally.

Double-clicking on an XSWT file will open it in the XSWT editor. The editor provides basic syntax highlighting. An extremely useful feature of the IDE is the XSWT Preview, where you can preview the form being edited (it updates when you save the file). The Preview should open automatically when you open the XSWT file; if it does not (or you close it), you can access it via the Window|Show View… menu item.

Some (custom) widgets may not appear in the Preview; this is because the Preview does not load jar files from the projects.

Figure 1.3. Editing an XSWT file

The FreeMarker Editor opens when you double-click files with the *.ftl or *.fti extension. The FreeMarker Editor offers basic syntax highlighting, validation (error markers appear during editing if the template is not syntactically correct), and basic content assist. Content assist can help you with directives (<#...> syntax) and built-in operations (like ?number, ?size, ?default, etc). The content assist popup appears automatically when you type <# (actually a closing > is also needed for the editor to recognize the tag), and when you hit ? within a directive or an interpolation (${...}).

The first step when creating a wizard is to create a new folder under the templates directory of the project. A file named template.properties must be present in the newly created directory. This file is used to configure the wizard. Create a folder a folder named templates/examplewizard under the project, then create template.properties and add the following lines to it:

templateName = New Test Wizard
templateDescription = Generate an example
templateCategory = Test Wizards
supportedWizardTypes = simulation, network

These lines specify the name, type and category for the wizard. Category is used to specify how the wizards will be grouped in the tree control section of the template selection page. Wizard type specifies in which New … Wizard your wizard will appear. You can specify one or more of project, simulation, network, etc.; the list of all possible wizard types will be covered later in this document. In this case, the wizard will appear in the New Simulation and New Network wizard dialogs.

You can now decide what data you would like to ask the user to provide. Template variables and their values can be defined as key-value pairs:

nodeType = Dummy
networkSize = 6

The nodeType variable will be used as the submodule type in your network, while the networkSize defines how many submodules you want in the network.

We define a custom wizard page where the user can specify the values of the above variables (i.e. override their default value, specified above).

page.1.file = parameters.xswt
page.1.title = Network parameters

We will use the file parameters.xswt to define the layout and the content of the new wizard page.

Files with .xswt extension (Wizard Page definitions) are used to define the UI and add new wizard pages to gather user input for template generation. In the previous section, we specified that the file called parameters.xswt will contain the new wizard page definition. We will add a spinner control to specify the size of our network and a text control to specify the node type. Create a new file called parameters.xswt with the following content:

<xswt xmlns:x="http://sweet_swt.sf.net/xswt">
  <x:import>
    <!-- Import all widgets and utility classes  -->
    <package name="java.lang"/>
    <package name="org.eclipse.swt.widgets" />
    <package name="org.eclipse.swt.graphics" />
    <package name="org.eclipse.swt.layout" />
    <package name="org.eclipse.swt.custom" />
    <package name="org.omnetpp.common.wizard.support" />
    <package name="org.omnetpp.ned.editor.wizards.support" />
    <package name="org.omnetpp.cdt.wizard.support" />
  </x:import>
  <!-- Create a two-column layout  -->
  <layout x:class="GridLayout" numColumns="2"/>
  <x:children>
    <!-- First row -->
    <label text="Number of nodes in the network:"/>
    <spinner x:id="networkSize" minimum="2" x:style="BORDER"/>
    <!-- Second row -->
    <label text="Type of nodes:"/>
    <text x:id="nodeType" x:style="BORDER"/>
  </x:children>
</xswt>

The above defined wizard page will have two columns. The first column contains labels and the second contains editable widgets. The x:id="varName" attributes in the spinner and text control definitions are used to bind a template variable to the control. When a page is displayed, the content of the bound variables are copied into the controls. When the user navigates away from the page or presses the Finish button, the content of the controls are copied back to the bound variables. These variables can be used in the template files we are about to define in the following section.

When the template is used, the contents of the template folder (and its subfolders) will be copied over into the new project, thus preserving the directory structure with the exception of template.properties (it is also possible to specify other files and folders to be ignored by specifying a file list for the ignoreResources configuration key).

When the wizard is being used, a pool of variables is kept by the wizard dialog. These variables are initialized from the key = value lines in the template.properties files; they can get displayed and/or edited on custom wizard pages. Eventually, they get substituted into *.ftl files (using the ${varname} syntax).

Some variables have special meaning and are interpreted by the wizard dialog (e.g. the nedSrcFolders variable determines which folders get denoted as NED Source Folders by the New OMNeT++ Project wizard). Variables can be used to generate output file names, can be used as input file names, and can serve as input and working variables for arbitrarily complex algorithms programmed in the template (*.ftl) files.

Let us have a quick look at the FreeMarker template language. Variables can be inserted into the output using the ${varname} syntax. One can also write expressions inside ${..}. For example, ${numServers?number + 1} uses the number built-in operator to convert the numServers variable to a number, adds one to it, and inserts the result into the template output. FreeMarker has many other functions (conversion to string, upper-case version of a string, size of an array, etc.) that work as built-in operators.

Programming facilities can be accessed via directives that have the <#...> syntax. Use <#if> (<#if> cond>..<#elseif cond>..<#else>..</#if>) for conditionals; <#list> for iterations and loops (e.g. <#list words as w>..</#list>; <#list 0..9 as i>..</#list>; <#list 9..0 as i>..</#list>); and <#assign> for assigning variables (<#assign x=5>; <#assign x>the number ${i}</#assign>). One can define functions (<#function>) and macros (<#macros>). You can also include other templates (<#include>). Here, we only covered a small fraction of FreeMarker’s possibilities; we recommend that you read the FreeMarker manual for more information.

Let us create a file with a filename that has an .ftl extension (e.g. untitled.ned.ftl). Because of the extension, this file will be processed by the templating engine. The actual name of the file does not matter, because the <@setoutput .../> directive instructs the templating engine to output everything from the current file into the file that is specified by the targetFileName variable. The targetFileName, targetTypeName, bannerComment and nedPackageName variables are automatically filled out by the wizard, based on the filename and folder the user selected on the first wizard page.

<@setoutput path=targetFileName />
${bannerComment}

<#if nedPackageName!="">package ${nedPackageName};</#if>

network ${targetTypeName}
{
    node[${networkSize}] : ${nodeType}
}

The template variables will be substituted into the template automatically.

Specific wizard dialog types will also define extra variables for use in the templates. For example, the wizard type that creates a complete simulation (with all required files) will put the simulationName variable into the context. To see all defined variables, check the Appendix.

As a last step in our example, we will also create an INI file template:

Create a file called omnetpp.ini.ftl, and fill with:

<#if wizardType=="simulation">
network = ${targetTypeName}
</#if>

We need the INI file only if we are creating a simulation. If the current type is not simulation, the content will be empty, and the file will not be written to the disk.

wizardType = project

Project wizards create new projects and let the user create files in them. It is possible to adjust project properties to customize the new project. You can add C⁠+⁠+ support to the project, set source and NED folders, etc.

The first two pages of the wizard are standard: they prompt the user for the name of the new project and let the user choose a content template. These pages are followed by pages provided by the selected content template. If the user selected C⁠+⁠+ support on the first page, custom pages are followed by the standard CDT New Project pages.

When the user clicks Finish, the wizard creates the project and configures it according to the selected options (C⁠+⁠+ support, source folders, etc.). Then, template files are copied into the new project, performing template processing as necessary. Templated pages are responsible for creating the package.ned file according to the nedPackageName and namespaceName options, as well as creating source files in the NED and C⁠+⁠+ source folders.

There are a few useful variables that template files use. The rawProjectName variable contains the project name. This variable cannot be directly used as C⁠+⁠+ or NED package names, type names, etc, because it may contain spaces or other characters not allowed in identifiers. For convenience, the wizard provides sanitized versions of the project name that can be used as identifiers; they are in the variables projectName, PROJECTNAME and projectname, and differ in capitalization. The targetFolder variable is set to /<project name>. These variables cannot be edited in custom wizard pages.

The variables addProjectReference, makemakeOptions, sourceFolders and nedSourceFolders affect the creation of the project before template files get processed. It is allowable to provide an initialization value for these variables in template.properties and to let the user change them in custom pages.

For conformance with other wizards, the project wizard initializes the following variables with different case versions of the project name: targetTypeName, nedPackageName, and namespaceName. The targetMainFile variable is initialized to projectName+.ned, but there is no requirement for the template to actually create this file. It can provide a different initialization value for these variables in template.properties and can let the user change them in custom pages.

See the appendix for the variable names that are supported in project wizard templates.

wizardType = simulation

A new simulation is basically a new folder containing all files required to run a simulation. The simulation folder usually contains NED files, an INI file, and possibly also CC, H and MSG files.

The first two pages of the wizard are standard; they prompt the user for the parent and name of the new folder, and let the user choose a content template. These pages are followed by pages provided by the selected content template. Simulations can only be created in new folders under existing projects or folders.

When the user clicks Finish, the wizard creates the folder. The template files are then copied into the new folder, performing template processing as necessary.

There are a few useful variables that template files can use. The simulationFolderName contains the name of the new folder (without path). This variable cannot be directly used as a C⁠+⁠+ or NED identifier, because it may contain spaces or other characters not allowed in identifiers. For convenience, the wizard provides the simulationName variable which is a sanitized version of the folder name. The targetFolder variable is set to the workspace path of the new folder. These variables cannot be edited in custom wizard pages.

For conformance with other wizards, the simulation wizard initializes the targetTypeName variable with the simulation name. The targetMainFile variable is initialized to simulationName+.ned, but there is no requirement that the template actually creates this file. It can provide a different initialization value for these variables in template.properties and can let the user change them in custom pages.

The nedPackageName and namespaceName variables are set by the wizard to the NED package name and C⁠+⁠+ namespace expected for the given folder. These values are derived from the folder path, the toplevel package.ned file and the @namespace property in it, and cannot be overridden.

See the appendix for the variable names that are supported in simulation wizard templates.

wizardType = compoundmodule, network, nedfile, inifile, msgfile

These wizard types generate a single file. The first two pages of the wizard are standard; they prompt the user for the parent folder and name of the new file, and let the user choose a content template. These pages are followed by pages provided by the selected content template.

When the user clicks Finish, template files are copied into the selected parent folder, performing template processing as necessary. The template files are expected to create a file with the name chosen by the user.

The wizard passes the file name to the template files in the targetFileName variable.

There are a few useful variables that template files can use. The targetFolder variable is set to the workspace path of the parent folder. This variable cannot be edited in custom wizard pages.

For conformance with other wizards, the new wizard initializes the targetTypeName variable to a sanitized version of the file name (minus extension). This variable can be used as a NED or message type name in the generated file. The targetMainFile variable is the same as targetFileName.

One can provide a different initialization value for the targetTypeName variable in template.properties and let the user change it in custom pages.

The nedPackageName and namespaceName variables are set by the wizard to the NED package name and C⁠+⁠+ namespace expected for the given folder. These values are derived from the file path, the toplevel package.ned file and the @namespace property in it, and cannot be overridden.

See the appendix for the variable names that are supported in new file wizard templates.

wizardType = simplemodule

The simple module wizard creates a simple module, usually consisting of a NED file and C⁠+⁠+ implementation files. This wizard works in a similar way as the New NED File or New Compound Module wizard, but it is allowed to create other files (C⁠+⁠+ sources) in addition to the NED file.

wizardType = import

An import wizard is not a standalone type, but rather a flag on other wizard types. It makes the wizard appear in the File|Import… dialog in addition to the File|New … dialogs.

To access the import wizards, choose OMNeT++, Networks, simulations and other items as import source on the first page of the Import dialog. The next page will be the content template selection page. After choosing a template, the next page will be the file, folder or project name selection page of the New… wizard, followed by the custom wizard pages.

wizardType = export

Export wizards can be accessed via the File|Export… dialog and export data into one or more files in the workspace or in the file system.

To access the export wizards, choose OMNeT++, Networks, simulations and other items as export destination on the first page of the Export dialog. The next page will be the content template selection page, followed by the custom wizard pages.

Export wizards do not have a standard file/folder selection page, the target file name(s) must be obtained from the user on custom wizard pages.

The export wizard does not set targetFileName, targetMainFile, or any similar variables. It is entirely up to the template author to define a variable for storing the output file name, letting the user edit it, and saving the content in that file.

Template files are not allowed to produce any output; they are supposed to create the target files programmatically.

wizardType = wizard

A New Wizard wizard creates a wizard under the templates/ folder of a workspace project.

The first two pages of the wizard are standard. They prompt the user to select the project that will hold the wizard, choose the wizard name (name of the new folder under templates/), and pick a content template. These pages are followed by pages provided by the selected content template.

When the user clicks Finish, the wizard creates the folder under the templates/ folder of the chosen project. After that, template files are copied into the new folder, performing template processing as necessary.

There are a few useful variables that template files can use. The newWizardName variable contains the name of the new folder (without path), and newWizardProject contains the name of the project. The project name variables (rawProjectName, projectName, PROJECTNAME, etc.) and targetFolder variables are also set. These variables cannot be edited in custom wizard pages.

See the appendix for the variable names that are supported in New Wizard wizard templates.

By default, templates are processed and copied with the same name (chopping the .ftl extension), but it is possible to redirect the output of the template to a different file using the <@setoutput path=.../> macro. The filename can contain slashes, too, which means that one can write files in a different folder. If the folder does not exist, it will be created. For example:

<@setoutput path=targetFileName/>

If filename is empty, the directive restores output to the original file name (the template’s name). This also works if a folder name is given and only the file name is missing (<@setoutput path="src/">). Then, it will write the file with the original name but into the specified folder.

Empty and blank files (i.e. those containing only white space) will not be created (i.e. processing will skip writing it without any question, warning or error). This allows you to easily create files conditionally; you just have to surround the file body with <#if>..</#if>.

An XSWT form is defined in an XML file with the root element <xswt>. Some XSWT specific elements and attributes (import and package declarations, id and class attributes to name a few) are defined in the http://sweet_swt.sf.net/xswt XML namespace (we use the x namespace prefix here).

Controls that can be used in XSWT are instantiated by an element with same name as the control (but starting with lowercase).

Controls and classes used in an XSWT file must be imported before they can be used.

<xswt xmlns:x="http://sweet_swt.sf.net/xswt">
  <x:import>
    <package name="java.lang"/>
    <package name="org.eclipse.swt.widgets" />
    <package name="org.eclipse.swt.custom" />
    <package name="org.eclipse.swt.graphics" />
    <package name="org.eclipse.swt.layout" />
    <package name="org.omnetpp.common.wizard.support" />
    <package name="org.omnetpp.ned.editor.wizards.support" />
    <package name="org.omnetpp.cdt.wizard.support" />
  </x:import>
  <label text="Hello"/>
</xswt>

Entities and attributes in an XSWT file are directly mapped to the corresponding SWT controls and their properties. For example, a <styledText> tag creates an org.eclipse.swt.custom.StyledText control. Similarly, a text attribute causes the setText() method of the control to be called.

<styledText text="Hello world!" />

Alternatively, it is possible to call a public method on the control by embedding a "call" as a child tag and supplying the parameters as p0, p1, etc.:

<styledText>
  <setText x:p0="Hello World"/>
</styledText>

Integer constants in controls (public static final int fields) can be used in an XSWT file by appending the Java class name before them:

<gateChooser gateFilter="GateChooser.INOUT|GateChooser.VECTOR"/>

Constants in the SWT class do not need the SWT. prefix. You can write:

<button x:style="RADIO"/>

Children can be added to a compound control inside the <x:children></x:children> tags.

<group text="Hello">
  <x:children>
    <label text="Label 1" />
    <label text="Label 2" />
  </x:children>
</group>

Layout and layout data can also be added as a new tag inside a control element:

<text x:id="numServers" x:style="BORDER">
  <layoutData x:class="GridData" horizontalAlignment="FILL"
              grabExcessHorizontalSpace="true"/>
</text>

XSWT allows one to tag widgets with ID attributes. Widget IDs will become the names of template variables with the values being the content of widgets. For example, text widgets (org.eclipse.swt.widgets.Text) provide a string value (Java type "String"), while checkboxes and radio buttons provide a boolean (Java type "Boolean").

XSWT also allows filling up the widgets with default values (e.g. <styledText text="some text"/> ), but this feature should be used with care because the defaults set in XSWT may not make it to the file templates. This occurs because if the user clicks Finish early, the rest of the wizard pages (and their widgets) may not be created at all, so values set in the XSWT will take no effect.

For this reason, defaults should always be set in the property file. To do so, simply use a key with the ID of the widget; those values will be written into the wizard page when the page is created. For example, if you have a text widget with x:id="numNodes" and a checkbox with x:id="generateTraffic", then the following lines

numNodes = 100
generateTraffic = true

will fill in the text widget with "100" and select the checkbox. Widgets that do not have such lines in the property file will be left alone. The property file takes precedence over values specified in the XSWT file.

Compound data structures (arrays, maps, and any combination of them) can be specified in the JSON syntax (http://json.org). They can be iterated over in the templates and can be used as input/output for custom compound widgets. Examples:

apps = ["ftp", "smtp", "news"]
layers = {"datalink":"ieee80211", "network":"ip", "transport":["tcp","udp"]}

Now that we have covered basic XSWT, we can revisit how one can use page conditions. Consider the following practical example of creating a wizard for wireless networks.

On the first page of the wizard you could have a [] Configure routing checkbox with the ID wantRouting. If this checkbox is selected, you want to display a second page where the user can select a routing protocol, followed by configuration pages determined by the chosen routing protocol.

To achieve this, you would add the following lines to template.properties:

# page with the "wantRouting" checkbox
page.1.title = General
# page with the "protocol" combobox
page.2.title = Choose Routing Protocol
page.3.title = AODV Options
page.4.title = DSDV Options

page.2.condition = wantRouting
page.3.condition = wantRouting && protocol=="AODV"
page.4.condition = wantRouting && protocol=="DSDV"

The .condition keys will make the wizard include only the pages where the condition evaluates to true. Conditions can be arbitrary FreeMarker expressions that evaluate to true (as boolean) or "true" (as string). Conditions are re-evaluated after every page, so you can depend on variables edited on earlier pages.

It is also possible to create controls conditionally. To overcome the limitation that XSWT page descriptions are completely static, XSWT files undergo FreeMarker template processing before giving them to the XSWT engine for instantiation. This template processing occurs right before the page gets displayed, so data entered on previous pages can also be used as input for generating XSWT source. This feature can be useful in making conditional widgets (i.e. using <#if> to make part of the page appear only when a certain option has been activated on earlier pages), to create a previously unknown number of widgets (using a <#list>..</#list> loop), to populate combo boxes, listboxes or other widgets with options, and more.

<!-- Show only if the wizard is run from the New Simulation wizard-->
<#if wizardType=="simulation">
<label text="Description how the wizard works for new simulations."/>
</#if>

If the user navigates in the wizard back and forth several times (using the Next and Back buttons), the contents of wizard pages are always re-created with the current values of template variables just before getting displayed, so they will always be up to date.

Defining a wizard page in Java requires that you install the Eclipse Plug-in Development Environment (PDE) and that you have some Eclipse development skills.

The template.properties key for denoting a Java-based wizard page is page.<NN>.class, and the value should be the fully qualified name of the Java class that implements the wizard page. The requirements for the class are:

Since XSWT works via Java reflection, your own custom widgets can be used in forms, similar to normal SWT widgets. No glue or registration code is needed; simply add their package to the <import> tags at the top of the XSWT file.

However, some Java code is needed so that the wizard knows how to write template variables into your widgets and how to extract them after editing. This functionality can be added via the org.omnetpp.common.wizard.IWidgetAdapter interface. This interface must be implemented either by the widget class itself, or by a class named <widgetclass>Adapter in the same package. The interface has methods to tell whether the adapter supports a given widget, to read the value out of the widget, and to write a value into the widget.

In addition to basic data types (Boolean, Integer, Double, String, etc.), it is possible to use compound data types as well (i.e. those composed of the List and Map interfaces of the Java Collections API). The default values can be given in the template.properties file in the JSON notation and the result can be used in the templates (iteration via <#list>, etc.).

Jar files placed into the plugins/ subdirectory of an OMNeT++ project will be loaded automatically and will be available to all templates. Jar files in that directory may be plain Java jars and Eclipse plug-in jars (the latter makes it also possible to contribute new functionality into the IDE via various extension points, but this is outside the scope of this discussion about wizards).

Jar files placed in the folder of the template will be loaded automatically when the template is used and the classes in it will be available for that template. Custom SWT widget classes can be imported and used in XSWT forms, and other code can be used in the template files via the FreeMarker Bean Wrapper (e.g. ${classes["org.example.SomeClass"].someStaticMethod(...)}, see the example wizards.) Like .xswt files and template.properties, jar files are not copied over into the destination folder when the wizard executes.

If you are skilled in writing Eclipse plug-ins, there are ways you can extend content templates. One is to contribute to the org.omnetpp.common.wizard.templatecontributor extension point, which lets you supply IContentTemplateContributor objects that can extend the content template implementation in various ways. You can contribute new variables, functions or macros to the template context.

It is possible to bind template variables to a specific control by using the x:id attribute.

<text x:id="templateVariableName" />

This is the way that template variables are bound to the controls (R=read, W=write):

Some non-interactive widgets which cannot be connected to template variables but are useful in forms as structuring elements:

In the following sections, we describe the individual wizard types and their supported template variables. Variables will be marked with one or more letters to show in which wizard types they are supported as shown in the previous table.

Variables marked as (*) are set by the wizard automatically and generally it does not make sense to change their values.

The following variables are only defined if the template was loaded from the workspace (i.e. a project’s templates/ subdirectory):

Sanitization means making the name suitable as a NED or C/C⁠+⁠+ identifier (spaces, punctuation and other inappropriate characters are replaced with underscore, etc.).

The variables below are for advanced use only. They can be used to access directly all known NED and message types, static classes for utility functions and the whole context used during template processing.

iif(condition, valueIfTrue, valueIfFalse)

Inline if. The FreeMarker language does not have a conditional operator (like ?: of C/C⁠+⁠+ ), but the iif() function can save you from having to spell out <#if>..<#else>..</#if>, when required. It is important to note that unlike in C/C⁠+⁠+, the evaluation is not lazy (i.e. both the "then" and the "else" expressions are always evaluated).

<@do expression !/>

FreeMarker does not have a construct for calling a function and then discarding the result. One could use <#assign dummy = expression>, but this will fail if the called (Java) function is void or returns null. We recommend our small <@do ..!/> macro which takes one argument and does nothing, and the exclamation mark (the FreeMarker default value operator) cures the void/null problem.

The following Java classes are available during template processing:

Represents the Java Math class, which contains mathematical functions. See http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Math.html .

Math has the following methods:

double cos(double x)

double sin(double x)

double pow(double x, double y)

etc.

Represents the Apache Commons StringUtils class, which contains over a hundred utility functions for manipulating strings. See: http://commons.apache.org/lang/api/org/apache/commons/lang/StringUtils.html .

StringUtils has the following methods:

boolean isEmpty(String s)

boolean isBlank(String s)

String capitalize(String s)

String upperCase(String s)

String lowerCase(String s)

boolean startsWith(String s, String suffix)

boolean endsWith(String s, String prefix)

String[] split(String s)

String join(String[] strings)

etc.

Represents the Apache Commons WordUtils class, which contains utility functions for manipulating strings as word sequences. See http://commons.apache.org/lang/api/org/apache/commons/lang/WordUtils.html .

WordUtils has the following methods:

String wrap(String str, int wrapLength)

String capitalize(String str)

String swapCase(String str)

etc.

Represents the Apache Commons CollectionUtils class, which contains some useful functions for manipulating collections (like lists). Functions include computing set union, intersection, and difference. See http://commons.apache.org/collections/apidocs/org/apache/commons/collections/CollectionUtils.html

CollectionUtils has the following methods:

Collection union(Collection a, Collection b)

Collection intersection(Collection a, Collection b)

Collection subtract(Collection a, Collection b)

etc.

Contains utility functions for reading files in the following formats: XML, JSON, CSV, property file, and functions to read and return a text file as a single string, as an array of lines, and as a an array of string arrays (where string arrays were created by splitting each by whitespace).

There are two sets of functions; one works on files in the Eclipse workspace and the other on "external" files (i.e. files in the file system). Files are interpreted in the Java platform’s default encoding (unless they are XML files, which specify their own encoding).

FileUtils has the following methods:

org.w3c.dom.Document readXMLFile(String fileName)
org.w3c.dom.Document readExternalXMLFile(String fileName)

Parses an XML file, and return the Document object of the resulting DOM tree.

Object readJSONFile(String fileName)
Object readExternalJSONFile(String fileName)

Parses a JSON file. The result is a Boolean, Integer, Double, String, List, Map, or any data structure composed of them. The JSON syntax is documented at http://json.org ; if you want to check whether a particular text file corresponds to the JSON syntax, use http://jsonlint.com .

String[][] readCSVFile(String fileName, boolean ignoreFirstLine,
                       boolean ignoreBlankLines,
                       boolean ignoreCommentLines)
String[][] readExternalCSVFile(String fileName, boolean ignoreFirstLine,
                       boolean ignoreBlankLines,
                       boolean ignoreCommentLines)

Reads a CSV file. The result is an array of lines, where each line is a string array. Additional method parameters control whether to discard the first line of the file (which is usually a header line), whether to ignore blank lines, and whether to ignore comment lines (those starting with the # character). Comment lines are not part of the commonly accepted CSV format, but they are supported here nevertheless due to their usefulness.

Properties readPropertyFile(String fileName)
Properties readExternalPropertyFile(String fileName)

Parses a Java property file (key=value lines) in the workspace. The result is a Properties object, which is a hash of key-value pairs.

String[][] readSpaceSeparatedTextFile(String fileName,
                         boolean ignoreBlankLines,
                         boolean ignoreCommentLines)
String[][] readExternalSpaceSeparatedTextFile(String fileName,
                         boolean ignoreBlankLines,
                         boolean ignoreCommentLines)

Reads a text file and return its contents, split by lines with each line split by whitespace. Additional method parameters control whether to ignore blank lines and/or comment lines (those starting with the # character). The result is an array of lines, where each line is a string array of the items on the line.

String[] readLineOrientedTextFile(String fileName)
String[] readExternalLineOrientedTextFile(String fileName)

Reads a text file in the workspace and returns its lines. Comment lines (those starting with a hash mark, #) are discarded. The result is a string array.

String readTextFile(String fileName)
String readExternalTextFile(String fileName)

Reads a text file, and return its contents unchanged as a single string.

boolean isValidWorkspacePath(String path)

Returns true if the given string is syntactically a valid workspace path.

boolean isValidWorkspaceFilePath(String path)

Returns true if the given string is syntactically a valid workspace file path. This function does not check whether the file exists, or whether the given path already points to a resource of a different type.

IWorkspaceRoot getWorkspaceRoot()

Returns the workspace root object. The workspace contains the user’s projects.

IProject asProject(String path)

Returns the handle for the workspace project with the given name. Throws exception if the path is not a valid workspace project path. This function does not test whether the project exists. To test that, call the exists() method on the returned handle.

IContainer asContainer(String path)

Returns the handle for the workspace container (i.e. project or folder) with the given name. Throws exception if the path is not a valid workspace container path. This function does not test whether the container exists. To test that, call the exists() method on the returned handle.

IFile asFile(String path)

Returns the handle for the workspace file with the given name. Throws exception if the path is not a valid workspace file path. This function does not test whether the file exists. To test that, call the exists() method on the returned handle.

IResource asResource(String pathName)

Returns the handle for the workspace project, folder or file with the given name. If the resource does not exist and the path contains more than one segment (i.e. it cannot be a project), it is returned as a file handle if it has a file extension, and as a folder if it does not.

File asExternalFile(String path)

Returns a java.io.File object for the given path. The object can be used to access operations provided by the File API, such as exists(), length(), etc.

void copy(String path, String destPath, IProgressMonitor monitor)

Copies a workspace resource (file, folder or project) specified with its path to the destination path. For projects and folders, it copies recursively (i.e. copies the whole folder tree). From the project root directory, it leaves out dot files, hidden files, and team private files.

void copyURL(String url, String destFilePath,
                      IProgressMonitor monitor)

Copies the file at the given URL to the given destination workspace file.

String createTempFile(String content)

Writes the given string to a temporary file and returns the path of the temporary file in the file system. The file will be automatically deleted when the IDE exits, but it can be also deleted earlier via deleteExternalFile().

void createFile(String fileName, String content)

Creates a workspaces text file with the given contents in the platform’s default encoding.

void createExternalFile(String fileName, String content)

Creates a text file in the file system with the given contents in the platform’s default encoding.

void deleteFile(String fileName)

Deletes the given workspace file. It is acceptable to invoke it on a nonexistent file.

void deleteExternalFile(String fileName)

Deletes the given file from the file system. It is acceptable to invoke it on a nonexistent file.

void createDirectory(String fileName)

Creates a workspace folder. The parent must exist.

void createExternalDirectory(String fileName)

Creates a directory in the file system. The parent must exist.

void removeDirectory(String fileName)

Deletes a workspace folder. The folder must be empty. It is acceptable to invoke it on a nonexistent folder.

void removeExternalDirectory(String fileName)

Deletes a directory in the file system. The directory must be empty. It is acceptable to invoke it on a nonexistent directory.

Provides utility methods to work with NED types and check their existence.

NedUtils has the following methods:

boolean isVisibleType(String typeName, String inFolder)

Returns whether the given NED type is visible in the given folder. If the type is a fully qualified name, it is recognized if it is defined in the same project as the given folder, or in one of its referenced projects. If the type is a simple name (without package), it is recognized if it is in the NED package of the given folder.

INEDTypeInfo getNedType(String typeName, String inFolder)

Like isVisibleNedType(), but actually returns the given NED type if it was found; otherwise, it returns null. Useful if you implement a complex wizard page in Java.

Provides entry points into various aspects of the IDE. This includes access to the Eclipse workspace (projects, folders, files) and the NED index. The former is documented in the Eclipse Platform help; documentation for the latter can be found in the sources (Javadoc). See http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/resInt.htm and http://help.eclipse.org/galileo/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/core/resources/IWorkspaceRoot.html

IDEUtils has the following methods:

boolean openConfirm(String title, String message,
                            String detailsMessage)
boolean openQuestion(String title, String message,
                             String detailsMessage)
boolean openError(String title, String message,
                          String detailsMessage)
boolean openWarning(String title, String message,
                            String detailsMessage)
boolean openInformation(String title, String message,
                            String detailsMessage)

Opens a standard message dialog with a closable details message.

Provides a collection of Java language related utility functions.

LangUtils has the following methods:

boolean hasMethod(Object object, String methodName)

Returns true if the object has a method with the given name. Method args and return type are not taken into account. Search is performed on the object’s class and all super classes.

boolean hasField(Object object, String fieldName)

Returns true if the object has a field with the given name. Field type is not taken into account. Search is performed on the object’s class and all super classes.

boolean instanceOf(Object object, String classOrInterfaceName)

Returns true if the given object is an instance of (subclasses from or implements) the given class or interface. To simplify usage, the class or interface name is accepted both with and without the package name.

String toString(Object object)

Produces a user-friendly representation of the object. In case of collections (lists, maps, etc.), the representation is JSON-like.

List<Object> newList()

Creates and returns a new mutable List object (currently ArrayList).

Map<Object, Object> newMap()

Creates and returns a new mutable Map object (currently HashMap).

Set<Object> newSet()

Creates and returns a new mutable Set object (currently HashSet).

Class<?> getClass(Object object)

Returns the class of the given object. Provided because BeanWrapper seems to have a problem with the getClass() method.

Provides functionality to start external applications from the wizard.

ProcessUtis has the following methods:

ProcessResult exec(String command, String[] arguments,
                           String workingDirectory,
                           String standardInput, double timeout)

Executes the given command with the arguments as a separate process. The standard input is fed into the spawn process and the output is read until the process finishes or a timeout occurs. The timeout value 0 means wait infinitely long to finish the process. Arguments at the end of the argument list are optional.

String lookupExecutable(String name)

Finds the given executable in the path and returns it with full path. If not found, it returns the original string.