The UML Parsing Analysis recipe

In this interesting and novel tutorial trail you will learn how to translate technical texts into UML models, using Dr Darren's innovative UML Parsing Analysis recipe - adapted to MagicDraw UML. This very powerful and effective technique can be combined with all of your requirements analysis, systems analysis, software engineering and systems engineering work, as well as with analysis and modelling of other technical, scientific, and even artistic topics.

The UML Parsing Analysis leverages two main techniques explored in related tutorial trails that you should study first:

  1. HOWTO use UML Components as logical and graphical wrappers in MagicDraw UML
  2. HOWTO use editorial stereotypes in Comments

There is a limitation to the degree and flexibility of binding afforded by handles from UML Comments drawn to model elements, since Comment handles are not true relationships, they do not appear in the UML model (repository) proper, and they are not easily traced. We will therefore also be exploring how to parse text into (misappopriated and stereotyped) Components (and optionally Artifacts) as "relatable parsing containers", and how to use Dependencies for very powerful and flexible UML Parsing Analysis. The widely practised, age-old technique of just copying technical text into Comments and relating them loosely with handles does not meet the requirements for the UML Parsing Analysis recipe; only the "happily misappropriated" stereotyped Component meets Dr Darren's conditions, and it is a truly powerful relatable parsing container.

Plenty of examples are available both within this eSchool and other sites: please do complete this tutorial trail here before visiting these resources (and then do please come back) !

Candidate source for the UML Parsing Analysis recipe

Text sources that can be parsed into Comments bound to your UML model elements include:

  • software specification documents like the UML and
    SysML specs can be mapped into conformance models (which are the
    primary examples for this tutorial trail)
  • architecture documents and systems analyses can be bound to analysis classes
  • software documentation can be bound to forward- or reverse-engineered UML design classes
  • software requirements documents can be "eaten up" and bound to requirements elements such as Use Cases or SysML requirements.
  • systems design manuals can turned into SysML block models (we will be exploring actual examples using real scientific instruments)
  • descriptions of complex systems can be translated into UML analysis models (for example we will be exploring animal taxonomies from Wikipedia articles)
  • vision statements can be translated into UML posters (including executable elements to demonstrate the achieved vision).

HOWTO use relatable UML Classifiers as parsing containers that can carry Dependencies to other Elements

It is often handy to be able to parse text into a relatable UML Elements (rather than into a Comment with just "handles") so that one can leverage Dependencies and the Display Related Elements facility of MagicDraw UML. Although a DirectedRelationship can be made between base Elements, the UML Parsing Analysis recipe employs (at least) the Dependency as the relationship, and (at least) a NamedElement. as a "parsing container" to hold the parsed analysis text.

There a number of candidate Classifiers that are suitable as relatable parsing containers, including:

  • Component offers itself very well (if clearly stereotyped as a semantic misappropriation) because:
    • it can participate in ComponentRealization dependencies, which can be
      easily traced to the contents of the Component as parsing container
    • it can nest (both graphically and physically) to form trees of parsed text
    • it can graphically contain other elements to form "parasitic" logical views:
      • TIP: In MagicDraw UML the Component symbol does not "steal ownership" of elements moved into it in a diagram
        • WARNING: the Component element in the model browser will correctly steal ownership of elements moved into it in the browser
  • Artifact also offers itself because:
    • it is traditionally associated with documentation
    • it can nest (both graphically and physically) to form trees of parsed text
    • con: it can't graphically contain other important elements, such as Class
  • Class is NOT a candidate, as it can't graphically nest, so it fails an important requirement of the UML Parsing Analysis recipe

DO NOT use Package (or Model) as a parsing container, as it steals ownership of elements, and thus is ill-suited to forming logical views !

I recommend that you parse text into Comment first then only "upgrade" to a Classifier if really necessary. Reasons for upgrading include:

  1. you want to reuse the parsed text many times in different places easily by using Display Related Elements
  2. you want to relate other elements to the parsed text in a reusable way

HOWTO use stereotyped Components as parsing containers for technical text

A very good candidate for a relatable parsing container is the Component (a Classifier): In the "self-referential spirit" of UML Parsing Analysis the example below is a UML Parsing Analysis of one of the pages from this tutorial trail.

