API and Extension Point Reference

Compliance to the Eclipse UML2 API and Programmatic Access

This section explains the compliance of the YAKINDU EA-Bridge API to the Eclipse UML2 API. In general, EA models can be handled the same way as Eclipse UML2 models as explained in the UML2 Developer Guide. However, there are situations where the YAKINDU EA-Bridge behavior is slightly different from that of Eclipse UML2, as explained in the following.

Creating Models

Instead of the wizard UML Model in category Example EMF Model Creation Wizards, the wizard New EAP File in category YAKINDU EA-Bridge must be used to create a new EA model (more details in the user interface section).

New EAP File wizard

Unlike regular Eclipse UML models, the only valid root element in EA models is of type Model; the types Profile and Package are not allowed as roots in EA models. Also, the default EA code engineering language must be specified, which defines the set of primitive types available in the Enterprise Architect (more details below). The root model is named Model, which can be changed (if write access is enabled) via the Properties view.

Editing the new EAP file

The corresponding code for creating a new model and for loading an existing model programmatically is shown below. This functionality is provided by the Eclipse Modeling Framework (EMF) and applies to most models in Eclipse. This code assumes that the UML package is already registered, e.g. the code is running inside a plug-in in the Eclipse platform.

// create a new UML model
final Model model = UMLFactory.eINSTANCE.createModel();
model.setName("New Model");
model.createNestedPackage("New Package");
// save it in a new eap-file
final ResourceSet set = new ResourceSetImpl();
final URI uri = URI.createPlatformResourceURI("/SampleProject/sampleModel.eap", true);
final Resource eaResource = set.createResource(uri);
eaResource.getContents().add(model);
eaResource.save(Collections.singletonMap(EAResource.OPTION_READONLY, Boolean.FALSE)); // save with write support if not already set in global preferences
// load a model from an existing eap-file
final URI uri = URI.createPlatformResourceURI("/SampleProject/sampleModel.eap", true);
final Resource eaResource = EAResourceUtils.loadEAResourceSilent(uri, false, true, new NullProgressMonitor());
final List<Model> rootModels = new ArrayList<Model>();
for (EObject root : eaResource.getContents()) {
	if (root instanceof Model)
		rootModels.add((Model)root);
}

All API used in the code above is provided by EMF, so please consult the EMF help for details. The only exception is a resource load option (OPTION_READONLY), explained below. Saving an eap-file as uml-file or vice versa (saving a uml-file as eap-file) works in principle but may be incomplete if not all cross references (EMF proxies) could be resolved due to inconsistencies in the EA model - this applies to both, the programmatic as well as UI-based action (save-as in the UML Model Editor).

// save an eap-file as uml-file
final URI eapUri = URI.createPlatformResourceURI("/SampleProject/sampleModel.eap", true); // must exist
final URI umlUri = URI.createPlatformResourceURI("/SampleProject/sampleModel.uml", true); // does not exist
final Resource eaResource = EAResourceUtils.loadEAResourceSilent(eapUri, false, true, new NullProgressMonitor());
ResourceSet set = eaResource.getResourceSet();
final Resource umlResource = set.createResource(umlUri);
umlResource.getContents().addAll(eaResource.getContents());
set.getResources().remove(eaResource); // remove EA resource from resource set, otherwise the model might be deleted
umlResource.save(null); // save the new UML resource		

One more thing must be respected when adding multiple elements with cross-references to a connected EA model! The YAKINDU EA-Bridge sorts the elements prior to adding them to the database such that cross-references are always stored correctly. This requires that all cross-referenced model elements must be added at once (no matter whether they are nested or not), e.g. via package.getPackagedElements().addAll(elementsToAdd). The UML has several derived feature lists, e.g. package.getNestedPackages which subsets the packaged elements feature; these subsetted list implementations (DerivedEObjectEList) split an addAll call to multiple add calls. But this splitting might fail with above-mentioned strategy of the EA-Bridge if there are cross-references between the individual elements. Using package.getPackagedElements().addAll(elementsToAdd) works though.
The general advice is: do not use the subsetted derived lists when adding multiple elements but always the original containment feature.

