Java To OmniGraffle

If you ask developers using Mac OS X about their favorite diagramming tool, you will often get the same answer: OmniGraffle. I also like OmniGraffle very much, and I'm still wondering what makes this tool so much better then all the GEF based editors.

When I have to create diagrams for documenting some Java code, I used to manually draw an UML like class diagram with OmniGraffle. This is an error prone process, and a boring one as well. So, I tried to find a better solution. Since I didn't find any existing tool, I wrote a small Eclipse plugin my self. It automatically generates OmniGraffle class diagrams from existing Java code.

Its usage is very simple: Open or create a drawing in OmniGraffle. Then switch back to Eclipse and select "Create OmniGraffle Diagram" from the context menu of a package in the package explorer, as shown in Figure 1. Configure the output, as shown in Figure 2. The plugin will scan the package and add a class diagram of this package to the front most drawing opened with OmniGraffle. Figure 3 shows the result created by the plugin without any manual changes. It is a visualization of the package "ReverseLookup" of GEF3D.

Fig. 1: Context menu entry

Fig. 2: Configuration Dialog

Fig 3: Created class diagram

At this moment, the plugin can only create class diagrams for a single package. Update: The plugin can create class diagrams for selected types, packages, and sub packages. Besides, the context of selected classes, that is types on which the selected types depend on, can be visualized as well. Attributes are drawn as associations if possible, parameterized collection types are recognized and replaced by 0..* associations. You can configure the output with some switches. Besides filtering members based in their scope, I have added some "filters" I often use when I draw diagrams manually:

• Getter and setters can be omitted
• Methods implementing or overriding methods of interfaces or classes already shown in the diagram can be omitted as well
• In order to better see relations between classes, you can force to draw all associations, even if they would be filtered out by the scope filter.

The newly created shapes are initially drawn using OmniGraffle's hierarchical layout algorithm.

Tip: In order to manually change the diagram, you may want to have a look at my collection of UML shapes at Graffletopia.

You can install the plugin via the update site:

http://jevopi.de/updatesite/de.jevopi.JavaToOmniGraffle

This is an beta alpha version, which will expire 2012. If you find this plugin useful, flattr me! Or leave me a comment below. Depending on the feedback, I will continue developing the plugin -- or not ;-)

In the preferences, you can set the default configuration settings and define the name of your OmniGraffle installation (however, the plugin tries to find the latest installed version automatically).

Last but not least: Of course, this plug is only available on Mac OS X, since OmniGraffle is a native Mac application. The communication between Eclipse and OmniGraffle is done via AppleScript, which is very easy thanks to Peter Friese's blog post.

(At Stackoverflow, someone estimated a tool for creating OmniGraffle diagrams from Eclipse UML2 based models would require 18 months development effort. Well, I needed less then 18 hours. But I only convert Java packages to class diagrams... ;-) ).

Update 2011-11-01:

1. Besides packages, selected types and sub packages can be visualized.
2. The context of visualized types can be visualized. That is, types on which the selected types depend on, such as super classes, can be rendered additionally to the selected classes. These context types are rendered in gray.
3. The default package is now handled as well (see comment by mathpup).

String.format vs. MessageFormat.format vs. String.+ vs. StringBuilder.append

Usually I'm not a performance hacker, i.e. I seldom use the final keyword, and I dare to use List.size() in loop expressions. But I'm a little bit sensitive when it comes to string operations, as they can cause severe performance problems, and sometimes security issues as well, e.g., if an SQL query is to be created (ok, bad example, one can use PerparedStatement instead of hacking an SQL string). For logging I often have to concatenate strings, such as

if (log.isLoggable(Level.INFO)) {
    log.info("Command created - cmd=" + cmd); //$NON-NLS-1$
}

Actually I'm not writing lines like this myself, I let log4e do the job -- I really love that tool! But sometimes these string concatenations are hard to read, using a String.format or MessageFormat.format would make it much easier. Here are some examples:

foo(String.format("Iteration %d, result '%s'", i, value[i%2]));

foo(MessageFormat.format("Iteration {0}, result ''{1}''", i, value[i%2]));

// single line:
foo( "Iteration " + i + ", result '" + value[i%2] + "'");

// multi line:
String s;
s = "Iteration ";
foo(s); s+= i; foo(s); s+= ",\nresult '";
foo(s); s+= largeString(i); foo(s); s+= "', '"; 
foo(s); s+= largeString(i+1); foo(s); s+= "'";

