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.
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.
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. Requirement
s and GUIElement
s).
The figure below sketches these sets of meta classes.
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:
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.
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.
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).
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.
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.
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
.
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.
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.
t_trxtypes
and t_document
)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.
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):
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.
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:
SimpleExampleStereotype
applied.ComplexExampleStereotype
applied.ComplexExampleStereotype
applied (the values of additional stereotype properties are stored as tagged values).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:
ComplexExampleStereotype
(including cross-references to other model elements) are correctly loaded as shown in the properties view below.