Category Archives: Tools

Create UML diagrams with simple DSL – PlantUML

Historically I disliked creating design UML diagrams, because the tooling for it mostly requires drawing boxes and connecting them with lines or arrows. I find such workflow very time consuming and wasteful. This short blog post will describe much better way to create UML diagrams.

But first of all, you may argue that UML importance in today’s agile software development world is fading out. I would agree partially.

Creating UML Class Diagrams

From my point of view UML class diagrams are needed very rarely. I can find only two use cases for it:

  • To analyze existing code base
  • To communicate suggested design with the team

When you need to analyze existing code base, class diagrams can be easily generated by your IDE from the existing code. IntelliJ idea provides this as part of payed version:

UML

To find out how to create such diagram, read this IntelliJ IDEA documentation. It is also easy with Eclipse or it’s flavors (e.g. Spring Tool Suite):

UML

You just need to use plugin called ObjectAid.

When we need to sketch class diagram upfront to consult design with the team, I would suggest to create prototype with desired class structure instead and generate class diagram from the live code (again with IDE). You may find some important facts about the design while creating prototype. There’s no need to create logic and tests, just APIs of the design.

And of course when you don’t need such generated diagram anymore, just wipe it out. Low level design may change easily and you don’t want to keep outdated diagrams around. You can generate new diagram from live code easily.

Non-Class diagrams

So when we need Class diagram, it’s smart to generate it from live code. But what about other UML diagrams like:

  • Structure diagrams (except Class diagram)
  • Behavioral diagrams
  • Interaction diagrams (especially useful is Sequence diagram from this bucket)

I personally created only few Use case and Flow chart diagrams during my career. But Sequence and Component diagrams are very useful to document high-level design decisions. Of course you don’t want to have them very detailed, but at high level designer intentions and considerations are sometimes good to document.

But the tool that is used for designing these diagrams has to be very easy to use and flexible. Sorry Visio or Enterprise Architect, I don’t include you into this bucket (although I have to admin I haven’t use EA for long time).

My tool of choice it PlantUML.  We can define design with very simple DSL. Therefore instead of connecting boxes and lines on canvas, we can focus on design itself. It can be used as standalone application but it also have impressive list of integrations. So you can easily use it with your IntelliJ IDEA, Eclipse or Spring Tool Suite.

Very compelling fact for me, is that DSL which defines diagrams can live with the project code-base and also be handled by source control system, with all the goodness it brings. This is simple screenshot from IntelliJ:

UML
eclipse-pmd

eclipse-pmd – New PMD plugin for Eclipse

I am Eclipse user. So when I wanted to analyze my code by PMD, I needed to use “PMD for Eclipse” plugin. This plugin used to be very buggy, which was enhanced in later versions (currently 4.0.3). But the performance is really bad sometimes. Especially when you are dealing with relatively big codebase and have option “Check code after Saving” on.

ecplise-pmd plugin

So when I realized that there is new alternative PMD plugin called eclipse-pmd out there I evaluated it immediately with great happiness.

Installation uses modern Eclipse Marketplace method. You just need to go “Help” -> “Eclipse Marketplace…” and search for “eclipse-pmd”. Than hit “Install” and follow instructions.

After installation I was a little bit confused because I didn’t find any configuration options it general settings (“Window” -> “Preferences”). I discovered that you need to turn on PMD for each project separately. Which make sense, because you can have different rule set per project. So to turn it on, right click on project -> “Preferences” -> “PMD” (there would be two PMD sections if you didn’t uninstall old PMD plugin)-> “Enable PMD for this project” -> “Add…”. Now you should pick a location of PMD ruleset file.

pick-ruleset

Unlike old PMD plugin, eclipse-pmd don’t import ruleset. It is using ruleset file directly. This is very handy, because typically you want to have it in source control. When you pull changes to ruleset file from source control system, they are applied without re-import (re-import was needed for old PMD plugin).

Problem can be when you (or your team) don’t have existing ruleset. I would suggest to start with full ruleset and exclude rules you don’t want to use. Your ruleset would evolve anyway, so starting with most restrictive (default) deck make perfect sense for me. Unfortunately eclipse-pmd plugin doesn’t provide option to generate ruleset file. So I created full ruleset for PMD 5.1.1 (5.1.1 is PMD version not plugin version). I have to admit that it was created with help of old PMD plugin.