PROS:

  1. can be packaged
  2. can carry dependencies
  3. can contain/own other elements (like other Classes, Components, Comments or Artifacts):
    • can therefore contain (nest) easily other Components used as parsing containers:
      • the nested parsing container Components form a wonderful parsed text tree in your analysis model !
      • try using Show Owner on nested parsing container Components, very powerful !
  4. The Component symbol can graphically contain other elements that it does not necessarily own:
    • WARNING: the Component element in the model browser will correctly steal ownership of elements moved into it in the browser
    • In MagicDraw UML the Component symboldoes not "steal ownership" of elements moved into it in a diagram

CONS:

  1. Not intrinsically distinguished from Class or Component as used for software engineering:
    • This very useful and powerful misappropriation of the UML2 Component seems to unnecessarily annoy certain UML2 purists.
    • Indeed as long as one does not over-use the attributes, operations, or features specific to UML2 Component  semantics there is no problem:
      • Just clearly stereotype your parsing container Component to indicate the parsing context and/or parsed text source:
        • example: «UML2», «UML2», «SysML», «design manual», «source:test-456-ITC», «fredd.bloggs@somewhere.net»
      • use pen- or fill- colour and/or italic text to distinguish the parsing container Component symbol visually from other Component symbols
      • make sure that the option Header in bold is off (use Header in bold only for regular Components adhering to strict UML semantics)
  2. One can't use HTML text style:
    • I recommend that you turn of the Header in Bold option and turn on the Word Wrap option so that the name used as text displays well
  3. In MagicDraw UML the Component is only available on diagram menus of certain diagram types
  4. In MD SysMLthe Component is not even allowed (Block extends Class) and is not offered on any SysML diagrams
    • this useful misappropriation of the Component as a relatable parsing container and/or logical wrapper of blocks seems to
      unnecessarily annoy certain fanatical devotees SysML, too.
    • please use it freely in MD SysML,, however know that your model is not compliant with SysML1.0 (although it may still be very useful).

Despite these subtleties, if you really want the most powerful tecnical analysis modelling results, this is a very, very powerful strategy !

Component as relatable parsing container (with Dependencies) vs. Comment as parsing container (with handles)

In the following image we see a parsing ot the familiar UML2.1.2 specification text for 7.3.14 Element (from Kernel) into stereotyped Components as relatable parsing containers. For comparison, the process is repeated for selected text snippets with Comments.

Pros of the Component vs Comment as a "parsing container":

  • Can package a dedicated diagram that features the relatable parsing container Component and its text, with its related elements (see next page)
    • TIP: drag that "focus" diagram from the browser onto the parsing container Component to make it the active hyperlink of the container !
    • A Comment can't even really package (let alone package a focus diagram) !
      • (Note that in MagicDraw UML and Comment can contain nested Comments, only)
  • Parsing container Components can be nested to form a parsed text tree (and traced using ComponentRealization)
  • Can parasitically "wrap" other elements to form logical views of them without "stealing ownership".
    • this is also the major advantage of Component over Artifact (or other Classifiers) as a relatable parsing container.

Cons of the Component vs Comment as "parsing container":

  • Can't be related via a Dependency easily to the Property at an Assocation end:
    • when a Property is available to target as an attribute in the attributes compartment this is no problem
    • a Comment handle can be correctly drawn to a Property at an Assocation end

Note the use of tagged values with enumeration literals to describe clearly the source and "coordinates" of the parsed text (in this case from the UML2.1.2 spec) in the parsing containers. In general, try to get as much text out of the parsing container's name, and into the model in this way.

Example: Components used as parsing containers reused via Display Related Elements

Here the elements related to a parsing container Component for the UML2.1.2 stereotype 7.3.14 Element (from Kernel) have been generated using the context menu:

Related Elements -> Display Related Elements

Then the remaining dependencies between other elements were generated using:

Related Elements -> Display Related Elements

(The diagram layout was then massaged a bit after using "Layout Organic Style".)

Note that:

  • The text parsed into Comments and related by handles only on the previous diagram have NOT been displayed !
    • This is why relatable Elements like Component are sometimes chosen as relatable parsing containers
  • The text parsed into Components on the previous diagram has been redisplayed via ComponentRealizations):
    • Con: although it is correctly generated, the parsed UML2.1.2 Attributes text for 'The Comments owned by this element. Subsets Element::ownedElement.' can't be related to a Property anywhere in the diagram.
  • One usually is not interested in all of the elements related to a parsing container, only those relevant to a given analysis context.

Using Components as relatable parsing containers offers these particular features (as well as the ability of its symbol to graphically contain elements that its text refers to). This is the key to understanding the whole UML Parsing Analysis recipe !