foo(new StringBuilder("Iteration '")
    .append(i).append(", result '").append(value[i%2]).append("'")
    .toString());

(Update: the multi line test was added after daObi and Laurent commented the first version) Hmm... maybe the "+" isn't that bad ;-) I do not understand why String.format andMessageFormat.format have these different notations, and frankly I seldom get the format string right in the first run. So, besides the aesthetics, what about performance. What would you guess? My guess was StringBuilder would be the fastest, followed by the format methods, and the String operator "+" would be the slowest as new Strings are to be created all along. I run a little test (calling these methods 100000 times, foo() is doing nothing and was, besides other things, only added in order to avoid too much compiler optimizations, although I have no idea if that worked ;-) ). Note that in the test only a few strings are concatenated, but I think that's a typical example and it was the setting I was thinking about to use format methods instead of string concatenation (and it's quite similar to many toString methods). I was surprised by the result:

String.format:	757 ms
MessageFormat.format:	1078 ms
String +:	61 ms
String + (multi line):	162 ms
StringBuilder:	74 ms

Gosh! The "+" operator clearly is the winner! It is 10 (ten!) times faster then the format methods. 10 times, can you believe that. I was really surprised, and frankly, I couldn't believe it. (Update: daObi and Laurent explain it, see their comments below). Thus I changed the test, assuming the compiler tricked me, but I always got more or less the same results. I figured it may be the size of the strings, so I also changed that. That is, I used large strings (with 70.000 characters, the method returns one of two strings in order to avoid compiler optimization) in the concatenation:

for (int i = 0; i < n; i++) {
    s = MessageFormat.format("Iteration {0,number,#},\nresult ''{1}'', ''{2}''", i,
   largeString(i), largeString(i+1));
}

for (int i = 0; i < n; i++) {
 s =  "Iteration " + i + ",\nresult '" + largeString(i) + "', '" + largeString(i+1) + "'";
}

Actually, the test is a little bit unfair, as in all cases at least the result string has to be created (i.e. also the format methods have to create strings), but at least the string is rather long. The result string s has a length of 140027 characters, so this is a pretty long string, isnt't? Here are the result of the long-string-test:

String.format:	584 ms
MessageFormat.format:	816 ms
String +:	621 ms
String + (multi line):	867 ms
StringBuilder:	555 ms

Yeah! Now we have the order I expected in the first place: StringBuffer.append is the winner, followed by String.format. MessageFormat.format has a little problem and is even slower than the String concatenation. But compared to the result of the first test, all methods are at the same speed. So, what did I learn? First, I will use the plain and simple string concatenation in the future more often, as it is easier to write in many cases compared to some weird format strings. I will use String.format only if I probably need to translate my code, since this is easier to translate a format string than changing the code (if the order of the sentence components change in another language). And, of course, I will use StringBuilder if large strings have to be concatenated, but I think I use it less in toString-methods. And maybe I'm going to read a book about performance hacking -- do you have any recommendations? Anyway, this test also teaches me (again) that good performance is not (only) a question of single statements, but a question of good algorithms and good design in general. Note: Actually this is not the first time I was surprised by the result of a preformance test. I did a test once comparing the performance of different class library designs in case of a math library for matrices and vectors. I have documented the test in the LWJGL forum, and its results influenced the design of the GEF3D geometry package (see package documentation).

String.valueOf(Object obj) vs. Object.toString()

I'm programming with Java for more than 10 years now and I have always used Object.toString() to print out any kind of objects, usually for debugging and logging purposes. Looking at code written by others, this seems to be pretty usual. But there is a big problem: the object may be null. In this case, the call to Object.toString() will result in a NullPointerException. Sometimes ;-) I'm well aware of this problem, so I usually wrote ((obj==null)?"null":obj.toString()). By accident I found this nice function a day ago: String.valueOf(Object obj). What does it do? It's a static method and it looks like that: return (obj == null) ? "null" : obj.toString();. Looks pretty familiar. Why didn't I found this method earlier? Carnival barker: "Are you using this method? If not, start today and bugs like this will become history!" So, I would recommend to use String.valueOf(Object obj) rather than Object.toString(). But there are others (e.g. here or there) who recommend to prefer Object.toString(), because you can save one method call. IMHO this is the wrong place to start optimizations. I also found some tutorials which explain that you can use one or the other without discussing the differences. Maybe that's why I needed 10 years to find this nice static method.