Reading Extensions

Enterprise Architect extensions

An Enterprise Architect model, exported from Enterprise Architect, can be divided into two parts:

Here is a sample xml file exported from Enterprise Architect:
<uml:Model xmi:type="uml:Model" name="EA_Model" visibility="public">
...
</uml:Model>
<xmi:Extension extender="Enterprise Architect" extenderID="6.5">
...
</xmi:Extension>
The extension section contains additional data relative to model elements:

Those sections contains XML Tags representing extension of a model element:
For instance: 

   <element xmi:idref="EAID_19A79944_2484_4e77_A373_D50FE935071B" xmi:type="uml:Text" name="Text" scope="public">
    <model package="EAPK_1FA6553F_CF5C_486f_BD38_8E7C24F0D7CE" tpos="0" ea_localid="2164" ea_eleType="element" name="Text"/>
    <properties documentation="Using Images on Elements" isSpecification="false" sType="Text" nType="0" scope="public"/>
    <project version="1.0" phase="1.0" created="2005-10-19 16:55:09" modified="2005-10-19 16:55:48" complexity="1" status="Proposed"/>
    <code gentype="<none>"/>
   </element>
Here <elementt> is the XML Tag representing the Extension of a model element
It has nested XML Tags (as <project>) containing additional XML Attributes (as version="1.0")

Extension data structure in the model

The reader is able to extract this additional data through the form of properties.

Property

A property is a (key,value) couple and represents an XML Attribute with its value:
<project version="1.0" phase="1.0" created="2005-10-19 16:55:09">
In bold a property "created" with value "2005-10-19 16:55:09"

Category

Those properties are stored in "Categories", which represent their owner XML Tag name.
In the previous example, the property version="1.0" is stored in the category "project"
Regarding properties which are directly defined inside the root XML Tag, they are stored in an empty category (empty string). For instance scope="public" is nested in the category ""

Qualified name

We call qualified name, the string representation of a property preceded by its category name. For instance, project.created is the qualified name of the property created nested inside category project.
.scope is the qualified name of the property scope nested inside the root XML Tag

Properties API

The Class EAAnnotations can be used to manage extensions data.

Getting all Properties for a specific Category

The method EAAnnotations.getProperties(umlElement, categoryName) returns a java.util.Properties object containing all properties nested inside this category.

Here is a sample code that shows how to get the Properties corresponding to a Category 

Properties properties = EAAnnotations.getProperties(myElement, "project");
For the following Enterprise Architect Extension: 
   <element xmi:idref="EAID_19A79944_2484_4e77_A373_D50FE935071B" xmi:type="uml:Text" name="Text" scope="public">
    <model package="EAPK_1FA6553F_CF5C_486f_BD38_8E7C24F0D7CE" tpos="0" ea_localid="2164" ea_eleType="element" name="Text"/>
    <properties documentation="Using Images on Elements" isSpecification="false" sType="Text" nType="0" scope="public"/>
    <project version="1.0" phase="1.0" created="2005-10-19 16:55:09" modified="2005-10-19 16:55:48" complexity="1" status="Proposed"/>
    <code gentype="<none>"/>
    <style appearance="BackColor=-1;BorderColor=-1;BorderWidth=-1;FontColor=8388608;VSwimLanes=1;HSwimLanes=1;BorderStyle=0;"/>
    <modelDocument/>
   </element>
This will return the following Properties:
	version="1.0"
	phase="1.0"
	created="2005-10-19 16:55:09"
	modified="2005-10-19 16:55:48"
	complexity="1"
	status="Proposed"

Getting a Property from its qualified name

The method EAAnnotations.getProperty(umlElement, qualifiedPropertyName) returns a String representing the property value.

Sample code: 

String value = EAAnnotations.getProperty(myElement, "project.version");
For the following Enterprise Architect Extension: 
   <element xmi:idref="EAID_19A79944_2484_4e77_A373_D50FE935071B" xmi:type="uml:Text" name="Text" scope="public">
    <model package="EAPK_1FA6553F_CF5C_486f_BD38_8E7C24F0D7CE" tpos="0" ea_localid="2164" ea_eleType="element" name="Text"/>
    <properties documentation="Using Images on Elements" isSpecification="false" sType="Text" nType="0" scope="public"/>
    <project version="1.0" phase="1.0" created="2005-10-19 16:55:09" modified="2005-10-19 16:55:48" complexity="1" status="Proposed"/>
    <code gentype="<none>"/>
    <style appearance="BackColor=-1;BorderColor=-1;BorderWidth=-1;FontColor=8388608;VSwimLanes=1;HSwimLanes=1;BorderStyle=0;"/>
    <modelDocument/>
   </element>
This will return the value: 1.0.

Diagram's graphElements don't have any sub categories. In consequences all properties are stored in the root category: 

