Creating Use Cases with the NetBeans 5.5 UML Tools

I'm currently working on a project that has given me the opportunity to use the NetBeans tools I evangelize.  I'm in the beginning part of a software project when modeling is critical.  The obvious tool choice was the NetBeans 5.5 UML feature.  This blog entry will give you some "tips and tricks" on how to effectively create Use Cases using the NetBeans 5.5 UML feature.  Here's a Use Case that might apply to a blogger tool just to get you in the mood.

usecase sample

Getting the UML Modeling Feature

Before you can use the UML functionality in NetBeans 5.5, you have to add it to the IDE.  The UML functionality used to be bundled in the Enterprise 5.5 Pack but now it's available as a standalone feature via the NetBeans Beta Update Center.  I think this was a great move for the feature which will hopefully allow it to grow and mature more rapidly.

First, go to the Update Center, from the menus choose "Tools->Update Center".  You'll see something like this.

update center

Notice the "NetBeans Update Center Beta" is selected.

Press the "Next >" button and you'll see this.

update center 2

Select "UML Modeling" and "Add >" it.  Continue through the process until the UML Modeling feature is installed.

Creating the Project

Now that you have the UML Modeling feature installed, create the project.  In the new project dialog, choose "UML" for the category and "Platform-independent Model" for the Project.  Here's what the new Project dialog will look like.

new project

When you "Finish", you'll be presented with a diagram dialog asking what type of diagram you want to create.  Choose "Use Case" and give it a name.  Here's what that dialog will look like.

new diagram

Use Case Refresher

If you're like me, you don't spend enough time modeling so you tend to forget some of the basic tenants of UML.  First, I believe all documentation should be useful.  I know many developers are afraid of "paralysis analysis" but too many swing the other way to "hacking before thinking".  I recently read some of the Agile stuff and was generally impressed.  I especially like Scott W. Ambler's discussion on documentation.  UML when done correctly is more than "just pretty pictures".

Remember there are really two artifacts around Use Cases; the textual Use Case and the Use Case Diagram (UML).  Here's a good resource to get you started with Use Cases

The textual Use Case describes expected and exceptional courses of interaction between actors and the system.  The Use Case Diagram graphically represents the interaction.  The real meat and potatoes is really behind the textual representation.  Ideally, the Diagram and the textual description could be kept together.  I'll show you how to do that with NetBeans 5.5 UML.

Creating the Use Case Diagram

Before we can fill in the textual use case information, we need to create the diagram.  From the steps above you should be staring at a blank Use Case diagram in NetBeans 5.5.  First, let's add an "Actor".



There is a feature of the UML feature that might take some getting used to.  When you drag and drop a component on the drawing service, the pointer is in what I call "semi-automatic" mode like a semi-automatic pistol.  All you have to do to fire is pull the trigger again without cocking.  In this mode, every time you click the mouse on the drawing surface you'll get another instance of the component you chose from the palette.  To get back to "manual" or "pointing" mode, simply hit the "ESC" key.  You can also select the pointer on the toolbar at the top.

Name the "Actor" "Bank Customer" by double-clicking on the "unnamed" label and typing in the new name.

Next, add a "Use Case" and name it "Login to Bank Account".  As you can see we're going to model a bank customer interacting with an online banking system.  Add another "Use Case" and name it "Transfer Funds".  

Now let's add some dependencies showing the actor - system interaction.  Choose a "Usage" dependency and drag it from the "Bank Customer" to the "Login to Bank Account" Use Case.  Also drag a "Usage" from "Bank Customer" to "Transfer Funds".  Lastly, drag a "Permission" dependency from "Login to Bank Account" use case to "Bank Customer" actor.  At this point, your diagram should look something like this.


Adding the Real Meat

As I said, the real meat of a Use Case is the textual description of the interactions.

We will use the "Documentation" property of Use Case element to document the interactions.   The "UML Documentation"  window looks tempting but I currently recommend against using it for a couple of reasons.  First, as issue 80014 describes, you can type a lot of text in the "UML Documentation" window then loose it if you don't click on the right part of the IDE.  Also, I filed issue 91102 for this behavior.   If you put blank lines in the "UML Documentation" window between your text, the IDE adds a line each time you leave the window.   Because of these two issues, I recommend you use the "Documentation" property to enter the textual use case.  The "Documentation" property expects HTML to be entered.  You don't need a proper HTML page with "<html></html>" tags.  You only need to focus on using HTML for formatting purposes.  To open the "Documentation" property editor, click the "..." next to the property.

doc property

Important Notes About Property Editor!

The property editor deals strangely with line ends.  In particular, when you have a <li> for a list, make sure the text for the <li> is right next to the tag and not split onto the next line.

For example:

This HTML-

Bank Customer enters userid/password.

Yields this display-

   Bank Customer enters userid/password.

Notice how the text is below the number for the list item.

Similarly, if you enter this:

Bank Customer enters

You will see this-

   Bank Customer enters

To get the desired results, enter the HTML like this.

<li>Bank Customer enters userid/password.

Also, the property editor does NOT have an undo feature.  So if you accidentally wipe out a bunch of text, too bad.  Hit the "OK" button frequently to save the contents.

Here's a template to use for the Use Case Text.

<u><b>Main Flow of events:</b></u>
<u><b>Exceptional Flow of events:</b></u>
Filling the details for the "Login to Bank Account" would look something like this displayed in a browser.

formatted text

Sharing With Others

The make or break for any UML tool is its ability to output its model in a usable format.  The NetBeans 5.5 UML Modeling feature does a great job of producing a HTML UML report.  To run the report, right-click on the project node and choose "Generate Model Report".  This will cause the IDE to create a HTML report and open it in the web browser.


The report feature doesn't seem to work correctly on Mac OSX.  According to issue 82394, there are also problems on Linux and Solaris.

Thanks to Parallels, I was able to run NetBeans 5.5 on Windows XP Pro on my Mac to produce the report correctly.  Here's what our little Use Case example looks like.



Future blog entries will include more of my modeling experiences with NetBeans 5.5 UML Modeling.  Until then, remember modeling is worth the time.  Do just enough documentation to fulfill the needs of the project team and the future system maintenance.  

Post a Comment:
  • HTML Syntax: NOT allowed

David Botterill


« July 2016