Mastering J2EE Application Development Series

Step 3 of 12: Design and Modeling

Design First, Code Next
by Scott W. Ambler
Model J2EE applications with style using a collection of techniques for creating effective Unified Modeling Language (UML) diagrams.
If there is one thing I've noticed over the years, it's that the best programmers think through the design of their code before they actually write it. Some will talk through their design with another programmer, often drawing sketches on a whiteboard while they're doing so. Others will use a more sophisticated, software-based modeling
tool that generates the source code for them. Either way, both groups take the time to think things through via modeling before they jump into the code.
"You can't just slap a J2EE application together
and hope to succeed; instead, you need to
think your design through first"
J2EE applications are very complex beasts: you're often working with Java Server Pages (JSPs), Servlets, Web Services, EJB Session Beans, EJB Entity Beans, XML-based data, and Oracle databases. You can't just slap a J2EE application together and hope to
succeed; instead, you need to think your design through first. That doesn't mean you need to spend weeks or even months writing a huge document, as Agile Modeling clearly shows, but you do need to do something. The trick is to know how to model effectively
and do just enough modeling to get the job done.
This article describes a collection of techniques for creating effective Unified Modeling Language (UML) diagrams using Oracle JDeveloper 10g. We'll focus on the object-oriented (OO) aspects of an e-commerce application using UML use case diagrams, UML sequence diagrams, and UML class diagrams. Other aspects of your application, such as the
user interface and your database, are important and should also be modeled along similar lines, but will not be discussed here.
A typical approach to developing OO software is to identify usage requirements. In this situation use cases are applied although we could just as easily have written user stories (a la Extreme Programming), and then model the logic of those requirements with sequence diagrams. Your use cases describe how people work with the system, using business
terminology to do so. Although this sort of information is critical to your success, it isnt sufficient for software development and it needs to be transformed into something more technical. This is where sequence diagrams come into play theyre used to visually represent how a portion of a use case will be implemented using your chosen technologies (in
this case J2EE). While you draw sequence diagrams you will identify methods/operations, which are supported by attributes/properties, which in turn are implemented by classes. All of this information, as well as the relationships between classes, forms your object schema which is captured by your UML class diagram(s). Your object schema is then
mapped to your database schema, either hard-coded using SQL or automated via a persistence framework such as Oracle TopLink. Object/relational mapping and database design are out of scope for this article, although style issues are clearly important for these two activities as well.
Effective Use Case Diagramming
Figure 1. A poor rendition of a UML use case diagram, drawn with Oracle JDeveloper's
Use Case Modeler. (See end of article for larger image.)
UML use case diagram(s) overview the usage requirements for your system and are often used to communicate the scope of software development projects. Figure 1 depicts a poorly rendered use case diagram; Figure 2 depicts the same information with a few
simple changes to improve its readability and usefulness.
So what did I do to improve the diagram? First, I applied business-oriented names to the use cases. "Create Order Record" is a technically-oriented name, whereas "Place Online Order" uses actual business terminology. The primary audience for use case diagrams
is project stakeholders, not DBAs, so you should use business-oriented terminology wherever possible.
Second, I applied several basic layout strategies:
G Use case symbols (the ovals) should be sized consistently. Large bubbles look more important than smaller bubbles, so unless you purposely mean to imply importance you should strive to keep them the same size.
Figure 2. A readable rendition of a UML use case diagram, drawn with Oracle
JDeveloper's Use Case Modeler. (See end of article for larger image.)
G Consistently place actors on diagrams. Place human actors on the left side of the diagrams, system actors on the right side. People in western cultures read left to right, and because human actors are typically the starting point in any system, you want to place
them where people naturally start to read a diagram.
G Included use cases are depicted to the right of the parent use case. This is the common UML modeling convention, and following common conventions such as this makes your diagrams easier for others to read.
G Extending use cases are depicted below parent use cases. This is also the common convention.
G Indicate relative timing by position. Figure 2 depicts the order placement use case cluster above the "Checkout" use case, reflecting the order in which the use cases would be invoked. Although use case diagrams aren't meant to depict the order of business
operations, this is a more natural ordering and thereby makes the diagram easier to understand.
Your use case diagram overviews your understanding of system requirements. Therefore, a poor quality diagram may get your project stakeholders thinking that your understanding of their requirements is also poor. Why cause trouble for yourself when it is so easy to
draw good use case diagrams?
Effective Sequence Diagramming
Figure 3. A poor rendition of placing an order, drawn with the Sequence Modeler in
Oracle JDeveloper 10.1.3 (preview). (See end of article for larger image.)
UML sequence diagrams model the flow of logic within your system in a visual manner, enabling you to identify critical behavior within your objects. Figure 3 presents a UML sequence diagram showing the detailed logic of placing an order online. A significant
challenge with sequence diagrams is that they grow very
"A poor quality diagram may get your project
stakeholders thinking that your understanding
of their requirements is also poor"
large, particularly in a horizontal direction, very quickly. Sequence diagrams become unwieldy when you need to scroll the screen, motivating me to prematurely stop modeling. The solution is to
reorganize the diagram into smaller ones.
Figures 4 and 5 depict improved versions of Figure 3. Figure 4 depicts the user interaction aspects, showing the actor interacting with the various HTML pages of the system. This style of
sequence diagram enables you to explore how people actually interact with the system without getting bogged down in the technical details. Since I've focused on just this aspect of the use
case it is much easier to go into greater detail. It's important to note that I've broken a Oracle JDeveloper tool rule in Figure 4: I've indicated stereotypes such as <<JSP>> and <<servlet>>, where I should have been putting object names.
Figure 5 depicts a more traditional approach to sequence diagramming, focusing on the internal code logic of adding an item to an order. I've applied two interesting tricks to improve its usefulness.
Figure 4. Placing an order User interaction. (See end of article for larger image.)
First, the object lifelines are layered in a similar manner as you would layer the architecture of your system. I show Servlet(s), then Session Bean(s), then Entity Bean(s). When you take a layered approach you'll find that the message flows very nicely from left to right.
Second, messages are left-justified. The logic implemented by the session bean looks a lot like actual Java code, making it easy to read by Java programmers.
Notice how I used a UML note to describe each of the improved sequence diagrams. UML notes make it clear to someone unfamiliar with it what a diagram actually depicts. You can apply notes on any UML diagram.
Figure 5. Placing an order Internal logic flow. (See end of article for larger image.)
Effective Class Diagramming
UML class diagrams are typically used for several purposes, including domain/conceptual modeling, analysis modeling, and detailed design modeling of your object schema.
JDeveloper includes the ability to create UML class diagrams; I
"Do not spend too much time making your
diagrams look pretty"
would use this tool feature for domain/conceptual modeling and analysis modeling. It also includes the
ability to create EJB diagrams, which apply the standard EJB profile to UML class diagrams, which I
would use for creating design-level diagrams. Figure 6 depicts a poorly rendered EJB diagram and Figure 7 an improved version.
To improve the diagram I started by rearranging the classes following a few simple rules: First, I layered the diagram by putting session beans on the left and entity beans on the right. Second, whenever possible I like to draw relationships
horizontally on the diagram. On a non-EJB class diagram I prefer to show inheritance hierarchies vertically, with the super class above its subclasses. Third, for composition relationships, in this case between Order and OrderItem, I prefer to draw the part (OrderItem) to the right of the whole (Order).
I also overrode the relationship names so that they actually communicated something of value. "OrderItem Item" says nothing; "described by" describes the actual relationship.
Finally, I made a few important cosmetic changes to the diagram. I turned off showing the package name, the UML stereotypes, and the tagged values. I can get package name from the list box, the color of the class indicates its stereotype, and I can access all relevant information (including tagged values) by double-clicking on a class. Agile Modeling
Figure 6. A poor rendition of the EJB object schema, drawn using JDeveloper's EJB
Profile Modeler. (See end of article for larger image.)
advises you to depict models simply, which is
Figure 7. A readable rendition the EJB object schema. (See end of article for larger
image.)
exactly what I did. I also chose to show only the remote methods on Session Beans and only the properties on Entity Beans, the two most important pieces of information
respectively regarding each type of class.
Conclusion
I'd like to conclude with several simple guidelines that should help you immensely:
G Name diagrams descriptively. "Online Order System" is a much more intuitive name than "UML Use Case Diagram 1."
G Use business terminology. A good class name is "Customer," not "Cust," regardless of name of data table which the class eventually maps to.
G Follow Java naming conventions for EJBs. You're programming in Java, therefore you should follow Java conventions. You might find my Java coding guidelines posted at www.ambysoft.com/javaCodingStandards.html to be of value.
G Create small models. Models don't need to be big, nor all encompassing, to be useful. Models which are small and to the point are easy to comprehend and to work with.
The best word of advice that I can give you is to not spend too much time making your diagrams look pretty. Your true goal is to develop working software, not to create pretty pictures. By knowing and understanding common modeling guidelines, you will be able to create fairly good diagrams right from the very start, certainly much better than the before
pictures presented in this article, with no extra effort.
This article has just revealed the tip of the modeling style iceberg. For more guidelines, visit http://www.agilemodeling.com/style/.
Next Steps
1) Read about UML Modeling and MDA in Oracle JDeveloper 10g: Statement of Direction
2) Watch Viewlets: [UML Class Modeler] [UML Use Case Modeler] [UML Activity Modeler] [Java Class Modeling] [Database Schema Modeler]
3) Download Oracle JDeveloper 10g
4) Learn how to use Oracle JDeveloper to create a diagram that captures the essential information requirements of a system. Modeling Java Classes
Additional Information:
Develop UML Diagrams from XMI in Oracle JDeveloper: This article describes the method for manually creating an XMI file from an XSLT, importing it into a UML tool (Oracle JDeveloper 10g), and then constructing a UML class diagram from the XMI file.
Learn how modeling tools allow you to visually create tables on a diagram: Designing, Modeling and Generating Database Tables
Learn how to create activity diagrams and diagram elements, and how to generate e-business integration code for messaging: Modeling Activities for E-Business Integration
The ADF Business Components J2EE Design Pattern Catalog: This paper lists the J2EE Design Patterns that the ADF business components implement for you.
Advanced support of UML profiling that covers the UML-based MDA approach
Scott W. Ambler is a Senior Consultant with Ronin International, Inc., a columnist with Software Development magazine, and the author of several books including The Elements of UML 2.0 Style, Agile Database Techniques, and The Object Primer 3rd Edition: Agile Model Driven Development with UML 2.
Copyright 2005, Oracle. All Rights Reserved.

Figure 1.

Figure 2.

Figure 3.

Figure 4.

Figure 5.

Figure 6.

Figure 7.