XmiElement

Introduction

XmiElement (interface IXmiElement, namespace uml4net) is the abstract base class of every object that can appear in an XMI document: all the generated UML classes in uml4net/AutoGenClasses, and the XMI-specific constructs such as xmi:Extension. The generated class Class is declared as public partial class Class : XmiElement, IClass, and so is every other concrete UML metaclass.

The UML 2.5.1 metamodel itself knows nothing about identifiers or documents. XmiElement adds exactly the state that is needed to get an object from an XMI document into a fully connected object graph, and back out again. It is hand-coded; it is not part of the metamodel.

Identity

Property	Meaning
XmiId	The xmi:id of the element. Unique within its document (XMI 2.5.1 clause 7.6.1); optional — an element without one is still read, cached under a synthetic key, and assembled, but cannot be referenced.
XmiGuid	The xmi:uuid, a globally unique identifier. Used by the XmiElementCache to resolve XPointer references of the form xpointer((//*[@xmi:uuid='value'])[1]).
XmiType	The xmi:type as read, with the prefix uml4net uses, for example uml:Class.
XmiNamespaceUri	The namespace URI the element was read in, for example http://www.omg.org/spec/UML/20161101.
DocumentName	The name (file name or URI) of the document the element was read from. For an element reached through an href, this is the document part of the href as written, e.g. http://www.omg.org/spec/UML/20161101/UML.xmi or ../lib/types.xmi.
FullyQualifiedIdentifier	{DocumentName}#{XmiId} (or _#{XmiId} when there is no document name). This is the key under which the element is stored in the XmiElementCache, and the key that every xmi:idref and href is turned into.

The DocumentName and the FullyQualifiedIdentifier are what make cross-document references work: a reference href="PrimitiveTypes.xmi#Boolean" resolves against the element whose DocumentName is PrimitiveTypes.xmi and whose XmiId is Boolean, whichever file that document was actually loaded from.

Pending references

While an XMI document is being read, the elements it refers to may not have been read yet, or may live in another document. The generated readers therefore do not set reference properties directly; they record the identifiers on the element, and the Assembler turns them into object references once every document has been read.

Property	Filled by the reader with
SingleValueReferencePropertyIdentifiers	Dictionary<string, string>: property name → identifier, for single-valued references such as type="_b" or <type xmi:idref="_b"/>. A property that is given twice is reported (XmiReadException in strict mode) and keeps its first value.
MultiValueReferencePropertyIdentifiers	Dictionary<string, List<string>>: property name → identifiers, for multi-valued references such as memberEnd="_a _b" or repeated <redefinedProperty xmi:idref="…"/> elements.
CompositeReferencePropertyIdentifiers	Dictionary<string, List<XmiCompositeReference>>: property name → proxies. A proxy is an xmi:idref or href that appears where a contained element is expected (XMI 2.5.1 clause 7.10.1); XmiCompositeReference.Position records where it stood among the property's elements so the definition can be inserted in document order.

Identifiers are stored as written: a bare id, a same-document #id, or a document#id / document#xpointer(...). The Assembler qualifies bare identifiers with the element's own DocumentName.

After assembly the single- and multi-valued dictionaries still hold their entries — they document what the element referred to, and the writers do not need them since they write from the resolved properties. Resolved composite proxies are removed from CompositeReferencePropertyIdentifiers; proxies that could not be resolved are kept.

Unresolved references

UnresolvedReferences (List<XmiUnresolvedReference>) preserves, verbatim, each href reference element while it is read: the property name, the identifier and the raw XML of the reference element. As soon as the Assembler resolves the reference, the entry is removed. After reading, the list therefore holds exactly the references that could not be turned into an object reference — typically references into a document that is not available, such as the UML metamodel referenced from a profile.

The XMI writers write these entries back unchanged, so a model whose references could not be resolved still survives a read–write cycle without losing them. IXmiReaderSettings.ThrowOnUnresolvedReferences turns them into a single UnresolvedReferencesException at the end of the read instead.

Extensions and the cache

• Extensions (List<XmiExtension>): the xmi:Extension elements found inside the element. Their content is preserved as raw XMI, and processed further when an extender reader is registered for the extender (see the Enterprise Architect extension).
• Cache: the XmiElementCache the element was added to. It is set by XmiElementCache.TryAdd and is used, for example, by the allInstances() emulation of derived properties such as Class::extension and Vertex::incoming.

Ownership is not on XmiElement

Ownership — Possessor, Owner, OwnedElement — belongs to the UML Element and lives on the partial IElement interface, not on XmiElement: an xmi:Extension is an XmiElement but not an Element. See ContainerList for how ownership is maintained.

Lifecycle of an element

1. A generated IXmiElementReader creates the element, sets its identity properties from the XML attributes, adds it to the XmiElementCache, reads its value properties, records its references in the three dictionaries, and reads its contained elements into its ContainerList<T> properties.
2. The XmiReader loads the external documents that the recorded hrefs point to, reading their elements into the same cache.
3. The Assembler synchronizes: every recorded identifier is looked up in the cache and assigned to the corresponding property.
4. The element is fully connected. Its derived properties (Owner, Namespace, QualifiedName, Member, …) are computed on access from the assembled graph.

See also

• XmiElementCache — where elements are registered and looked up
• Assembler — resolves the recorded identifiers into object references
• ContainerList — the collection of the composite properties
• uml4net.xmi project — the readers and writers that produce and consume these elements