Example: Component used as "parsing container" that logically groups elements

The following shows an example of text from the specification of the UML2.1.2 7.3.45 Realization (from Dependencies) parsed into relatable parsing container Components, including an illustration of the notations and conventions referred to in the specification. This is a very powerful recipe, and it simply can't be done as well by only parsing technical text into Comments (which may only "relate" to elements through handles - which can't be traced - and can't graphically contain logical views):

HOWTO use sterotyped Artifacts as relatable parsing containers

Another candidate (besides a happily-misappropriated Component) for a relatable parsing container is the Artifact (a Classifier):

PROS:

  1. can be packaged
  2. can carry Dependency relationships to other "relatable" NamedElements
  3. little note icon suggests a documents (and thus is a good container for parsed text)
  4. well distinguished from software engineering elements like Class or Component
  5. can contain/own other elements (like other Comments or Artifacts)
    • can be nested to build nice logical trees of parsed text in your analysis model

CONS:

  1. One can't use HTML text style:
    • I recommend setting Header in Bold option off and word wrap on
  2. In MagicDraw UML one can't create an Artifact under a Component (so one can't easily insert an Artifact into a wrapper Component)
    1. create the Artifact under the nearest Model/Package IN THE BROWSER then
    2. move it IN THE BROWSER into the desired owrning wrapper Component
      (since you are using UML Parsing Analysis it almost certainly want to do that), then
    3. use create symbol to show the parsing Artifact in the diagram:
      • is a WORKAROUND (a bit tedious, however the results can be rewarding):
  3. In MagicDraw UML Artifact is only available on diagram menus of certain diagram types (and especially not in SysML diagrams)

Despite these subtleties, if you want powerful text analysis modelling results, this is one good strategy

TIP: consider also using a Component as a parsing container.

Example: Artifact used as container for parsed text with dependencies

In this example I have parsed some of the SysML1.0 spec text for conformance analysis vs. MD SysML.

The original SysML1.0 specification text to be analysed was:

'11.3.2.4 NoBuffer

Description
When the «nobuffer» stereotype is applied to object nodes, tokens arriving at the node are discarded if they are refused by outgoing edges, or refused by actions for object nodes that are input pins. This is typically used with fast or continuously flowing data values, to prevent buffer overrun, or to model transient values, such as electrical signals. For object nodes that are the target of continuous flows, «nobuffer» and «overwrite» have the same effect. The stereotype does not override UML token offering semantics; it just indicates what happens to the token when it is accepted. When the stereotype is not applied, the semantics are as in UML, specifically, tokens arriving at an object node that are refused by outgoing edges, or action for inpu pins, are held until they can leave the object node.

Constraints
[1] The «nobuffer» and «overwrite» stereotypes cannot be applied to the same element at the same time.'

Most of the text has been parsed into UML Comments and handles are used to relate the text to UML elements.

I have chosen to "upgrade" at least two of the parsed spec text sentences from Comment parsing container to Artifact parsing containers:

  • "For object nodes that are the target of continuous flows, «nobuffer» and «overwrite» have the same effect."

    • has been related by dependencies to some other elements, including some wrapper Components as navigation points.
  • "[1] The «nobuffer» and «overwrite» stereotypes cannot be applied to the same element at the same time."
    • has been turned into a parsed constraint container.

The result is shown in the image below.


TIP: see the next page to see how Display Related Elements is used to show which elements are related to the original subject.

Example: Artifacts used as parsing containers reused via Display Related Elements

Here the elements related to a parsing wrapper for the SysML1.0 stereotype 11.3.2.4 NoBuffer have been generated using the context menu:

Related Elements -> Display Related Elements

Note that:

  • the text parsed into Comments on the previous diagram have NOT been displayed
  • the text parsed into Artifacts on the previous diagram has been redisplayed via Dependencies

Although a bit more fuss than parsing text into Comments, parsing into Artifacts (or even into Components) brings with it this particular advantage.

Examples of the UML Parsing Analysis for software, engineering, and science


Please complete this tutorial trail here before visiting these resources !

Examples of the UML Parsing Analysis recipe using MagicDraw UML available online include:

Within this eSchool:

At other sites:

  • Literally hundreds of entertaining examples are available at the home of the UML Parsing Analysis recipe:

The technique has evolved over the years;
the recipe given here is the most up-to-date.