User Interface

Create and Open EA Models

There are basically two different kinds of EA models: either they are stored in local eap-files or in remote database repositories such as a MSSQL database.

EA Models in Local eap-files

Eap-files can directly be accessed within Eclipse, e.g. by copying a file into a project of the current workspace. The file extension eap is automatically registered for the default EA UML Editor as shown in the figure below.

The EA UML Editor is capable of accessing EA models

Instead of placing eap-files physically into your workspace projects, they can also be linked into the workspace whereas the physical files are located somewhere else on your file system. To do so, choose File -> New -> File -> press Advanced and select Link to file in the file system -> Browse to your eap-file -> choose a location and name for the link in your workspace.

Create a link to an external eap-file using the 'New File' wizard

Within the Eclipse Project Explorer, linked files will be shown with a link-arrow decorator on the file icon, as shown in the screenshot below.

A linked eap-file

The YAKINDU EA-Bridge also ships an own New EAP File wizard (via File - New - Other... - YAKINDU EA-Bridge) for creating new EA models as shown in the screenshot below. Here, in addition to the file location (relative to the workspace root), the Default Language must be specified. It will be the default Code Engineering Language in EA, which maps to a corresponding primitive types library in Eclipse (more details here).

New EAP File wizard

EA Models in a Remote Database

Besides local eap-files, the Enterprise Architect allows to store its models in a remote database systems (MSSQL, MySQL, Oracle, and others). The YAKINDU EA-Bridge also supports access to such remote database systems if the corresponding database driver feature is installed. A list of all installed drivers is shown in the preferences page Window - Preferences - YAKINDU EA-Bridge - Database Drivers.

Preference page with a list of all installed database drivers

The Microsoft JDBC Driver 4.0 may not be redistributed, but it can easily be added manually. It must be downloaded from the Microsoft Download Center and the file sqljdbc4.jar, which is contained in the downloaded archive, must be copied to: <eclipse folder>/plugins/com.yakindu.bridges.ea.core.mssql-fragment_<version>/lib/
That target folder also contains a readme.txt file with instructions how to install the Microsoft MSSQL driver.

Each database driver ships a wizard for creating a configuration file as illustrated for an MSSQL database configuration in the screenshot below.

New EA MSSQL Configuration wizard

The newly created database configuration file (sample.mssql.eap in the example above) can then be accessed by the YAKINDU EA-Bridge the same way as normal eap-files.

Editor

The YAKINDU EA-Bridge loads EA models as regular UML2 models, so the regular UML Model Editor can be used to open EA models. It is the default editor for eap-files, so double-clicking eap-files within the Eclipse workspace should open the UML Model Editor. Alternatively, it can be opened via the context menu Open With - UML Model Editor.

The default UML Model Editor with an example EA model

By default, the editor loads all stable supported UML model elements including profiled UML models. Additional UML libraries are loaded (lazily) into the resource set as shown at the bottom in the figure above:

example.profile.uml
The Example profile definition file (corresponds to this EA profile).
*.profile.uml
Further required pre-defined UML profiles.
UML.metamodel.uml
The actual UML meta model.
example.library.eap
Built-in primitive type libraries that are mapped to code engineering languages in EA (more details in API section).
*.library.uml
Custom primitive type libraries that are mapped to code engineering languages in EA (more details in API section).

Write support is restricted, so it is disabled by default but can be enabled in the preferences. The creation and deletion of most supported UML elements and the modification of their properties works fine whereas certain UI operations such as moving elements are not yet properly supported and may yield undefined results. Please keep in mind that the primary use case of the YAKINDU EA-Bridge should be to read and process EA models programmatically - the Enterprise Architect should remain the main authoring tool for EA models. Therefore, the main use case for the default UML Model Editor is to validate and review EA models, maybe to perform minor model changes. Programmatic creation and modification of EA models (like code generation, model transformation, or model validation), on the other hand, works fine if you follow the guidelines in the API section.

Preferences

The YAKINDU EA-Bridge has preference pages that provide options to configure its behavior. The individual options are briefly explained here and, if needed, explained in detail in further sections.

EA-Bridge preferences page

