One way to define the functional requirements of an application is simply to list everything that the application should be able to do. Although that approach is not necessarily wrong, it is naïve in that it fails to take into account the real-world use of the application. Applications don’t exist in isolation; they interface with all sorts of users. Therefore, it’s much more realistic and useful to approach the functional requirements from the standpoint of how the application is used. This approach naturally leads to a kind of functional requirement called use cases.

Use cases present the application requirements by showing various ways in which users might interact with the application. The following is an example of a simple use case:

Use cases can be formatted in many ways. Generally, use case experts talk about three basic formats.

Brief: One paragraph outlining the main success scenario. The preceding example was in the brief format.

Casual: Multiple paragraphs outlining not only the main success scenario, but also alternative scenarios. The following is an example of a casual format use case:

Formal: The most elaborate of the formats for a use case document. This format lists all the steps for the use case as well as supporting data such as actors and conditions. The formal use case is discussed in more detail in the next section.

Typically you’ll want to create formal use cases for a functional requirements document. In this section we’ll look at how to create a formal use case. A formal use case can include the following sections:

The following is an example of a formal use case. Note that this example does not have any open issues.

Now that we’ve had a chance to see the structure of a formal use case, we’ll next look at how to start writing these use cases for an application.

Now that you’ve seen how to write a use case, it follows that you’ll want to know how to start forming these use cases. For example, what level of granularity is appropriate? Should you have ten uses cases or a hundred? The answer to these questions is subjective. There is no one correct set of use cases for an application. However, you will likely find the following guidelines to be helpful:

UML (Unified Modeling Language) is a language in common use for modeling applications. Although UML is perhaps most frequently used during the design phase (as we’ll see in the next section) it is not uncommon to use UML during analysis as well. One of the three parts of a system model in UML is what’s called the functional model. The functional model allows you to create use case diagrams, which can be very helpful. UML use case diagrams generally are not detailed enough to be used apart from written use cases. However, they are often a nice addition to written use cases as they provide a visual representation of the uses cases, actors, and systems. Figure 1.1 illustrates actors and uses cases for a common system, a store.

Figure 1.1. An example of use cases in UML.

CRC cards are a low-tech, yet very effective, way to determine exactly what classes you need to write, what those classes need to be able to do, and how those classes relate.

Typically, you’ll find that 3x5 or 4x6 lined index cards work best as CRC cards. At the top of the index card, write the name of the class. On the left side of the index card, list the responsibilities for the class. On the right side of the card, list the classes with which the class needs to collaborate to accomplish those responsibilities. Figure 1.2 illustrates the format for a CRC card.

Figure 1.2. The typical format for a CRC card.

CRC cards are useful because you can draw them up quickly and make changes just as quickly. Using CRC cards, you can rapidly map out the functionality of an application; when you decide to split a single class into two classes, combine two classes, or change a class name, you can do that with your CRC cards in a few seconds. You can also sit around a table with a team and work together on the cards.

Now that you know the format of CRC cards, you’ll undoubtedly have a few questions regarding how to decide what constitutes a class, what responsibilities are, how to know what classes are collaborators, and so forth. The next few sections address each of these questions.

Deciding what constitutes a class is as much an art as it is a science. Just as every painter has different ideas about composition, use of color, and so on, so too does every application designer have different ideas about how to build an application. However, you’ll likely find certain guidelines helpful when you try to determine what classes your application needs.

It’s often a good idea to look at your use cases to find classes. Classes are nouns. You can scan use cases for all the significant nouns and use those as classes in your application. For example, consider the Generate Map use case we described earlier in this chapter. From that use case we can easily identify these relevant nouns which are natural candidates for classes: “address form,” “address data,” “mapping service,” “map data,” and “map.”

When you have selected all the candidates for classes, write them down on your CRC index cards. The next step is to determine the responsibilities for each class.

