Introduction

Overview

The YAKINDU EA-Bridge provides quick and efficient access to models that were created and are managed by the Sparx Systems Enterprise Architect (subsequently referred to as Enterprise Architect or EA) from within Eclipse. That is, using the YAKINDU EA-Bridge your EA models are accessible as if they were regular (Eclipse UML2) models. Operations such as creating, loading, and modifying models can (with few technical limitations) be performed transparently.

The YAKINDU EA-Bridge can be used as a transparent adapter between your EA models and arbitrary Eclipse Modeling based tools. Code generation, model-to-model transformation, model validation, and headless model processing (e.g. for automated report generation) can thus be realized without introducing any direct dependencies to the EA model format.

YAKINDU EA-Bridge as adapter between EA and Eclipse UML2 tooling

This documentation covers conceptual aspects, the user interface, and the API and extension points of the YAKINDU EA-Bridge. The examples and development tools also provide respective documentation, in case they are installed.

Supported UML Elements and their Properties

The UML in general is a modeling language that includes 242 meta classes (UML 2.4.1). The Eclipse UML2 implementation conforms to the UML standard and implements all of them. The Enterprise Architect, on the other hand, has its own internal meta model to represent UML models. Many EA meta classes can directly be mapped to UML meta classes (e.g. Class, Operation, and Dependency), but there are also meta classes that can not directly be mapped (e.g. an Association in UML has Properties as association ends whereas the EA includes their information in the meta class Association). In addition, the Enterprise Architect supports further modeling concepts that do not exist in the UML standard (e.g. Requirements and GUIElements). The figure below sketches these sets of meta classes.

Overview of supported UML concepts

Eclipse UML2 implements the entire set of UML meta classes whereas the Enterprise Architect defines its own meta classes. All meta classes that can directly (e.g. Class and Operation) or indirectly (e.g. Association) be mapped, are denoted by set 2. Meta classes denoted by set 1 are part of the UML standard but are not covered by the EA meta model (e.g. InterfaceRealization and n-ary associations). Meta classes denoted by set 3 are EA-specific and not part of the UML standard (e.g. Requirement and GUIElement).

This discrepancy implies that it is not possible to completely map EA models to UML2 models (or vice versa). The YAKINDU EA-Bridge handles these cases as follows:

  1. UML concepts that can directly or indirectly be mapped to EA concepts are automatically converted.
  2. UML concepts that are not supported in EA are either forbidden or stored as EA tagged values.
  3. EA meta classes that are not part of the UML standard are either ignored or represented as model annotations.

A complete list of EA-specific properties that are loaded as annotations is given in the user interface section.

The YAKINDU EA-Bridge does not yet cover the entire UML meta model (we will increase the set of covered meta classes in future versions). It is currently limited to support structural modeling concepts that are usually used within class, component, and composite structure diagrams. A complete list of supported UML meta classes is listed here. If you request specific meta classes or features, please contact us. Please be aware that the YAKINDU EA-Bridge - like the Eclipse UML2 implementation - does not target the exchange of diagram information but is limited to the underlying model data.

File and Resource Handling

Eclipse UML2 files (file extension uml) are stored as XMI files in an XML-based persistence format. Loading UML2 models (when accessing them by any Eclipse tooling) is done by loading the XMI contents from a uml-file and parsing it to an in-memory model (see EMF help for details). Saving UML2 models is in turn done by serializing the in-memory model back to XMI and storing this into a uml-file.

The idea of the YAKINDU EA-Bridge is to work with EA models in Eclipse as if they were plain Eclipse UML2 models. However, Enterprise Architect project files (file extension eap) are Microsoft Access database files (see also Enterprise Architect User Guide), which introduces some technical limitations.

Loading eap-files with the YAKINDU EA-Bridge can still be performed similar to loading uml-files: the database is queried while constructing the model in memory. In versions prior to 3.0.0, the YAKINDU EA-Bridge supported lazy loading which was very slow and did not yield satisfactory results. To give an example, loading a model with 20.000 model elements lazily took several minutes because of the large amount of database queries; loading the same model completely in version 3.0.0 takes less than 5 seconds (because only few database queries are needed), no matter whether the model is located in a local eap file or in a remote database.

When modifying EA models via the YAKINDU EA-Bridge, a database transaction is created and database updates are performed within this transaction. In contrast to the Enterprise Architect (which does not have a dirty state when modifying the model - all changes are immediately written to the database), the YAKINDU EA-Bridge commits the transaction to the database not before the file is explicitly saved. If the file is closed without saving, the transaction is not committed and the updates are not applied to the database. This might yield conflicts when an eap-file is modified simultaneously by the Enterprise Architect and within Eclipse; the transaction commit may fail. External changes of the eap-file are detected within Eclipse as soon as the timestamp of the file changes if enabled in the preferences, which in turn will cause the Eclipse editor to re-load the model (and discard the current transaction, if there is one). This is, by the way, the default behavior in most Eclipse-based editors.

You should always reload a file when it has been modified externally

There are several technical limitations when editing eap-files via the YAKINDU EA-Bridge, e.g. with the default tree-based UML Model Editor:

Due to these limitations, all eap-files are opened read-only by default with the YAKINDU EA-Bridge (can be changed in the preferences).

Cross References to other Models

Eclipse UML2 models may span several (fragment) resources, and Eclipse UML2 resources may cross-reference each other. However, the Enterprise Architect does not allow any kind of cross-references to other files. Here, a UML model is always limited to the scope of exactly one project file (or database). This is why cross-references to elements outside an EA model can not be supported by the YAKINDU EA-Bridge.