Refresh EAP files on window activation in case they are modified
When this option is enabled and EAP files are modified externally, e.g. by the Enterprise Architect, the workspace file is refreshed as soon as the Eclipse workbench window regains focus. The default UML Model Editor, for instance, performs a model reload based on that event. Other clients may react differently. (more details in file and resource handling section)
Reload model only on hash change
If a model is loaded with the EA-Bridge and in the meantime it is externally modified, e.g. with the Enterprise Architect, then the workspace file is refreshed. This causes the entire model to be reloaded which might be a time-consuming task for big models. This option enables a data hash calculation on load which is stored together with the loaded model. As soon as an external file refresh is triggered, the data hash is re-calculated and only if it differs (which means that relevant data was modified), the model is re-loaded. Otherwise the loaded model is untouched. Please keep in mind that hash calculation produces a slight overhead (typically less than 1 second) to model loading and saving. This is why the option is disabled by default.
Open EA models read-only
When this option is enabled, EA models cannot be modified (unless this is explicitly specified via a load option), i.e. any changes made to the in-memory model are not stored to the eap-file. This option is enabled by default to prevent unsupported modifications (e.g. creation of a not supported element) via the UI (UML Model Editor). For programmatic access of a model, e.g. for writing the results of a model transformation to an eap-file, write-access can - irrespective of this preference - be enabled as outlined in the API section.
Abort on first error (use with caution!)
When this option is enabled, model loading is aborted on the first loading error, e.g. because the EA model is invalid. Examples for invalid models are maliciously formatted integer values (e.g. multiplicity), invalid type references, and invalid cross reference target types. There may be many more cases, depending on the actual model type. (more details in error handling section)
Report errors to Eclipse Error Log
When this option is enabled and Abort on first error is false (which is the default case), all errors that occur during loading or saving are reported to the Eclipse error log and are shown in the UI via the ErrorLog view. (more details in error handling section)
Report loading errors as Resource markers for the eap-file
When this option is enabled and Abort on first error is false (which is the default case), all loading errors (errors during saving are excluded here) are reported as resource markers at the eap-file. These error markers are shown in the UI via the Problems view. (more details in error handling section)

The Database Drivers preference page is explained in the Installation section.

There are further UML-specific options in the preference page UML as shown below.

EA-Bridge preferences page for UML

Store navigable association ends in Association.ownedEnd
When this option is enabled, navigable associations ends are always stored as ownedEnd (and navigableOwnedEnd) of the association. When this option is disabled, navigable association ends are stored as ownedAttributes of the opposite association end's type, if possible (only for Class, Interface, and DataType). (see UML Standard for details about this option)
Ignore built-in primitive type case
When this option is enabled, primitive types are loaded case-insensitively, otherwise wrongly cased primitive types are not resolved. Example: if the code engineering language is Java for a classifier and a type Float is entered for one of its attributes, then it is only resolved correctly if this option is enabled. However, if you have an equally-named type in your model which should be used as type, this setting might lead to a mismatch.
Ignore port conjugated flag for a single provided/required interface
For ports, provided/required interfaces can be specified via a type that has InterfaceRealizations and Usages to interfaces. If there is only one provided/required interface, it can directly be set as port type; if Port.isConjugated() is true, it is a required interface, if it is false, it is a provided interface. However, the Enterprise Architect has explicit (non-UML) elements to specify provided/required interfaces, independent of the actual port type. If there is a single such provided/required interface modeled, and the actual port type is unset, then this interface is loaded as port type be the YAKINDU EA-Bridge. This boolean option specifies, whether the conjugated flag should also affect such a single provided/required interface (this option is true) or not (this option is false).
Ignore unknown profiles
If this option is disabled, then load errors will be created for all stereotyped elements whose profiles are not found. (disabled by default)
Report model loading statistics
When any of these options is enabled, the YAKINDU EA-Bridge reports detailed model loading statistics to the selected locations; useful to analyze why a model takes a long time to load.
Report slow loading EA-Bridge extensions as warnings to Eclipse log
EA-Bridge extensions are supposed to load their contents fast, i.e. they should not take longer than loading the actual model. If there is an extension that takes longer, it will be reported as a resource load warning. If this option is set to false, such warnings are suppressed.
Supported EA languages as UML primitive type libraries (optional)
If custom code engineering languages are registered as primitive type libraries, they are listed here.

Most of these options can also be set as resource load options for programmatic access (more details in load options section).

UML Profiles can be loaded from multiple locations; the default locations used by Enterprise Architect installations are enabled by default.

EA-Bridge preferences page for UML Profile Locations