<diagram xmi:id="EAID_136D4058_F38B_4900_8133_60E38D1ED020">
	<model package="EAPK_AD89E7B5_FD6C_4926_843C_4EC936DB4CFB" localID="93" owner="EAPK_AD89E7B5_FD6C_4926_843C_4EC936DB4CFB"/>
	<properties name="Architecture_Car" type="Logical"/>
	<project author="aleguenn" version="1.0" created="2018-03-13 17:35:40" modified="2018-03-14 12:00:10"/>
	<style1 value="ShowPrivate=1;ShowProtected=1;ShowPublic=1;HideRelationships=0;Locked=0;Border=1;HighlightForeign=1;PackageContents=1;SequenceNotes=0;ScalePrintImage=0;PPgs.cx=2;PPgs.cy=1;DocSize.cx=795;DocSize.cy=1134;ShowDetails=0;Orientation=P;Zoom=100;ShowTags=0;OpParams=1;VisibleAttributeDetail=0;ShowOpRetType=1;ShowIcons=1;CollabNums=0;HideProps=0;ShowReqs=0;ShowCons=0;PaperSize=9;HideParents=0;UseAlias=0;HideAtts=0;HideOps=0;HideStereo=0;HideElemStereo=0;ShowTests=0;ShowMaint=0;ConnectorNotation=UML 2.1;ExplicitNavigability=0;ShowShape=1;AllDockable=0;AdvancedElementProps=1;AdvancedFeatureProps=1;AdvancedConnectorProps=1;m_bElementClassifier=1;SPT=1;ShowNotes=0;SuppressBrackets=0;SuppConnectorLabels=0;PrintPageHeadFoot=0;ShowAsList=0;"/>
	<style2 value="ExcludeRTF=0;DocAll=0;HideQuals=0;AttPkg=1;ShowTests=0;ShowMaint=0;SuppressFOC=1;MatrixActive=0;SwimlanesActive=1;KanbanActive=0;MatrixLineWidth=1;MatrixLineClr=0;MatrixLocked=0;TConnectorNotation=UML 2.1;TExplicitNavigability=0;AdvancedElementProps=1;AdvancedFeatureProps=1;AdvancedConnectorProps=1;m_bElementClassifier=1;ProfileData=;MDGDgm=SysML1.4::BlockDefinition;STBLDgm=;ShowNotes=0;VisibleAttributeDetail=0;ShowOpRetType=1;SuppressBrackets=0;SuppConnectorLabels=0;PrintPageHeadFoot=0;ShowAsList=0;SuppressedCompartments=;Theme=:119;SaveTag=1C7B8CA2;"/>
	<swimlanes value="locked=false;orientation=0;width=0;inbar=false;names=false;color=-1;bold=false;fcol=0;tcol=-1;ofCol=-1;ufCol=-1;hl=0;ufh=0;hh=0;cls=0;bw=0;hli=0;SwimlaneFont=lfh:-10,lfw:0,lfi:0,lfu:0,lfs:0,lfface:Calibri,lfe:0,lfo:0,lfchar:1,lfop:0,lfcp:0,lfq:0,lfpf=0,lfWidth=0;"/>
	<matrixitems value="locked=false;matrixactive=false;swimlanesactive=true;kanbanactive=false;width=1;clrLine=0;"/>
	<extendedProperties/>
	<elements>
		<element geometry="Left=1270;Top=690;Right=1500;Bottom=792;" subject="EAID_25EA64C1_4C78_4efe_8538_7E9D9C50EE0C" seqno="1" style="DUID=50C90185;HideIcon=0;AttPri=0;AttPkg=0;AttPro=0;AttPub=0;Constraint=1;BCol=16760576;"/>
		...
	</elements>
</diagram>
The XML Tag <element> represents here a GraphNode. The following call will return its geometry value:
String value = EAAnnotations.getProperty(myGraphNode, ".geometry");

Setting a Property

The method EAAnnotations.setProperty(umlElement, category, property, value) set on the umlElement the value of the property in its category.

Sample code: 

EAAnnotations.setProperty(myElement, "project", "version", "2.0");
will increment project version to 2.0.

Enabling extensions extractions

When reading an Enterprise Architect model, no extensions are extracted by default. Extension extraction is handled through two options:

Options.OPTION_XMI_READ_EXTENSIONS

This options enables the extraction of all extensions data. It may have significant performance impacts. By default, they are not parsed.
Here is a sample code that shows how to read the Enterprise Architect extensions: 

	import com.sodius.mdw.metamodel.uml21.io.ea.EAAnnotations;
	import com.sodius.mdw.metamodel.uml21.io.ea.Options;
	...
	Map<String, Object> options = new HashMap<String, Object>();
	options.put(Options.OPTION_XMI_READ_EXTENSIONS, true);
	
	MDWorkbench workbench = MDWorkbenchFactory.create();
	Model umlModel = workbench.getMetamodelManager().getMetamodel("uml21").createModel();
	umlModel.read("Enterprise Architect Application", "", options);
	
	Operation myOperation = ...;
	String staticType = EAAnnotations.getProperties(myOperation, "type").getProperty("static");
	String uid = EAAnnotations.getProperties(myOperation, "model").getProperty("ea_guid");
	...
	umlModel.clear();
	workbench.shutdown();

Options.OPTION_XMI_READ_EXTENSIONS_SUBSET

This option enables the extractions of specific list of qualified properties, separated by comma.
Properties should be described by a qualifiedName category.propertyKey:

	import com.sodius.mdw.metamodel.uml21.io.ea.EAAnnotations;
	import com.sodius.mdw.metamodel.uml21.io.ea.Options;
	...
	Map<String, Object> options = new HashMap<String, Object>();
	options.put(Options.OPTION_XMI_READ_EXTENSIONS_SUBSET,  "type.static,model.ea_guid");
	
	MDWorkbench workbench = MDWorkbenchFactory.create();
	Model umlModel = workbench.getMetamodelManager().getMetamodel("uml21").createModel();
	umlModel.read("Enterprise Architect Application", "", options);
	
	Operation myOperation = ...;
	String staticType = EAAnnotations.getProperties(myOperation, "type").getProperty("static");
	String uid = EAAnnotations.getProperties(myOperation, "model").getProperty("ea_guid");
	...
	umlModel.clear();
	workbench.shutdown();

Related tasks
Reading UML Data
Reading Enterprise Architect Data
Programming the Reader Configuration
Reading a Package
Managing Ids

Related references
MDAccess UML API Reference
MDAccess for MagicDraw API Reference