You can see that I literally included all the rule categories. I would suggest to specify your set this way and exclude/configure rules explicitly as needed. Here is link to PMD site that explains how to customize your ruleset. This approach can be handy when PMD version will be updated. New rules can appear in category and they will be automatically included into your ruleset when you are listing categories, not rules individually. But you have to keep eye on new rules/categories when updating PMD version anyway, because categories often change with new PMD version.

So now we should have rulset configured and working. Here are some screen shots of rules in action:

When you hover over left side panel warning:

eclipse-pmd

When you hover over problematic snippet:

eclipse-pmd

When you do quick fix on problematic snippet:

eclipse-pmd

Generating suppress warning annotation for PMD rules is very nice feature. It also provide quick fixes for some rules. Take a look at its change log site for full list.

These PMD warning sometimes clash with Eclipse native warnings, so there is possibility to make them more visible. Go to “Window” -> “Preferences” -> “General” -> “Editors” -> “Text Editors” -> “Annotations” and find “PMD Violations”.

eclipse-pmd

Here you can configure your own style of highlighting PMD issues. This is mine:

eclipse-pmd

To explore full feature list of this plugin take a look at its change log site.

There are some features in old plugin I miss though. For example I would appreciate some quick link or full description of the rule. Short description provided is sometimes not enough. I encourage you to take a look at full PMD rule description if you are not sure what’s source of the problem. You will learn a lot about Java language itself or about libraries you are using. Quick links would help a lot in such case.

Also some rules doesn’t use code highlighting (only side panel markers). It is sometimes hard to distinguish between compiler and PMD issues. This is problem for me because our team doesn’t use JavaDoc warnings but I do. So I get a lot of JavaDoc warnings from code written by teammates. And sometimes I can miss PMD issue because it is lost in JavaDoc warnings. (Fortunately SVN commit is rejected if I forget to fix some rule).

Conclusion

This plugin enhanced my Eclipse workflow. No more disruptions because of endless “Checking code…” processing by old plugin.

Step filtering: Skip certain packages while debugging in Eclipse

As Java developer, you are probably using a lot of frameworks. Spring or Hibernate can significantly reduce amount of boilerplate code. But inversion of control, dependency injections and proxies can be confusing during debugging. It is often annoying when debugger steps into third party library code. You realize that your code is wired via proxies and you have to add breakpoint into code you expect to hit.

But there is better way in Eclipse. Feature called Step Filtering. Very few my former and current colleagues using Eclipse were aware of it. Just go into Window -> Preferences and search for Step Filtering. Check Use Step Filters and specify packages/classes you want to skip during debugging.

step-filtering

Generate UML class diagrams from code with ObjectAid

I’ve used ObjectAid Eclipse plugin for years. But very few of my colleagues were aware of it. This fact surprises me and therefore I would like to highlight it. It is very handy for generation of UML class diagrams from your code. It is also invaluable for analyzing of existing design.

One of the top UML tools is Enterprise Architect. But I was never happy with Enterprise Architect usability. I find it much easier to sketch class structure in Java and generate  UML class diagrams by ObjectAid. Advantage of this approach is that you have basic skeleton of the module. You can check-it in, so that team can start working on implementation.

Have to mention that it’s commercial product, but Class Diagram version is free.  For my UML class diagrams needs (design analyze, generating UML diagrams for documentation, modules design sketching) it was enough so far.

They provide also paid Sequence diagram and Diagram Add-On versions. To be honest I have never tried these. For sequence diagrams I was using only Enterprise Architect so far. I would be definitely pushing towards buying ObjectAid licenses if we wouldn’t have Enterprise Architect licenses already.

There’s no point for me to provide detailed description of it, because ObjectAid site contains short and explanatory overview. I suggest to start with One-Minute Introduction.

Everyone understand how inaccurate can UML class diagrams become. Keeping them up to date manually doesn’t make sense at all. ObjectAid fills this gap, because you can maintain your class diagrams up to date. But I had problems in the past when diagrams couldn’t handle renaming or moving of Java classes. Not sure if this is still problem of recent versions, because my diagrams are short lived. I can easily generate new diagram by just dragging appropriate classes into Class diagram editor. This is beauty of ObjectAid plugin.

Links: