Sunday, August 21, 2011

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

36 comments:

Jan Köhnlein said...

Very nice work!

Did I get this right: Even though the resulting diagram is modifiable, it rather works like a view (no feedback to the Java code on diagram changes, exisiting diagram information is lost on regeneration)? That'd sound familiar to me ;-)

I wonder what *you* think about roundtripping (convert diagram changes back to Java code) or at least reconciliation (not loose manual diagram changes when changing the Java code).

Jens v.P. said...

@Jan: Yes, it's a one way ticket only ;-) The created diagrams are not semantic aware. And yes: roundtripping would be great. However, I didn't had much time, and I wanted to get some nice diagrams for real-world application. I needed less then 12 hours to create this little plugin, and I'm wondering how long one need for creating any GEF/GMF-based editor, producing these kind of high-quality diagrams (and the usability of OmniGraffle).

I could think of making this tool more "round-trippable". E.g., it should be possible to recognize existing class shapes, and do not re-create them again. And it also should be possible to parse the text of the shapes in order to create Java code from it. Actually, there exists a project called "graffle.modeling" (http://code.google.com/p/graffle-modeling/), but I didn't evaluated that tool because I was scared by the notion of "Prolog predicates", "OWL Ontologies", and "RDF graphs" ;-)

Marcus said...

Looks very nice, but I cannot get the plugin, http://jevopi.de/updatesite/de.jevopi.JavaToOmniGraffle leads to an 403 forbidden error.

Jens v.P. said...

@Marcus: The update site is not intended to be opened with the web browser, but with the Eclipse update system. Copy the URL and open in Eclipse: Help / Install New Software..., press button "Add..." and copy the URL into the dialog (Name and Location). You can then directly install the plugin via the Eclipse installation mechanism.

Marcus said...

@Jens: I know, I tried this in Eclipse Helios SR2, but no package appeared. This it why I tried it in my browser.

Marcus said...

Ahh, my fault. I had "Group items by category" checked, that lead to the package not to be shown.

Anonymous said...

That's a fantastic idea! Thanks very much. Looking forward to seeing this develop.

mathpup said...

This does not seem to work with a default package. I know that default packages are discouraged, but for my school assignments, I am required to put the classes into the default package. The only workaround I found was to make a copy of the entire Eclipse project and rename the default package to a specific package name, and use your plugin to convert that to OmniGraffle.

Jens v.P. said...

@mathpup Yeah, that's right. Besides, selecting multiple packages or single classes doesn't work either. Will be fixed in next version.

David Romero said...

Jens, very excited to see this working! Thanks so much for your work! I'm having a problem getting the plugin to work with OmniGraffel Pro. I've tried updating the plugin's preferences. I've tried "OmniGraffel Pro", "OmniGraffel Professional", and even "/Applications/OmniGraffel Professional.app" in the OmniGraffel app property with no luck. Any suggestions? Thanks again!

David Romero said...

Got it working actually, upon closer inspection the full name in the /Applications directory is "OmniGraffle Professional 5" What an awesome tool! Thanks so much Jens!!

Ken said...

Yipes -- this really did expire and I needed to diagram my latest!

Is there an update?

Jens v.P. said...

@Ken: Yeah, it really did :-)

OK, I have updated the tool in order to work until June 2012.

However, I'm still not sure how to continue with this tool. I'm well aware that it's only a little tool. On the other hand, if you have spent 100$ on OmniGraffle, I'm wondering why not spent 5$ on a small tool that saves you a lot of time.

Actually, what we need is an EclipseStore, as dontations and Flatter do not really work.

Tim said...

This plugin seems to be exactly what I'm looking for. However, no diagram appears in my OmniGraffle. Could that be due to the expiration issue?

Are you planning to continue development? I don't think that this tool has to do very fancy and complex things. Just create fine OG output and that's it (--> do one thing and do it right!).

If it worked for me, I'd surely be willing to donate a few bucks (good work deserves to be paid). So, I'm looking forward to your response.

Jens v.P. said...