Search for EA profiles (XML) within the same resource
Enables profile lookup within dedicated DB entries of the same resource. (enabled by default)
Search for UML profiles in same resource
Enables profile lookup in the same resource. This means a lookup is performed within the eap-file. If the profile was found the search mechanism terminates. (disabled by default)
Search for EA profiles (XML) in files in same folder
Enables profile lookup within xml-files having following the format used in EA in the folder that contains the EAP-project. Again, if the profile was found the search mechanism terminates. (disabled by default)
Search for UML profiles in *.profile.eap / *.uml files in the same folder
Enables profile lookup within files having one of the two above mentioned extensions in the folder that contains the EAP-project. Again, if the profile was found the search mechanism terminates. (disabled by default)
Search for EA profiles (XML) in files in the enclosing Eclipse project
The search for profiles is done on the enclosing project. All subfolders are consulted and all found XML-files are inspected until the required profile was found. When a profile was found the search mechanism is terminated. (disabled by default)
Search for UML profiles in *.profile.eap / *.uml files in the enclosing Eclipse project
The search for profiles is done on the enclosing project. All subfolders are consulted and all found files matching the two extensions mentioned above are inspected until the required profile was found. When a profile was found the search mechanism is terminated. (disabled by default)
Search for EA profiles (XML) in custom 'MDG Technologies path' list
The search for profiles is done in all directories given in "MDGTechnology PathList". (disabled by default)
Search for EA profiles (XML) in user AppData subfolder
Enables profile lookup within xml-files following the format used in EA in the APPDATA directory that contains the EAP-project. Again, if the profile was found the search mechanism terminates. (disabled by default)
''Search for EA profiles (XML) in EA installation subfolder 'MDG Technologies' ''
Enables search for profiles within xml-files following the format used in EA in the 'MDG Technologies' subdirectory of the installation directory of the EA. Search mechanism terminates if the profile was found. (disabled by default)
Search for registered Eclipse UML profiles
UML Profiles can be registered in Eclipse. If this option is enabled this registry is considered. See help pages about how to register a UML profile in Eclipse. (enabled by default)

The UML concepts to be supported by the YAKINDU EA-Bridge can be restricted. This is useful because the disabled parts will not be loaded (which saves time) nor validated (which will avoid error reporting on these parts). The YAKINDU EA-Bridge is very often used to validate structural models e.g. for code or report generation. Typically, only specific parts of an EA model are relevant for this, so some UML concepts and/or specific packages may be excluded as described below.

EA-Bridge preferences page for UML coverage

Support for UML interactions
When this option is enabled, interactions are loaded. Please note that the YAKINDU EA-Bridge only provides limited support for interactions (e.g. one diagram per interaction element) and that not all concepts are supported (yet).
Support for UML state machines
When this option is enabled, state machines are loaded. Please note that the YAKINDU EA-Bridge only provides limited support for state machines and that not all concepts are supported (yet).
Support for UML activities
When this option is enabled, activities are loaded. Please note that the YAKINDU EA-Bridge only provides limited support for activities and that not all concepts are supported (yet).
Show hidden packages
When this option is enabled, UML packages with the tagged value EABridge-hidePackage set to true are not loaded by the YAKINDU EA-Bridge. Please note that this could lead to inconsistent models, e.g. if the hidden package contains cross-reference targets. Hidden packages can be shown again via the context menu on the parent package as explained below.

The nested UML preference page Extensions controls further EA-specific concepts that are not part of the UML standard. They are described below in the #Extensions section.

EA-specific Actions

The YAKINDU EA-Bridge provides additional EA-specific actions on EA models and their model elements.

Open with Enterprise Architect

The context menu on eap-files provides an action to open the Enterprise Architect with the selected file. This does only work on the Windows platform with the Enterprise Architect being installed.

Context menu on eap-files

Clear Error Markers

The YAKINDU EA-Bridge may - dependent on the preferences - create resource markers for all loading errors (more details below). Since there is no automated background job that cleans up these error markers in case the model has been fixed, this action may be used to remove all these error markers. If there are still errors in the model, the resource markers may of course re-appear when the EA-model is loaded the next time.

Open EA and Select Element in Project Browser

The action Open EA and Select Element in Project Browser on EA model elements is only available on the Windows platform with the 'EA Integration' feature and the Enterprise Architect being installed. This action opens the Enterprise Architect with the current model (if it is not already open) and selects the currently selected model element in the EA Project Browser.

Context menu on EA model elements

Get Selected Element in EA Project Browser

The action Get Selected Element in EA Project Browser on EA model elements is also only available on the Windows platform with the 'EA Integration' feature and the Enterprise Architect being installed. This action asks a running Enterprise Architect instance for currently selected model element in the EA Project Browser and selects the same element inside the Eclipse UML Editor.

Change EA Primitive Type Language

Each EA project has a default code engineering language configured (in EA, select Tools - Options - Source Code Engineering - Default Language for Code Generation). In addition, each EA element (roughly corresponding to sub-types of the UML meta class Classifier) may individually refine its code engineering language in its properties dialog as shown below. The important implication of that setting is the drop-down list of primitive types in all child elements; e.g. if the language of a Class is set to C++, then the available primitive types in all owned attributes are only C++ types.

EA code engineering language per model element

Change primitive type language in Eclipse