Detailed model handling such as creating packages, interfaces, or any other kind of UML elements, is documented in the UML2 Developer Guide and does not differ for EA models, with several exceptions that are discussed below:

As soon as the resource is saved, all model elements are written into the database and are connected. That means, as soon as they are modified or deleted, the database is updated as described in the file and resource handling section. So before the initial save, the entire model only exists in-memory and no database operations occur. After the initial save, all model elements are connected to the database and are mapped to EA model elements.

Relationships in EA Models

The UML standard contains different kinds of relationships that are represented differently. Association and Dependency, for example, are packageable elements that may be contained in any package and relate to arbitrary many model elements. Generalizations and InterfaceRealizations, for example, are not packageable elements but may be contained in Classifiers and BehavioredClassifieres respectively, and relate the owner to arbitrary many model elements. Please consult the UML standard for further details.

The Enterprise Architect, on the other hand, only supports binary relationships (i.e. relationships between exactly two model elements), with the single exception of n-ary associations (which are represented as nodes). Furthermore, the Enterprise Architect does not have the concept of single relationship owners but it always requires both connected model elements. If any of the two model elements is deleted, then the relationship is also deleted. If a new relationship should be created, both connected model elements must already exist in the model.

This is an important constraint when working with EA models via the YAKINDU EA-Bridge, because relationships with more or less than two related elements cannot be expressed in EA models. Binary relationships can be created with the YAKINDU EA-Bridge as follows (n-ary associations will be supported in a later version of the YAKINDU EA-Bridge).

  1. The association must be created with its including association ends referring to the related elements before the association is added to the EA model. The reason is that association ends, which are regular UML Properties, are part of the EA association and thus not stored as Properties in the EA database.
  2. The association must be added to the EA model at once, i.e. with a single add(..) or addAll(..) call. This is the only way the YAKINDU EA-Bridge is able to store the association properly into the EA database.

Unfortunately, creating associations this way is not possible with the Default UML Model Editor out of the box. The typical way of creating an association programmatically, however, is as follows.

// first create association and association ends as owned ends
final Association assoc = UMLFactory.eINSTANCE.createAssociation();
final Property end1 = assoc.createOwnedEnd("end1", type1); // type1 must already exist in the model!
final Property end2 = assoc.createOwnedEnd("end2", type2); // type2 must already exist in the model!
// optional: if an end should be navigable, add it to 'navigableOwnedEnds'
assoc.getNavigableOwnedEnds().add(end1);
// add association including association ends to the EA model as the last step
myPackage.getPackagedElements().add(assoc);

Since version 1.1, all other supported relationships (e.g. Dependencies and Realizations) may be created without their references being set. The temporary invalid model will be reported by the YAKINDU EA-Bridge as warnings, but as soon as the references to the connected elements are set to valid model elements, the warnings will be removed again.

Operation Return Parameters in EA Models

The UML standard defines the return type of an operation as follows: "If this operation has a return parameter, type equals the value of type for that parameter; otherwise, type is not defined." (section about operations in the UML standard) In other words, an owned parameter with the direction return defines the return type of the operation.

The Enterprise Architect is also capable of modeling owned parameters with the direction return, but they are not used to define the operation return type. Instead, the EA operation itself has a direct reference to a type as shown in the screenshot below: YourEnumeration is the operation return type whereas the only owned parameter has YourStruct as type.

EA operation properties specify the operation return type directly

The YAKINDU EA-Bridge converts this EA operation into a well-formed UML operation as shown in the screenshot below: two parameters exist, param1 as a regular parameter with direction in and the unnamed parameter with direction return (direction is indicated by the parameter icon). The operation signature is derived accordingly.

UML operation specify the return type via return parameter

The YAKINDU EA-Bridge encapsulates this conversion. Programmatically created return parameters are automatically saved as EA operation return types and vice versa.

Stereotype Applications in EA Models

The Eclipse UML2 implementation stores stereotype applications within the root content list of the UML resource, no matter where the stereotyped elements are located in the model. The stereotype application contains a reference to the stereotyped model element (not the other way around).

