Architexa Review: Understand and Document Java Code Bases within Eclipse

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 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.