Keep in mind that the consequence of changing the language for an element affects all uses of primitive types in its child features. For example, if the language of Class1 in the figure above is changed to Delphi, then type int of the attribute becomes invalid. The Enterprise Architect does not validate that error; but the EA-Bridge does and produces a load error that will be promoted as explained in the error handling section.

Hide / un-hide Packages

Packages may be hidden such that they are not loaded anymore by the YAKINDU EA-Bridge. This is useful if the contents of particular packages is not of interest, e.g. because they contain documentation that is not relevant when processing the EA model in Eclipse. A package is hidden if it has the tagged value EABridge-hidePackage set to true. The action for hiding/un-hiding packages is only available on packages. The eap-file must be opened with write access to be able to write tagged values (can be enabled in the preferences).

Hide Package(s) in Eclipse
The above-mentioned tagged value will be added to all selected packages. When reloading the model (e.g. by re-opening the UML Model Editor), the packages are not shown anymore. This does not work on root models.
Un-hide Child Package(s) in Eclipse
If the selected packages contains sub-packages that are hidden (i.e. have the above-mentioned tagged value), then these tagged values will be removed. When reloading the model (e.g. by re-opening the UML Model Editor), the packages are shown again. This also works on root models.

Extensions

The YAKINDU EA-Bridge comes with a flexible extension mechanism that e.g. allows to represent EA-specific properties via EMF model annotations. All extensions are listed in the Extensions preference page and explained next.

EA-Bridge preferences page for UML extensions

Stereotype Resolution Strategies

UML profile and stereotype handling in the Enterprise Architect does not follow the UML convention, so it is possible to apply an arbitrary stereotype to an element regardless of whether they are defined in a profile or not. The correct way to apply stereotypes to EA elements is via the '...' button next to the stereotype text field in an element's property page, selecting a profile and stereotype as shown in the screenshot below.

Applying stereotypes in the Enterprise Architect

If the stereotype is not properly set with the '...' dialog (e.g. the stereotype name is manually typed into the text field), it is stored in the database without the information to which profile it might belong. This is where the Stereotype Resolution strategies come into play. Whenever stereotypes are found for an EA element, these strategies work as follows.

  1. If the preference option Resolve non-qualified stereotypes by searching for a unique match is enabled, all non-qualified stereotypes are loaded that can unambiguously be matched to stereotypes of registered Eclipse UML2 profiles via their simple names.
  2. The remaining fully qualified stereotypes (i.e. "<profile name>::<stereotype name>") are loaded if they exist in registered Eclipse UML2 profiles.
  3. All remaining stereotypes that could not be mapped to a registered UML profile, are reported as load errors.

Please note that additional strategies may be contributed (more details in API section).

EA-specifics as Annotations

There are a couple of EA-specific properties that are not part of the UML standard as already discussed in the introduction. The YAKINDU EA-Bridge ships with extensions that can load several of these properties as EMF annotations in the UML model. Examples are Fixed Value for parameters and Transient for attributes as shown in the UML Model Editor in the screenshot below. Please do not hesitate to contact us via email if you need access to further EA-specific properties.

EA-specific properties in the UML Model Editor

Furthermore, the YAKINDU EA-Bridge ships extensions to load EA requirements as model annotations and/or as stereotyped classes with stereotype properties as shown in the figure above.

Each of these extensions can be enabled or disabled via the preferences. It is also possible to contribute additional custom extensions, as explained here.

Error Handling

In case the YAKINDU EA-Bridge is not able to load or save an EA model to construct a proper UML model for it, so-called load or save errors occur. The preference settings Abort on first error, Report errors to Eclipse Error Log, and Report loading errors as Resource markers for the eap-file specify how such errors are handled. The following combinations are possible:

Abort on first error
If this option is set, the loading and saving process aborts on the first error by throwing an exception. Use this option with caution since the model does not load completely in case of an error. The other two options for error reporting are ignored.
Report errors to Eclipse Error Log
If this option is set, all errors that occur during loading or saving will be reported to the Eclipse Error Log. Abort on first error must be disabled for this to work.
Report loading errors as Resource markers for the eap-file
If this option is set, all load errors (save errors are excluded here) are added as resource markers and listed in the Eclipse Problems View. Abort on first error must be disabled for this to work. The resource markers are persistent and may be cleaned manually by the Clear Error Markers action.

The latter two reporting options can be combined. It is also possible to deactivate error reporting entirely, but then there is no indicator anymore whether the model is loaded/saved correctly.

These options can also be used as resource load options for programmatic access (as explained here).

The default UML Model Editor also shows load errors and warnings in its Problems tab. It is still possible to switch back to the Selection tab to browse the loaded model. The button Open with Text Editor opens a read-only text editor with a database dump of the EA database contents for low-level review of the model.

The UML Model Editor shows load errors in the problems tab