In versions prior to 3.0.0, a dedicated in-memory resource was used to manage stereotype applications, but this is obsolete with the revised loading mechanism. Since version 3.0.0, the YAKINDU EA-Bridge loads all stereotype applications into the resource contents list (just like Eclipse UML2).

Resource Load Options

The YAKINDU EA-Bridge provides several ways for configuring and customizing the access of EA models. This section explains several load options (whereas extension points are explained below). The simplest way of using resource load options is to set them in the surrounding resource set as already shown above:

resourceSet.getLoadOptions().put(EAResource.OPTION_READONLY, Boolean.FALSE);
Load OptionTypeDefaultDescription
OPTION_READONLYBooleanTRUEWhether or not modifications of the model will be written to the database. Enable this option for creating and modifying EA models. Read the introduction carefully before modifying EA models. This load option overwrites the global preference option.
OPTION_USERNAMEStringnullIf the EA database requires a username and password, it may be specified together with load option OPTION_PASSWORD.
OPTION_PASSWORDStringnullIf the EA database requires a username and password, it may be specified together with load option OPTION_USERNAME.
OPTION_PROGRESS_MONITORIProgressMonitornullWhen a progress monitor is set, loading and saving is reported to that monitor. Both tasks may also be canceled via the progress monitor.
OPTION_DB_DRIVERStringnullA specific database driver may be specified here if there are multiple database drivers available for a particular EA model, e.g. for MSSQL databases. The value must be the label as shown in the preferences.
OPTION_RELOAD_ONLY_ON_HASH_CHANGEStringFALSEIf 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. This load option overwrites the global preference option.
OPTION_DB_DRIVERStringnullA specific database driver may be specified here if there are multiple database drivers available for a particular EA model, e.g. for MSSQL databases. The value must be the label as shown in the preferences.
OPTION_ABORT_ON_FIRST_ERRORBooleanFALSEWhen set to TRUE, loading / saving aborts immediately if an error or warning occurs. Otherwise loading / saving is performed as good as possible. For more details, see error handling section. This load option overwrites the global preference option.
OPTION_REPORT_TO_ERROR_LOGBooleanFALSEWhen set to TRUE, all loading / saving warnings and errors are reported to the Eclipse error log. For more details, see error handling section. This load option overwrites the global preference option.
OPTION_REPORT_AS_RESOURCE_MARKERSBooleanTRUEWhen set to TRUE, all loading / saving warnings and errors are reported as Eclipse resource markers on the eap-file. The resource marker type is defined in IEAUMLConstants.EA_UML_ERROR_MARKER_TYPE. For more details about resource markers, see resource markers; for more details about error handling in the YAKINDU EA-Bridge, see error handling section. This load option overwrites the global preference option.
OPTION_LOCK_TYPE
(only for local eap-files)
StringACCESSThis option is only relevant when writing or updating local eap-files. The database driver for local eap-files supports file access while other applications (like the Enterprise Architect) may also access (and possibly modify) the same file. As a consequence, the database driver should lock access to the tables to be modified to avoid inconsistent data.
OPTION_TAGGED_VALUE_NOTESBooleanTRUEWhen this option is disabled, tagged value notes are not loaded or saved. This load option overwrites the global preference option.
OPTION_DUPLICATE_TAGGED_VALUE_KEYSBooleanFALSEWhether or not to allow loading tagged values with duplicate keys. Since tagged values are loaded as EAnnotations, entries with duplicate keys are technically possible but reported as validation error. So keep in mind that when enabling this option, tagged values with duplicate keys will yield validation issues. This load option overwrites the global preference option.
UML_LOAD_CONCURRENT_THREADSInteger1With this option, the YAKINDU EA-Bridge loads data from the database concurrently in n threads. This typically results in better performance on large and slightly worse performance on small models. This load option overwrites the global preference option for UML.
UML_IGNORE_PRIMITIVE_TYPE_CASEBooleanFALSEWhen this option is enabled, primitive types are loaded case-insensitively, otherwise wrongly cased primitive types are not resolved. This load option overwrites the global preference option for UML.
UML_ASSOCIATION_OWNS_ENDSBooleanFALSEWhen 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). This load option overwrites the global preference option for UML.
UML_SUPPORT_INTERACTIONSBooleanTRUEWhen this option is enabled, UML interactions are loaded by the YAKINDU EA-Bridge with some limitations; for example, interaction diagrams must always be contained in an interaction element and there must only be one diagram per interaction. Moreover, not all concepts are supported (yet). This load option overwrites the global preference option for UML Coverage.
UML_SUPPORT_STATE_MACHINESBooleanTRUEWhen this option is enabled, UML state machines are loaded by the YAKINDU EA-Bridge to some extent; not all concepts are supported (yet). This load option overwrites the global preference option for UML Coverage.
UML_SUPPORT_ACTIVITIESBooleanTRUEWhen this option is enabled, UML activities are loaded by the YAKINDU EA-Bridge to some extent; not all concepts are supported (yet). This load option overwrites the global preference option for UML Coverage.
UML_SHOW_HIDDEN_PACKAGESBooleanFALSEWhen this option is enabled, UML packages with the tagged value EABridge-hidePackage set to true are not loaded by the YAKINDU EA-Bridge. For more details, see section about hiding packages. This load option overwrites the global preference option for UML.
UML_LOAD_WARNING_SLOW_EXTENSIONSBooleanTRUEEA-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. This load option overwrites the global preference option for UML.
UML_IGNORE_UNKNOWN_PROFILESBooleanFALSEWhen this option is disabled, load errors will be created for all stereotyped elements whose profiles are not found. See help pages about how to load UML profiles in Eclipse.
UML_PROFILE_LOOKUP_IN_SAME_RESOURCEBooleanFALSEIf this option is enabled, UML profiles in the same resource (eap-file) will be considered. For more details, see preference options for UML Profile Locations.
UML_PROFILE_LOOKUP_IN_SAME_RESOURCE_AS_XMLBooleanFALSEIf this option is enabled, XML profiles in the same resource (eap-file, imported via EA 'Resources' view) will be considered. For more details, see preference options for UML Profile Locations.
UML_PROFILE_LOOKUP_IN_SAME_FOLDERBooleanFALSEIf this option is enabled, sibling files in the same folder of the eap-file with extension .profile.eap and .profile.uml are searched (before files that are located elsewhere in the same workspace project). If multiple matching profiles are found, a warning is reported and the first one is used. For more details, see preference options for UML Profile Locations.
UML_PROFILE_LOOKUP_IN_SAME_FOLDER_AS_XMLBooleanFALSEIf this option is enabled, sibling files in the same folder of the eap-file with extension .xml are searched (before files that are located elsewhere in the same workspace project). If multiple matching profiles are found, a warning is reported and the first one is used. For more details, see preference options for UML Profile Locations.
UML_PROFILE_LOOKUP_IN_SAME_PROJECTBooleanFALSEIf this option is enabled, files with extension .profile.eap and .profile.uml are searched in the enclosing project of the eap-file for defined profiles. There is no special search order in this case. If multiple matching profiles are found, a warning is reported and the first one is used. For more details, see preference options for UML Profile Locations.
UML_PROFILE_LOOKUP_IN_SAME_PROJECT_AS_XMLBooleanFALSEIf this option is enabled, files with extension .xml are searched in the enclosing project of the eap-file for defined profiles. There is no special search order in this case. If multiple matching profiles are found, a warning is reported and the first one is used. For more details, see preference options for UML Profile Locations.
UML_PROFILE_LOOKUP_IN_CUSTOM_PATHLISTBooleanTRUE (on Windows), FALSE (otherwise)In the Enterprise Architect MDG Technology management view, custom paths can be entered which will be stored inside the Windows registry. If this option is enabled, that path list is searched for profiles contained in MDG Technology files (only available on Windows). For more details, see preference options for UML Profile Locations.
UML_PROFILE_LOOKUP_IN_APPDATABooleanTRUE (on Windows), FALSE (otherwise)In the Enterprise Architect Resources view, MDG Technology files can be imported 'to the User', which means that they will be stored in a subfolder of the user's AppData folder. If this option is enabled, that location is searched for profiles contained in MDG Technology files (only available on Windows). For more details, see preference options for UML Profile Locations.
UML_PROFILE_LOOKUP_IN_INSTALLPATHBooleanTRUE (on Windows), FALSE (otherwise)The Enterprise Architect loads all MDG Technology files from subfolder 'MDGTechnologies' of its installation folder. If this option is enabled, that location is searched for profiles contained in MDG Technology files (only available on Windows). For more details, see preference options for UML Profile Locations.
UML_PROFILE_LOOKUP_IN_REGISTERED_PROFILESBooleanTRUEIf this option is enabled, registered profiles are considered. For more details, see help pages for profile support for UML Profile Locations.