After you’ve decided on the initial candidates for classes, you can assign responsibilities to those classes. Assigning responsibilities is an important step because it helps you determine the viability of the class candidate. If a class candidate doesn’t have any responsibilities, it must be unnecessary, and you can discard it. If the candidate seems to have too many responsibilities, it probably needs to be divided into two or more classes. There are some schools of thought that state that a class should have no more than one responsibility. While we respect that standpoint, we find it to be severe. A general rule of thumb that we use is that a class should have between one and three responsibilities.

It’s important to understand what a responsibility is (and what it is not). A responsibility is essentially what a class (or an instance of the class) should be able to do or facilitate. Although there is a relationship between a class’s methods and its responsibilities, they are not identical. You should not think of a class’s responsibilities in terms of methods or method names. A class may require many methods to accomplish just one responsibility. At this point in the design, it’s too early to map out the actual methods. Responsibilities are higher-level abstractions than methods.

A responsibility is usually something that can be written out in plain language in a few words. The following are examples of possible class responsibilities:

As you work on determining the responsibilities for the classes in your application, you will most likely drop classes, add classes, and change existing classes. These revisions are a desirable part of the process, which result in a well-considered design.

Although you can go through each class candidate and try to think of the responsibilities each class might have, that approach can be problematic. It encourages you to add responsibilities based on what you think the class candidate ought to do rather than based on what the application requires. A better approach is to scan the use cases for verbs—both explicit and implicit verbs. Explicit verbs are obvious because they are written in the use case steps. Implicit verbs are the verbs that are not written in the steps but are necessary for the successful completion of a step.

Many, if not most, classes cannot fulfill all their responsibilities on their own. They must rely on other classes to assist them. The assisting classes are called collaborators. Collaborators generally lend a hand either by providing data or by enabling the class to offload functionality.

After you have defined classes and class responsibilities, the next step in the design phase is to determine what each class’s collaborators are. This is extremely helpful in finding additional classes that you hadn’t previously thought of. For example, consider a Map class whose responsibilities include drawing a vector map based on a data model. It might be immediately obvious that in such a case a MapData class would be a collaborator since Map would want to query MapData for the data needed to draw the map. Locating collaborators is useful for us in terms of determining relationships between existing classes. In this case, because we likely already have a CRC card for the MapData class – derived from the “map data” noun we spotted in the use cases – this collaborator did not help us find a new class. However, when we think about the Map class still more, we’ll probably realize that drawing all the different types of elements on a map would probably be far too much for the Map class itself to handle. Instead we can rely on collaborators that draw the specific map elements, and we realize that these collaborators become new classes we missed before: Street, Highway, River, and CityMarker.

Classes have relationships with one another. When finding collaborating classes, you are finding the classes that have relationships. However, it’s possible and necessary to determine what type of relationship these collaborating classes have. Although every relationship between classes will be unique, it is possible to generalize those relationships into the following categories:

Association and aggregation are types of relationships that can more generally be called composition. Later in this chapter (in the section titled, “Inheritance and Composition”), we’ll compare and contrast the generalized principals of composition and inheritance as they apply to implementation.

By this point, you’ve decided on the classes your application requires as well as the responsibilities of each class, the class collaborators, and the relationships each class has with those collaborators. Although you might be anxious to start coding right now, there are still some steps to complete in the design phase.

The next step is to formalize the public APIs (Application Programming Interface, which means the public methods) of the classes.

Formalizing the API for a class is a matter of translating the responsibilities into method signatures. Not all responsibilities necessarily translate into public methods because some of what a class is responsible for might be private. For example, the AddressForm class might have a responsibility to validate user input. That is probably not something that translates into a public method. Rather, it is far more likely that this responsibility is handled internally by the class when the user clicks a button. However, some class responsibilities might translate into several public methods. For example, in the case of our map example, the responsibility “handle request and responses to and from server-side service” might translate into the following methods (depending on the application requirements):

function getMapDataForAddress(address:AddressData):void;
function getSavedMapData(id:uint):void;