The only two exceptions are UML profiles and primitive type libraries that are also known by the Enterprise Architect. UML profiles are briefly explained below, primitive type libraries are explained in detail here.

UML Profile Support

The UML standard defines an extension mechanism called profiles which allows to augment the UML by additional concepts that cannot be expressed in the standard scope, e.g. to better suit a certain application domain (see section 18 in UML Superstructure). A profile contains a set of stereotypes, which represent refined concepts. They extend UML meta classes and may add additional properties and relationships.

Example UML Profile

The following example profile (definitions in Eclipse as well as EA are shown in the screenshots below) is taken from the (example feature), in case it is installed (can also be installed later). The profile is called ExampleProfile and contains two stereotypes SimpleExampleStereotype and ComplexExampleStereotype. The former is only applicable to the meta class Class whereas the latter is applicable to a large number of meta classes. Unfortunately, the Enterprise Architect is not able to apply stereotypes to subclasses of the respective stereotype; for instance, SimpleExampleStereotype is not applicable to UML components (within UML Component is a subclass of Class). This is why all concrete meta classes must be explicitly extended as shown in the EA screenshot below. Furthermore, ComplexExampleStereotype also has a number of properties like enumAttribute and singleRef.

An example UML profile in Eclipse An example UML profile in Enterprise Architect

Stereotype properties like ComplexExampleStereotype.boolAttribute and ComplexExampleStereotype.enumAttribute are modeled as regular UML properties in Eclipse and the EA. References to other model elements (like ComplexExampleStereotype.refSingle) are modeled differently in the EA; instead of regular properties, a «taggedValue»-stereotyped directed association to the referenced type must be created (the EA toolbox provides a tool for this association).

Please consult the online documentation of Sparx Systems to learn more about how to define, import, and use UML profiles in the Enterprise Architect.

Location of UML Profiles

Whenever a model with stereotyped elements is loaded, the applied stereotype and the owning profile must also be loaded. The following locations for UML profiles are supported by the YAKINDU EA-Bridge:

The search mechanism to find profiles can be configured in the preferences. The search for an profile name is performed in the following order and terminates on the first match.

  1. EA profiles in embedded xml entities inside the same eap-file that is loaded (tables t_trxtypes and t_document)
  2. UML profiles in the same eap-file that is loaded
  3. EA profiles in ''*.xml' sibling files (in the same folder as the eap-file is located)
  4. UML profiles in .profile.uml/eap sibling files
  5. EA profiles in ''*.xml' files in the same workspace project (and in any of its subfolders)
  6. UML profiles in .profile.uml/eap files in the same workspace project (and in any of its subfolders)
  7. EA profiles in ''*.xml' MDG technology files in the users application data folder (see environment variable "APPDATA")
  8. EA profiles in ''*.xml' MDG technology files located in one of the users search path entered in EA
  9. EA profiles in ''*.xml' MDG technology files located in the installation directory of EA
  10. UML profiles in the UML2 profile registry (see below)

The search terminates as soon as in any of the four steps above, a profile with a matching name (ignore case) is found. If there are multiple matching profiles in that step (e.g. multiple equally named profiles in the same eap-file), then the first profile is used and a load warning is reported with a list of all other profiles that have also been found.

Definition of a UML Profile

When integrating the YAKINDU EA-Bridge into an Eclipse-based tool chain, UML profiles should be provided as Eclipse UML registered profiles. To do so, please create a new plugin project and follow the steps below in this guide on the Eclipse wiki (only the UI parts, you typically don't need the code snippets):

  1. Create a new Eclipse plugin project.
  2. Create a profile
  3. Import Primitive Types (optional, only if your stereotypes should have properties - tagged values in EA)
  4. Create Enumerations and Literals (optional, only if you need enumerations)
  5. Create Stereotypes
  6. Create Stereotype Generalizations (optional, only if you want stereotypes that inherit from each other)
  7. Create Stereotype Properties (optional, only if your stereotypes should have tagged values)
  8. Reference Metaclasses
  9. Create Extensions
  10. To make sure that your profile does not violate any UML constraints, right-click it and select Validate - if there are issues, solve them!
  11. Define your Profile

Now you should save your profile and register it as an extension in plugin.xml (adjust location to match the file location and uri to match the NsUri attribute of your profile):

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
  <extension point="org.eclipse.uml2.uml.dynamic_package">
    <profile
        location="platform:/plugin/com.yakindu.bridges.ea.examples/resources/example.profile.uml#_OfDcwTwqEiGQsoes7YN-_x"
        uri="http://com.yakindu.bridges.ea.examples/exampleprofile/1.0.0">
    </profile>
  </extension>
</plugin>

Run your plugin either in a new runtime, deploy it directly into your running Eclipse instance, or export it into some directory.

Usage of UML Profiles

The regular usage of UML profiles as defined in the UML standard (also explained on the Eclipse wiki) is as follows: first, a profile must be applied to a package; second, stereotypes of that profile may be applied to model elements that are nested within the profiled package; third, additional stereotype-specific properties may be set for the stereotyped model elements (tagged values). However, this procedure is not implemented in the Enterprise Architect. There, stereotypes can be applied to any compatible model element regardless of whether a profile is applied to the nearest package or not. The figure below shows an example with profiled model elements:

Profiled UML model elements in the Enterprise Architect

In order to load profiled UML models with the YAKINDU EA-Bridge, the exact same profile must be registered in Eclipse (the article "Introduction to UML2 Profiles" explains how this is done). Then the model is loaded as shown in the figure below:

Profiled UML model in Eclipse