Archive for the 'Structure101' Category
Architecture Diagrams in Structure101 are mapped to the physical code by patterns associated with each cell in the diagram. This enables the visual specification of rules that can then be applied to a specific version of your code so that Structure101 can overlay any violations on the diagram and let you discover the offending code items.
When you let Structure101 create the diagrams for you, and stick to changes like adjusting the layering, expanding packages, or moving packages to new parents, etc., you can mostly leave it to Structure101 to handle the patterns. However, occasionally you may see some behavior that seems odd unless you understand how patterns interact. And of course you may want to take advantage of the more advanced capabilities.
A key aspect that is not obvious at first is the “most specific pattern” rule. This says that where a physical class maps to more than one cell, the Architecture Diagram associates the class with the cell that has the “most specific” pattern.
Here’s an example diagram which was automatically generated from part of the Findbugs code-base:
… and here is the same diagram showing the pattern associated with each cell:
If I have a code-base that happens to contain a class edu.umd.cs.findbugs.classfile.impl.ClassFactory, then that class matches the pattern associated with the cell called ClassFactory. However it also matches the patterns for both ancestor cells “impl” and “classfile”. Since the ClassFactory cell’s pattern is the most specific (no wildcards), that is the cell to which Structure101 associates our physical class. And since a class is associated with at most one cell, that class is not associated with either ancestor cell, even though it matches their (less specific) patterns.
As expected, here are the associated items that Structure101 reports for the ClassFactory cell:
… and the parent “impl” cell:
Now I delete the 3 inner cells so that the diagram looks like this (the patterns for the remaining cells are unaltered):
Since the cells with the more specific patterns are gone, the classes that were associated with them now match the next most specific pattern – the parent “impl” cell:
This can be puzzling – I click on the “expand” button, the child cells are added to the diagram (which I expect), but the list of items associated with the parent is suddenly empty (which I don’t).
Why would we do it this way? We figured it was the best way to be future proof (the wildcards handle any added/removed classes) while at the same time supporting refactoring (e.g. if I move a class to a new package, the most specific pattern goes with it, but all the other classes still match to the original parent).
Here an interesting use case.
I am currently working on a reuse project. We have a large legacy Java application that we are trying to farm for implementations of some high level functions in a new application. To do this we are identifying the top-level classes that provide the initial entry point(s) to the desired high level functionality and then trying to discover all of the classes in the old system needed to support the identified top-level classes.
I have been doing this manually by going to the collaboration perspective in Structure101, selecting the “go to suppliers” option of a top-level class, and then manually drilling down through all of the classes the top-level class uses (that is, for every class the top-level class uses, I select “go to suppliers” and find out all the classes that class uses, etc. etc. etc.), tracking the needed classes as I go. This is not feasible to do given the size of the project.
Is there anyway I can get Structure101 to basically give me the transitive closure of all the classes used by the identified top-level classes, preferably as plain old ASCII text? Stucture101 seems to have already computed all the information I need, I just cannot figure out a non-manual way of getting the information.
As it happens, there is no first class support in Structure101 for this specific feature. However, it is do-able by leveraging other features and model options. Here’s how you would go about it.
First step is to set Overview granularity in the project properties. With this setting, the model stops at the outer class level but still takes account of all the member-level dependencies. So if Foo.x() calls Bar.y(), the model shows Foo and Bar and a “uses” dependency from Foo to Bar.
Second, tagging. Select a top-level class A in e.g. the Composition perspective, right click and choose Tag / Used by selected / Indirectly. Tag adornments (little blue dots) will appear on all the classes that A uses directly or indirectly (transitive closure of A). Then right click again and choose Tag / Selected so that A is also tagged. Repeat this for other top-level classes.
Now you have all the classes tagged, so all you need to do is export the tag list. Unfortunately, Structure101 does not have a button for that (grrrr) so we have to find another way of getting there…
From the main menu choose Tag / Invert item tags followed by Tag / Hide tagged. You have just subsetted the model to contain only those classes that you are interested in. Now all we have to do is get them into one table where we can right click and choose Copy / Copy all. Easiest for this is probably to switch to the Slice perspective, choose the “Outer class” level, and then you’ll likely see a single main cluster. Select this (actually it will get automatically selected for you). Hey presto, the table bottom left (Items tab of the Graph Contents viewer) contains the full list so a right-click should seal the deal.
We just released our new generic jobbie, Structure101g.
If you already know Structure101 for Java or Structure101 for C/C++, you probably already have a good idea of what Structure101g might be. This is for those (and there are many, oh so many) who do not.
Graphviz is a wonderful tool that can be used to create graph visualizations of stuff. All you do is stick in a logical graph model via a text file and out pops a nice picture. For the seminal example, see this view of the Unix family tree (and here is the corresponding text input file). Visit their gallery for lots more examples.
Occasionally the input is written by hand, but mostly it is generated by some piece of code that parses the domain-specific artifacts. For example, Graphviz is widely used to obtain subset pictures in code-base scenarios, e.g. the set of files in a directory and the includes/imports relationships between those files.
Although it is generally totally wonderful, graphviz (and other tools of its ilk) have one big weakness: graph visualizations do not scale. Subset pictures work fine (as in the includes example above) but there is no way to get a meaningful visualization of all the files across all directories.
The key in Structure101g, as in all Structure101 products, is to view the big model through the prism of hierarchy. Divide & conquer – use slices as a mechanism to get both subset views and “big picture” views. The other key differentiators are rich browsing and analysis environment rather than bitmap (or SVG) image, and some nice stuff around plumbing so that end users can create models interactively without leaving the UI.
Ok, so far so product pitch. Here the important stuff:
- To display data froma particular domain, Structure101g needs a meta-description (xml) of the entity and relationship types in that domain. We call this a flavor.
- In nearly all real-world cases, a flavor has an associated runner: This is the piece of code that parses the domain specific artifacts (or perhaps just some glue on top of an existing parser).
- At time of writing, there are flavor/runner implementations for the domains OSGi/Eclipse (bundles), Maven (POMs), Ant (targets and properties in a build.xml file), XSL (stylesheets), and Web (html pages and associated images, scripts, stylesheets, etc.).
- Graphviz is completely free to all and sundry.
- Structure101g is completely free for the above flavor/runner pairs, but we (Headway) have control-freakish tendencies so you need to talk to us about making a flavor generally available (either for free or commercially) or buy a domain license for proprietary usage.
- Graphviz does lots of different graph types and layouts. Structure101g is hard-wired to directed graphs with hierarchical top-down layout.
For more info and background, see this demo or visit the Structure101g home page.
Just got back from SD West and unpacked our Jolt Productivity Award. Huge credit and thanks to all the users that provided the stream of feature suggestions that has contributed to making Structure101 such a great product. And congratulations to the product and development team at Headway who spent so many tortuous hours discussing and honing each new feature (sometimes politely!) so that the product stayed usable as it got deeper.
… in the Design and Modeling category. Yeah!
Press release
Just released, Version 3.1 adds lots of new stuff to the Architecture perspective to make it much easier to discover the current structure and move classes or packages around to define a preferred architecture.
First thing is a simple expand and collapse button on each cell. So for example you can ask Structure101 to create a high-level architecture diagram from the current code-base – no need to worry about how deep to make the initial diagram since you can now expand and collapse cells once you have the initial diagram.
Let’s say you get the following diagram:
This shows a layering violation from the strut2 package to the dispatcher package. Click the “+” to find out what is being used at the next level of detail.
So something in struts2 is using something in dispatcher.controller. Expand both cells…
And we see there is a single class-to-class dependency causing the violation. Also, since the Dispatcher class is below the other classes in the dispatcher.controller layering, we know that the other classes use, but it does not use the other classes. And the layering in the struts2 package indicates that we can move Dispatcher to the indicated level to fix the violation without creating new ones. Just drag and drop Dispatcher to create this:
Collapsing the 2 top-level cells by clicking the “-” icons shows the original layering but with the underlying code rearranged so there is no longer an architecture violation.
Other stuff that has been added in this version:
- Once you have moved classes or packages, you can get a list of all the moved items.
- You can convert the list of moved items into transformations on the underlying model. This lets you iterate on a restructuring job – use an architecture diagram as a kind of “Sandbox” until you have some set of changes you’re happy with, then convert them into transformations and start sandboxing the next set of changes.
- You can now apply strict layering to a diagram. This means that cells can only use cells immediately below them, not below that.
- You can show any dependencies (i.e. not just violations) either on the whole diagram or on selected cells.
- You can drag items onto an architecture diagram from the dependency breakout.
Final note, if you are using the architecture diagrams to drive your developers, you should choose the expansion level of cells consciously before publishing them to the project repository. Their code changes will be checked against the visible levels only.
I have updated the architecture diagrams for the just-released Spring 2.5. Any new or changed packages are highlighted (since 2.0.6). The diagrams are also online – if you pointed your IDE plugin at these after my previous entry, you will be seeing the updated diagrams in your IDE already, and any compile time messages about architecture violations will be based on the new versions.
Here’s the new top-level architecture:
And here are the internals of the larger subsystems:
org.springframework.aop:
org.springframework.beans:
org.springframework.jdbc:
org.springframework.jms:
org.springframework.orm:
org.springframework.web:
Released today, the new version 3 capabilities make Structure101 a nicely rounded architectural control solution in addition to the previous structural analysis and complexity measurement capabilities.
For example:
- You can now define layering constraints on your code-base using simple, intuitive architecture block diagrams
- Communicate these architecture diagrams to the development team through IDE plug-ins
- Developers get warned immediately if they make code changes that are inconsistent with the architecture
- RSS activity feeds let you know if new architecture violations make it into a build
Also, there’s a new online demo (about 13 minutes, with audio (me!)) and the version 3 Help is available online.
Full press release
Enjoy!
Structure101 lets you work with both structure (the whole code-base as it is) and architecture (the subset of the structure that you really care about, and how it should be). It lets you define the architecture in the context of the physical structure and diseminate this to the team. Architecture diagrams are what makes this possible.
Layering and composition
Structure101 architecture diagrams use a concise visual notation for representing architectural layering and composition. Here is an example of one of the architecture diagrams that we use for the structure101 code-base.
The principle is simple; components (“cells”) should only depend on components at lower levels, not in the same or higher levels.
Layering Overrides
Sometimes a top-down dependency structure is too simple to capture the intent of an architecture. “Overrides” allow you to override the default layering of a diagram. For example we may decide to allow a specific dependency from a cell to a higher-level cell. The override is shown as a green (“allowed”) arrow on the architecture diagram. (Note that enabling this “upward” dependencies practically merges the “hiView”, “xbase” and “graph” components from the perspective of testing, reuse, development, etc.)
A more common example is where we wish to enforce a more strict layering. For example we may want one layer to only use the next layer down, but not layers below that. Such an override is shown as red (“disallowed”) on the architecture diagram.
Combining diagrams
It is not necessary to include all aspects of an architecture on a single structure101 architecture diagram.
A common scenario is where a number of “add-ins” are distributed across several packages. For example, this diagram shows part of the structure101 architecture.
It is correct, but incomplete. Classes in assemblies.X should never depend on classes in lang.Y. We could express this by adding several overrides, but it is much cleaner to use a separate diagram for this aspect of the architecture.
The next diagram defines a number of “language packs” that do not have a direct equivalent in the physical structure (they are “pure” architecture components), but express the architectural constraint that was missing above.
The combination of the 2 diagrams defines the intended architecture.
Mapping the architecture to physical code
In order to understand how a physical code-base conforms to an intended architecture, we need to map the architectural components (cells) to physical code.
Simple patterns are used to establish this mapping. This has a number of benefits:
- If a diagram contains a component mapped to com.headway.lang.* and the team creates a new package com.headway.lang.cobol, then the diagram is not rendered obsolete – all the classes in the new package map to the intended component.
- I can create components with more complex mappings with expressions such as com.headway.*.test.?
- I can create and show a component for which no code has yet been created, either by specifying no pattern or specifying the paths where I expect the new code to be implemented.
- I can effectively “hide” physical entities from a diagram. For example any code in com.headway.lang.cobol will simply map to a component with the expression com.headway.lang.* – I do not need to show package cobol on the diagram if I don’t want to.
Another flexibility is that a physical entity maps to the component with the most specific pattern. For example if I include 2 components, one with com.headway.lang.* and the other with the expression com.headway.lang.java.*, then the class com.headway.lang.java.myClass will map to the latter. The effects of this can be at the same time subtle and powerful. For example I could move the component that maps to com.headway.lang.java.* into another “parent” altogether.
Finally, each diagram has a (possibly empty) expression that maps to “excluded” items. This is useful if some physical entities would otherwise undesirably map to a component in the diagram.
Once the mapping is established, any dependencies that violate the architecture is shown on the diagram as a curved dotted line as shown here between component “graph” and the higher-level package “hiView”.
It is easy to discover the code-level cause of a violation by selecting it on the diagram within a structure101 client or IDE plug-in.
This update now checks for architecture violations automatically when you do a build (previous version was “on-demand” only). More on structure101 IDE plug-ins.