We first mentioned UML in relation to analysis. However, one of the most common uses of UML is during the design phase because you can use UML class diagrams to visually represent all the classes, their APIs, and the relationships between the classes. UML class diagrams are really useful because they allow you to look at all the classes and there relationships all at one time in a relatively succinct format. Usually a UML class diagram doesn’t replace the need for technical documentation. However, UML class diagrams can often supplement technical documentation and serve as a useful tool both during the design phase as well as during the implementation phase when you must actually write all the classes shown in a UML class diagram. Figure 1.3 shows a very simple UML class diagram that shows two classes and an interface.

Figure 1.3. A simple UML class diagram.

Note that this figure shows only public class members, yet you can also represent private and protected members.

Not only does UML provide a nice way to visualize the classes used by an application, but it also provides the possibility to export stub code for all the necessary classes and interfaces. At the time of this writing there is no known ActionScript 3.0 stub code generator for UML. However, since this is a common feature for many other languages (Java, C#, etc.) it is reasonable to think that there will be an ActionScript 3.0 generator for UML in the near future.

There are few rules for naming classes, packages, variables, functions, and interfaces in ActionScript. In each case, you can use only letters, numbers, dollar signs ($), and underscores (_) and the first character must not be a number. Although the rules are few, there are still conventions for naming that you might find useful. At the very least, you will find it useful to know what conventions we use in this book. You should know that the conventions we use aren’t the only conventions, and you aren’t obligated to use them. We introduce this topic here because consistent and conscious coding conventions are a boon to application development. By applying conventions consistently you can expect to write code that is easily read by you and anyone else during team development. Remember that classes can involve hundreds of lines of code, and using consistent conventions helps you to more quickly identify parts of the code and their purposes.

var city:Map;

var cityMap:Map;

private var _cityMap:Map;

public function getMapDataForAddress(address:AddressData):void;

com.examplecompany.jediknight.services

One of the rules of good object-oriented design is that all classes should be black boxes: you can put things in and take things out, but you can’t determine how it operates. In other words, the only way to interact with a class instance is to use its public methods. You should never be able to look into an object or change the object’s state except by asking the object to tell you about itself or to change its own state. The object must always maintain sovereignty. The minute an object is no longer in charge of its own internal world, the entire object-oriented universe starts to crumble and fall apart into an unmanageable train wreck.

This idea of classes being black boxes is a fundamental principle of object-oriented design called encapsulation. Encapsulation is absolutely necessary for an object-oriented design to succeed because it enables objects to interact with one another in known and well-defined ways. This approach models the world in which we live in many ways. Every object in the physical world has boundaries that define it and its interface with the world around it. Your body interacts with the air by way of respiration, for example. Without these well-defined interfaces there would be chaos, and it would be impossible to interact with anything in a useful or meaningful way.

Implementing classes so that they adhere to the principle of encapsulation is quite simple. To achieve this goal, there are just two basic rules:

student.gpa = 400;

public function getGPA():Number {
   return _gpa;
}
public function setGPA(value:Number):void {
   if(value > 4) {
      _gpa = 4;
   }
   else if(value < 0) {
      _gpa = 0;
   }
   else {
      _gpa = value;
   }
   dispatchEvent(new Event(Event.CHANGE));
}

student.setGPA(4);

textfield.text = "GPA: " + student.getGPA();

public function get gpa():Number {
   return _gpa;
}
public function set gpa(value:Number):void {
   if(value > 4) {
      _gpa = 4;
   }
   else if(value < 0) {
      _gpa = 0;
   }
   else {
      _gpa = value;
   }
   dispatchEvent(new Event(Event.CHANGE));
}

student.gpa = 4;

textfield.text = "GPA: " + student.gpa;

public class Student {

   public function _classes:Array;
                                                                                    
   public function Student() {
      _classes = new Array();
   }

   public function attendClass(class:AcademicClass):void {
      _classes.push(class);
      // Now that the class was passed in as a parameter the 
      // Student instance can store that reference in the array 
      // and use it later. This doesn't break encapsulation 
      // because the reference was passed in via the public API.
   }

   // Remainder of implmentation.

}

public function get students():Array {
   return _students;
}

school.students.splice(10, 5);

public function get students():Array {
    return _students.concat();
}

One class can leverage the functionality of another class in one of two basic ways: inheritance or composition. Both are powerful techniques. Inheritance allows you to define a new class so that it automatically gets the interface and implementation of an existing class. The following code declares a class called Employee:

public class Employee {
   public function Employee() {}
   public function work():void {
      trace("working");
   }
}

The new class, which we call the subclass, can build on the foundation of the existing class, which we call the superclass or base class, without needing to rewrite the original code or write any new code to use the superclass code. There are different types of employees, and we can define different subtypes by inheriting from the Employee superclass. For example, the following Executive class inherits from Employee by using the extends keyword:

public class Executive extends Employee {
   public function Executive() {}
   public function attendMeeting():void {
      trace("attending meeting");
   }
}

Furthermore, inheritance automatically enables polymorphism because the subclass inherits the interface of the superclass. That means that an Executive object is also an Employee…just a more specific type. An Executive object can be used any time an Employee object is expected although the reverse is not true:—an Employee object cannot stand in for an Executive object. Note that the Executive class defines another method called attendMeeting(). Because Executive objects inherit from the Employee superclass, you can call the work() method for an Executive and you can also call the attendMeeting() method which is specific to Executive.

In contrast with inheritance, composition allows you to write a new class (a front-end class) that has an instance of an existing class (the back-end class). Every time you define a class with a property whose type is another class, you are using composition in some sense. The following example is a rewrite of the Executive class example just shown so that it uses composition rather than inheritance:

public class Executive {
   private var _employee:Employee;
   public function Executive() {}
   public function attendMeeting():void {
      trace("attend meeting");
   }
   public function work():void {
      _employee.work();
   }
}

When you use composition, the new (front-end) class does not automatically inherit the interface of the existing (back-end) class. The front-end class can use the back-end class instance only by way of its public interface. If the front-end class needs to have part or all of the same interface as the back-end class, you must write code that defines the interface as well as its implementation. That is the reason that this rewrite of the Executive class has to define a work() method. Unlike the example that used inheritance, the composition version of the Executive class does not inherit the work() method. If you want the work() method to be part of the Executive interface, you must define it. The preceding example uses a technique called delegation to pass along the method call to the composed object.

Because a class that composes an instance of another class does not automatically inherit the object’s interface, composition does not automatically enable polymorphism. In other words, using composition, an Executive object is not an Employee, and it cannot stand in for an Employee. (The solution to this issue is to use interface constructs as discussed earlier in this chapter.)

In reading the preceding paragraphs, you might think that inheritance sounds like a much better technique for reusing existing functionality. It sounds like composition requires much more work with little or no advantage. Yet both inheritance and composition have their advantages and disadvantages.

Coupling refers to the degree to which two objects must know about one another. When the objects have to know a great deal about one another to work, we call that tight coupling; when they have to know little to nothing about one another, we call that loose coupling. In object-oriented design, we generally strive to have loose coupling among the objects in the system. Loose coupling creates flexible and adaptable systems. If objects are tightly coupled, the system is rigid—one change in one object can cascade and break the entire system. If objects are loosely coupled, changes are much less likely to break things, and even when changes do cause malfunctions, the malfunctions are generally contained.

Many design patterns aim to create loosely coupled systems. For example, if an object needs to ask another object to run a behavior, the traditional way to accomplish this goal is for the object to have a reference to the collaborator and to call a method of that collaborator. That way of structuring an application uses tight coupling because the calling object has to have a reference to the collaborator and it has to know the signature of the method it wants to call. It’s difficult to make changes to that structure. The Command pattern described in Chapter 10 addresses this issue by completely decoupling the objects. The Command pattern adds an intermediary layer that parameterizes the behavior and allows the calling object to simply have a reference to the intermediary object and know about a standard interface. This is just one example of how design patterns can promote loose coupling or decoupling, and you’ll see many more examples throughout the book as you read about each of the patterns.

In FlexUnit basic unit tests require the following elements:

The first category of elements isn’t specific to unit tests. That category is simply comprised of the classes you’ve already written. They are part of unit testing because you are testing that they actually work the way you expect. For the basic test cases we’ll test the following class.

package example {
  public class SimpleConverter {
    public function SimpleConverter() {}
    public function convertToRadians(degrees:Number):Number {
      return (degrees / 180) * Math.PI;
    }
    public function convertToDegrees(radians:Number):Number {
      return (radians / Math.PI) * 180;
    }
   }
}

Test cases and test runners, on the other hand, are unique to unit testing. Since test cases and test runners are likely new to you we’ll look at how to create them in the next sections.

package tests {
  import flexunit.framework.TestCase;
  public class SimpleTest extends TestCase {
    public function SimpleTest(method:String) {
      super(method);
    }
  }
}

package tests {
  import flexunit.framework.TestCase;
  import example.Simple;
  public class SimpleTest extends TestCase {
    public function SimpleTest(method:String) {
      super(method);
    }
    public function testConvert0ToDegrees():void {
      var simple:SimpleConverter = new SimpleConverter();
      var degrees:Number = simple.convertToDegrees(0);
      assertEquals(degrees, 0);
    }
    public function testConvertPIToDegrees():void {
      var simple:SimpleConverter = new SimpleConverter();
      var degrees:Number = simple.convertToDegrees(0);
      assertEquals(degrees, 180);
    }
    public function testConvert0ToRadians():void {
      var simple:SimpleConverter = new SimpleConverter();
      var radians:Number = simple.convertToRadians(0);
      assertEquals(radians, 0);
    }
    public function testConvert180ToRadians():void {
      var simple:SimpleConverter = new SimpleConverter();
      var radians:Number = simple.convertToRadians(180);
      assertEquals(radians, Math.PI);
    }
  }
}

<?xml version="1.0" encoding="utf-8"?>
<!-- Notice that the Application tag adds the flexui namespace prefix and maps it
to flexunit.flexui.*. Also notice that it registers initializeHandler() as an event
handler for the initialize event.-->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:flexui="flexunit.flexui.*"
 initialize="initializeHandler(event)">
    
   <mx:Script>
      <![CDATA[
         import flexunit.framework.TestSuite;
         import tests.SimpleTest;

         private function initializeHandler(event:Event):void {
            // Create a new TestSuite object.
            var suite:TestSuite = new TestSuite();

            // Use the addTest() method to add each of 
            // the four test cases to the suite.
            suite.addTest(new SimpleTest("testConvert0ToDegrees"));
            suite.addTest(new SimpleTest("testConvertPIToDegrees"));
            suite.addTest(new SimpleTest("testConvert0ToRadians"));
            suite.addTest(new SimpleTest("testConvert180ToRadians"));
               
            testRunner.test = suite;
            testRunner.startTest();
         }
       ]]>
    </mx:Script>
    <flexui:TestRunnerBase id="testRunner" width="100%" height="100%" />
</mx:Application>

package example {
  public class SimpleConverter {
    public function SimpleConverter() {}
    public function convertToRadians(degrees:Number):Number {
      return (degrees / 180) * Math.PI;
      }
      public function convertToDegrees(radians:Number):Number {
        return 0;
      }
   }
}

public static function suite():TestSuite {
   var suite:TestSuite = new TestSuite();
   suite.addTest(new SimpleTest("testConvert0ToDegrees"));
   suite.addTest(new SimpleTest("testConvertPIToDegrees"));
   suite.addTest(new SimpleTest("testConvert0ToRadians"));
   suite.addTest(new SimpleTest("testConvert180ToRadians"));
   return suite;
}

private function initializeHandler(event:Event):void {
   testRunner.test = SimpleTest.suite();
   testRunner.startTest();
}

Many unit tests are synchronous—meaning that you can immediately determine if a test has passed or failed. For example, the SimpleConverter test in the preceding section passed or failed a test immediately. However, it’s possible that some tests may depend on asynchronous operations. For example, a class may need to make a request and wait for a response from a service method before a test can be verified properly. In such cases it’s important to be able to run tests asynchronously. For an example consider the following class which loads data from a text file when calling the getData() method.

package example {
   import flash.events.EventDispatcher;
   import flash.net.URLLoader;
   import flash.events.Event;
   import flash.net.URLRequest;

   public class AsynchronousExample extends EventDispatcher {

      private var _loader:URLLoader;

      public function get data():String {
         return _loader.data;
      }

      public function AsynchronousExample() {
         _loader = new URLLoader();
         _loader.addEventListener(Event.COMPLETE, onData);
      }

      public function getData():void {
         _loader.load(new URLRequest("data.txt"));
      }

      private function onData(event:Event):void {
         dispatchEvent(new Event(Event.COMPLETE));
      }

   }
}

With a few simple changes it’s possible to run FlexUnit tests asynchronously so you can test operations like getData(). Asynchronous operations should use events to notify listeners when the operation has completed. Typically when you register a listener for a particular event you use the addEventListener() method, and you pass it a reference to the listener method. When writing test cases for asynchronous operations you should register a listener method to handle the event that signals a completed operation. However, rather than registering the listener directly, you should use an inherited TestCase method called addAsync(). The addAsync() method allows you to specify a listener method along with a time out in milliseconds. This allows you to specify what method should handle the event, but if the event doesn’t occur within the timeout window then the test will fail. The event listener method should run the assertion. The following example uses these techniques. You’ll see that the class extends TestCase just like a basic unit test. Furthermore, this test case class also accepts a method name as a parameter for the constructor, and it passes the parameter to the super constructor. What differs is that the test method registers a listener using addAsync() and defers the assertion to onData(). This example times out after 2000 milliseconds. That means that if the data loads in 2000 milliseconds or less then the assertion will run. However, if the data doesn’t load in time then the test case assumes that it was due to a failure and the test fails.

package tests {
   import flexunit.framework.TestCase;
   import example.AsynchronousExample;
   import flash.events.Event;
   import flexunit.framework.TestSuite;

   public class AsynchronousTest extends TestCase {

      public function AsynchronousTest(method:String):void {
         super(method);
      }

      public function testGetData():void {
         var asynchronous:AsynchronousExample = new AsynchronousExample();
         asynchronous.addEventListener(Event.COMPLETE, addAsync(onData, 2000));
         asynchronous.getData();
      }
       
      private function onData(event:Event):void {
         assertNotNull(event.target.data);
      }

      public static function suite():TestSuite {
         var suite:TestSuite = new TestSuite();
         suite.addTest(new AsynchronousTest("testGetData"));
         return suite;
      }

   }
}

The following test runner will run both the simple tests and the asynchronous test.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:flexui="flexunit.flexui.*"
 initialize="initializeHandler(event)">

   <mx:Script>
      <![CDATA[
         import flexunit.framework.TestSuite;
         import tests.SimpleTest;
         import tests.AsynchronousTest;

         private function initializeHandler(event:Event):void {
            var suite:TestSuite = new TestSuite();
            suite.addTest(SimpleTest.suite());
            suite.addTest(AsynchronousTest.suite());
            testRunner.test = suite;
            testRunner.startTest();
         }
       ]]>
    </mx:Script>
    <flexui:TestRunnerBase id="testRunner" width="100%" height="100%"/>
</mx:Application>