People at Architexa have just released its Architexa tool for free to
individuals and teams up to 3 members. Using their own slogan, Architexa
is a tool "to understand and document Java code bases within Eclipse".
At first it seems yet-another tool to generate UML diagrams from an
existing code base (and it certainly is) but it has got other
interesting features that differentiates it from its competitors. In
fact, such tools have been around for a long time and some of them even
enjoyed gPeople at Architexa have just released its Architexa tool for free to
individuals and teams up to 3 members. Using their own slogan, Architexa
is a tool "to understand and document Java code bases within Eclipse".
At first it seems yet-another tool to generate UML diagrams from an
existing code base (and it certainly is) but it has got other
interesting features that differentiates it from its competitors. In
fact, such tools have been around for a long time and some of them even
enjoyed good adoption rates (think about Rational Rose).
Architexa, however, seems to focus on a niche: doing things
fast
and collaboratively, and I must acknowledge they're pretty close to
achieving that goal. In fact, Architexa is not a fully fledged UML
diagramming tool such as Rational Rose was or other plugins still are.
Rather, it offers interesting features and possibilities using UML as
the main UI. In my opinion, it's an important point to take into account
when reviewing it.
The only catch is Architexa being an Eclipse plugin. Sure, there are
lots of Eclipse users out there and giving priority to Eclipse is a
sound choice on their part. However, there are lots of
another-IDE-kind-of-guy out there (I'm mainly a NetBeans kind-of-guy)
and developers working on corporations may not have the freedom to
install their IDE of choice.
Installing Architexa
Installing Architexa is as straightforward as installing an Eclipse
plugin. Just add the software repository URL you get during signup to
Eclipse and install the plugin. The installation procedure is simple and
almost unattended: the only question you'll be asked is trusting a
certificate. Once the plugin is installed, just restart your Eclipse
instance and you're ready to go.
Using Architexa
Architexa user interface is pretty straightforward:
- A couple of menu items (both in the main menu and in contextual menus) to open one of the available diagrams.
- Some menu items to manage Architexa indexes.
- Some menu items to access Architexa documentation right inside your Eclipse IDE.
Three types of diagrams are currently available:
- Layered Diagram
- Class Diagram
- Sequence Diagram
Depending on the context you invoke a particular item, Architexa will
take you to the chosen element in the corresponding diagram.
Since I suspect this kind of tool is most useful to developers working
on big projects whose entire code base they've got no complete knowledge
of, I decided to review it importing a subset of an EJB module of an
application I worked on in an empty Eclipse project and start from
there.
Layered Diagram
The Layered Diagram looks like a package diagram at first, but there's
much more to it than this. It's a very useful representation of your
project architecture which, as every Architexa diagram, can be easily
configured to contain
just the level of detail you need. This
way, you can get a quick overview of module dependencies into your
project and you can progressively "drill down" in order to discover more
detailed relationship between packages and between package contents
(classes and interfaces) and other elements.
Here's how a layered diagram looks like:
 |
Layered Diagram |
As you can see, the diagram is divided into layers and when you hover a
component with your mouse dependencies are shown as arrows of different
sizes. By default, objects in an upper layer are dependent on objects on
a lower layer.
In the previous diagram, the
interceptors
packages was collapsed, and you can expand it just double clicking on
it. Furthermore, in the following picture you can see the dependencies
of an element (
AuditableEntityListener) just hovering the mouse pointer over it:
 |
Layered Diagram - Discover the Dependencies of an Item |
Architexa UI is great because it relies on intuitive concepts to convey
information to the user. The size of the elements in this diagram are
proportional to the "quantity" of information which is present in the
project. This way, you can get important information with a quick
glance, such as:
- Which big packages and classes are.
- Where a great number of dependencies are concentrated.
- Whether your architecture contains cycles.
By default, the level of detail of the diagram is minimum but the user
can expand it "on demand". In the following picture you can see how you
can add additional information about an element just hovering over it
and using the dependencies arrows to add additional levels to the type
hierarchy:
 |
Layered Diagram - Add Levels to the Type Hierarchy |
 |
Layered Diagram - Add Levels to the Type Hierarchy |
This diagram offers a pretty restricted palette you can use to add
insightful detail to your diagram in order to use it as a good
documentation tool. The palette currently includes elements such as
actors, databases and user comments.
Class Diagram
At first sight, a class diagram behaves more or less like a class
diagram generated in any other UML diagramming tool you may have tried.
However, it's based on Architexa's design philosophy we saw in the
previous section: reduce the clutter and get the job done. When you
generate a class diagram from a class, you're just presented something
like this:
 |
Class Diagram |
No doubt that's just the bare minimum you need to know about a class.
Once again, you can have Architexa add the information you're interested
in using its user interface. First of all, at the class level, you can
add
referencing types and methods. Then, you can add other class
information (such as methods, interfaces, etc.) using the menu that
appears when hovering the class and selecting the items you want to
show:
 |
Class Diagram - Select Class Information |
As you can see, you can filter methods by visibility and items by type
(interface, class, methods and fields). If you want to add them all,
just use the
Add All button:
 |
Class Diagram - Method Information |
You can further refine the information of a class item using its contextual menu shown in the next picture:
 |
Class Diagram - Class Item Contextual Menu |
As you can see, you can add a wealth of information, such as called and
calling methods, referenced and referencing methods and declaring class.
 |
Class Diagram - Types Referenced by a Method |
Finally, there's also a quick way to add called method information. When you hover a method, an arrow control is shown:
 |
Class Diagram - Add Called Methods |
and if you click it you'll be presented a dialog where you can choose the called methods you want to add:
 |
Class Diagram - Called Methods Selection Dialog |
The dialog can be used to filter methods by visibility and there are two
buttons that allows you to add either all called methods or the callee
hierarchy. The resulting diagram looks like this:
 |
Class Diagram - Called Methods |
Obviously, this process can be applied to any element added to the
diagram until you've added all the information you want to show.
Sequence Diagram
The sequence diagram provided by Architexa is very similar to diagrams
generated by similar tools. Once again, however, Architexa philosophy is
reducing the clutter and letting the user decide what he wants to be
shown in it.
An initial sequence diagram looks like this:
 |
Sequence Diagram |
Hovering over the class lets you choose members to be shown into the
diagram, using the method selection window we've already described in
previous sections:
 |
Sequence Diagram - Method Selection Window |
Once a method is chosen, the diagram is updated:
 |
Sequence Diagram - Selected Method |
Hovering on other diagram elements let you add depth to the call
hierarchy, selecting more and more levels to be shown. Adding methods
called by the persist method results in the following diagram:
 |
Sequence Diagram - Methods Called by the persist Method |
Collaborative Features
Architexa provides basic collaborative features and lets you share
diagrams with other people. The Architexa main menu contains the
following items:
 |
Collaborative Features |
As you can see, you can get diagrams from a server or share your own.
When you share a diagram, you're given two choices: sharing using a
server (which acts as a central repository) or sharing by email (which
simply attaches the diagram to a newly created email message):
 |
Sharing a Diagram |
Another way you can share a diagram is presented when you
save a newly created diagram:
 |
Saving a Diagram |
Architexa lets you save a diagram as either:
- A file in the local disk.
- A shared diagram in a private server.
- A shared diagram in a community server.
Conclusions
Architexa is not the typical UML diagramming tool in that it's built
with a different design philosophy. Instead of "just" producing diagrams
out of an existing code base, it lets the user customise the diagrams
and decide the details that must be included in an easy and intuitive
way. This fact fulfils the Architexa's slogan promises: it's a great
tool to create diagrams that "make sense", according to each user's
needs.
If you haven't tried it, it may seems just a "nuance", but it's a great
usability leap for such a tool in the right direction. I've been an user
of UML modelling tools for years, and I grew more and more dubious
about the alleged improvements in developers' productivity. Most of the
times, if not all, I ended up always relying on my textual IDE to
navigate through the code base, jumping from method to method as needed.
This time, however, I feel that Architexa can fill a gap and can really
be useful to a developer, not only in the documentation stage, at least
in a handful of use cases. Architexa UI is very efficient and pretty
intuitive and during the tests I performed I felt very "proficient" at
jumping from a dependency to another or from a method call to another.
But all that glitters is not gold, and Architexa has got its own
shortcomings. First of all: it's an Eclipse plugin and it's not
available for other IDEs. This is a deal-breaker for many users, such as
I, who are not willing to switch their IDEs.
Then, some important Java language features are missing, such as
generics.
Generic aren't new kids on the block (two major Java releases have seen
the light after support for generics was added to the language). They
can't be dismissed as something of little importance, either. I don't
know why no information about generic types and signatures appear on
Architexa diagrams, but I hope this gap will be filled soon.
Then, I'd really like to see "awareness" about more Java technologies
built into the tool. When I started reviewing it, I decided to use a
fragment of an EJB module to see if there were more bells and whistles
than what I was reading on other reviews which used simple Java
projects. Given Architexa's design philosophy, I'd really like to see
more information about classes, at least in the Layered Diagram.
Furthermore, since many recent Java EE technologies heavily relies on
runtime-available
annotations, such as EJB and JPA, I added
entities and EJBs to the project to see whether annotations were
discoverable information: unfortunately, they were not.
Architexa is a good tool and I think it's in the right track to catch on
developers and rise adoption from the bottom up. Developers can take
good advantage of it and I believe it's a critical aspect for such a
tool to gain adopters. Instead of being a tool imposed to them for
methodology's sake, it's a tool that adds real value and can get their
job done more easily and more effectively. Furthermore, Architexa is now
free for individuals and small teams (up to 3 members) so that everyone
can sign-up, download it and start to use it on its own, real life
projects.ood adoption rates (think about Rational Rose).
Comments