These options are obsolete and have been removed: EA_CONTENT_FACTORY, OPTION_LAZY_LOADING, OPTION_EXPERIMENTAL_FEATURES, OPTION_REPLICA_WRITABLE, UML_LOADING_STATISTICS_AS_INFO_STATUS.

Extension Points

The following extension points can be used for providing additional functionality to the YAKINDU EA-Bridge.

Extension Point Name and IDTypeDescription
Resource Adapter:
com.yakindu.bridges.ea.core.resourceAdapter
AdapterResource adapter extensions are registered at all EAResource instances, for example to set specific default load options. Please see an example in the extension point definition.
Primitive Types Library:
com.yakindu.bridges.ea.uml.primitiveTypesLibrary
name and URIThe Enterprise Architect uses code engineering languages to define the set of built-in primitive types as explained in the UI section. The default ones are already provided by the YAKINDU EA-Bridge. If custom code engineering languages are used in EA models, they must be registered for the YAKINDU EA-Bridge. This is done with this extension point by providing the exact same name as the code engineering language in EA and a URI that points to a UML primitive type library containing the exact same primitive types as the code engineering language in EA.
Stereotype Resolution Strategy:
com.yakindu.bridges.ea.uml.stereotypeResolutionStrategy
IStereotypeResolverThe Enterprise Architect does not validate whether a stereotype is correctly applied or not as already explained in the user interface section. In case a stereotype cannot be resolved via its fully qualified name, the default stereotype resolver tries to find an unambiguous match in all registered profiles. This extension point allows custom stereotype resolvers to provide custom matchings of EA model stereotypes to specific stereotypes of registered UML profiles.
Element Contributor:
com.yakindu.bridges.ea.uml.elementContributor
IElementContributorThis extension point provides a mechanism to extend and influence the loading and saving of EA models. Extensions may load additional elements (such as EAnnotations), suppress the loading of regular elements, and perform additional save operations such as writing additional information to the database. All EA-specific annotations, for instance, are element contributors. See Javadoc of IElementContributor for further details of how to implement an element contributor.