@Tim: After the expiration date, instead of a diagram only a note is visible in the OmiGraffle diagram. (Maybe your comment and my update overlapped. Check if you have the latest version (0.2.0.2012...) installed.

Tim said...

I updated to the latest version. However, the diagram does not appear in my open OG (Pro 5) document. It did appear once, but never since. Is there a way to find out the reason? Some debug output or similar?

PS: Perhaps it would be easier for you to get paid if it were a standalone application or a OG plugin?

Jens v.P. said...

@Tim: Did you get the message box "OmniGraffle Diagram Created"? If you got that message, then the overall tool is working and probably there is a problem with the name of your OmniGraffle application.

You can try to manually execute the following AppleScript:
---------------------------------------------
property OG : "OmniGraffle Professional 5"
using terms from application "OmniGraffle Professional 5"

tell application OG
tell canvas of front window
set newNote to make new shape at end of graphics with properties {draws shadow:false, size:{82.0, 82.0}, name:"NoteShape", autosizing:vertically only, origin:{10.0, 10.0}, text:{{text:"Test"}}}
return newNote
end tell
end tell
end using terms from
---------------------------------------------
If that works, JavaToOmniGraffle should work as well. If it doesn't, you have to adjust the name of OmniGraffle (" "OmniGraffle Professional 5" in line 1 and 2 of the script). Once you have figured out the correct name, open the JavaToOmniGraffle preferences and set it there accordingly.

Tim said...

The first time I ran the script, it created something in OG. When I delete this and try to re-run the script, it says error "OmniGraffle Professional 5 got an error: AppleEvent handler failed." number -10000

Eclipse export doesn't work either.

Jens v.P. said...

@Tim: You must have a document opened with OmniGraffle. If there is no opened document, the script fails with that error message. (I assume the script fails at "make new shape...").

Tim said...

With a new document, the script works every time. Before that, I only had an opened one. However, Eclipse does not work. I use Eclipse 4.2 M5. Can this be the problem?

Jens v.P. said...

@Tim: Maybe Eclipse 4.x is the problem, in deed. I have tested the script with Eclipse 3.x only.

Ken said...

Thanks, Jens,

Worked great, but I'm using Eclipse 3.7.1

Yes there needs to be an Eclipse store.

This has saved me lots of time -- would be willing to pay for it. In general I will send < $10 for a neat utility like this without thinking twice. > $20 feels like "real money" and I need to think.

Let me know how much and how.

---==>Ken

Jens v.P. said...

@Ken: Isn't it working with 3.7.1? I've just tested it with 3.7.0, and at least that works.

I'm happy you're happy with the tool :-) Actually, 20$ is much to much, as it is only a small tool, isn't it. I thought more about 3 to 5$ (and this is why I was thinking of a kind of AppStore, as it doesn't make much sense to manually manage payment and licenses in that case). At the moment, I only have this PayPal donate button. If it doesn't work, don't bother -- it's the thought that counts.

月讀 said...

Great Job.
I need your plugin, please keep to develop it.

Kevin said...

Thanks, it is great. However it does not show the public scope.

Jens v.P. said...

@Kevin: The public scope check box is disabled, as public attributes and operations are always generated. But you can omit private or protected members.

langersteff said...

I AM STOKED! This is exactly what I was looking for! You definitely got my +1!

Anonymous said...

Just wondering: Has anyone successfully used this great plugin with Juno?

Anonymous said...

Very nice - and works fine on Eclipse-Juno.

Anonymous said...

This tool is very very nice. This is exactly what i searched over months. And it works without any greater configurations. Very nice.

Bruce Edge said...

Nice tool. Definitely a need for this in the marketplace. Please continue development.

Anonymous said...

Hi Jens, i have a problem with that.... i' using Eclipse 4.3 (Kepler) whit JavaToOmnigraffle Feature 0.2.3.201209291226 and Omnigraffle 6. The problem is that i can't draw anithing, it also says to me that "New classes should be visible in your OmniGraffle drawing" but nothing. In OmniGraffle i do: New Resources -> New Template. Can you help me? thanks a lot

Jens v.P. said...

@Anonymous: I have tried it with Kepler and OG 6, and it is working just fine. However, I'm still using OS X 10.8. Besides, instead of opening a template, simply open a new document. Hope that helps.

hoeiriis said...

I'm experiencing the same issue as the previous commenter. All that appears in OG are small empty boxes, running OG 6, E 4.3, OS X 9.

Steffen Luypaert said...

I am afraid this is not working anymore from OS X 10.9 on?
I have a diagram opened in Omnigraffle. In Eclipse I create a new Omnigraffle diagram. It responds with "New classes should be visible in your Omnigraffle drawing". However, nothing appears.
When I try to execute the Applescript above, it fails on the "set newNote to make new shape at end of graphics with properties {draws shadow:false, size:{82.0, 82.0}, name:"NoteShape", autosizing:vertically only, origin:{10.0, 10.0}, text:{{text:"Test"}}}" line with the syntax error "Expected “,” or “}” but found application constant or consideration.".

Jens v.P. said...

@Steffen: I have tested it on 10.9 as well and it works for me. However, it only works with OmniGraffle 5. With OmniGraffle 6, AppleScript is only available in the Pro-version. Honestely, I'm a little bit disappointed about the latest OmniGraffle developments: With AppleScript only available in the Pro-version and the requirement to log into Graffletopia, effectively preventing stencils to be directly installed from OmniGraffle), I'm not sure whether I should better look for an alternative drawing tool...