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):