Primitive Type Libraries

UML primitive type libraries are UML model files with the file extension .library.uml. Similarly, the YAKINDU EA-Bridge loads an additional (read-only) in-memory resource for an eap-file that contains all available built-in data types. For example, loading a file MyProject.eap, all built-in types will be loaded in a resource MyProject.library.eap inside the same resource set. The screenshot below shows such an example. The file extension is also available programmatically as a constant in IEAUMLConstants.EA_DATATYPES_FILE_EXTENSION, the resource can be retrieved via EAResourceUMLUtils.getEADatatypesResource(EAResource).

Built-in primitive type libraries of EA models

The Enterprise Architect allows to specify custom code engineering languages containing custom primitive types. To add support for such custom primitive types in the YAKINDU EA-Bridge, a corresponding UML primitive types library must be provided and registered via the Primitive Types Library extension point. The extension point and library name name must match the name of the EA code engineering language. The URI is typically a platform-plugin URI as shown in the example of the extension point definition.

HTML Text of Comments

Enterprise Architect supports different link types in notes. A note is persisted as HTML text where each link contains an EA specific prefix according to its link type. In the Eclipse UML2 implementation, notes are accessed via org.eclipse.uml2.uml.Comment#getBody(). The result is the raw HTML text with the EA-specific links.

