Tightening Up the Model

This time around, the modeling effort is starting to zero in on a more refined, detailed design. The overall model is beginning to take shape, and we’re seeing some of the benefits of putting more effort into the up-front design stage.

The team has refined the domain model (see Figure 6-4).

Figure 6-4: The domain model the second time around

During the prototype and model review meeting, the team found that it needed to update the terminology used on the domain model. This was because, back when the project was just getting started, the team had anticipated using an older version of the ESRI technology. Since then, the team had opted to use the mapplet as a way to perform some tests on its new high-end mapping server, ArcGIS Server.

So the team needed to bring the model into closer synchronization with the architecture of the new map server. In the new architecture, we see, for example, conceptual entities for “Geocode Server” and “Map Server” (both of these are predefined objects residing in ArcGIS Server). There’s also a “Hotel Server,” which is in reality part of the more generic Map Server, as Hotels are just one of the data layers that we query in the Map Server.

In any project, it’s vitally important that the domain model be kept up to date throughout, as it forms a kind of object-oriented glossary of terms. It’s the Babel fish^[6.] that keeps everyone talking the same language.

The “Generate Hotel Map for AOI” Use Case

Figure 6-5 shows the “Generate Hotel Map for AOI” use case being edited in the team’s CASE tool (Enterprise Architect [EA] from Sparx Systems^[7.]).

Figure 6-5: Editing the “Generate Hotel Map for AOI” use case

Revised Use Case: “Generate Hotel Map for AOI” 

BASIC FLOW:

The Map Viewer queries the Hotel Server for Hotels within the current AOI and stores the results in a Hotel Collection. The Map Viewer gets the Map from the Map Server, displays the Map at the specified scale, and puts an icon on the Map for each Hotel in the collection that meets the criteria defined in the Display Filter.

ALTERNATE FLOW:

When the map scale is zoomed out beyond a predefined value, the system does not query the Hotel Server and generate a Hotel Collection.

Contrast this with the original version of the use case. The most noticeable improvement is that the use case has been divided into “Basic Flow” and “Alternate Flow” sections. The scope of the use case has also been trimmed down—that is, it no longer starts at the UI, but instead picks up the story from the point of interaction between the Map Viewer and the Hotel Server. The result is a more focused, more manageable chunk of functionality from which to drive its sequence diagram.

Also, as a result of the team’s model review activities (particularly the discovery of the ambiguous domain objects during robustness analysis), the text has been effectively disambiguated.

Figure 6-6 shows the robustness diagram for the “Generate Hotel Map for AOI” use case. Note that the new robustness diagram more accurately reflects the technical architecture of the ArcGIS product: Maps are “served” by the Map Server, while Hotels are “served” by the Hotel Server (although strictly speaking, the Hotel Server is part of the Map Server).

Figure 6-6: The robustness diagram for the “Generate Hotel Map for AOI” use case

In this release of the software, we are not yet attempting to do a proximity search near an address, so there is no use of the “Geocode Server” on the robustness diagram.

Figure 6-7 shows the sequence diagram for the “Generate Hotel Map for AOI” use case. Notice how the use case text has been pasted directly into the left border of the diagram. This helps to keep the sequence diagram and the use case tightly bound. If one or the other starts to stray, then it’s easily noticeable and its twin view can be updated. This practice can also make a huge difference in the accuracy of any team’s modeling efforts, because the team is designing the program directly from the system behavior defined in each use case.

Figure 6-7: The sequence diagram (revisited) for the “Generate Hotel Map for AOI” use case

If we think of the use case scenario text and the sequence diagrams as being different views of the same activity, then we can see why they’re so closely interrelated. They’re actually different representations of the same sequence of steps (in addition, the sequence diagram shows the system’s internal workings).

This sequence diagram took a while to figure out, and it involved a fairly detailed discussion of how the C# code actually worked, along with a discussion of what information was kept in cached HTML inside the web browser (price-band filtering information) for performance reasons and what queries would be done by hitting the database (amenity filtering). We came up with a design that used both a display filter for changing price bands (operating on cached HTML within the browser) and a query filter for amenity filtering, which hits the server (e.g., when we’re only looking for Hilton hotels with 24-hour room service).

Note that query filtering did not get implemented in the first release of the mapplet. Even though the sequence diagram might not precisely match the code, working through it proved to be a very valuable exercise for the insight it gave the team into how the design needed to work.

Use Case: “Display Rollover Information” 

This particular use case didn’t change during the first two modeling passes (however, we’ll improve it substantially in the next chapter). Here’s the use case text for “Display Rollover Information.”

Basic Flow:

The user positions the mouse cursor over a hotel icon in the map display. The mouse icon changes to “selection hand” and the hotel icon changes to “selected hotel.” The system displays a map tip, displaying the hotel name. The user may click the hotel icon to display a hotel information pop-up that displays the hotel’s attributes for all of the fields in the hotel pop-up fields collection. The system queries the hotel attributes to determine which hotel details are available for the hotel. Within the hotel pop-up, the system displays hyperlinks for available hotel details. The user may click these to invoke the “View Detailed Hotel Info” use case.

Alternate Flow:

If no hotels are found at click coordinates, do nothing.

If multiple hotels are found at click coordinates, the system constructs a list of the selected hotels’ names and displays them in a pop-up. The user may select a hotel from the list to display the associated hotel information pop-up.

The robustness diagram for this use case is shown in Figure 6-8. Note that the robustness diagram takes into account the alternative course of “If multiple hotels are found at click coordinates.”

Figure 6-8: The initial robustness diagram for the “Display Rollover Information” use case

There’s actually quite a lot that can be done to improve both this diagram and the ensuing sequence diagram (see Chapter 7 to give them a serious roughing up (or should that be “smoothing over”?). You’ll be surprised at the result!

The sequence diagram for this use case is shown in Figure 6-9.

Figure 6-9: The sequence diagram for the “Display Rollover Information” use case

As we described earlier, during this prototype-intensive stage of the project, the team actually breezed over robustness analysis and also skipped the detailed class diagram entirely. As we hope you’re starting to suspect, insufficient modeling results in the need for code-level refactoring. So, in the next section, we show some of the prototype source code, because it’s useful to see what can happen when crucial parts of the design modeling stage are skipped. We then do some minor refactoring to the code in preparation for the next release.

Refactoring is a useful fallback position if your team has skimped on the up-front design. In other words, if a less-than-optimal design has been coded up, it’s not the end of the world: refactoring provides a handy escape route. However, as we discuss in our book Extreme Programming Refactored: The Case Against XP, refactoring can be a serious resource drain—it is not the most efficient way to design software. It really is better to focus on getting the design right as early as possible.

In Chapter 7, we return to the robustness and sequence diagrams, and examine some improvements that could have been made prior to coding.

^[6.]A Babel fish (according to The Hitchhiker’s Guide to the Galaxy by Douglas Adams) is “small, yellow, and leech-like” but has the bonus of behaving like a universal translator if you stick one into your ear.

^[7.]See www.sparxsystems.com.