Create Beautiful UML Diagrams in Minutes from the JetBrains IDE

A few days ago I needed to assemble together several disparate pieces of information about the current project. Our technology stack is complex, and people have different backgrounds, so I realised that a visual representation in UML would be the best fit.
The current article details how to prepare a working environment using Graphviz and PlantUML in PHPStorm, then goes through the process of creating a simple sequence diagram to use them.

Diagrams: the “why” and the “how”

Created by the Object Management Group, UML is the de-facto standard design language in the software community. If you are not familiar with it, or just need a quick refresher, this article on the developerWorks website is very good.

As I tried a couple of online services, it became increasingly clear that they were not fit for my complex set of interacting components. I then turned to my favorite diagramming, tool Graphviz. It turned out there was no straightforward editor on top of it to do sequence diagrams. Luckily, I pretty quickly found PlantUML, which uses Graphviz for all it diagrams but sequence ones. I was impressed by the amount of integrations it offers so I decided to give it a try, and was amazed with the speed of which I produced the end result.

In the next sections we’ll learn how to get our environment up and running, and then draw a quick example sequence diagram.

Setup

Prerequisite

Installing Graphviz using brew worked perfectly for me.

$ brew install graphviz

If you prefer an alternate method, you can download the package instead.

PlantUML

Internally, our company uses PHPStorm as an IDE for developing PHP code, and IntelliJ idea for the Java bits. I will present details for the PHPStorm users, but the steps should be easy to replicate in other IDEs of the same vendor.

Let’s open the preferences and start looking for new plugins.

01-phpstorm-plugins

We need to search for “PlantUML” and install it.

02-phpstorm-install-plantumlintegration

After restarting the IDE, we notice there are new filetypes available for us to create:

03-phpstorm-newfiletypes

Sequence Diagram example

Let’s create a new UML Sequence diagram, named “demo”. Notice how the .puml extension was automatically added.

04-phpstorm-newumlsequence

The diagram I actually needed to produce is very heavy, and not fit for the purpose of this quick introduction. Then I remembered checking the Clean Coders Yahoo group the other day, and found some Ruby sourcecode they were talking about. I thought it would be a good example to try our new diagram superpowers on, as it’s short.

The first step is to define the participants in our diagram. It’s easier to list them all in the beginning, because this way we can choose the order in which they appear.

05-defineparticipants

We will now add the sequence of events. The PlantUML website has a great page on the various options available, so make sure to check it out.

06-describesequence

The stock look and feel is nice and gets us far. I however felt the need to prettify the end result by introducing some nice formatting options. The manual page for the skinparam command is very helpful.

07-nicelyformatted

Conclusion

After installing Graphviz and PlantUML extension for PHPStorm, we were able to produce a sequence diagram in a few minutes. You can take a look at the final version of the code as we obtained it. The advantage of having these tools available straight from the IDE is that the diagrams can be part of the project code, and be managed together.

HowTo Quickly Erase All Documents from an ElasticSearch Index

Let’s say you are locally developing things using the amazing ElasticSearch technology, and would like to quickly wipe out all documents from a specific index.

Assuming you have ES installed on localhost, and the index name is playground, here’s how you would do it:

curl -XDELETE 'http://localhost:9200/playground/?pretty=true'

And the index is now empty, waiting for test data!

Fix Vagrant problems after Mavericks update

Updated the OSX to 10.9 over the weekend.

While most of the troubles I encountered were caused by PHP 5.3 being completely wiped out and the system getting a stock install of 5.4, there were other minor things which didn’t go quite smoothly.

I use a VirtualBox + Vagrant + puppet combination to work on some side projects, and this was affected in a pretty mysterious way, as can be seen below:

➜  centos64 (master) ✗  vagrant up
Bringing machine 'default' up with 'virtualbox' provider...
[default] Importing base box 'theCentos64'...
[default] Matching MAC address for NAT networking...
[default] Setting the name of the VM...
[default] Clearing any previously set forwarded ports...
[default] Creating shared folders metadata...
[default] Clearing any previously set network interfaces...
There was an error while executing `VBoxManage`, a CLI used by Vagrant
for controlling VirtualBox. The command and stderr is shown below.

Command: ["hostonlyif", "create"]

Stderr: 0%...
Progress state: NS_ERROR_FAILURE
VBoxManage: error: Failed to create the host-only adapter
VBoxManage: error: VBoxNetAdpCtl: Error while adding new interface: failed to open /dev/vboxnetctl: No such file or directory

VBoxManage: error: Details: code NS_ERROR_FAILURE (0x80004005), component HostNetworkInterface, interface IHostNetworkInterface
VBoxManage: error: Context: "int handleCreate(HandlerArg*, int, int*)" at line 68 of file VBoxManageHostonly.cpp

This was not an easy task to fix, as Mavericks is pretty new, and Google doesn’t help very much with finding the solution.

In my case, I discovered that if I restarted VirtualBox things will be working again.

sudo /Library/StartupItems/VirtualBox/VirtualBox restart

