Chapter 5. Web Site Manager - Analysis

 

When you maintain a web site, it’s helpful to have tools. In this chapter and the next, we’ll develop an application that can serve as a framework for a number of tools to track and manipulate pages in a web site.

 

What tools might we have?

·        Viewers - to show pages

·        Editors - to change pages

·        Evaluators - to score pages on some attribute

·        Critics - to suggest improvements

 

For example, we might have a viewer for a page that shows its file characteristics: read/write attributes, name, path, size, etc. Another tool might be an HTML editor. Another tool might show characteristics of the page as a graph node: number of links in or out, local density. Some tools might work with both the file nature and web nature of a page: perhaps to estimate the download time for a page and all pages it includes.

 

The application will use the graph framework we already developed, and it will be a framework for site manager applications. The framework will give tools access to the pages of a site. In the long run, the framework would probably grow to do more. For example, looking at the HTML form of pages might be so common that it would make sense to build in an HTML parser.

 

Approach

In this chapter, we’ll develop:

·        use cases (scenarios)

·        high-level object model

·        screen designs

 

In the next chapter, we’ll implement this:

·        software design

·        simple implementation (using the Graph framework)

 

The resulting framework will demonstrate several key ideas, and we’ll come back to it in later chapters to explore other framework issues.

Sidebar: Use Cases Use cases are a tool designed to help in the requirements/analysis stage of development. They are scenario-based: they describe typical and exceptional flow through the system, partitioned in a way that shows how the user benefits from using the system.   Actors are the active entities, that correspond to the roles that participate in a use case. For example, a User might be an actor; so might an external system. Actors can be arranged in a hierarchy, e.g.,                         User                            Order Processor                            Administrator An actor is usually shown with a stick-figure icon (TBD).   A use case represents a set of scenarios. It is usually described via a template like this:                Use case name                Pre-conditions                Post-conditions                Normal flow                Alternate flows                Exceptions   The icon for a use case is an oval, containing the use case name. (TBD).   Two relationships are used to link use cases: uses and extends. The uses relationship is sort of like a subroutine call; it lets you build a complex use case from simpler ones. The extends relationship holds when one use case is like another but with extra steps added in. This lets you deal with a simple case first, then extend it to handle more complexity. Neither of these relations corresponds to class inheritance. (Use cases can use an inheritance relationship; an abstract use case can be inherited by concrete use cases with compatible pre- and post-conditions.)   As the actors and use cases are identified, it’s useful to have a use-case diagram showing which actors use (and are used by) which use cases:     While the use cases are being developed, you’ll also want to consider an analysis object model, and sample screen designs.

 

Use Cases

Vision: Develop a system to help an author view and edit web pages

that form a site the reader can browse.

 

We can see three use cases implied by the preceding paragraph: View Page, Edit Page, and Browse Site. We have two actors: Author and Reader.

 

 

 

 

 

 

 

We’ve made a simple start. Are we embarked on a bloodless process of turning a crank to produce the system? Not at all, it’s more an active process of moving between the various possibilities. We may have an initial screen design in mind. Similarly, we haven’t carried out any real object design, but we expect things like Page, File, and Tool to be part of the model. These preconceptions are not absolute guides - but if we reach the end of analysis without talking about some sort of Page object, we need to think more deeply.

 

These initial three use cases suggest several issues.

 

The biggest issue is the relationship between Edit Page and Browse Site. We need to make it explicit that changing a page changes what the Reader sees. Do we really want immediate changes though? What about a change that affects two or more pages simultaneously? (For example, we might be moving information from one page to another, or changing the appearance of the site.) In such cases, we don’t want the user to see the partial changes. This suggests the need for a new use case “Publish Site” that updates a site with a whole set of changes.

 

A second issue is the distinction between View Page and Edit Page. We don’t really need this - we can require the tool to know whether it has made any changes. So, we’ll fold these two use cases together.

 

A third issue is the relationship between a page and its representation (e.g., as a file). This is barely on the horizon, but we’ll need to consider the problem eventually.

 

