Items
Previous  Top  Next

The key items in a Structure101g data file are modules and, optionally, submodules. These represent the entities in the domain being modeled.

Modules

Think of modules as the highest-level concrete concept in a domain (the term "concrete", here, generally means that it is possible for instances of this construct to have their own dependencies). The key defining aspect of a module, in Structure101g, is that it is totally impossible for one module (whatever its type) to contain another module (whatever its type).

Let's illustrate this (somewhat obscure beginning) by thinking about the Java domain. Clearly the member (method or a field) level is inappropiate because there is a higher-level construct in the language that is pretty concrete, namely the notion of a class (or interface). A class (in the purest sense) doesn't conform very well to the definition of a module above because it is possible to nest classes. And package isn't quite right because a package isn't really concrete (never has its own dependencies). In fact, the "right" choice for Java, the one that ticks all our boxes, is the outer class level (whereby we do not distinguish between classes and interfaces).

In most domains, the choice of the module level is more straightforward. For example, if were interested in modeling HTML files and hyperlink "dependencies" between them, we would very quickly decide that the file is the appropriate item for the module level.

Now that we have got that out of the way, let's have a look at an example data file (staying with the HTML theme).

<
data flavor="com.headway.examples.html">
   <
modules>
      <
module name="index.html" id="1" type="file"/>
      <
module name="aboutus/index.html" id="2" type="file"/>
      <
module name="aboutus/contact.html" id="3" type="file"/>
   <
/modules>
   <
dependencies>
      <
dependency from="1" to="2" type="links"/>
      <
dependency from="2" to="1" type="links"/>
      <
dependency from="3" to="1" type="links"/>
      <
dependency from="3" to="2" type="links"/>
   <
/dependencies>
<
/data>

We can quickly see here that the file contains a modules section which in turn contains a flat list of all the individual module instances in our system.

It is very common (almost a requirement!) for modules to have hierarchical names - for example, the name "aboutus/index.html" implies that there is a module with a local name of "index.html" that resides in a virtual container called "aboutus".

A module element must contain the three attributes shown in the examples above: name, id and type. As you would expect, the id (arbitrary string) for an item must be unique within the file. There are no constraints on name or type.

A module can also optionally specify a signature attribute. This makes most sense where a domain entity (e.g. a function) has a short name and a long name. Where a signature is specified, Structure101g automatically appends it to the item's display name in various scenarios (e.g. tooltips).

Finally, Structure101g understands 3 module states: resolved (default), unresolved and error. A state of "unresolved" denotes some entity that has not been parsed, while the state error denotes an entity where the parse failed in some form. These states are automatically rolled up in the Structure101 viewing model.

Submodules

Modules can optionally contain submodules, and submodules may contain further submodules (to arbitrary depth).

For example, our HTML domain might also wish to support anchors (to deal with the case where there is a link to e.g. myfile.html#myanchor).

<data flavor="com.headway.examples.html">
   <
modules>
      <
module name="index.html" id="1" type="file"/>
      <
module name="aboutus/index.html" id="2" type="file"/>
      <
module name="aboutus/contact.html" id="3" type="file">
         <
submodule name="a1" id="4" type="anchor"/>
         <
submodule name="a2" id="5" type="anchor"/>
      <
/module>
   <
/modules>
   <
dependencies>
      <
dependency from="1" to="2" type="links"/>
      <
dependency from="2" to="1" type="links"/>
      <
dependency from="3" to="1" type="links"/>
      <
dependency from="3" to="2" type="links"/>
      <
dependency from="1" to="4" type="links"/>
   <
/dependencies>
<
/data>

Submodules have exactly the same attributes as modules: name, id and type (all required) plus an optional signature. The only difference is that, for submodules, the name value should always be local (relative to its container) rather than fully-qualified.

Finally, returning to the Java theme, it is worth noting that the following (assumes classes com.foo.Outer and com.foo.Outer$Inner) is perfectly legal (the same type, here "class", can occur at both the module and submodule levels).

<data flavor="com.headway.examples.java">
   <
modules>
      <
module name="com.foo.Outer" id="1" type="class">
         <
submodule name="Inner" id="2" type="class"/>
      <
/module>
   <
/modules>
<
/data>

Note also that it perfectly legal to have multiple different module types, as in the example below.

<data flavor="com.headway.examples.java">
   <
modules>
      <
module name="com.foo.MyClass" id="1" type="class"/>
      <
module name="com.foo.MyInterface" id="2" type="interface"/>
   <
/modules>
<
/data>