So this is not strictly related to Vagrant itself, rather to the VirtualBox provider I was using.

HowTo Easily Upgrade Ruby on Mountain Lion

The default Ruby version coming with Mountain Lion is a bit old
➜  ruby -v
ruby 1.8.7 (2012-02-08 patchlevel 358) [universal-darwin12.0]

If only for staying up-to-date with the latest Ruby version, you will want at least 1.9 on your local machine.

There are multiple ways to achieve this, but I found it easiest to use the Ruby Version Manager. This clever command-line tool gives you the freedom you want, at a minimal cost.

Let’s start by installing it:

➜ curl -L https://get.rvm.io | bash -s stable --ruby

At the time of this writing, the latest Ruby version was 1.9.3, and RVM already installed it on your machine.

All you need to do now is to type
➜ rvm use 1.9.3
➜ ruby -v
ruby 1.9.3p385 (2013-02-06 revision 39114) [x86_64-darwin12.2.1]

In case you will need to return to the default ruby version, this is easily accomplished by
➜ rvm system

The screencast has even more detailed RVM usage, geared towards developers.

Easy Setup of Sencha Command on Your Mac

Prerequisite: If you haven’t done this already, setup Sencha Touch SDK.

Step 1: Download Sencha Cmd from the dedicated page.

Download latest Sencha Cmd from the sencha.com website

 

Step 2: Move the archive to a working folder. I used ~/Documents/Work/learn/sencha.

Step 3: Unpack SenchaCmd-3.0.2.288-osx.app.zip by double-clicking it. You should find the installer in your working directory, like in the picture below.

Step 4: Launch the setup by double-clicking the installer. Proceed to the next step. Accept the license agreement and click Next once more.


Make a note of the installation folder you choose in this step. I used /Users/g/bin. Proceed to the end of the wizard and click Finish.

Step 5: Verify that everything went okay. This is achieved from the command-line, by navigating to the SDK setup folder and launching the sencha command.

Note 1: The Sencha Cmd installer automatically adds its dependencies to the .bashrc settings file. if your favorite shell is not bash, you need to perform an extra-step before the verification works. If you’re a zsh user like me, at the end of your .zshrc file you need to add 2 lines to make this work.


export PATH=/Users/g/bin/Sencha/Cmd/3.0.2.288:$PATH
export SENCHA_CMD_3_0_0="/Users/g/bin/Sencha/Cmd/3.0.2.288"

Don’t forget to reload the settings file:

. ~/.zshrc

Note 2: If you had previous versions of Sencha installed, it’s a good time to cleanup your .bashrc (or .zshrc) file from those occurrences.

Easy Setup of Sencha Touch SDK on Your Mac

Step 1: Go to the download page of the Sencha Touch product.

In the Free Commercial Version form, enter your email address and click the Download button.

At the time of this writing, the latest stable SDK version is 2.1.1, which you will find referenced in the paragraphs below.

Step 2: Click the download link in your email. This will open a browser window and start the sdk download process. The result should be a sencha-touch-2.1.1-commercial.zip file in your Downloads folder.

Step 3: Move the sdk archive to a working folder. I used ~/Documents/learn/sencha/sencha-touch-2.1.1-commercial.zip as the final destination.

Step 4: Unarchive the sdk. This should create a folder ~/Documents/learn/sencha/touch-2.1.1 on your machine.

That’s it!

Now, when you see instructions on the Sencha documentation that look like

#  Make sure the current working directory is the Sencha Touch 2 SDK
cd /path/to/sencha-touch-2-sdk

you will need to do use the path obtained in step 4 above. In my case, this means:
cd ~/Documents/learn/sencha/touch-2.1.1

HOWTO remove all dangling commits from your git repository

A good explanation of the dangling commits source tells you how they get created.

git fsck --full
Checking object directories: 100% (256/256), done.
Checking objects: 100% (3658/3658), done.
dangling commit 79a3a6af4cda22c8b4f9f6eb01f537d961c088df
dangling blob 82c4e5aa9483cbd92cb4f03c2a8c23272ce41df9
dangling commit 5a857dc2e84bed64434c22a204bf5ed039802b46
dangling blob 3a482dae3fa596c91314ec25311952b740445846
dangling blob 2ed1ba8e6e884414e19b0a59989a0daef1918ccf
dangling commit 3c3a2073d9335627b48ff5f309bf1c6eafb69919

How to quickly remove those?

git reflog expire --expire=now --all
git gc --prune=now

Make sure you really want to remove them, as you might decide you need them after all.

How to install kcachegrind / qcachegrind on Mac OSX

Installing kcachegrind via macports takes a long time because it has to build KDE, as well.

An alternative faster way is described below.

  • download Qt binary and install it
  • download and install graphviz; I used brew install graphviz
  • fix default graphviz location by symlinking to a place where cachegrind will find it sudo ln -s /usr/local/bin/dot /usr/bin/dot
  • qmake -spec 'macx-g++'; make
  • copy generated qcachegrind.app to your Applications folder
  • enjoy!