This is a solution for generating UML Diagrams in your JavaDocs from your classes in the NetBeans 7.x IDE. If you just want the solution scroll down to the appropriate Section The Solution. If you want some background to the situation, some ranting, and some counter arguments, feel free to read the rest.
NetBeans UML is a much needed tool and resource. Unfortunately, NetBeans UML, is MIA (missing in action) in the latest versions of the NetBeans IDE; everything after 6.9.x. Luckily, I have discovered a pretty decent work around. My solution does not allow you to convert a UML diagram into a set of classes and method stubs, but at least it allows you to convert your code into a pretty UML diagram.
Update 3/31/2012: yWorks has another great tool, yEd, read more here.
Update 08/09/2012: yWorks has released a new version, for supporting Java 7 I believe. The version is titled: yworks-uml-doclet-3.0_02-jdk1.5 read more at the bottom.
A Note on NetBeans UML:
One aspect of annoyance from the NetBeans UML plugin is that not even a semi-broken UML generator is available for NetBeans 7.x, which is frustrating for the community of users. I think many of the users of the plugin would appreciate and happily accept even a half-working version, even if that did set back production of a complete solution. I am going to assume however and hope that the changes made to NetBeans 7.0 resulted in an explosion in the amount of work necessary to get the UML plugin working again with the latest version. This code explosion being large enough, that starting over or getting something semi-working are an equivalent amount of work. I have a hard time believing that the old code that worked up through 6.x was so horribly written that all of a sudden such an explosion could occur, but perhaps that is in fact the case.
Nevertheless, in defense of the developers working on the plugin, if we (the user community) wanted the plugin sooner, we could all donate our time to helping code it. I know, many of you are like me and hope that NetBeans UML will be back up and running soon, so to the community working on that, good luck and do your best, your tool is definitely an important service that many of us enjoy. In the meantime here is an alternative solution to the problem.
The Solution:
Step 1: Head over to yWorks UML Doclet and download their tool.
Step 2: Right click on your java project of choice in your project explorer within NetBeans 7.0.x
Step 3: Choose Properties.
Step 4: Select Documenting under the Build category.
Step 5: At the textbox for Additional Javadoc Options: paste the following:
-docletpath “<yid>\lib\ydoc.jar” -resourcepath “<yid>\resources” -doclet ydoc.doclets.YStandard -umlautogen
Where <yid> is the file path for the files above. In my case <yid> reads as: C:\Users\Matt\yworks-uml-doclet-3.0_01-jdk1.5
Step 6. Click ok.
Step 7. Right click on your project in the projects explorer.
Step 8: Click Generate Javadoc.
You are finished, within your Javadoc you will find that you have a beautiful UML diagram for your classes.
Extra Information:
I derived my solution above from the documentation contained within yWorks UML Doclet. Specifically within the yworks-uml-doclet-3.0_-1-jdk1.5/doc folder. One peculiar “characteristic” of the documentation is within the html based Usersguide. Section 4 has a bit about running yDoc, near the bottom of this section it mentions the steps necessary to run yDoc within NetBeans 5.5. As a caveat, luckily it works with 7.0.x as well, nice job yWorks! Aside from that, the documentation leaves off an important step. Near the bottom of section 5 – yDoc Features, there is a line of text that explains what -umlautogen does, and that is the important step I had difficulty finding. Without that important statement nothing happens, and I found just -umlgen was not sufficient, which makes sense since further reading will tell you to include the @y.uml tag in files which you wish UML diagrams to be generated. Moral of the story read all the documentation, as a counter argument, another moral would be, include all the steps necessary to complete the task in your documentation.
August 2012 Update:
With the release of Java 7, yWorks has released a new ywork-uml-doclet which is necessary in order to get the java docs to be generated properly. I ran into a handful of errors on this point until I realized I needed to update, so if you have problems, check this first. Also I am including a very simple netbeans project which allowed me to generate java-docs. If you want to use my project for a test-run, you will still need to change the <yid> to fit your doclet-path. However, I hope it will be helpful if you have any problems.
Uml Example Project – Just change your paths, right click on the project and generate javadocs.
Hi Matt,
I have tried it but i got an error like this:
No source files and no packages have been specified.
I’m new to Java and NetBeans so i don’t know what to do with that.
It will be really easy for me to use this uml design coz it is really annoying to draw the uml diagrams for me.
This could be one of two things and if anyone has knows the problem and a solution I would appreciate it if you could also add to this dialogue.
There error seems to to say you have some missing files. There are two places that could have missing files, first, your own code for your project. You are going to build a javadoc, that incorporates UML class diagrams, but Netbeans needs code to build that java-doc from. So, I want to confirm that you have a package and a source file in your Netbeans project. If you don’t have any source code in your project, there is nothing that Netbeans can build that java-doc from.
The second case, where files might be missing, are the files in the Additional Javadoc Options, for reference and clarity sake, here is the exact line I have written in my Additional Javadoc Options text field.
-docletpath “C:\Users\Matt\yworks-uml-doclet-3.0_01-jdk1.5\lib\ydoc.jar” -resourcepath “C:\Users\Matt\yworks-uml-doclet-3.0_01-jdk1.5\resources” -doclet ydoc.doclets.YStandard -umlautogen
From reading the error, I believe your case to be the first one, but it wouldn’t be first time I was wrong. Let me know if either of those solutions help.
Hi Matt,
I have tried it but i got an error:
javadoc: error – Cannot find doclet class ydoc.doclets.YStandard
and of course i replaced the path ” C:\Users\Matt\yworks-uml-doclet-3.0_01-jdk1.5″ by my path
I am also getting the same error:
javadoc: error – Cannot find doclet class ydoc.doclets.YStandard
I am using a JDK1.7 though.
Thanks
Hi Matt ,
I have the same problem:
I try this
-docletpath “/Users/Walter/yworks/lib/ydoc.jar” -doclet ydoc.doclets.YStandard -resourcepath “/Users/Walter/yworks/resources” -umlautogen
and
-docletpath “/Users/Walter/yworks/lib/ydoc.jar” -resourcepath “/Users/Walter/yworks/resources” -doclet ydoc.doclets.YStandard -umlautogen
I am using NetBeans in a Mac Lion
Thanks , i will wait your anserws
Based on the error messages you folks have described, unfortunately I cannot tell you any new information about what the problem is, other than Netbeans isn’t able to find either the ydoc.jar or it cannot find the necessary resources from the resource path.
As additional information I have only run this on Windows 7 and cannot confirm whether it works on Mac or not, perhaps someone else can comment if they’ve gotten it to run on Mac. According to the user guide, additional steps are necessary for Unix/Linux and nothing is mentioned in regards to Mac, so that might be the problem.
The step that I can suggest is read the userguide.pdf file located in the yWorks/doc folder for more information about how to set it up, which is the resource I followed to get it to work the first time and the origin for this blog-post.
According to section 2 of the user guide, under System Requirements: “yDoc 3.0_02 requires JDK 1.5.0 or JDK 1.6.0 installed on your system.”
I would really appreciate it if any of you get it to work, to post your solution. It is difficult for me to debug your issues from this end, as I am unaware of any other settings you may have set up on your machine, specifically within Netbeans that might be causing issue, though I cannot think of anything off the top of my head.
Sorry I can’t be more of a help. As a final note, thousands of people have read this post, and I don’t think anyone would read this post for fun, so presumably some of those people have got it to work, and not bothered posting a comment.
If you have had success getting this to work and have read this far, please comment on your success, so I can know at least someone has gotten it to work. I hope this blog-entry isn’t wasting everyone’s time by always resulting in failure. Also if you have noticed a step that I have missed in the process, please let me know so I can include it in the entry so others can benefit. I hope this helps and good luck.
Hi guys, I found a solution to the bug many of you experienced. Just remove the “” in the line
-docletpath “\lib\ydoc.jar” -resourcepath “\resources” -doclet ydoc.doclets.YStandard -umlautogen
and retype it the netbeans textbox for additional javadoc options. The “” will thus be replaced with “”.
I believe netbeans was unable to read the “” characters that was typed in the webpage properly, hence unable to find the relevant files.
Hope this helps 🙂
This worked for me thanks 🙂
I was able to generate successfully my java docs but I don’t see any UML diagrams what did I do wrong? I follow all the steps you post, greetings from Mexico!
Your example works fine, but I find that this message:
YStandard Doclet version 3.0_02
Valid license file found.
doesn’t appear when I generate the documentation on my project and no Uml images are generated in my project
=) lograste obtener los diagramas de clase ???
Hi it is the comments “” around the resources part that need to be changed
I got my javadocs too by removing the “” …… but I don’t see any UML diagrams….enrique marmolejo :p avisa si lograste obtener los diagramas de clase …saludos desde Mexico tmbn n.n
Hi,
it’s generating fine, but I get these kind of issues! Most diagrams are split like that…
Does anybody have an idea about this?
http://i.imgur.com/6TM2T.png
Additional information:
It doesn’t seem to be a browser related problem, since it occured on Firefox 14.0.1, Chrome 21, IE9.
The diagrams are split into multiple sub-images and fail to merge in the final HTML-file. But why isn’t yWorks generating single images in the first place?
Okay I fixed it!
Open /resources/ydoc.cfg, search for “tiling” and turn it off by replacing the “true” with “false”.
Thanks for that fix it works great
Kal Zander: Thanks for the tip on the image fix.
People who get javadocs without the UML diagrams: be sure to add -umlautogen (or maybe some other switch from the list in the yWorks user guide) to the “Additional Javadoc Options” field. I didn’t catch that at first, and so I was getting javadocs with no diagrams.
Also, the user guide says to add paths to any libraries to the docletpath option. When I did that (in NetBeans IDE 7.2), NetBeans suddenly could not find the yWorks doclet (which was first in the path). I’m not sure what the problem was, but the workaround was to do a clean build of the project (which copied the external library jar files to the NetBeans project dist folder) and then generate the javadocs _without_ adding any extra paths to the options field.
Hi, everything worked just fine to me. I only had to replace the quotes, like another user previously said.
Awesome, it also worked for me ;-), nice job yWorks
This has worked great for me but the only thing it does not do is do is one for an innerclass, is there a setting I can change?
I would personally like to let you know that I have worked the last 15 hours with other less than satifactory UGH stuff. Your post made my day.
Creately online diagram software could be used as an alternative to Beans to create UML diagrams. Specifically all UML diagram types can be created with creately