A final issue (ha!) is the relationship between actors. How many Authors and how many Readers will there be (especially at the same time)? For now, we’ll allow a single Author, and multiple simultaneous Readers.

 

Revised Use Cases

UC View Page is deleted; its functionality is folded into Edit Page.

 

UC Edit Page should make it clear that a tool may be read-only. Also, add step 5, “The page is added to the list of pages changed since the last ‘Publish Site’ operation.”

 

 

[KEY] We have captured the idea that editing happens to a separate set of pages from the main site, and that it takes an explicit action to synchronize the two sets of pages. This is an important insight.

 

More Use Cases

We’ve described ongoing maintenance of a site, but we’ve ignored the need to create a site in the first place. To do this, we’ll add use cases for Create Site, Create Page, and Import Pages.

 

 

 

 

 

 

 

 

 

 

 

 

Remaining Use Cases

Our set of use cases is filling out. There are some techniques to help see if they're complete:

1.     Try scenarios (real or pretend). For this project, we could watch a real site owner at work, and see if everything's covered.

2.     Consider things from a "lifetime" perspective: when things are created, used, and destroyed.

3.     Consider pairs of actions, e.g., create/delete.

 

By observation, we discover that real owners sometimes move pages, and Move Page is a plausible use case. We can also see that we can Create and Edit a Page, so we add Delete Page as well. Finally, we consider Delete Site, to match up with Create Site.

 

 

 

 

 

 

 

 

With these additional uses cases, we have a fairly complete set. The biggest "design decision" is the idea of keeping the working area separate from the site itself. Other than that, they are fairly free of requirements on the user interface. We could develop a Perl script that would provide a decent first cut.

 

[TBD - paragraph before is weak.]

 

Let’s briefly look at the lifetime of a site:

[ CreateSite (( CreatePage | ImportPage | EditPage | MovePage | DeletePage)* PublishSite)* DeleteSite] || BrowseSite

This expression tells us that a site is created, things happen to it, and the site is deleted. Any changes can be followed by PublishSite. The site is browsed in parallel.

 

We should rewrite the use cases to clean up the vocabulary, simplify the sentence structures, and see if we've missed anything.

 

Next, we'll start developing an "analysis model" consisting of objects implied by the use cases. Then we’ll consider the user interface.

 

 

 

Analysis Model

We’ve developed a set of use cases; now we’ll build a conceptual object model that can support them. This model is at the analysis level: the objects described will be those in the use cases. (During design, we’ll take the analysis model as a starting point, but we’re not committed to mimicking it exactly.)

 

To build this model, we’ll bounce around between the use cases, the object model diagram, and scenario diagrams, looking for objects and their relationships.

 

UC Create Site

We have the web site itself: Site. We have the web pages: Page. We also have the location of the pages in the system; we’ll call that a WorkSite. The Site has some sort of upload() method that can move pages into the site. Finally, there is a list of changes: Change and ChangeList.

 

To help validate the model so far, we might walk through a scenario diagram:

 

In the scenario diagrams, we won’t worry about whether the actor or some manager object coordinates the series of steps.

 

UC Delete Site

It’s often easy to work in pairs, so we’ll look at Delete Site next. We see no new objects, but we do see a new operation: some sort of “delete.” Notice the ambiguity in the use case: when we talk about the site, are we talking about what we’ve called the Site or the WorkSite?

 

We can resolve this by saying that the WorkSite must be empty (to delete it), but the Site need not be. This lets us delete pages, and then delete the Site, without first requiring us to publish the newly empty site.

 

We need an isEmpty() method on WorkSite (so we can determine that it’s empty).

 

UC Edit Page

We add the idea of a Tool, with edit() and save() operations. We also see the use of a Change object, added to the ChangeList.

 

 

The current object model:

 

 

UC Publish Site