A general conversion of all links in a UML model by the YAKINDU EA-Bridge is not desired, because a UML model might be processed by different applications with different link handling. Therefore, each application has to convert links each time when the body of a comment is accessed. The link conversion should be done with an instance of com.yakindu.bridges.ea.core.utils.EANotesLinkConverter or an application-specific subclass. By default, the EANotesLinkConverter removes all links except file links which are not manipulated by EA, and web site links for which the HTTP protocol is used.

Comment comment = /* ... */
EANotesLinkConverter converter = new EANotesLinkConverter() {
	@Override
	protected String convertPackageLink(String destination, String linkText) {
		return linkText; // Replace link by its text.
	}
	@Override
	protected String convertElementLink(String destination, String linkText) {
		return buildLink("newDestination", linkText); // Replace destination of link.
	}
};
String comment = converter.convertLinks(comment.getBody());

The link types supported by EANotesLinkConverter are:

EA Link TypePrefixConverted ByExample
Attribute$feature://convertAttributeOrOperationLink(String, String)<a href="$feature://{A729AEA1-3E70-4199-83DC-5BE43721019F}"><font color="#0000ff"><u>attribute</u></font></a>
Browse for File$path=convertBrowseFileLink(String, String)<a href="$path=C:\kostal-sweng\tools\eclipse-committers-oxygen-2-win32-x86_64"><font color="#0000ff"><u>browseForFile</u></font></a>
Diagram$diagram://convertDiagramLink(String, String)<a href="$diagram://{143D4036-F381-4543-AC95-57C31A1504DA}"><font color="#0000ff"><u>diagram</u></font></a>
Diagram Image$diagramimg://convertDiagramImageLink(String, String)<a href="$diagramimg://{143D4036-F381-4543-AC95-57C31A1504DA}"><font color="#0000ff"><u>diagramImag</u></font></a>e
EA Command$uicmd=convertEACommandLink(String, String)<a href="$uicmd=ActivateTechnology;param1=MEEP"><font color="#0000ff"><u>eaCommand</u></font></a>
Element$element://convertElementLink(String, String)<a href="$element://{9BDC1FEA-3BD5-4195-8330-1DA53F813826}"><font color="#0000ff"><u>element</u></font></a>
Element Image$elementimg://convertElementLink(String, String)<a href="$elementimg://"><font color="#0000ff"><u>elementImage</u></font></a>
FileNot available, because link destination is not modified by EA<a href="C:\Test.html"><font color="#0000ff"><u>file</u></font></a>
Help$help://convertHelpLink(String, String)<a href="$help://www.google.de"><font color="#0000ff"><u>help</u></font></a>
Image Manager$imageman://convertImageManagerLink(String, String)<a href="$imageman://id=1083648271;mdg=Global;name=DoorsLink.png;type=Bitmap;"><font color="#0000ff"><u>imageManager</u></font></a>
Learning Center$learning://convertLearningCenterLink(String, String)<a href="$learning://{13C58F9E-501B-4fbc-B527-5488B2D0CBDE}"><font color="#0000ff"><u>learningCenter</u></font></a>
Matrix$matrix://convertMatrixLink(String, String)<a href="$matrix://"><font color="#0000ff"><u>matrix</u></font></a>
Operation$feature://convertAttributeOrOperationLink(String, String)<a href="$feature://{8FFB4DAC-5782-4a74-AAA9-2FA84F004FB8}"><font color="#0000ff"><u>operation</u></font></a>
Package$package://convertPackageLink(String, String)<a href="$package://{3F883307-D07B-4462-95AC-C3238BD63E6D}"><font color="#0000ff"><u>package</u></font></a>
Search$search://convertSearchLink(String, String)<a href="$search://Name=Simple;Term=test;"><font color="#0000ff"><u>search</u></font></a>
Team Review$forum://convertTeamReviewLink(String, String)<a href="$forum://"><font color="#0000ff"><u>teamReview</u></font></a>
Web Site$inet://convertWebSiteLink(String, String)<a href="$inet://www.google.de"><font color="#0000ff"><u>webSite</u></font></a>
unsupported prefixconvertUnsupportedEALink(String, String)