This use case doesn’t require new objects, but does add new operations. To let the site reflect the changes, we’ll add methods publish(ChangeList) and apply(Change). To ChangeList, we’ll add elementAt(int), getElementCount(), and clear() methods.

 

 

UC Create Page

The Create Page use case introduces the idea of a page location. In web terms, we already have a name for this: URL. An earlier draft of the use cases talked about “file” as well; we cleaned it up to only refer to pages and page locations. We should go back and use “URL” for page location, since it’s a well-understood domain term.

 

The use case is a little ambiguous - when it talks about the “specified location”, it’s really talking about putting the Page into the WorkSite. (The Site will pick up the new page upon a Publish Site.) The use case should make this clear.

 

If we think of the tool as an editor, we don’t strictly need the location until we’re ready to save the new page. Perhaps we can combine Create Page with Edit Page.

 

 

UC Browse Site

We see that the site needs to serve up pages: get(URL). A Page needs to be able to report the URLs it links to: URL[] getLinks().

 

The Model So Far

This is a good point to stop and assess our model. We have a few use cases we haven’t covered yet: Import Pages, Move Page, and Delete Page. We’ll look at them later, and see what they do to the model.

 

 

Walk through the use case scenarios again to ensure that we can support all the needed behavior. (Notice that we added links from the WorkSite to the Tools and the ChangeList.)

 

Where is our model weak?

·        We need to make sure the Site object supports the transactions it needs. The publish(ChangeList) method lets it do that.

·        The idea of Change and ChangeList is reminiscent of the Command pattern. This should make us wonder - can we use this fact to provide some sort of undo capability? It’s worth taking the idea back to the use cases.

·        Page and URL have a more complicated relationship, especially when we consider “who knows what”:

·        WorkSite and URL need to be related and aligned somehow. We rely on being able to match up pages between Site and WorkSite.

·        The Tool defines methods for editing and saving Pages, but it can’t really alter the page without the cooperation of the Site.

 

 

Remaining Use Cases

Import Pages: There’s not much difference between importing a page and creating a new one; we can treat “import” as just another Tool.

 

Delete Pages: We need an operation on the site deletePage(URL).

 

Move Pages: We could treat this as a combination delete/create/delete, but instead we’ll add a single Site operation: movePage(fromURL, toURL).

 

Synchronizing Sites

What is the relationship between the ChangeList and the WorkSite? The ChangeList is mentioned explicitly in the use case, but it is really an artifact. The point of using it is to make the Site synchronize its contents with the WorkSite.

 

The idea of synchronizing sites is a broader notion than copying things from the ChangeList: it will also help us talk about mirror sites, multiple versions of a site, and other things.

 

[Key] Approach: Eliminate the ChangeList from our model (and from the use cases as well).

 

We may re-introduce the ChangeList later as a design element; that’s all right - that’s what it is.

 

So, add a synchronize(Site) operator to Site, and eliminate the distinction between Site and WorkSite.

 

In some ways, this is a radical change, but it’s one enabled by the use cases. Had we been buried in code, we might not have noticed this possible approach.

 

 

 [TBD Page level vs. site level]

What Have We Accomplished?

We have:

·        Developed an analysis object model coherent with our use cases. This model builds on concepts our users can understand and discuss.

·        Explored the interaction between Site and Tool, to balance responsibilities, and make it clear that the Site manages the pages.

·        Introduced site synchronization. Instead of the ChangeList, which had a very specific form, we’ve introduced the more powerful idea of site synchronization. This simplified both the use cases and the model.

 

This is a good opportunity to back through the use cases and the model, ensuring that they’re in synch with each other, and that the model supports the behaviors we need.

 

The Latest Analysis Model

 

This is a much trimmer model than we started with.

 

Screen Design

A screen design should also be part of our analysis. You shouldn’t focus on this too strongly in the initial stages: seeing a screen can shut out useful ideas for the use case and the model. The user interface is often a volatile part of the system, so you want to depend more on the use cases and the object model, which are more stable.

 

Here’s a possible screen:

 

 

 

With these menus: