Billy McCafferty : Architecture

Greenfield Development with ASP.NET MVC & S#arp Lite - Day 3

Billy McCafferty — Tue, 16 Oct 2012 22:10:00 GMT

A series of posts providing proven guidance for developing ASP.NET MVC applications from idea to well-designed implementation.

Day 3 – Define the Domain Design Model

Objective of the Day

Transform the actor/system interaction diagrams - from Day 1 - and the domain conceptual model - from Day 2 - into a design model, which will be used as the basis for implementation. The design model will include two artifacts:

Class Diagram: A class diagram extends the domain conceptual model to include data types, methods, and supporting classes necessary for implementation.
Sequence Diagrams: Sequence diagrams express the interactions among classes and the messages invoking, and responding to, those interactions, accordingly.

Inputs

Actor/System interaction diagrams
Domain conceptual model

Activities

Designing the domain conceptual model, and evolving that into the domain design model represents the transition from business-oriented to implementation-oriented requirements. While there are two outputs from this process, class diagrams and sequence diagrams, they are defined in parallel with each other, each contributing to the design of the other.

Transforming the conceptual model into a design model is most effectively done iteratively. This does not mean that each refinement need take a two-week iteration to complete. Indeed, each iterative refinement may only take 30 minutes or so to complete. Tackling this transformation iteratively allows you to learn from each pass, applying new knowledge to the class diagram and to the sequence diagrams in successive passes.

Furthermore, you need not tackle the entire domain model when defining the design model; only focus on the scope and level of detail that is immediately useful.

The steps involved with each elaboration iteration, for defining/refining the class diagram and sequence diagrams, are as follows:

Identify the bounded context which will be the focus of design model elaboration. (The bounded context need not be strictly adhered to, but should be identified to assist in focusing the elaboration effort.)
Select one or more high priority User Stories (or Use Cases) which are representative of the bounded context and, preferably, are of higher risk.
Refine (or initially define) the class diagram, focusing on classes, attributes, and associations within the context of the User Stories.
For each User Story, refine (or initially define) sequence diagrams illustrating the behavior and interactions of each class involved.
Update the class diagram to reflect any new or modified classes, behaviors, and/or attributes discovered during the design of sequence diagrams.

When defining sequence diagrams, do not feel constrained to only include classes which are already defined within the class diagram. The exercise of building out the sequence diagrams will quickly lead to the discovery of new classes and behaviors which are not yet a part of the class diagram; that’s one of the points of doing this. Furthermore, do not feel obliged to create a sequence diagram for every User Story or requirement. Sequence diagrams are time consuming to create and are quickly subject to change. Accordingly, I see sequence diagrams as disposable artifacts which need not be maintained after they have been implemented as code.

Sequence diagrams are particularly useful at the following times:

To illustrate the interactions involved with a complex User Story,
To illustrate a "boiler-plate activity," such as the interactions involved with the CRUD (create/read/update/delete) of a single domain object, in order to establish a standard practice and to serve as a useful reference for new team members, and
To tell a more junior developer exactly how you’d like something implemented.

In the final step, when updating the class diagram to reflect new or modified behaviors, use each message, passed between two classes within the sequence diagram, to indicate the need for a respective method on the class from which the message originates. In other words, if a communication is indicated between two classes in the sequence diagram, there should be a respective method (or return result from a message) in the class diagram.

Deciding to what granularity to create the sequence diagrams is a tricky decision. If too little time is spent, then the sequence diagram will provide very little guidance towards implementation. But too much time may result in granularity which is otherwise obvious or clearly assumed. As a rule, continue to break-down the sequence diagram to further levels of granularity until:

The effort is no longer reducing uncertainty and risk,
The increased granularity is no longer providing "new" information, or
The increased granularity is no longer useful to the task at hand (such as providing an initial estimate).

From the perspective of including this practice within an overall project methodology, defining/refining the design model should be roughly performed at the beginning of a project to assist with estimating and to improve understanding of the project. It should also be performed in more detail at the beginning of each development iteration to define/refine the design model for that iteration.

GRASP Patterns

The definitive challenge at this point is figuring out exactly how to transform the conceptual domain model into an appropriate design model describing classes with attributes, associations, and behavior. While sequence diagrams are a tool to visualize interactions among classes and their behaviors, the diagramming technique itself does not provide guidance on how to determine how the classes will interact and what their respective behaviors will be. Doing this correctly is a critical element to ensuring the codebase is well-designed and maintainable.

GRASP patterns provide guidance for assigning responsibility and interactions to objects; GRASP is an acronym for General Responsibility Assignment Software Patterns and were defined to provide guidance for OOA&D. While there are nine GRASP patterns in all, five key GRASP patterns should be mastered and considered continuously in the creation of the design model. What follows are the five patterns, each including the problem that arises when adding behavior to a model, and the guiding principle/solution for meeting that challenge. (Reference Applying UML and Patterns by Craig Larman, from which the following patterns are quoted, for a very well written discussion of these principles and other fundamentals of OOA&D.)

Information Expert

Problem: What is a general principle of assigning responsibilities to objects?

Solution: Assign a responsibility to the information expert - the class that has the information necessary to fulfill the responsibility.

Creator

Problem: Who should be responsible for creating a new instance of some class?

Solution: Assign class B the responsibility to create an instance of class A if one or more the following is true:

B aggregates A objects.
B contains A objects.
B records instances of A objects.
B closely uses A objects.
B has the initializing data that will be passed to A when it is created (thus B is an Information Export with respect to creating A).

An exception to this is that if the logic required to create class A is of considerable complexity, consider moving the creation logic to a helper class, called a Factory [GoF 1995].

Low Coupling

Problem: How to support low dependency, low change impact, and increased reuse? Coupling is how strongly one class is connected to, or has knowledge of, other classes. Highly coupled classes suffer from the following problems:

Changes in related classes force local changes.
Harder to understand in isolation.
Harder to reuse because its use requires the additional presence of the classes on which it is dependent.

Solution: Assign a responsibility so that coupling remains low.

This terse solution is not very helpful; indeed, it’s often simpler to instill low coupling by watching for signs of tight coupling and to refactor, accordingly. Martin Fowler’s Refactoring is by far the best resource available for becoming familiar with these "smells" along with concrete guidance for taking corrective action.

High Cohesion

Problem: How to keep complexity manageable? Cohesion is how strongly related the responsibilities of a class are. Classes with low cohesion suffer from the following problems:

Hard to comprehend.
Hard to reuse.
Hard to maintain.
Delicate and constantly effected by change.

Solution: Assign a responsibility so that cohesion remains high.

Like the solution for Low Coupling, this isn’t immediately useful advice. The point is to aim towards encapsulating related logic together, and to introduce new classes as necessary to continue to do so. Again, Fowler's Refactoring is a tremendous resource for this topic.

Controller

Problem: Who should be responsible for handling an input system event?

Solution: Assign the responsibility for receiving or handling a system event message to a class representing one of the following choices:

Represents the overall system as a Facade [GoF 1995].
Represents a User Story or Use Case scenario within which the system event occurs, often named <UserStoryName>Handler, <UserStoryName>Coordinator, or <UserStoryName>Controller.

As an aside, this GRASP pattern is nicely enabled via ASP.NET MVC with an explicit controller layer. But as the naming of a controller would imply, the scope of each controller should be limited to that implied by its name, accordingly. For example, a controller by the name of "ManageUsersController" would imply performing User-related CRUD operations; User-related report generation should likely belong to a separate controller. Incidentally, this would also better support High Cohesion - what is good for the support of one pattern is often good for another.

CRC Cards

It is sometimes difficult to figure out the very first step for adding behavior and collaboration activities to objects. A technique which may assist with getting the ball rolling or to help when brainstorming the behavior of a new bounded context within a domain is a technique known as CRC cards (Class-Responsibility-Collaborator cards).

CRC cards are very simple yet effective for defining brainstorming the responsibilities of each object. To utilize, grab some index cards, title each with a class name of interest, and write two things on each:

Responsibilities: For each CRC card (i.e., each class), write one or a few bullet points describing the extent of responsibility for the class. Keep GRASP patterns in mind when defining the scope of responsibility.
Collaborator Objects: List one or more collaborator classes which need to be interacted with in order to carry out the responsibilities of that class.

After documenting responsibilities and identifying collaborator objects, the task of transforming this information into the class diagram, and into sequence diagrams, is greatly simplified.

Refactoring & Refactoring to Patterns

GRASP patterns are a tremendous guide for answering the question of "what belongs where." But as a system evolves, changes are inevitably introduced by client request, or more frequently, by further discovery of requirements. For example, what may at first appear to be simple may quickly become complex after coding begins. In these cases, refactoring techniques can greatly assist to answer the question of "how to adapt to change." In a nutshell, refactoring is the practice of improving the design of existing code. While the details of refactoring are beyond the scope of this article, two tremendous resources (i.e., absolutely required reading for any developer) are Refactoring by Martin Fowler and Refactoring to Patterns by Joshua Kerievsky.

Putting it Into Practice

This day’s "Putting it Into Practice" will consist of a number of example artifacts, including the class diagram (both initial and revised), CRC cards, and sequence diagrams. Let’s review each in turn.

By far, transforming the concept model into the design model is the one of the trickiest tasks and the most important to get as close to "right" as possible. The rule to keep in mind is to design the simplest model which could possibly work to fit the needs of the requirements and elaborate iteratively and only when necessary. (Keeping in mind the design elaboration steps discussed previously.)

Initial Domain Class Diagram

At some point, the concept model must be transformed into an implementable design model. This is the time to put our techie hats on and start to think in terms of classes, properties and methods. To get the ball rolling, let’s take a stab at designing a minimal class diagram to support the concept model discussed earlier.

Initially, we’ll focus on the bounded context of support ticket management, and the objects which participate with this activity. We’ll leave the reporting context until later on; this will also give Acme Telecom a little more time to make up their mind on what they want to see in the report.

What follows is the class diagram reflecting the first attempt at modeling the domain as an implementable design:

There are a number of differences from the conceptual model which were carefully considered:

The concepts Management, SupportStaff, and Admin have been combined into a single class called StaffMember. The following considerations were taken into account to make this decision:
- All of these concept objects are employees of Acme Telecom.
- Each of the concepts share duplicate data.
- While each may be allowed to do different tasks (e.g., manage staff vs. open support tickets), it does not yet appear that the classes themselves would behave differently. I.e., it’s not yet apparent that an Admin class would have different methods than a Manager class.
- Having the flags "IsAdmin" and "IsManager" may indicate that we may need role-management capabilities; while this may be true, we’ll want to avoid delving into the weeds further until warranted. (With that said, we’ll want to fully think out security management before we begin coding…it’s much more difficult to incorporate security management later on in project development.)
The concepts SupportTicket and SupportCall have been merged into a single class called SupportTicket. This could have been argued either way, but the two concepts are equivalent from a data workflow perspective. Consequently, I went for the simpler approach.
SupportTicket.Status has been pulled out as an enum value as we rarely expect the status types to change. Additionally, since the status may also be considered within data workflows, having it as an enum value will simplify the workflow conditionals and provide support for the use of a finite state machine, if deemed necessary down the road. (See Kerievsky's Refactoring to Patterns for guidance on when/how to make this decision.)
Preferably, SupportTicket.IssueType would also be an enum to keep things simple. But, the requirements state that the SupportStaff must be able to dynamically add new issue types, when needed, when opening a support ticket. Consequently, IssueType will need to be a persistable domain class.

Take special note that this model does not imply anything about infrastructural details such as persistence and security. These will be added to the class diagram as they are included in the sequence diagrams. Trying to anticipate all of the infrastructural classes at this time will likely lead to over-engineering (or wrong-engineering altogether).

With that said, the architect should have a good idea of how such infrastructural concerns will be addressed in the final solution. It is appropriate to have at least discussed how the overall project will be architected and what tools will be used to support infrastructural concerns. The overall architecture will have a strong impact on the sequencing of messages through the application tiers.

For the task at hand, we’ll take into account the fact that we’ll be using S#arp Lite as our underlying framework and architecture.

Accordingly, before going further, read the article "S#arp Lite: The Basics" to get a better understanding of how a S#arp Lite project is architected: http://devlicio.us/blogs/billy_mccafferty/archive/2011/11/11/s-arp-lite-the-basicss.aspx . Pay particular attention to the package diagram, describing how the layers are organized.

Sequence Diagram for Opening a New Support Ticket

Did you read the introduction to S#arp Lite as referenced above? OK, great, we’re ready to continue. (You'll likely be lost, bewildered, confuddled and worse if you haven't read it...I hope you'll only experience one or two of those symptoms if you have read it.)

We have designed the beginnings of the class diagram. We’re now ready to elaborating, refining, and adding behavior to the class diagram by analyzing the sequence of events involved with opening a new support ticket. This particular user story was selected because it covers much of the bounded context that we’re currently working on and is a critical element of the CLogS application.

As we’ll see, the design of the sequence diagram is where we have to seriously start thinking about:

How will data be loaded from the database?
How will data be saved to the database?
How will messages travel among the Web, Controllers, Tasks, Domain, and Data layers of the project?
How will the Tasks layer expose the core API of the application to the Controllers layer?

While this is a daunting task, be patient and revise your first sequence diagram many times until you feel it’s clear and clean.

Let’s now consider a sequence diagram for the following user story:

Support Staff may open a new support ticket and provide details including: Customer, Issue Details (such as description and "dynamically managed" type), Status, and Resolution Details (if resolved immediately). Status of the call may be New, In Progress, or Resolved. ("Dynamically managed" means that if the issue type isn’t available, the Support Staff may enter a new one when entering the support ticket.)

To make things simpler, ignore any extraneous features in the first design of the sequence diagram to focus on the core of the requirements; e.g., we’ll ignore the dynamically managed issue types for now.

(Click to embiggen.)

The sequence diagram above describes the collaboration of objects in support of allowing a staff member to open a new support ticket.

While designing the above sequence diagram, four new objects were identified, which may be added to the class diagram:

ManageSupportTicketController: This MVC controller class will reside in the .Web layer of the project and will have the responsibility of handling requests for the management of a support ticket.
ManageSupportTicketTasks: This tasks class (aka "application service" class [Fowler 2002]) will reside in the .Tasks layer of the project and will have the responsibility of carrying out the coordination activities for the management of a support ticket.
SupportTicketViewModel: This view model DTO (data-transfer object) will carry information from the controller to the view and vice-versa for the purposes of allowing a StaffMember to add/update support ticket information.
IRepository<SupportTicket>: This interface will provide a means to communicate with the underlying data access mechanism to persist the new support ticket to the database.

In a nutshell, the sequence is as follows:

The StaffMember requests to open a new support ticket.
The StaffMember is presented with a form.
A sub-process facilitates the StaffMember to select the respective customer (elaborated below).
The StaffMember provides the requested information and submits the form.
The StaffMember is either:
- presented with the same form, with validation information, if the submitted information contained validation problems, or
- presented with a listing of open support tickets with a message stating that the support ticket was successfully saved.

We’ll now turn our attention to look at the sub-process for selecting a customer...

The sequence diagram above describes the sequence of events to allow a StaffMember to select a customer via an AJAX post-back on the page. The form will have a "Customer Account Number" input box on it; when it changes, an AJAX post-back will try to find the customer record. If the customer exists, the customer information will be dynamically shown; if it doesn’t, the StaffMember will need to provide a few customer details before submitting the form.

As implied, many details about a user story are discovered during the process of designing a sequence diagram. To ease organization of the requirements, the sequence diagrams and details may be simply printed out and stapled to an index card with the user story written on it, or uploaded as attachments to the user story in an online requirements management tool.

In both sequence diagrams, arguments may be made that all of the UML is not "by the book"; e.g., the use of stereotypes has been basterdized a bit to make the diagram more expressive. I bring this up to express the point that less time should be spent worrying about making a UML diagram perfect as should be spent conveying useful information. When everything’s said and done, these diagrams will likely be thrown away once they’ve been implemented as working code.

If the underlying project architecture is already established (e.g., we’re using S#arp Lite as the foundation), designing the sequence diagram is relatively straight-forward. If the intention is to grow the architecture "organically," then elaborating the sequence diagram may take a few iterations.

CRC Cards for "Ticket Resolution Report by Support Staff"

In our discussions thus far, we haven’t gotten into the details of exactly how the support ticket resolution report will be generated. So before tackling the respective sequence diagram, we’ll use CRC cards to brainstorm a bit about the classes to be involved with the user story. The CRC cards don’t need to be exhaustively detailed; just enough in order to move on to the associated sequence diagram. CRC cards don’t/shouldn’t need to be maintained throughout the project life-cycle; once they’ve served their usefulness, toss them (or archive them away to some hidden place if throwing them away saddens you).

As demonstrated, the CRC cards were used to work out the basics of the classes involved with generating a support ticket resolution report, per the requirements. Now that the general responsibilities have been defined, we’re able to confidently move on to designing the respective sequence diagram.

Sequence Diagram for Creating a "Ticket Resolution Report by Support Staff"

(Click to invigorate.)

The sequence diagram above describes the collaboration of objects in support of the creation of a support ticket resolution report for a specific staff member.

While designing the above sequence diagram, four new objects were identified, which may be added to the class diagram:

SupportTicketReportsController: This MVC controller class will reside in the .Web layer of the project and will have the responsibility of handling requests for the creation of support ticket related reports.
SupportTicketReportTasks: This tasks class will reside in the .Tasks layer of the project and will have the responsibility of carrying out the coordination activities for the creation of support ticket related reports.
IRepository<StaffMember>: This interface will provide a means to communicate with the underlying data access mechanism to retrieve staff member information.
IRepository<SupportTicket>: This interface will provide a means to communicate with the underlying data access mechanism to retrieve support ticket information.

We’ll now turn our attention to look at the revised domain class diagram, taking into account what we’ve learned with the creation of the CRC cards and sequence diagrams.

Revised Domain Class Diagram

Now it’s starting to look like a real application! (On paper anyway. >:/ ) The class diagram now contains enough classes to warrant noting which project layer each class belongs in. We also have enough information to decorate classes with methods (i.e., behavior) in addition to attributes. If you’ve been paying attention, you may notice that some of the class names are slightly different from the CRC cards and/or sequence diagrams; e.g., ManageCustomersController was called ManageCustomerController in the sequence diagram. This is perfectly fine and expected; your design should continue to evolve as conventions are established, details are discovered, and new changes are incorporated.

With the sequence diagrams established to describe how the objects collaborate, and the class diagram designed to show how the classes are organized, we’re ready to begin switching gears from design to implementation. If you’ve been designing user stories along the way, the actual implementation should be the easy part!

Outputs

Domain class diagram
Sequence diagrams

That wraps up Day 3 in this series. In Day 4, we'll begin the implementation phase of the project and get our hands dirty with some code!

Enjoy!
Billy McCafferty

Greenfield Development with ASP.NET MVC & S#arp Lite - Day 2

Billy McCafferty — Fri, 12 Oct 2012 22:00:00 GMT

A series of posts providing proven guidance for developing ASP.NET MVC applications from idea to well-designed implementation.

Day 2 – Define the Domain Conceptual Model

Objective of the Day

Transform the requirements from Day 1 into an appropriate domain conceptual model reflecting objects, attributes, and associations.

Inputs

Project Vision
User Stories or Use Cases
Data Dictionary

Activities

The domain conceptual model is a visual representation of conceptual or real-world objects in the domain of interest [Fowler, 1996]. (The domain design model, which will be discussed in Day 3, is a visual representation of the classes and behaviors which will be implemented in the software.)

The conceptual model is not a class diagram describing classes with methods. But in practice, the conceptual model will iteratively become the basis of the class diagram of the design model. Specifically, the conceptual model reflects the following information:

Domain conceptual objects,
Associations between conceptual objects, and
Attributes of conceptual objects.

The important distinction between conceptual model and design model is that the conceptual model should represent a clear business-oriented abstraction of the domain; i.e., the client should be able to look at the conceptual model and understand it fully without difficulty. Compare this to the design model which will include method names, data types, polymorphic associations, and supporting classes, such as factories and services.

To illustrate, suppose your domain includes the concept of “Customer” and “Employee.” The conceptual model would reflect two separate objects, each having duplicate attributes such as first name and last name. The design model may instead reflect a parent “Person” class, inherited by both Customer and Employee, having duplicated fields moved up to the Person superclass. Applying UML and Patterns [Larman 2004] goes into great deal concerning this process and is highly recommended read.

We’ll get into more details of the design process when we see it in action, next.

Putting it Into Practice

For Acme Telecom’s CLogS, the business requirements have been established. It is now time to begin transforming the requirements into a domain model.

The first step along this path is to define the conceptual model. We’ll define the conceptual objects, define their relationships with other objects, and add attributes, describing the pertinent information associated with each. But how exactly do we go about naming the conceptual objects? [Larman 2004] suggests looking for objects which fall into a Conceptual Class Category, such as:

Physical or tangible objects,
Places,
Transactions and transaction line items,
Roles of people,
Physical container of other things,
Things in a container,
Organizations,
Events,
Processes,
Rules and policies, or
Nouns.

For finding associations, Larman suggests looking for the following types of associations:

A is a physical or logical part of B,
A is physically or logically contained in/on B, or
A is recorded in or is a line item of B.

Now that we know what to look for, what artifacts do we look at as potential sources for objects? The primary sources include the vision, data dictionary, and user stories; i.e., the artifacts from Day 1.

As a caveat, if you find conceptual objects in the vision or data dictionary that are not included in the user stories, you should double check to make sure that the user stories are adequately representative of the requirements. While you may find extra concepts in the data dictionary, since it provides explanatory details of terms, extra concepts in the vision – but not found in the user stories – likely indicates an inadequacy, accordingly.

Looking at the inputs from the previous day, potential conceptual objects include:

Customer
Support Staff
Management
Support Call
Support Ticket
Ticket Resolution Report per Support Staff
Ticket Resolution Report per Issue Type

Compiling the list of concept objects will likely incite useful discussion, much of which will help to ensure that the business has been adequately modeled, and how the concept model will be later transformed into the design model.

At right, review an example of how the conceptual model could be visually modeled, for the concepts discussed, with associations and attributes. As shown, all of the major elements of the conceptual model have been visualized. There are some interesting things to note concerning this model:

There are many duplicated fields between Management and SupportStaff. When implemented, these will likely be combined into a single Employee class; but recall that this is the conceptual model and should include more, rather than less, detail to cover all of the unique concepts within the requirements.
SupportTicket and SupportCall have a one-to-one relationship with each other. These may have instead been merged into a single concept (and will be done so in the design model), but splitting them into separate concepts at this stage emphasizes that there is a call from the customer which leads to a ticket being opened.
TicketResolutionReport is a report concept which includes a listing of SupportTickets and a number of ResolutionMetrics. Note that there is not an explicit association between TicketResolutionReport and the SupportTicket object to emphasize that the report, rather than being a core element of the domain, is an auxiliary concept to the domain. This is a subtle and subjective point but can help to establish bounded contexts during the design of the implementation. While it would not have been wrong to have included an explicit association, doing so would not have added much useful meaning to the context of the requirements. Associations between objects in a conceptual model should indicate some degree of permanence.
As an additional note, the ResolutionMetrics attribute of TicketResolutionReport may indeed be a separate concept object itself; but at this point, it’s added as a placeholder, to be expanded upon at a later time.

As may be inferred, there’s certainly a lot of subjectivity and brainstorming that goes into creating the domain conceptual model. As such, don’t try as much to get it "just right" as to ensure that it comprehensively captures all of the key concepts and associations within the requirements.

When creating the conceptual model and you are faced with the decision to split a concept (or merge separate concepts), err on the side of splitting the concept to provide more granularity than may be necessary for the actual implementation; i.e., it’s better for the conceptual model to be too expressive than too simplistic. Once the concepts are established, you can always combine and regroup as necessary for the design model, but you don’t want to miss anything along the way.

As a final note, defining conceptual objects is more important than identifying the associations among them, and more time should be spent on object identification, accordingly.

Outputs

Domain conceptual model

That wraps up Day 2 in this series. In Day 3, we'll Define the Domain Design Model...

Enjoy!
Billy McCafferty

Greenfield Development with ASP.NET MVC & S#arp Lite - Day 1

Billy McCafferty — Fri, 24 Aug 2012 17:15:00 GMT

A series of posts providing proven guidance for developing ASP.NET MVC applications from idea to well-designed implementation.

Part I - Planning & Design

For the planning and design phase of project delivery, each "day" will have an objective, inputs, activities, and outputs:

Objective: This is a short description of the goal – or expected end result – of the day.
Inputs: These are the informational inputs, document artifacts, and decisions that should have been made before beginning the day’s activities.
Activities: This is the core element of each day, describing the interactions with the client and the practices used for ultimately transforming ideas into production code. For each day, we’ll discuss the activities to be achieved and put them into practice on our example project.
Outputs: These are the artifacts that will have been generated during the day’s activities, some of which may be used as inputs for subsequent days.

Day 1 – Define the Requirements & Actor/System Interactions

Objective of the Day

Work with the client to translate ideas into requirements. By the end of the day, you should be able to concisely describe the project’s vision, actors, and implementable requirements.

Inputs

Client project ideas, with knowledge of who will be interacting with the system.

Activities

Project Vision

The first activity of the day is to establish the project vision. The vision describes the high-level goals of the system and the business case for implementation. It’s the two-minute elevator speech describing what the system is intended to achieve.

While defining the project vision, a key activity will also be to clearly define the “actors,” or the people who interact with the system and the goal(s) of those interactions, accordingly.

This may seem like a simple, or even dismissible, step, but clearly defining the vision and actors is one of the most essential elements of the entire project. The vision serves as a good litmus test to use to verify if a client idea is relevant to the project’s vision. Additionally, by clearly defining the actors, it allows you and the client to focus on just those requirements which satisfy the needs of those actors; i.e., if an idea comes up which doesn’t serve the needs of one of the defined actors, it can be summarily discarded or put on an “idea parking lot” (so the client feels like you’re actually going to look at it again someday…which you’re not). In other words, don’t skip this!

Putting it into Practice

Our aspiring client’s company is Acme Telecom. Acme Telecom would like to create a support call tracking system to log and monitor all calls, which will be tracked as “support tickets,” coming into its support department. Currently, Acme Telecom’s paper-based system is making it difficult to assess how well its support staff is responding and closing calls. Acme Telecom doesn’t want to try to do too much at once, so the client wants to keep things very simple and small for this first release. Accordingly, the vision that we and the client were able to agree on was as follows:

Acme Telecom’s paper-based approach to support call tracking is limiting the company’s ability to improve support capabilities. Accordingly, Acme Telecom needs an easy-to-use, secure, web-based Call & Logging System (or "CLogS" for short) for its Support Staff to track and resolve support calls from Customers as “support tickets.” In addition to facilitating support ticket resolution, the system must provide high-level reporting for Management to filter support ticket logs and to assess key performance metrics, such as rate of resolution and resolution bottlenecks.

Not only does this vision define the general scope of the project, but did you notice that the actors were also clearly stated? (We can even infer hints of the domain model…but that’ll be for a later discussion.)

Taking the vision a bit further, the actors, and goals of each actor, are as follows:

Actor	Major Goals
Support Staff	Log support ticket. Update and/or resolve calls opened by self.
Customer	Have support staff resolve calls.
Management	Run filterable reports on call logs. Run "canned reports" to assess resolution performance.

With that, we have a good general scope definition of the project, we know who the primary stakeholders are, and what each would like to achieve.

At this stage, it doesn’t look like the customer would actually be interacting with the system since they’ll be calling the Support Staff directly...should we include them as an actor? Yes, due to the fact that they represent the key stakeholder to be satisfied and should be considered during requirements elaboration by asking “Is this idea going to help the Customer get their calls resolved?”

User Stories or Use Cases?

Both User Stories and Use Cases summarize the various features of the system. Each should be small enough to be estimable, but big enough that the client would be willing to pay for its implementation and measure progress. With that said, it is important to decide, very early on, if requirements will be defined using User Stories or Use Cases (or another means altogether) as there are appreciable differences between the two.

Users Stories, an element of the Scrum/XP, are very short requirement descriptions which are intended to be elaborated during development iterations; they are truly markers for further discussion. A User Story is a feature stated from the perspective of the actor(s) who will benefit from that feature. Each User Story typically includes the following details:

Description: The feature from the actor’s perspective.
Priority: Higher priority features should be addressed earlier in the project life-cycle while lower priority features may be dropped in favor of higher priority change requests, or dropped altogether to assist with meeting schedule deadlines.
Risk: Higher risk User Stories may be A) split into smaller risk User Stories, B) researched to mitigate risk, C) reflected as a higher uncertainty in the estimate, or D) dropped to reduce uncertainty in scope and schedule.
Estimate: Typically described in “points” rather than in hours to better facilitate relative-estimating techniques.

To learn more about User Stories, I encourage you to read User Stories Applied by Mike Cohn.

Use Cases, on the other hand, include much more detail for each requirement. For example, while a User Story may be described in a sentence or two, a Use Case describes prerequisites for the Use Case to be activated, a “happy path” of execution, exceptive cases to execution, and post-conditions, describing the state of the system after completion. To learn more about Use Cases, I encourage you to read Applying Use Cases by Geri Schneider.

There are pros and cons to each; google “User Story vs. Use Case” to get a swath of opinions. Personally, I prefer User Stories if I feel the client is very unsure of what the final system will be, or if the client is supportive of flexible scope; I prefer Use Cases if the end result is very definable or if the client demands fixed bid (which always makes me shudder). There’s more to it than that, but for the purposes at hand, we’re going to go with User Stories for Acme Telecom’s CLogS application.

Putting it into Practice

Now that the vision, actors, and actor-goals have been defined, we’re ready to define the requirements of the solution. We’ll do so by working with the client to define the requirements as User Stories. To keep things simple, we’ll ignore Priority, Risk and Estimate, focusing simply on the description of each. Our User Stories for CLogS are as follows:

Support Staff may open a new support ticket and provide details including: Customer, Issue Details (such as description and “dynamically managed” type), Status, and Resolution Details (if resolved immediately). Status of the call may be New, In Progress, or Resolved. (“Dynamically managed” means that if the issue type isn’t available, the Support Staff may enter a new one when entering the support ticket.)
Support Staff may manage Customer details, adding and updating Customer information when necessary.
Support Staff may view listing of all tickets opened by self, defaulting to those which are not resolved and filter the listing, accordingly.
Support Staff may search for an existing support ticket, opened by self, view details of ticket, and update its status and resolution details.
Management may view listing of all tickets, defaulting to those which are not resolved and filter the listing, accordingly.
Management may view report showing information regarding how quickly calls are being resolved, called the “Ticket Resolution Report by Support Staff.” The report may be run for all Support Staff or for a specific Support Staff employee. The manager creating the report may only include Support Staff of whom they are manager.
Admin may view the “Ticket Resolution Report by Support Staff” for any and all Support Staff.
Management may view chart showing a breakdown of call by issue type and average resolution time for each issue type, called the “Ticket Resolution Report by Issue Type.” The manager creating the report will only see stats for Support Staff of whom they are manager.
Admin may view the “Ticket Resolution Report by Issue Type” to include any and all Support Staff.
Admin may manage all details of Support Staff and Management, along with which Support Staff are assigned to which Manager. Each Support Staff may only have, and must have, one Manager.

Data Dictionary

One of the most frequently skipped steps of project delivery is also one of the simplest and helpful: the creation of a data dictionary. A data dictionary is a simple glossary of domain-related terms which serves to reduce requirements confusion between the client and project delivery team.

As project requirements become more complicated, a data dictionary becomes increasingly important to ensure everyone is speaking the same language. (Not) surprisingly, it’s frequently difficult for even client associates to agree upon term definitions; a data dictionary helps to get people talking and to (hopefully) agree upon the meaning of business terms. Forming this agreement of definitions forms the basis of Ubiquitous Language, a prominent component of Domain-Driven Design.

A few years back I developed a project management tool for a construction management project. One of the key features of this tool was a Master Budget Report which combined information from various sources to ultimately provide an Estimate at Completion for each project. The report’s data columns included Expenditures, Change Orders, Pending Obligations, Remaining Obligations, Total Obligations, and others. It took over three months of workshops involving client stakeholders from the financial group, project controls group, project managers, and upper management to agree upon what constituted a Pending Obligation vs. a Remaining Obligation and to sort out other such definitions and equations associated with the report. Imagine the frustrations that would have ensued if we had tried to develop this “standard” report when no one agreed to what was actually “standard.”

The lesson of the story is...don’t underestimate the usefulness of a well-discussed data dictionary. And knowing is half the battle.

Putting it into Practice

Acme Telecom’s CLogS is starting to take shape as vaporware; we’ve agreed to the vision and even the requirements. But during requirement elaboration discussions, there was some confusion on a few key terms. The following data dictionary helped to alleviate the confusion:

Term	Definition
Customer	A person who has an Acme Telecom account number. (Anyone else is just an annoying person wasting Support Staff’s time.)
Resolution Time	The number of business days (whole number) to resolve a call is calculated by taking the difference between the day a ticket is opened, and the day when it is resolved, excluding weekends. If a ticket is resolved in the same day it was opened, its resolution time is 0 days.
Avg. Resolution Time	This is the number of mean business days (decimal number) it takes for an arbitrary group of support tickets to be resolved; i.e., the sum of business days to resolve each ticket divided by the number of tickets.

It was easy to assume that everyone understood what "resolution time" meant when discussing requirements. But as we attempted to define this term in the data dictionary, it was recognized to be a non-trivial idea. Having this cleared up will help to ensure that anyone using the system has the same understanding of the term...assuming they’ve taken five minutes to read the data dictionary, which is quite an assumption in and of itself!

It should also be noted that the data dictionary was used to not only clarify project-related terms and calculations, but also to clarify the definition of actors.

While it’s not necessary to document every project term, any term which involves tricky calculations, subjectivity in defining, or has been identified as causing disagreement, should certainly be included. Furthermore, the data dictionary may be separated into separate lists such as Actors, Domain, and Calculations, but start simple and expand when necessary.

Actor/System Interaction Diagrams

I’ve been a strong proponent of agile development techniques for years; but a challenge I’ve always had is keeping track of the "big picture" as requirements are broken down into more granular requirements as user stories. An associate of mine, Jim Tucker, introduced me to a quick and easy technique that I’ve not seen surpassed for expressing the big picture in a clear and concise manner.

Before delving into technical design, Jim creates "Actor / System Interaction Diagrams" (as UML sequence diagrams) to document how the actors interact with each other and with the underlying system, treating the system as a black box. It’s possible to use this technique not only for the overall system, but down to the level of a single user story. This facilitates "zooming in and out" of the details as appropriate.

This is similar in nature to the back and forth between an actor’s actions and system’s responses described within a Use Case (an alternative approach to User Stories for documenting feature requirements), and to Craig Larman’s System Sequence Diagrams in Applying UML and Design Patterns. It differs from Use Cases in the fact that it’s more graphically oriented, and differs from both in that it may be easily expanded to include many participants and need not be constrained to a single feature. On a recent project, we used this technique to illustrate the high-level interactions among eight actors and multiple third party systems; the end result was simple enough for the client to understand and verify its logic, but expressive enough to be a useful artifact during technical design.

To use this approach, it’s first necessary to understand UML sequence diagrams, which is beyond the scope of this article. (Googling "UML sequence diagrams" will get you going in the right direction.) Having an understanding of sequence diagrams, Actor / System Interaction Diagrams differ from sequence diagrams in the following ways:

Actors are used in place of classes.
The system itself is treated as a single participant in the sequence diagram.
The "messages" among participants, instead of being API calls, are requests between actors and/or the system itself.

But, as usual, an example speaks a thousand words...

Putting it into Practice

The trickiest User Story in the CLogS application is as follows:

Support Staff may open a new support ticket and provide details including: Customer, Issue Details (such as description and type), Status, and Resolution Details (if resolved immediately). Status of the call may be New, In Progress, or Resolved.

This one caused the most discussion and had the most unknowns. Accordingly, it was decided that an Actor / System Interaction Diagram would be created to clarify the sequence of interactions.

The actors that will be in the sequence diagram include Customer, Support Staff, and the CLogS application. The sequence of events to handle a new support call is as follows:

Customer calls Support Staff and describes the issue.
Support Staff opens a new support ticket in CLogS which requires the following sub-steps:
1. Support Staff gets Customer account number.
  1. Support Staff uses account number to find customer.
  2. If not found, Support Staff adds a new Customer entry.
  3. If found (or after created), Support Staff generates a new support ticket for the Customer.
2. Support Staff adds issue details to the new support ticket entry.
If resolvable, Support Staff assists the Customer and marks the support ticket as resolved.
Otherwise, Support Staff gives the Customer the support ticket reference number and pinky swears to resolve the issue and get back with them.

The Actor / System Interaction Diagram above shows the actors involved and their interactions with each other. Although this level of detail isn’t necessary for every User Story, it’s a useful technique for illustrating the business processes behind more complex User Stories. Furthermore, this technique need not be limited to the User Story level; alternatively, you could create Actor / System Interaction Diagrams for major modules and/or include third party systems as additional "actors." UML sequence diagrams are quite versatile for this kind of work.

Outputs

Project Vision
User Stories or Use Cases
Data Dictionary
Actor / System Interaction Diagrams

That wraps up Day 1 in this series. In Day 2, we'll Define the Domain Conceptual Model...

Enjoy!
Billy McCafferty

Greenfield Development with ASP.NET MVC & S#arp Lite - Introduction

Billy McCafferty — Thu, 02 Aug 2012 21:08:00 GMT

A series of posts providing proven guidance for developing ASP.NET MVC applications from idea to well-designed implementation.

So you’ve landed your first project! Just days ago your client came to you and said “I’ve got a great idea and I want you to build it!” With unwavering confidence, you quickly retorted “And I’ll build it, and it’ll be friggin’ awesome!” You agree to a price, you put all the business paperwork in place, and you’re ready to get coding…you sit down at the computer, raring to go, and think to yourself “Now where the hell do I start?”

To begin with, you’ve already gotten ahead of yourself. Before a single key stroke of code is developed, it’s time to do some planning. And once the planning is done - and only after that - it’ll be time to turn those plans into maintainable, tested code.

While there are plenty of coding samples of design patterns and "best practices," it’s sometimes difficult to figure out how the developer got from an empty directory in Windows Explorer to an implemented piece of architectural and functional beauty. This series of posts will walk you through the basics of the project life cycle, from project inception to project completion, turning ideas into requirements, requirements into plans, and plans into code, with a clear and blatantly unfair bias towards the developer’s perspective.

This isn’t intended to discuss a particular project management methodology or advocate the principles of any specific development methodology. Instead, this series’ focus is on using a number of tricks of the trade of traditional Object Oriented Analysis & Design (OOAD) and various development techniques to turn ideas into working code. In other words, bits and pieces from UML, design patterns, OOAD, Domain-Driven Design , Test-Driven Development , etc…you know, like what you’d do on a real project.

Although we’ll be using S#arp Lite as the project starting point and architectural infrastructure, most of the principles and techniques we’ll be using will be applicable to just about any development implementation you’d prefer.

The project activities will be examined over seven “days” with each day focusing on a distinct element of project production. Note that each day, when mapped to a real project, may represent an hour, a day, a week, or perhaps even a month(s) depending on the activities involved and the size of the project. (So don’t take "day" too literally.)

The seven days of the project will cover three major themes of project delivery:

Part I focuses on the planning and design elements of project delivery; i.e., turning project ideas into a workable design. Part I is split into three days:
Part II focuses on the implementation phase of project delivery; i.e., turning the design into a working project. Part II is split into four days:
- Day 4 – Setup the Project & Security Infrastructure
- Day 5 – Develop CRUD & Data Management Capabilities
- Day 6 – Provide Reporting Capabilities
Part III focuses on extending the project to integrate with third-party, external services with an appropriate separation of concerns.
- Day 7 – Integrate with External Services

While this series of posts walks through the development of the project in a seemingly waterfall fashion, it does not intend to promote such a methodology; indeed, an agile/iterative approach to development is recommended but is beyond the scope of this series to discuss. If you find them useful, I'd encourage you to adapt some or all of the described techniques into your organization’s preferred methodology.

At the end of the series, you should have a basic understanding of how to turn a project idea into a well-designed, maintainable deliverable using real-world techniques, starting from nothing but an idea.

Who is the Intended Audience?

While I am attempting to write this series to be understandable by any skill level, you're expected to have basic knowledge of UML (specifically class diagrams and sequence diagrams) and to be familiar with ASP.NET MVC and C#. For materials on these subjects, refer to Pro C# 2010 and the .NET Platform [Troelsen 2010], Professional ASP.NET MVC 3 [Galloway 2011], and UML 2.0 Pocket Reference [Pilone 2006]. Other references will be provided along the way to help fill in any missing gaps and secondary subjects.

Developers of experienced-beginner to intermediate levels will gain the most from this series.

The next post in this series is Day 1 – Define the Requirements & Actor/System Interactions...

Enjoy!
Billy McCafferty

Checklist for Developing Message-Based Systems

Billy McCafferty — Tue, 23 Mar 2010 21:22:00 GMT

Even when developing the most basic CRUD application, we ask ourselves a number of questions - whether we realize it or not - during the initial phases of development concerning the architecture and construction of the project. Where will the data be persisted? What mechanism will be used to communicate with the database? How will data from the database be transformed into business objects? Should separated interfaces and dependency injection be employed to maintain a clean separation of concerns between application logic and data access objects? What UI components will be leveraged to speed development of the UI layer? When developing message-based systems (see Message-Based Systems for Maintainable, Asynchronous Development for an introduction) it's immensely helpful to formalize such questions about how the systems will be designed and developed. Creating a checklist of such items to decide upon, and formalizing answers for the application context, helps to:

Standardize how components (applications participating in the message-based system) will communicate with the messaging middleware;
Provide architectural guidance throughout project development concerning how components will leverage message end-points;
Define the data model that will be used for sending commands and exchanging data among components;
Assist new developers on the team with getting up to speed with maintaining and extending the message-based system; and
Support consistency (and predictable maintainability) amongst the components of the system.

This post provides an addendum, if you will (I'm sure you will), to Message-Based Systems for Maintainable, Asynchronous Development for complementing the article with a checklist of questions and architectural topics that should be discussed, decided upon, and/or spiked before beginning development of your budding message-based system. Accordingly, this does not describe a methodology for developing message-based systems, but simply a checklist of topics which should be taken into consideration before development begins. Many of the checklist items below serve as good starting points for team discussion and for the development of architectural spikes for demonstrating implementation details.

Messaging Middleware

What messaging middleware solution will form the background of the message-based system?
How are channels addressed in the selected middleware? (E.g., as a string or as a port number?)
How does the nomenclature of the middleware match up to standard elements of message-based systems and design patterns? E.g., in Robot Operating System (ROS), a channel is called a "topic." Likewise, is their middleware specific nomenclature for elements such as component, publisher, subscriber, point-to-point channel, publish/subscribe channel, message, command message, request-reply message, router, message end-point, and other messaging design patterns?
What mechanism is available for peeking at messages going over a point-to-point channel?
What utilities are available for viewing active channels, publishers, and subscribers?
What other tools does the middleware provide for debugging and observing the messaging system? Will custom utilities need to be developed to autment development and debugging capabilities?

Integration with Messaging Middleware

How will message end-points publish a messages?
How will message end-points subscribe to a channel for messages?
How will message end-points poll a channel?
What technique will be used to decouple the component (participating application) from the message end-point when sending a message? E.g., dependency injection, separated interface, or other?
What technique will be used to decouple the component from the message end-point when receiving a message or polling a channel? E.g., callback, separated interface, or other?
Should exceptions raised by the messaging middleware be wrapped in component specific exceptions for looser coupling? If so, what will be the standard exceptions? Additionally, how will such exceptions be logged and tracked for debugging; e.g., email alerts, logging, exception message channel?

Channels and Routing

What channels will be created and what data type should each channel carry?
Will a hierarchical naming strategy be leveraged for naming and organizing channels? If so, what are the naming conventions for the project?
Has an invalid message channel been setup with a logger to capture and record invalid messages?
How should a predictive router be implemented, when needed?
How should a reactive router (e.g., a message filter) be implemented, when needed?

Message Elements

What data elements may the header of a message contain and how should each be specified? E.g., return address, message expiration, timestamp, origin, format indicator, etc.
How should a message identifier and correlation identifier be generated and included in the header?
What is the messaging data model supported and/or enforced by the messaging middleware? E.g., ROS supports http://www.ros.org/wiki/msg.
What canonical data model will be used to imbue message content with domain specific semantic meaning? E.g., JAUS.
How will message translators and/or message mappers be leveraged for converting between each component's domain model and the canonical data model?
How will a command, document, event and request-reply message be composed?

Other Topics

How will components maintain information that is associated with a correlation identifier?
Are there existing components which need to interact with the messaging middleware which cannot be modified? If so, how will each communicate with the messaging middleware?
How will each component participate with the message based system; e.g., as a polling consumer, as an event-driven consumer, as strictly an event publisher, as a combination of these?
Should exceptions raised by a component participate in a global exception tracking and debugging mechanism?

As stated previously, this checklist is not intended to provide a methodology for developing message-based systems, but should serve as a good basis to make sure "T's are crossed and I's are dotted" when deciding upon the major architectural aspects and development techniques that will be leveraged throughout the development of your (team's) message-based system.

Enjoy!
Billy McCafferty

A Few Thoughts on DDD, DTOs, View Models, Repositories and Separation of Concerns

Billy McCafferty — Sat, 06 Mar 2010 16:41:00 GMT

What I've loved most about developing an open-source project is the ideas that I get from others who look at the work and either A) validate ideas, B) suggest that something stinks, or C) call a royal WTF and force people (e.g., me) to explain ideas more fully. It's usually during these explanation attempts that light bulbs start to come on and ideas are refactored and become more substantiated (or at least more defendable). The S#arp Architecture forums have been a gold mine, IMO, for the discussion of the practical application of balanced DDD techniques on real-world projects. After feedback that I've already gotten on my recent post concerning application services and CQS and listening to and adding my two cents concerning ideas on the S#arp forums, I'd like to share a few ideas (that I shared on the forum) concerning drawing the line among application layers, the management of DTOs and View Models, and a general discussion of separation of concerns. (As Chris Carter correctly (and a tad bluntly) explained, don't take these ideas at face value...use them as a point of discussion and contemplation to come to your own conclusions with your project team...and let me know what you think.)

Every great developer knows that any problem can be solved by adding another layer of abstraction. ;)

Obviously, with additional layers of abstraction and indirection, we also introduce complexity and additional objects which need to be maintained. Over the past year, I have had struggles concerning just how far the "DTO paradigm" should be taken to effectively separate layers from the domain and "best practices" for how they should be used. I don't think the answer can be found in a best practice (but I also hate to leave it simply at "it depends"). I truly feel that the most important practice is for a project development team to decide, and firmly agree upon, which approach will be taken on a project and for the agreed upon approach to be followed with discipline (and enforced via code reviews) by the team.

On a couple of recent projects, the biggest problems we ran into weren't concerning which approach to leveraging DTO for layer separation was "best," but on coming to a firm layering decision and having the team discipline to adhere to those practices. Because of these "gray" areas, which we didn't come to a firm team agreement on, there were inconsistent practices used by the developers which led to rot, particularly between the controller (or code-behind) and application services layer.

So while we can discuss which approach is best or most effective, I think the greater concern is for the team to pick a direction, to stick to it, and to diverge or refactor as a team decision.

But as I said, I don't want to leave it at "it depends." ;) So after reading everyone's ideas here and contemplating further on past projects and the ideas I recently put forth in http://devlicio.us/blogs/billy_mccafferty/archive/2010/03/05/better-application-services-and-cqs-with-s-arp-architecture-1-0-q3-2009.aspx, here are a couple of ideas that I've been trying to adhere to (and/or will be adhering to on my next project). The layers referenced below may be viewed in a package diagram here for better clarity of what's discussed.

Usually, one object should be used to populate a form while a second should be used to collect data from a form. The former would contain information for default/selected values along with drop-down values, for examples, while the latter would encapsulate which options were selected when the user submitted the form. Personally, I use a <EnityName>FormViewModel to populate the form and use an entity to collect from the form...but I see it equally valid to instead use an intermediary DTO to collect from the form if further separation is warranted. Additionally, I feel it is OK for a FormViewModel object to have references to domain objects to make it easier to transfer data to the form for input population. This is an arguable point and would be just as valid to only pass DTOs in the view model for a cleaner separation between view and domain, with the acceptance that there will be more objects and maintenance that comes with that approach.
I believe that view models should be maintained either in the application services layer OR in a separate ViewModels class library if a project team feels the additional separation is warranted (although I can't envision much reason to do so). (I'll be modifying my sample project post to reflect the former.) Either way, they should not be maintained in .Core to keep a very clean separation from domain concerns. While the name "ViewModel" implies that they are a view concern, they only describe what should be displayed, not how it should be displayed. Accordingly, there is still a very clear separation of concerns between the view layer (which the user interacts with) and the view model classes. Furthermore, the application services expose methods which should be usable by any type of client. In line with this, a ViewModel or FormViewModel class does not impart a particular mechanism for the implementation of the view layer - again, it only describes what data should be available to the view. So even if view model classes are maintained in app services, this does not preclude there use by various client types; e.g., they could be equally consumed by ASP.NET, ASP.NET MVC, Spark, SilverLight, etc. (The only caveat is that if the view model classes maintain references to domain objects, then it will be more difficult to expose them for serialization via web services and WCF. Accordingly, a project team should firmly decide if ViewModels may contain references to domain objects.)
I believe that DTOs should be maintained in a separate assembly and have no reference to .Core or be maintained in .Core if warranted with the acceptance of decreased "shareability." DTOs should almost always be serializable; i.e., transferable via web services and WCF. This allows the DTOs class library to be easily shared with a consumer of web services which may expose these objects, for easier deserialization. Some of the motivations for deciding when to use DTOs would be to provide a clean separation between the view and app services (if a project team feels its warranted), to expose data to web service consumers, and to better enable Command/Query Separation.
Repositories may return Entities, Value Objects or DTOs, in addition to other "basic" types; e.g., primitives, arrays, etc. Ideally, repositories would not be used by domain objects (even via their interfaces) and would have their interfaces maintained in the application services layer. If the repository interfaces are maintained in .Core, then this forces DTOs to be maintained in .Core as well with the possibility that domain references may "leak" into DTOs. If the repository interfaces are maintained in .ApplicationServices, then DTOs may be maintained in a cleanly separated library without worrying about the line between DTOs and domain objects being grayed. But data interfaces (and DTOs) may be maintained in .Core if the team feels the simplification is warranted.

With all this said, I still think the most important decision is deciding a path to take for your project, having the project team agree upon it, and maintaining the discipline to stay on course.

Your feedback on these ideas is most welcome!

Billy McCafferty

Better Application Services and CQS using S#arp Architecture 1.0 Q3 2009

Billy McCafferty — Fri, 05 Mar 2010 18:47:00 GMT

Updated 2010.03.09 to reflect small modifications that were decided through subsequent discussions on S#arp forum and other DDD posts.

Obviously, S#arp Architecture is the bee's knees when it comes to developing ASP.NET MVC applications. ;) But as a project evolves and gets larger, "out of the box" S#arp Architecture 1.0 guidance runs into a few pain points. Particularly, there's poor use of the application services layer, the separation between controllers and application services is not very clear, entity listing pages become performance bottlenecks as the domain model gets sizable, there is no command/query separation (CQS) "out of the box", and unit tests require re-occurring maintenance to deal with changes in the number of constructor parameters to controllers and application services. While the amicable and adroit Alec Whittington (who is taking over the lead role from me on S#arp Architecture) is hard at work upgrading S#arp Architecture to accommodate recent dependency upgrades and accommodating ASP.NET MVC 2, I wanted to take a stab at resolving some of the architectural issues that I've run into, on S#arp projects over the past year.

I've developed and included a sample project, built on S#arp Architecture 1.0 Q3 2009, for the following key reasons:

To resolve some "pain points" that develop as S#arp projects grow to large sizes,
To demonstrate better use of the application services layer,
To demonstrate better command/query separation of the entity listing pages for dramatically better performance as the domain model grows,
To create an architectural spike for a new project I'm working on, and
To collect feedback from the S#arp community to determine if this is an appropriate architectural direction for the next release of S#arp Architecture.

Please post any feedback and/or suggestions you may have in the comments below or, more preferably, to the S#arp Architecture forums at http://groups.google.com/group/sharp-architecture.

Setup instructions

Unzip the sample project to a BetterAppServices folder
Create a new database called BetterAppServices
Using SQL Enterprise Manager, run:
1. /BetterAppServices/db/Schema/CreateBetterAppServicesDb_ChangesWillBeLost.sql
2. /BetterAppServices/db/StoredProcedures/CreateGetProductCategorySummaries.sql
3. /BetterAppServices/db/StoredProcedures/CreateGetProductSummaries.sql
Open /BetterAppServices/BetterAppServices.sln with VS 2008
In VS 2008, open BetterAppServices.Web/NHibernate.config and change the connection string to point to your BetterAppServices database
Right click the BetterAppServices.Web project and "Set as StartUp Project"
Run (F5) the project to see everything in action.

Changes from "out of the box" S#arp Architecture 1.0 Projects

This project is more of an architectural spike more than anything else at the moment. Accordingly, the CRUD scaffolding generator has been removed and non-essential unit tests have been removed to focus on the architecture itself. Many of the changes will be incorporated into the S#arp CRUD scaffolding generator; this will either be available in the next release, or will be provided as an add-on, as this new approach does add complexity and introduces a major breaking change to existing 1.0 projects.

Major changes include:

/db Folder Changes
- Added /db/Schema/CreateBetterAppServicesDb_ChangesWillBeLost.sql. This gets auto-regenerated when unit tests are run. The motivation was to have the DB schema automatically maintained while developing.
- Added /db/StoredProcedures/CreateGetEntityNamePluralSummaries.sql. These SPs provide command/query separation for the entity listing (Index.aspx) pages, which frequently became a performance bottleneck.
Cross-Project Changes
- Moved /BetterAppServices.Core/DataInterfaces/* to /BetterAppServices.ApplicationServices/DataInterfaces/. This is the only major, possible breaking change for existing applications. This was done to further remove the potential of domain objects using data repositories directly, and to allow the repositories to return objects from a new Dtos project for command/query separation, among other benefits (dicussed below). Decided not to do this to support domain services which may require the use of repositories and to make upgrading from previous version much simpler in some cases. Having the interfaces in .Core doesn't necessitate that domain objects use them; in fact, my rule of thumb is for all domain objects to avoid the use of repositories unless an exceptive case exists.
- Replaced all uses of "using BetterAppServices.Core.DataInterfaces;" to "using BetterAppServices.ApplicationServices.DataInterfaces;" to support the above mentioned change.
- Replaced all uses of IRepositoryEntityName with IEntityNameRepository. Be default, all entities now have an explicit repository. This avoids the need to manually change from the generic to the explicit, when the need arose, in unit tests and in constructors; which was frequently occurring.
/BetterAppServices.Core/QueryDtos (/BetterAppServices.Dtos)
- Added a Dtos class library to provide an appropriate location for View Models and DTOs. While this project currently has a dependency on BetterAppServices.Core, so that the View Models can contain references to domain objects, this dependency could be severed for better separation between the view and the domain. The caveat is that much more work would be required maintaining a more complete DTO layer and transferring data via DTOs in all of the CRUD pages. Decided that a separate assembly was overkill. Consequently, added this namespace to contain query DTOs for transferring results of "report" queries into objects. With this example project, only the listing page uses "pure" DTOs for much better performance. The other CRUD pages still communicate directly with domain objects to keep things much simpler. This is something that can be argued either way and it should depend on the project needs to determine if a more separated approach is warranted.
- Added EntityNameDto.cs to act as a summary object to be bound to results from stored procedures (e.g., the entity listing pages), or other DTO needs.
/BetterAppServices.ApplicationServices/ViewModels
- Added this namespace and EntityNameFormViewModel.cs to hold data related to adding and updating the EntityName. This object gets populated and passed to the entity form pages, accordingly.
/BetterAppServices.ApplicationServices
- Added reference to BetterAppServices.Dtos so that app services can return DTOs.
- Added EntityNameManagementService.cs. This app service class removes the CRUD logic from the controllers, makes the logic more reusable, and creates an appropriate class to add additional application service logic to.
- Added IEntityNameManagementService.cs. This app service interface makes unit testing more maintainable because you can mock the service interface and not worry about when the concrete class' constructor arguments change.
- Added /DataInterfaces/IEntityNameRepository.cs. As described above, every entity now has an explicit repository interface to avoid changes down the road when custom interfaces would inevitably be introduced.
/BetterAppServices.Data
- Added /BetterAppServices.Data/EntityNameRepository.cs to implement the associated interface. An important thing to note is that method provided invokes a stored procedure to act as a reporting means in line with command/query separation. This is useful for entity listing pages which would frequently, previously, end up loading a huge portion of the domain model to show summary information.
- Added /BetterAppServices.Data/NamedQuery/GetEntityNameSummaries.hbm.xml and set its compile action to "Embedded Resource." This provides the "short cut" for invoking the stored procedure. It could easily be modified to accept paging parameters.
- Added reference to BetterAppServices.Dtos so that repositories can return DTOs for better command/query separation.
/BetterAppServices.Web
- Added reference to BetterAppServices.Dtos to be able show DTOs on web pages.
- Changed ComponentRegistrar.AddCustomRepositoriesTo "BetterAppServices.Core" to "BetterAppServices.ApplicationServices" to reflect the new location of the data repository interfaces.
/BetterAppServices.Web.Controllers
- Added reference to BetterAppServices.Dtos.
/BetterAppServices.Tests
- Modified MappingIntegrationTests.CanGenerateDatabaseSchema to save DB schema to /db/Schema/CreateBetterAppServicesDb_ChangesWillBeLost.sql every time the unit test is run.

To reiterate, many of the changes above can be incorporated into a CRUD scaffolding generator; the focus with this example project is on providing an archtectural spike of the proposed architectural revisions.

Even if you don't use S#arp Archtiecture, this sample project should serve as a good example of using application services and basic use of command/query separation (CQS). Although the CQS in the sample project could be taken much further, I felt that the sample provides a good balance between practical maintainability and a more austere separation of concerns.

Enjoy!

Billy McCafferty

Message-Based Systems for Maintainable, Asynchronous Development

Billy McCafferty — Tue, 02 Mar 2010 04:22:00 GMT

Preface (you know it’s good if there's a preface)

In Architectural Paradigms of Robotic Control, a number of architectures were reviewed including deliberative, reactive, and hybrid architectures. Each of these exhibit a clean separation of concerns with layering and encapsulation of defined behaviors. When implemented, the various capabilities, such as planners and mobility controllers, are encapsulated into discrete components for better reusability and maintainability. A pivotal aspect not discussed in the previous article is how the various system layers and components communicate with each other, such as reporting sensor feedback and sending commands to actuator controllers. Effectively resolving this communication challenge is not only important to robotic systems but to many other industries and domains for the successful integration of disparate applications.

To give credit where credit is due, this article pulls quite heavily from the patterns, taxonomy, and best practices presented in Enterprise Integration Patterns (Hohpe, 2003). This well organized book is chock full of hard learned lessons and solid guidelines for developing maintainable message-based systems. This article should not be seen as an adequate replacement for that book (it’s more like cliff notes with a spackling of robotics bias); indeed, Enterprise Integration Patterns should have a prominent place on your bookshelf if you're developing message-based systems – so read this post and then browse http://www.eaipatterns.com/ while waiting for your copy to arrive to delve deeper.

A Need for Message-Based Systems

A few industries in particular, such as finance, healthcare and robotics, are demanding integration of an intimidating number of separate technologies that may be spread across computers, networks, and/or built upon a variety of technological platforms. Not only is this integration tricky, it can come with a significant cost to performance and maintainability if not implemented correctly. Accordingly, a solution is needed which facilitates loosely coupled integration while accommodating the performance demands of the task at hand. Taking a message-oriented approach to inter-application communications is one such way to accommodate these demands in a maintainable manner without sacrificing performance. This article gives an introduction to developing message-based systems using messaging middleware, describes taxonomy for discussing messaging topics and patterns, and includes a number of best practices.

Before delving further, it's important to clarify a few terms that will be used frequently:

Messaging Middleware (aka, a message bus): a 3rd party application which provides messaging infrastructure and capabilities (e.g., MSMQ, MS Concurrency and Coordination Runtime (CCR), Robot Operating System (ROS)),
Component: a stand-alone application or piece of executable code which communicates with the messaging middleware,
Message-based system: the entirety of the system including all integrated components and the messaging middleware.

As stated, messaging provides one means of facilitating inter-component communications. But as with any design approach, the project requirements must be carefully considered to determine if messaging is the appropriate mechanism for integration. While messaging is robust and facilitates integration, it also adds complexity and indirection. So before deciding to use messaging as the means of integration, consider all component integration options including (Hohpe, 2003):

File Transfer: wherein a component produces files of shared data which other components consume,
Shared Database: each component stores and retrieves data from a common database,
Remote Procedure Invocation: each component exposes specific procedures to be invoked remotely for exposing behavior and exchanging data,
Messaging: each component connects to a common messaging system, using messages to invoke behavior and exchange data.

Determining which integration approach is most suitable to your project's needs is beyond the scope of this article, focusing instead specifically on messaging. In turn, we'll review important elements of developing a message-based system including: message channels, messages, message routers, and message endpoints.

Message Channels

When a component sends information to another component in a message-based system, it adds the information to a message channel. The receiving component then retrieves the information from the message channel. Different channels are created for each kind of data to be carried; having a separate channel for each datatype better enables receiving components to know what kind of data will be retrieved from a given channel. For using a channel, each channel is addressable for sending and retrieving messages to/from them. How a channel is addressed varies depending on the messaging middleware being leveraged, but it's usually a port number or a unique string identifier. As a good practice for keeping channels organized, if string identifiers are available, a hierarchical naming convention may be employed to label channels by type and name; e.g., a channel carrying laser scans might be called "Perception/LaserScans."

There are two basic kinds of message channels:

Point-to-Point Channels (aka - client/server style): routes messages for components to talk directly with other components; e.g., a remote procedure call to another component. A message over a point-to-point channel only has a single receiver; so while the sender may not necessarily know who the receiver is, the sender can rest assured that the message will only be received by one receiver – it’s a FIFO queue.
Publish-Subscribe Channels (aka - broadcast): routes messages for components to publish data and an arbitrary number of components to subscribe to that data. A copy of the message is generated for each subscriber on the channel.

In addition to channels intended to carry information among components, it is a good practice to setup an invalid message channel that bad-formed or unreadable messages may be forwarded to for logging and to assist with debugging.

Messages

With a function call, a simple parameter or object reference may be passed and retrieved by the invoked method, sharing the same memory space. But when passing data between two processes with separate memory spaces, the data must be packaged into a "message" adhering to an agreed upon format which the receiver will be able to disassemble and understand. The sender of the message passes the message via a message channel. The receiver retrieves the message from the message channel and transforms the message into internal data structures appropriate for the task at hand.

A message is made up of two parts:

Header: describes the data being transmitted and details concerning the message itself; e.g., origin, timestamp information, message expiration (if content is time-sensitive), message identifier, correlation identifier, return address, etc., and
Body: the data content that the receiver is looking to use.

When sending a message, the sender intends for the message to be used, or responded to, in a particular way. The intention of the message may be described as being one of the following:

Command Message: invokes a procedure in another application,
Document Message: passes a set of data to another application,
Event Message: notifies another application of a change in state, and
Request-Reply: requests a reply from another application.

Event messages deserve a bit more discussion. In its simplest form, an event message would simply be informational, letting subscribers know that an event has occurred; e.g., a new laser scan is available. If subscribers would like details concerning the event, they would send a request-reply to the sender of the event to provide further details; e.g., the laser scan details. Alternatively, the event could be a document as an event to inform subscribers that an event has occurred along with the details of that event; e.g., a new laser scan is available with laser scan details included. The size of the event details and the rapidity in which the event occurs should be considered when deciding between publishing simple event messages and document messages as events.

Request-reply messages could also use a bit more describing. A request-reply is usually implemented as two point-to-point channels. The first channel delivers the request as a command message, while the second carries the reply back to the requestor as a document message. To keep the replying component more loosely coupled and reusable, the requestor should include a return address indicating the channel that the replier should use to publish the reply. After receiving the reply, a challenge for the requestor is to then correlate the reply to the original request. If the requestor is sending a number of requests in succession, it will likely be difficult to keep clear – if it matters – which request a reply is associated with. To resolve this, every request may include a unique message identifier that the replier would then include as a correlation identifier. (A message could have both a message Id and a correlation Id.) The requestor uses the correlation identifier to “jog its memory” concerning which request the response is for. But frequently, a request-reply is in context of a particular domain object, such as a terrain map or a bank transaction; but the correlation Id doesn’t include such information. To assist, the requestor can maintain a mapping (e.g., hashtable) between message Ids and relevant domain object Ids which are related to the original request. When the reply is received, the mapping may be used to load the appropriate domain objects and take further action, accordingly.

Obviously, it is important that the senders and receivers of a message system agree upon the format that messages will take for clear interoperability, better reusability of components, and extensibility of the system. Consequently, a canonical data model should be well defined that all applications will adhere to. The canonical data model does not dictate how each application's domain model must be structured, only how each application must format data within messages. Message translators are developed to convert the sending application's domain model into the canonical data model before sending a message; receivers of messages then use their own message translators to translate the message into their own domain. This mechanism allows applications built on completely different technologies (e.g., C#, Lisp, and C++) to communicate with each other and exchange data. Many off the shelf messaging systems define their canonical data model which must be adhered to. For example, the Robot Operating System (ROS), which we'll looking at in more detail in subsequent posts, defines their canonical model at http://www.ros.org/wiki/msg. But the canonical data model need not be limited to defining the types of primitives available and how to include them in messages.

Domain-specific canonical data models may augment message formatting rules, adding semantic meaning to the data within a message. For example, the Joint Architecture For Unmanned Systems (JAUS) is a set of message guidelines for the domain of unmanned systems, such as autonomous vehicles. The JAUS guidelines provide domain specific rules for communicating data, such as propulsion and braking commands, sensor events, pose and location information, etc. To demonstrate, JAUS message types include (Siciliano, 2008):

Command: initiate mode changes or actions,
Query: used to solicit information from a component,
Inform: response to a query,
Event set up: passes parameters to set up an event, and
Event notification: sent when the event happens.

A challenge in dealing with canonical data models is how to handle changes to the model. In order to support backwards compatibility of existing components when the canonical data model changes, new message channels could be created to carry the messages adhering to the model; e.g., "Perception/LaserScans_V1" and "Perception/LaserScans_V2." Alternatively, the existing channels could continue to be leveraged to carry messages adhering to different version of the canonical data model. To do so, the message, within its header, would include a format indicator, such as a version number or format document (e.g., DTD) reference. But if a sender knows that receivers of a particular message are mixed in what format is being used, a component would need to send two messages, one for each version of the canonical data model. Certainly, this is an important consideration when deciding which components should (or even can) be upgraded to newer formats, and in what order.

Message Routers

While the heavy lifting of the message routing is handled by the messaging middleware itself, there are times when it is useful to augment the middleware with custom message routers to support unique scenarios.

Suppose the destination of a message may change based on the number of messages that have already passed over a channel. In this scenario, the sender of a message may not know how many messages have been passed over a channel since other senders may have been publishing messages on the same channel. Consequently, a message router may subscribe to the channel to determine where each message should be forwarded to, based on the described business rules. Once the destination is determined, the router would then place the message on a subsequent channel to be delivered to the appropriate destination. This intermediary routing is described as predictive routing as the message router is aware of every possible destination and the rules for routing, accordingly. If the routing is based on content within the message itself, such as threshold values, then the custom router is known as a content-based router.

A drawback to using message routers is that if the routing rules change frequently, the message router will need to be modified just as often. To help remedy this, if the rules are expected to change frequently, configurable routing rules (e.g., via XML) could be employed to enable easier management of routing rules.

Let's now consider another scenario wherein it's left up to the subscribers to determine which messages they're interested in; i.e., subscribers will be responsible for filtering out the messages they're uninterested in. In this reactive routing scenario, each subscriber would provide a respective message filter which is similar to a message router, but simply forwards, or does not forward, a message onto a subsequent channel that the destination subscriber is listening to. Frequently, message filters decide to forward, or not forward, based on content in the message itself; e.g., only forwarding orders that have a coupon included. While being similar to a message router in basic functionality, a message filter only has one possible channel to forward the message onto.

Deciding between predictive and reactive filtering must take into account a number of considerations. Is the message content sensitive? Do you need to minimize network traffic? Do you need to be able to add and remove subscribers easily? Is the predictive router becoming a bottleneck of message dissemination? For further guidance on selecting among routing options, see (Hohpe, 2003), ppg. 241-242.

Message Endpoints

Each messaging middleware option (e.g., CCR, ROS) has unique requirements for communicating with it. Each has its own API, its own means of addressing channels, and its own rules for packaging messages. Ideally, the components of the system should not be aware of the specifics of communicating with the messaging middleware. Furthermore, while unlikely to occur, the middleware should be able to be replaced with another, requiring little, if any, changes to the components. Accordingly, the components must be loosely coupled to the messaging middleware. Message endpoints provide the bridge between the domain of each component and the API of the messaging middleware.

Message endpoints are similar in nature to repositories when communicating with a database. Repositories encapsulate the code required to communicate with a database to store and retrieve data while being able to convert information from the database into domain objects. If the database changes, or if the mechanism for database communication changes (e.g., ADO.NET to NHibernate), then, ideally, only the repositories are affected. The rest of the application knows little about database communications outside of the repository interfaces. Likewise, components of a message-based system should not be aware of messaging details outside of the message endpoint interfaces, which provide the means to send and receive data. The message endpoint accepts a command or data, converts it into a message, and publishes it onto the correct channel. Additionally, the message endpoint receives messages from a channel, converts the content into the domain of the component, and passes the domain objects to the component for further action. Internally, the message endpoint implements a message mapper to convert between the component domain objects and the canonical data model.

While posting to a channel is rather straight forward, a message endpoint may receive a message by acting as a:

Polling Consumer: wherein the receiver looks at a channel on a regular basis for new messages and/or as soon as it completes the processing of a previous message. This frees the receiver from having to deal with messages as soon as they arrive on the channel in favor of dealing with messages went it’s ready and willing. A consideration to keep in mind is that messages may queue up on a channel while waiting to be retrieved by the polling consumer. Additionally, a polling consumer may take up threads and resources while polling a channel, even if the channel is empty.
Event-Driven Consumer: wherein the message is given to the receiver as soon as it arrives on the channel. The benefits to this include avoiding messages queuing up while being able to process messages asynchronously. But the receiver is no longer in control of the timing in which it processes messages and must handle messages as soon as they arrive on a channel.

Many messaging middleware solutions include support for transactions that the message endpoints may leverage, making the endpoints transactional clients. To illustrate the need for this, suppose the receiver of a request-reply command crashes just moments after the command message is consumed and removed from the channel. When it recovers, the command message is lost and the sender will never receive a reply. Using a transaction, the command message is not removed from the channel until the response is completed and sent. Committing the transaction removes the command message from the channel and adds the reply document message to the reply channel.

There are a few recommendations which should be considered when developing message endpoints. In accordance with the SRP, message endpoints should be able to receive messages or send messages, but not both in the same message endpoint. Furthermore, a message endpoint should only communicate with one message channel. If a component needs to send a message on separate channels, it would leverage multiple message endpoints to do so. If your components are developed in line with DDD, it would be each component's application services layer which would communicate with the message endpoints, preferably via their interfaces instead of concrete instances. This facilitates swapping out the message endpoints with mock objects for unit testing. Leveraging separated interfaces and dependency injection helps enable this approach. While these guidelines introduce more objects and indirection, they are proven practices for increasing maintainability of the component and reusability of the message endpoints.

Performance of Message Based Systems

One would likely be quick to assume that developing a message-based system has a huge cost to performance. Domain objects are converted to messages, messages are passed over channels, routers and filters intercept and forward messages, and messages are converted back into domain objects...this sounds like a heck of a lot going on. But because each component executes in its own thread or process, they need not wait for other components to complete their job before being able to move on to handling another message or task.

In the figure above (adapted from Hohpe, 2003, pg. 73), note that a sequential process requires that each message life cycle is completed in full before moving on to the next message. But in an asynchronous, message-based system, each component can move onto a subsequent message just as soon as it has completed its part in the last one. This greatly compensates for the extra overhead imparted by the messaging infrastructure.

With that said, there are some component responsibilities which take a long time to complete and may impede the speed by which messages are processed. For example, imagine a component which takes images from a web cam and extracts information such as human figures or road signs. This is likely a time consuming process and would impact the turn around time in which the component could process subsequent messages. To alleviate this bottleneck, multiple instances of the same component may subscribe to the same point-to-point channel. Recall that a point-to-point channel ensures that each message only has a single receiver. The instances of the component then become competing consumers of each message. So if one instance of the component is still processing an earlier message, another instance can grab the next message that arrives for concurrent processing. Power in numbers!

Monitoring and Debugging

Due to the widely asynchronous nature of message-based systems, attention must be given to monitoring and debugging techniques to observe system behavior and iron out problems.

Logging message content is an invaluable measure towards getting a clear look at what communications are taking place. To facilitate this, logging could be added directly into sending and receiving components, but logging message content should not be a concern of components; accordingly, using a monitoring utility to log such information is a cleaner separation of concerns. Certainly a benefit of publish-subscribe channels is that a monitoring component may subscribe to all messages and log the information to a file or console window. While it’s just as valuable to monitor messages on point-to-point channels, if a monitor were to consume a message over a point-to-point channel, the message would be noted as consumed and would no longer be available to the intended receiver. Because such monitoring capability is so helpful in developing and debugging, many messaging middleware options include a "peek" option which allows a monitoring utility to review message contents on a point-to-point channel without actually consuming the message. This capability should be taken into consideration when comparing messaging middleware alternatives.

In addition to monitoring message content sent over channels, it’s also assistive to monitor active subscriptions to various channels to accurately determine which components are receiving which messages. This capability is typically built into messaging middleware solutions and is very assistive during development.

It’s possible that even if a message is routed appropriately, the receiving component may not know what to do with the message due to an incorrectly formatted header or body content. Invalid messages such as this should be forwarded to an invalid message channel which an error logging utility would monitor and log, accordingly. An invalid message channel is setup just like any other channel but with the intention of exposing such messages for debugging purposes.

Closing Thoughts

Developing asynchronous, message-based systems requires a paradigm shift from the more traditional, synchronously executed applications that most people are familiar with. It is not appropriate for every application domain and should be seen as one additional architectural option to consider when developing applications. But in some domains, such as robotics or in the integration of disparate applications, this approach to development is absolutely pivotal in providing responsive behavior without sacrificing maintainability of the overall system. Indeed, by splitting responsibilities into discrete components, loosely coupled to each other via messaging middleware, immensely complex problems can be broken down into understandable chunks while being flexible enough to accommodate changes to the underlying middleware or introduction of new components.

In the next couple of posts, we'll look at a checklist for developing message-based systems followed with examples in CCR and ROS.

Enjoy!

Billy McCafferty
http://wiki.sharparchitecture.net

P.S., for S#arp fans, we're trying to get another release together for the coming week...and this ain't no quarterly release. ;)

References

Hohpe, G., Woolf, B. 2003. Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions.

Siciliano, B., Khatib, O. 2008. Springer Handbook of Robotics.

Architectural Paradigms of Robotic Control

Billy McCafferty — Wed, 03 Feb 2010 22:39:00 GMT

Introducing a New Blog Series

Rarely do I make new year's resolution. But I found myself pinky swearing myself a single resolution for this year: write a series of tractable posts concerning the development of software for robotics. Accordingly, I intend to introduce background, techniques, and examples with respect to the following topics and more:

Software Architectural Approaches for Robotics (e.g., Deliberative, Reactive, Hybrid)
Software Design Methodologies (e.g., for Behavior Based Robotics, for Hierarchical)
Integration Patterns (Message Channels, Publish/Subscriber, RPC)
Machine Learning and Adaptation Techniques (Neural Nets, Genetic Algorithms, Fuzzy Logic)
Planning Algorithms (Discrete Planning, Continuous Spaces, Motion Planning)
Simultaneous Localization and Mapping Techniques (Kalman Filters, Particle Filters)
Tools & Frameworks (Microsoft Robotics Studio, Robot Operating System)

I'm writing this series of posts for two reasons. The first, as always, is to bounce ideas off readers as a sanity check. The second is to instill interest in readers in this rapidly evolving field. The sophistication of software algorithms within robotics is beginning to lag behind the potential capabilities of available hardware. Accordingly, if this series acts as motivational tool to get others involved in tackling the current algorithmic challenges involved in robotics, then all the better.

To make this series more interesting and applicable to the development audience that reads http://devlicio.us, I will attempt, when appropriate, to focus on patterns and general techniques that could possibly be applicable to scenarios outside of robotics. Additionally, due to this series' focus on software, I'll concentrate on leveraging simulators over physical, often expensive, robotics hardware to make it easier for readers to duplicate provided examples.

Enjoy!

Introduction to Architectural Paradigms of Robotic Control

While "architecture" is likely one of the least definable terms in software development, it is unavoidably a topic which has one of the greatest impacts on the extensibility and maintainability of an application. Indeed, a frequent cause of an application re-write is due to the architectural decisions that were made early in the project, or the lack thereof. Certainly one of the difficulties in instituting proper architectural practices in a project lies in the fact that architectural decisions must carefully be decided at many different levels of project development. Obviously, the architectural decisions at each level should be made in context of the project requirements in order to facilitate a proper balance of speed of development, scalability of development, and maintainability of the application in the future.

To illustrate, consider a basic eCommerce site vs. a corporate financial management application which integrates with various third party tools. There are two aspects of architecture which must be carefully considered. The first is deciding which project contexts will require architectural consideration. The second is defining the architectural approach to meet the needs of the given project context, and implementing any necessary prefactoring, accordingly.

For a basic eCommerce site, the project contexts requiring architectural consideration would likely include: appropriate separation between presentation and control, separation between control and the domain, separation between the domain and data access, and appropriate integration with a payment gateway. Perhaps the active record pattern might be chosen as the data access mechanism. If inversion of control seems overkill for such a small application, perhaps direct communications to the payment gateway via the domain objects might be chosen as the means of integration. Accordingly, judicious prefactoring would suggest that an architectural spike be created demonstrating appropriate use of the active record pattern with a selected tool along with an example of how and where integration with the payment gateway would take place.

For the more complex and demanding needs of the financial management application, architecture considerations, in addition to those taken into account for the basic eCommerce site, might include: what integration patterns might be leveraged to facilitate client integration, messaging patterns that might facilitate server side integration with third party financial calculators, and where inversion of control is appropriate. Perhaps RESTful services would be included to provide integration support for clients requiring such capabilities. Messaging via a publish/subscribe mechanism using a composed message processor might be selected as the ideal means for coordinating data with third party vendors on the server side. Again, proper refactoring, from an architectural perspective would include developing architectural spikes along with the foundational pieces of such an application to provide appropriate guidance for developers assisting with the project.

Developing software for robotics is no different, in this respect, than developing any other application. One must decide where the key architectural decisions need to be made and then provide adequate decisions and guidance to facilitate development in accordance with those decisions. As stated, these decisions must be made in consideration of the project needs. This post focuses on one project context, the architectural context of determining the overall approach to robotic motor control. We'll delve into three major architectural approaches to motor control along with highlighting a few specific implementations.

Deliberative vs. Reactive Robotics

Certainly the best source of intelligent systems to study and emulate are those found in nature. From the humble ant to the exalted human, evolution has honed a variety of strategies for dealing with the physical world. Accordingly, if we are to create intelligent systems, a good place to start is by emulating the behaviors and responses to stimuli demonstrated by living creatures.

In the early days of robotics, it was presumed that the most effective approach to emulating intelligence was by taking in detailed measurements provided by sensors, creating an internal representation of the world (e.g., grid-based maps), making plans based on that internal representation, and sending pre-planned commands to actuators (devices which convert energy into motion) for moving and interacting with the world. Inevitable, this approach presumes that the internal representation of the world is highly accurate, that the sensor reading are precise, and that there is enough time to carry out a plan before the world changes. In other words, this approach is highly deliberative. Obviously, the world is highly dynamic, sensor readings are sometimes erroneous, and time is sometimes of the essence when interacting with the world. E.g., you probably wouldn't want to spend much time creating an internal representation of the world if there's a Mac truck speeding towards you.

At the other extreme from deliberative is a reactive approach to interacting with the world. Taking a purely reactive approach does away with plans and internal representations of the world altogether; instead, a reactive approach focuses on using the world as its own model and reacts, accordingly. Instead of plans, reactive approaches often rely upon finite state machines to modify behavior as the world changes. Rodney Brooks changed robotics thinking upside down when he introduced this paradigm shift in the 80s. The robots he and his team produced were much faster in their reaction times, when compared to deliberative robots, and exhibited surprisingly complex behavior, appearing quite intelligent in many scenarios. But as is any extreme, a purely reactive approach to the world had it's own drawbacks; its difficulty in managing complex scenarios which demand careful planning is one such example.

The figure at right illustrates some of the differences between deliberative and reactive systems. Adapted from (Arkin, 1998).

While there are certainly pros and cons to either approach, there are some scenarios which are appropriate to one or the other. While still others may require more of a hybrid approach. Let's now take a look at each approach in more detail.

Deliberative/Hierarchical Style

One of the first successful architectural implementations on a mobile robotic platform was the well known robot known as Shakey, created at Stanford University in the 1960s. Of particular note was the robot's architecture which was made up of three predominant layers: a sensing layer, a planning layer, and an execution layer. Accordingly, as information would be made available by sensors, Shakey would make plans on how to react to the perceived world and send those plans on to the execution layer for low level control of actuators. This began the architectural paradigm known as sense-plan-act (SPA). As the SPA approach matured, additional layers were introduced in a hierarchical style, typically all of which having access to a global world model. The upper layers in the hierarchy would use the world model to make plans reaching into the future. After plan development completed at the highest levels, the plans would be broken down into smaller commands and passed to lower levels for execution. Lower layers would then further decompose the commands into more actionable tasks which would ultimately be passed on to actuators at the lowest level. In a hierarchical approach, the sensing layers participate in keeping the internal representation of the world updated. Furthermore, to better accommodate dynamic changes to the world environment, lower planning layers may suggest changes to plans based on recent changes to the world model.

The diagram at right roughly illustrates this hierarchical architectural approach. As should be noted, the sensing layers update the world model while a hierarchy of planning and execution layers formulate plans and breaks those plans down into actionable tasks. Adapted from (Kortenkamp, 1998).

4D/RCS

The current pinnacle of hierarchical architectures may be found in the reference architecture known as 4D/RCS (4 Dimensional / Real-time Control System). 4D/RCS is the latest version of the RCS reference model architecture for intelligent systems that has been evolving for decades. With 4D/RCS, six (more or less) layers are defined for creating and decomposing plans into low level action:

Unit/Vehicle/Mission Layer: this layer decomposes the overall plan into actions for individual modules. Plans are regenerated every 2 hours to account for changes to the world model.
Module Layer: converts actions into tasks to be performed on specific objects and schedules the tasks, accordingly. Plans are regenerated every 10 minutes.
Task Layer: converts actions on a single object into sequences of moves to carry out the action. Plans are regenerated every minute.
Elemental Layer: creates plans for each move, avoiding obstacles and collisions. Plans are regenerated every 5 seconds.
Primitive Layer: determines motion primitives (speed, trajectory) to facilitate smooth movement. Plans are regenerated every 0.5 second.
Servo Layer: sends servo control commands (velocity, force) to actuators. Plans are regenerated every 0.05 seconds.

At the heart of each and every layer are one or more 4D/RCS nodes which contain a behavior generation process which accepts commands from the next higher level and issues subgoals to the behavior generation process at lower levels. Furthermore, each node reports its task execution status up the chain for consideration into further planning. While plans are being solidified and disseminated, a sensory processing process in each node receives sensory input from lower levels, updates the world model, and collates the sensory data into larger units which it passes on to the next higher level; e.g., points get converted to lines which get converted to surfaces which get converted to objects with each successive rise through the 4D/RCS layers A visual summary of a 4D/RCS node quickly shows just how complex such a system can become. But sometimes the demands of a task require a respective amount of sophistication in the architectural approach. A comprehensive review of the 4D/RCS approach is discussed in (Albus, 2006).

The primary advantage to deliberative, hierarchical approaches such as 4D/RCS is that competent plans for managing complex scenarios can be generated and broken down into smaller chunks for lower levels to execute. But an obvious disadvantage to this comes in the form of much added complexity to the overall system while penalizing the speed at which the system can react to a changing environment.

Reactive Style

In the 1980s, Rodney Brooks, in an effort to overcome some of the limitations of sense-plan-act that Shakey and other such robots exhibited, introduced the concept of reactive control. "Simply put, reactive control is a technique for tightly coupling perception and action, typically in the context of motor behaviors, to produce timely robotic response in dynamic and unstructured worlds." (Arkin, 1998). In other words, by eliminating the reliance on maintaining an internal world model and avoiding large amounts of time generating plans, simple responses can be executed in reaction to specific stimuli, thus exhibiting behavior similar to that of living organisms. If there was any doubt in what Brooks was trying to imply, he boldly titled one of his works, Planning is Just a Way of Avoiding Figuring Out What to do Next. This paradigm shift away from planning turned sense-plan-act into a simpler sense-act.

Accordingly, in a sense-act paradigm, the primary focus is in carefully defining behaviors and the environment stimulus which should invoke those behaviors. This focus is deeply rooted in the idea of behaviorism; from a behaviorism perspective, behavior is defined in terms of stimulus and response by observing what an organism does. This approach of developing robotics around such behaviors, unsurprisingly enough, is commonly referred to as Behavior Based Robotics. By leveraging simple state machines, which we'll examine below, to define which behaviors are active for a given stimuli, the overall architectural complexity is greatly reduced while giving rise to responsive, seemingly intelligent behaviors. (The question of whether or not the robot is truly intelligent and/or self-aware is a debate that I'll leave to others such as Searle and Dennett.) While the reactive approach took the spotlight for a number of years, and is still very appropriate in some cases, its limitations in managing complex scenarios and performing sophisticated planning indicated that this approach was not the end all panacea for all situations.

The diagram at right clarifies that reactive systems remove planning and deal with sensory input within the context of each behavior. I.e., "Behavior 1" has no knowledge of the feedback coming from "Sensor 3." Adapted from (Kortenkamp, 1998).

A Design Methodology for Reactive Systems

Due to the simplistic nature of reactive systems, the corresponding design methodology for developing such systems is rather straight-forward (Kortenkamp, 1998):

Choose the tasks to be performed. E.g., find kitchen.
Break down the tasks in terms of specific motor-behaviors necessary to accomplish each task. E.g., find wall, follow wall, recognize kitchen.
For each action, find a condition under which each action should be taken. E.g., wall found.
For each condition, find a set of perceptual measurements that are sufficient to determine the truth of the condition. E.g., long straight line connected to obstacle.
For each measurement, design a custom sensory process to compute it. E.g., bumper sensor activated, edge length over threshold found.

When implemented, we find that the defined behaviors can be realized as states within a finite state machine and that found conditions act as the mechanism for changing from one behavior state to another. What's missing is an arbitration mechanism to determine which behavior wins out in light of competing conditions. Let's briefly look at implementation approaches to reactive systems along with how such arbitration is achieved.

Subsumption & Motor Schemas

A key concern with reactive, behavior based robotics is determining which behavior should take precedence if conditions exist to activate two or more behaviors. An arbitration mechanism needs to be introduced to resolve such competing situation. Brooks dealt with this issue by proposing an architecture known as subsumption. Simply enough, a subsumption architecture still uses a finite state machine to codify behaviors and transitions, but introduces behavioral layers which can provide input to other layers and override behaviors of lower layers. The advantage is in facilitating more sophisticated behaviors as a sum of "lesser" behaviors. It's better understood by reviewing the following example from (Arkin, 1998):

In the example, there are three behavioral layers: Avoid-Objects, Explore, and Back-Out-of-Tight-Situations. The Avoid-Objects Layer's responsibility is to avoid objects by moving away from any perceived obstacles. The Explore Layer's responsibility is to cover large areas of space in the absence of obstacles. The highest level assists the robot in getting out of tight spaces if the lower layers are unable to do so. Each discrete behavior can invoke transitions to other behaviors and/or provide input or advice to subsequent behaviors based on perceived conditions. The "trick" of subsumption is that higher levels can suppress commands between lower level behaviors; consequently, higher layers are able to handle more complex scenarios by manipulating lower level behaviors in addition to its own. To illustrate suppression, note, in the above example that the "Reverse" behavior in the Back-Out-of-Tight-Situations Layer suppresses any commands that the "Forward" behavior is sending to the actuators. By doing so, complex behaviors may emerge using a number of basic behaviors and a relatively simple architectural approach.

A major challenge in using a subsumption architecture is deciding the appropriate hierarchy of behavioral layers. In more complex scenarios, it quickly gets sticky deciding which layer should have the right to suppress which other layers. (Otherwise known as spaghetti-prone.) Additionally, since the layers have bi-directional dependencies amongst each other, in order to provide input and suppression, changes to layers can have large impacts on other layers, often resulting in shotgun surgery with any change. Ronald Arkin introduced a subsequent architecture to address these, and other concerns, with an approach known as Motor-Schema based control which does away with arbitrating competing behaviors. Each active behavior in a Motor-Schema based control system calculates a vector to be carried out by an actuator (e.g., wheels or arm). Using vector addition, a final vector for each actuator is computed and sent for execution. With this approach, the output of behaviors is combined instead of arbitrated. This avoids the need to determine suppression hierarchies and makes a more extensible application, within the limits of behavior based robotics.

Hybrid Style

Most modern architectural approaches to robotics control attempt to combine the planning capabilities of deliberative systems with the responsiveness of reactive systems. Appropriately enough, this is referred to as a hybrid style. While the deliberative approach takes a sense-plan-act perspective and the reactive approach follows with plan-act, a hybrid approach typically takes the form of plan, sense-act. So while the sense-act layers carry out behaviors, the deliberative planning layer can observe the progress of reactive behaviors and suggest direction based on reasoning, planning and problem-solving. The diagram at right crudely demonstrates this combination of the two approaches. Adapted from (Kortenkamp, 1998).

Three-Layer Architecture (3T)

James Firby's thesis proposing Reactive Action Packages (RAPs) (Firby, 1989) provided a solid approach for integrating deliberative planning with reactive behaviors in the form of a three layer architecture. A multitude of subsequent architectures have emulated a similar approach, coming to be known as 3T architecture. From Eran Gat's essay Three Layer Architecture (Kortenkamp, 1998):

Three-layer architectures organize algorithms according to whether they contain no state, contain state reflecting memories about the past, or contain state reflecting predictions about the future. Stateless sensor-based algorithms inhabit the control component. Algorithms that contain memory about the past inhabit the sequencer. Algorithms that make predictions about the future inhabit the deliberator. ... In 3T the components are called the skill layer, the sequencing layer, and the planning [deliberative] layer.

As implied by being a hybrid approach, this 3T architecture is not mutually exclusive to behavior driven robotics. Indeed, the skill layer itself is made up of unique behaviors which resemble that of reactive systems. The sequencing layer then uses the world model to determine when a change in behavior is required. The planning layer can then monitor the lower layers and perform more deliberative, time consuming processes such as path planning. The primary variation amongst 3T implementations lies in the decision between whether the planning layer "runs the show" or if the sequencing layer takes command and invokes the planning layer only when needed. Atlantis is one such example that leaves primary control to the sequencing layer to invoke the planning layer. Other examples of 3T implementations include Bonasso's Integrating Reaction Plans and Layered Competences through Synchronous Control and Standford's Junior which took 2nd place in Darpa's Urban Challenge.

Wrapping Up

The intention of this article has been to provide an introductory overview of paradigms of robotic control including deliberative/hierarchical systems, reactive systems, and hybrid systems. While each approach is appropriate in select contexts, a hybrid architecture is very adaptable for accommodating a large variety of robotic control scenarios with sufficient planning and reactive capabilities. The interested reader is encouraged to dig further into the references and links provided to learn more about these various approaches and design methodologies for implementation.

In the next post, we will examine messaging strategies to facilitate the communications amongst the layers and components of robotic systems.

References

Albus, J., Madhavan, R., Messina, E. 2006. Intelligent Vehicle Systems: A 4D/RCS Approach.

Arkin, R. 1998. Behavior Based Robotics.

Firby, J. 1989. Adaptive Execution in Complex Dynamic Worlds.

Kortenkamp, D., Bonasso, R., Murphy, R. 1998. Artificial Intelligence and Mobile Robots.

Dependency Injection 101

Billy McCafferty — Mon, 09 Nov 2009 22:26:00 GMT

(It looks like Kevin Pang and I must have seen the same vision this weekend or had a close encounter flashback as he's concurrently putting together a great series on Dependency Injection for Dummies...be sure to check out his posts for another take on this subject!)

Simply put, dependency injection is the technique of supplying an object with its service dependency(s) from an external source.

If you’re unfamiliar with dependency injection or just starting down the road of object oriented programming, the above statement might have the same effect as a mathematics book when the author puts forth a new equation that is about to be analyzed. Symptoms may include glassy eyes, nausea, and headaches. But when taken apart, we find that the idea of dependency injection is a much simpler concept than its grandiose title implies, and is a technique that many developers use commonly, quite naturally in many cases, without even knowing it.

Encapsulation

The place to start, in understanding the motivations and implementation of dependency injection, is with the basic idea of encapsulation. Crudely explained, encapsulation is the art of determining which bits of logic belong together and putting them into discrete objects. This allows the details of the logic to be modified within the encapsulated object without necessarily impacting the objects which use it. Furthermore, encapsulation provides a neat and clean way to package up reusable code to be used by many other objects without introducing code duplication.

From a real-world perspective, encapsulation is a very useful technique when building a self-aware robot to take over the world. When building any self-aware robot, you need to start with the basics, such as mobility and sensory perception. For example, a robot might have a stereo camera for observing the visible world, sonar sensors for detecting nearby objects around it, and touch sensors to know if it has made contact with the object it’s trying to pick up. Just by describing it, we’re already starting to imply areas of logic that could be nicely encapsulated: visual perception, sonar object detection, touch feedback, and mobility.

Assume for a moment that we’ll bypass the practice of encapsulation and throw all of the code for these various modules directly into the primary method which uses them, a benign method we’ll call TakeOverTheWorld, living in a .NET assembly called CommandAndControl.dll. The code might look something like the following:

public class WorldDomination {
   public void TakeOverTheWorld() {
      // Code to open USB connection to use stereo camera
      // Code to process camera images to identify humans

      // Code to open serial port to legs for moving
      // Code to send legs serial commands to move over to location of human

      // Code to generate speech to user; e.g., "All your leaders are belong to us"
   }
}

In the code, we see the TakeOverTheWorld method taking on a lot of responsibilities and given explicit knowledge about components which are subject to change when the robot components are upgraded. Some of the responsibilities which we’re burdening the method with include:

Knowing the stereo camera is connected via USB and how to open a connection to it;
Knowing how to process camera images to identify humans;
Knowing that the legs require communications to be sent via a specific serial port;
Knowing how to send low level communications to the legs as serial commands.

So what’s the problem you ask? For starters, the TakeOverTheWorld method would likely be a few thousand lines long and would be immensely difficult to maintain. Let’s suppose that we upgrade the camera to use a better stereo imaging device which now receives commands wirelessly. You’d have to carefully, tediously walk through all of the lines of TakeOverTheWorld to find any communications with the camera, upgrade the capabilities, and test, accordingly. But now testing is much more challenging as well. Since all of the other code, such as the mobility code, will also run whenever we invoke TakeOverTheWorld, then we’ll need to make sure that the rest of the robot is in perfect working order while we switch out one component. In other words, it’s simply not possible now to test the various components in isolation of each other. This approach quickly turns into spaghetti code, becoming a maintenance nightmare, difficult to debug, and exhibiting decreasing code quality as time progresses. What started out as a simple project to develop a robot to conquer the world is turning out to be about as effective as C-3PO…after being blasted by a storm trooper that is.

The first step that we can take, to make our robot for world domination a little easier to understand and maintain, is to encapsulate the various modules into their own, respective classes. Let’s look at the TakeOverTheWorld code again with a sprinkling of better encapsulation by moving the camera related responsibilities to a class called StereoCamera.cs and the mobility related responsibilities to MobilePlatform.cs. Furthermore, let’s move these two classes to a new class library assembly called Services.dll.

// Within the Services package (or class library)

public class StereoCamera {
   public void Connect() {
      // Code to open USB connection to use stereo camera
   }

   public MeaslyHuman IdentifyHumanInFieldOfVision() {
      // Code to process camera images to identify humans
   }
}

public class MobilePlatform {
   public void Connect() {
      // Code to open serial port to legs for moving
   }

   public void MoveTo(Location location) {
      // Code to send legs serial commands to move over to location 
   }
}

// Within the CommandAndControl package

public class WorldDomination {
   public void TakeOverTheWorld() {
      StereoCamera camera = new StereoCamera();
      camera.Open();
      MeaslyHuman human = camera.IdentifyHumanInFieldOfVision();

      MobilePlatform legs = new MobilePlatform();
      legs.Connect();
      legs.MoveTo(human.Location);

      // Code to generate speech to user; e.g., “All your leaders are belong to us”
   }
}

As demonstrated, we introduced two new classes, StereoCamera and MobilePlatform, and moved the related responsibilities to those classes. We also introduced a new package as a new class library, called Services.dll, to contain the two new classes. The package diagram now looks as the figure shown to the right.

This basic refactoring has resulted in a number of benefits:

There are far fewer lines of code in the TakeOverTheWorld method and easier to digest for whomever may be looking at it next;
The TakeOverTheWorld method is now much easier to understand the overall flow of control without getting bogged down in low level details;
The TakeOverTheWorld method now knows nothing about the details related to connecting to the camera via the USB connection (other than simply calling Connect), nothing about the mathematics behind processing camera images to identify humans, nor the details of opening a serial port and sending low level serial commands to move from point A to point B; and
The StereoCamera and MobilePlatform classes are now quite reusable from a variety of other objects that will surely need to use them.

Overall, this encapsulation refactoring has led to a design that is easier to maintain and will likely reflect in the general level of maintainability and quality. So things are better, but we still have much to improve. I suppose we’re beginning to resemble C-3PO, but only after Chewbacca put his head on backwards. (OK, so C-3PO didn’t have diabolical plans for world dominion, but let’s ignore that subtlety for now.) As we proceed, we’ll examine what other areas we’ll want to improve and learn a bit more about the definition of dependency injection along the way.

Services

Earlier, we defined dependency injection as the technique of supplying an object with its service dependency(s)… What exactly is a service dependency? A service, in the context of dependency injection, is any object which provides access to an external resource. In the refactoring exercise we performed on our code, and as implied by the package diagram, two services were introduced. The first provided access to the stereo camera; the second provided access to the legs for moving the robot around. In your own project, services may include web services, data access objects, file manipulation utilities, third party APIs, and many others.

Because services depend on external resources (e.g., a physical component or database), they are inherently more complicated to test, require that the external resource be available when we test our code, and are subject to change when the underlying resource being managed changes (e.g., when the component is upgraded). When considering these arguments, we want to remain loosely coupled to the services themselves. To contrast, the refactored code above, even after applying encapsulation, is tightly coupled to the underlying services.

To illustrate the idea of tight coupling, the TakeOverTheWorld method is creating each service directly with the new keyword; i.e., the method is creating a concrete instance of the service class. Not only does the method have a concrete dependency on the service class itself, this inherently implies that the application layer that the WorldDomination class resides in must have a direct dependency on the layer which the StereoCamera service class resides in. This layer dependency is shown as a directional line in the above package diagram from the CommandAndControl layer to the Services layer.

In addition to having a concrete dependency on the service itself, the TakeOverTheWorld method must also know to call Open for the respective services (and presumably Close); i.e., the TakeOverTheWorld method needs to know how to create and initialize the services before it’s even able to use them. These are further responsibilities which this method should not be concerned with.

Ideally, the TakeOverTheWorld method would be loosely coupled to the underlying services and wouldn’t have to know about such low level details of the service itself outside of calling methods such as IdentifyHumanInFieldOfVision.

Coding to Interface

The first step we can take towards making TakeOverTheWorld less tightly coupled to the service classes is to have the TakeOverTheWorld method code to the interfaces of the services rather than to the concrete classes themselves. One might argue against introducing two new interfaces for the objects; as we add new objects, we inherently introduce additional complexity to the overall system. Also, with interfaces, not only are we introducing a small amount of additional complexity to the overall system, but we’re also introducing indirection. In other words, in order for someone to fully understand what’s going on at runtime, the developer will need to determine which concrete object is being used under the interface. It shouldn’t be difficult to do so, but it does add time to understanding the overall system. These are fair arguments and ones not to be ignored. Whenever we are faced with a decision that will lead to a better design at the expense of added complexity, we carefully need to consider if the benefits of refactoring outweigh the penalties of added complexity. In this case, coding to interface (and another refactoring we will do next) will lead to a more maintainable system, provide a means to readily unit test the various components in isolation, and will result in a more loosely coupled design.

Accordingly, we simply need to add two interfaces to the Services package, have the service classes implement them, and change the references in the TakeOverTheWorld method to invoke the interfaces rather than the classes themselves. But as we’ll see, this next refactoring still leaves us tightly coupled to the service classes. Let’s look at the code.

// Within the Services package

public interface IStereoCamera {
   void Connect();
   MeaslyHuman IdentifyHumanInFieldOfVision();
}

public interface IMobilePlatform {
   void Connect();
   void MoveTo(Location location);
}

public class StereoCamera : IStereoCamera {
   public void Connect() {
      // Code to open USB connection to use stereo camera
   }

   public MeaslyHuman IdentifyHumanInFieldOfVision() {
      // Code to process camera images to identify humans
   }
}

public class MobilePlatform : IMobilePlatform {
   public void Connect() {
      // Code to open serial port to legs for moving
   }

   public void MoveTo(Location location) {
      // Code to send legs serial commands to move over to location 
   }
}

// Within the CommandAndControl package

public class WorldDomination {
   public WorldDomination() {
      camera = new StereoCamera();
      legs = new MobilePlatform();
   }

   public void TakeOverTheWorld() {
      camera.Open();
      MeaslyHuman human = camera.IdentifyHumanInFieldOfVision();

      legs.Connect();
      legs.MoveTo(human.Location);

      // Code to generate speech to user; e.g., “All your leaders are belong to us”
   }

   private readonly IStereoCamera camera;
   private readonly IMobilePlatform legs;
}

In the code above, note that the two interfaces were introduced and now the constructor of the WorldDomination class now handles creating the service instances and setting private members, represented as interfaces, to the service instances. The package diagram reflecting this refactoring is shown at right.

Even though the TakeOverTheWorld method is now communicating with the interfaces of the services, the class containing is still tightly coupled to the service classes due to the local instantiation of the classes within its constructor. To further alleviate this coupling, we’re going to have to move a step “up” and introduce a package which will be responsible for creating the service dependencies and injecting them into the WorldDomination class. Yes, we’re finally ready to see dependency injection in action.

Service Initialization and Injection

While the previous refactorings have taken us closer towards a more loosely coupled design, we still need to remove the object creation from the WorldDomination class altogether. By introducing a new package which will contain the robot system’s “main” program, we can leverage that layer to also initialize the service dependencies and inject them into the WorldDomination class. Let’s look at the code of the new package, called Robot, along with modifications to the WorldDomination class. (The Services package, and the interfaces and classes therein, will remain unchanged.) But before looking at the code, study the package diagram at right to see where the classes live and take particular note of the direction of package dependencies. There’s one dependency that’s still problematic, which we’ll discuss after the code.

// Within the CommandAndControl package

public class WorldDomination {
   public WorldDomination(IStereoCamera camera, IMobilePlatform legs) {
      this.camera = camera;
      this.legs = legs;
   }

   public void TakeOverTheWorld() {
      // Same as before
   }

   private readonly IStereoCamera camera;
   private readonly IMobilePlatform legs;
}

// Within the new Robot package

public class Program {
   // This is the “main” method of the entire robot application.
   // I.e., it’s the method that gets called to kick off the application.
   public void Main() {
      IStereoCamera camera = new StereoCamera();
      IMobilePlatform legs = new MobilePlatform();

      WorldDomination worldDomination = new WorldDomination(camera, legs);

      worldDomination.TakeOverTheWorld();
   }
}

In the code above, the Main method initializes the services and “injects” them into the constructor of the WorldDomination class. As you can see, the injection of service dependencies into a class is really nothing more than passing the service instances as arguments to the class instantiation. So when it comes right down to it, the intimidating phrase “dependency injection” is really quite simple in practice. But there’s still a problem in our implementation that could lead to design “rot” over time. The CommandAndControl package still has a dependency on the Services package. This is bad because during later phases of the project, without a high level of discipline, developers may forego injecting the service dependencies into the WorldDomination class, or other classes in the CommandAndControl package and simply instantiate the service classes directly using the new keyword. This would make all the work we’ve done to this point to support dependency injection a moot point. To enforce our design, we need to introduce a new pattern known as dependency inversion, also known as separated interface.

Separated Interface

To enforce our design, and to eliminate the package dependency from CommandAndControl to Services, we will move the service interfaces to the CommandAndControl package and reverse, or invert, the dependency direction between the two packages. Accordingly, the refactoring steps to do this include:

Copy the service interfaces from the Services package to the CommandAndControl package.
Change the interface references in the WorldDomination class to refer to the interfaces now found within the CommandAndControl package.
Remove the package dependency from CommandAndControl to Services. Now add a package dependency from Services to CommandAndControl. (In C#, this would be a matter of deleting the assembly reference from the CommandAndControl class library and adding a new assembly reference from the Services class library.)
Modify the service classes, StereoCamera and MobilePlatform, to implement the interfaces now found in the CommandAndControl package.
Modify the Main method, in the Main class to use the interfaces found within the CommandAndControl class.
Delete the obsolete interfaces from the Services package.

With the separated interface pattern implemented, the CommandAndControl package is only aware of the service interfaces without having any dependency, whatsoever, on the service implementations. As performed in the previous refactoring, the CommandAndControl package, the WorldDomination class specifically, is being given its service dependencies via constructor injection via initialization code found in the Robot’s main method.

With this, we have implemented a basic example, including all the required pieces, for performing dependency injection. It introduced a number of new pieces to the overall application, but our design is now loosely coupled to the underlying services and enables us easily swap out services with new implementations, without having to recompile the CommandAndControl package, and provides the ability for test doubles, such as mocks, stubs, and fakes, to be injected into the WorldDomination class when unit testing. (Unit testing with test doubles is beyond the scope of this article, but I encourage you to read http://xunitpatterns.com/Test%20Double.html to begin learning more about this subject.)

Dependency Injection / Inversion of Control (IoC) Containers

There’s one final topic which is appropriate to discuss when describing dependency injection: IoC containers. (Dependency injection is also known as “Inversion of Control,” as originally described by Robert Martin. Interestingly enough, the development community typically uses the phrase “dependency injection” when talking about the technique itself and “IoC” when talking about dependency injection containers. But rest assured, there is no difference whatsoever between “Dependency Injection” and “Inversion of Control (IoC).”) An IoC Container is a utility which is leveraged to initialize and inject dependencies into the objects that use them. While it is a bit more difficult to visualize than the “manual” dependency injection we performed in the previous refactoring step, an IoC Container is nothing more than an object factory which initializes an object and satisfies its service dependencies in the process.

With most IoC Containers (e.g., Ninject, Castle Windsor, LinFu, and many others), there are only a couple of steps required to setup and use the IoC Container:

Register all of the classes which may be injected into another object. In our carefree efforts for world domination via our robot, this would include, at minimum, registering the service classes MobilePlatform and StereoCamera. While each IoC Container has its own means of registering a class for later retrieval, the underlying mechanism is often as simple as adding the service class’ object type to a hashtable for later lookup. If we were using Castle Windsor with our project, the registration lines would look like the following:
```
container.AddComponent("camera", 
   typeof(IStereoCamera), typeof(StereoCamera));
container.AddComponent("mobilePlatform", 
   typeof(IMobilePlatform), typeof(MobilePlatform));
container.AddComponent("camera", typeof(WorldDomination));
```
Note that the last line registers the WorldDomination class itself. In doing so, we can let the IoC Container take care of the work of instantiating it with its service dependencies already injected. We don’t have to hand off instantiation of this class to the IoC Container, but it provides a useful benefit. Suppose the WorldDomination class needs a third service dependency provided via its constructor somewhere down the road. If we aren’t using an IoC Container to manage its creation, we’d have to look for every place where the class is created, via the new keyword, and pass in the extra dependency. If we leave its creation to the IoC Container, then we simply add the new service interface parameter to its constructor and the IoC Container will take care of the rest, assuming you’ve registered the third dependency as well.
Invoke the IoC Container to instantiate a registered object with its dependencies already injected. For our project, the following demonstrates getting a handle to the WorldDomination class:
```
WorldDomination worldDomination = (WorldDomination) 
   ServiceLocator.Current.GetService(typeof(WorldDomination));
```
This line of code tells the IoC Container to return an instance of the requested class with its dependencies injected. This actually uses an IoC Container known as Common Service Locator. Since almost all IoC Containers do the same actions – registering and instantiating objects – the major IoC Container authors worked together to establish a common interface for all IoC Containers. In this way, you can register your objects with your favorite IoC Container and then register the IoC Container itself with the Common Service Locator. It’s enough to make your head spin, but leads to further decoupling to the IoC Container itself so that you can easily swap out one for another (e.g., Castle Windsor for Ninject) without modifying the code which depends on the IoC Container.

How you setup and use an IoC Container depends on the environment that you’re developing within. For example, if you’re developing an ASP.NET MVC application, you can use an IoC Container to instantiate the controllers, injecting their dependencies via the controller’s constructor. For example, the following two lines of code, within the Global.asax.cs file, instruct the ASP.NET MVC framework to use Castle Windsor to instantiate controllers:

IWindsorContainer container = new WindsorContainer();
ControllerBuilder.Current.SetControllerFactory(
   new WindsorControllerFactory(container));

The only thing left is to register the controller dependencies that they require for their constructors and the IoC Container takes care of the rest.

While this will be enough to gain a basic understanding of what an IoC Container is and how it is used, a bit more studying will be required to learn how to actually set up and use one. For more information about IoC Containers, including examples of setup and usage:

Common Service Locator: http://www.codeplex.com/CommonServiceLocator
Castle Windsor Tutorial: http://www.castleproject.org/container/gettingstarted/
LinFu in 5 Minutes: http://www.codeproject.com/KB/cs/LinFu_IOC.aspx
Using Ninject: http://ninject.codeplex.com/wikipage?title=user%20guide&ProjectName=ninject
StructureMap: http://structuremap.sourceforge.net
A classic IoC Overview: http://martinfowler.com/articles/injection.html
Using IoC in a project: http://wiki.sharparchitecture.net/

Finally, for a much more thorough analysis of many of the concepts described above, I highly recommend reading Robert Martin's Agile Principles, Patterns, and Practices in C#.

Final Thoughts

Regardless of whether you’re looking to take over the world with a dominion of evil robots or simply trying to build a better web app, dependency injection and the use of an IoC Container can lead to an easy to maintain application that is loosely coupled to service dependencies. These attributes naturally lead to better quality and happier developers. (Both of which I would put squarely into a category known as “good.”) But while these techniques provide many benefits, they also introduce a bit more complexity; especially when going from “manual” dependency injection, as we did in the coding example, to the use of an IoC Container. Accordingly, your project team should carefully consider the benefits and added complexity to determine if it's right for your project. While the use of an IoC Container would be a bit overkill for a very simple application, its use is obviously pivotal in creating self-aware robotic legions for conquering the world.

Billy McCafferty
http://wiki.sharparchitecture.net/

The dojo is open... www.ITSamuraiSchool.com

Billy McCafferty — Mon, 18 May 2009 22:52:00 GMT

Codai's IT Samurai School is open for enrollment. It's Flash, so it'll take a few moments to download...but I hope you'll agree it's worth the wait... http://www.itsamuraischool.com

A few fun facts about the website and the school itself:

Born our of a short conversation at a BBQ concerning my desire to do high quality training
100% Flash front-end, outside of the checkout screens
Built on latest S#arp Architecture available from the trunk
6 months in the making, including the site and class preparation
21 classes initially, including ASP.NET MVC, Object-Oriented JavaScript, SQL Server Integration Services, S#arp Architecture and many others
5 cities initially, including Denver, Austin, San Jose, Washington DC, and Seattle
A handful of top notch trainers, including myself (IMHO)
Guest speakers and occasional, one-run only, unique courses

We look forward to seeing you in class!

Billy McCafferty

IT Samurai School coming soon...

Billy McCafferty — Mon, 04 May 2009 02:32:00 GMT

As if my life wasn't boring enough trying to get S#arp Architecture 1.0 out the door...

An argument for moving ASP.NET MVC controllers to a separate assembly

Billy McCafferty — Fri, 09 Jan 2009 19:21:00 GMT

I'd like to buy an argument.

I'm a proponent of isolating application tiers via separate physical assemblies; e.g., MyProject.Core for domain objects and logic vs. MyProject.Web for views. While I do not encounter much push back with this idea, I seem to raise eyebrows with my desire to move ASP.NET MVC controllers to a separate assembly as well. The result of creating separate, physical assemblies for the logical tiers, including the controllers layer, has a number of benefits.

The first and primary reason is that it decreases your ability to shoot yourself in the foot. Let me tell a war story to illustrate. About five years ago I was given the privilege to build the most exciting application of my career thus far. In developing it, we tried to emphasize adding complexity and patterns only while refactoring smells and keeping things as simple as possible (which is almost always the best route to take). We didn't take many prefactoring steps and let the system evolve organically. A painfully learned lesson was putting all of the tiers into one physical assembly and separating them only by namespaces and "team agreement." The major drawback to this was that every layer was technically able to communicate with any other layer, even bi-directionally. (Yes, the most excellent NDepend could assist, but what happens when you have to leave a project in another developer's and/or team's hands for a while?) Inevitably, bi-directional dependencies began to creep into the code. Progressively, the unit tests, for testing the domain layer, started becoming more and more dependent on an up to date test database and working external services; shortcuts began creeping in to the data layer and external services. Accordingly, the unit tests became slower, more fragile, and tedious to maintain. This bleeding of one layer into another had a few ill effects: developers stopped writing and running unit tests (because they were agonizingly slow to run), the application overall became increasingly difficult to maintain and difficult to make modifications without inadvertently affecting various layers simultaneously, and it became almost impossible to upgrade the data layer without touching all of the layers of the application. Yes, I could have done a lot more to prevent some of these problems, both technically and managerially...but I can't say I've learned as much from any other project as well! (A computer science professor of mine once said that you're not an expert until you've made every mistake in the book...that project almost gave me my expert credentials in one fell swoop. Just kidding, I have plenty more mistakes to make. ;)

Some of the other benefits of having physically separated tiers come out of this story as well:

It's helpful for being able to unit test logical tiers in isolation,
It's simple to upgrade your data access layer if only the IoC mechanism depends on it directly,
It's easier to manage a group of developers which can't violate the rules when separated assemblies can only depend on each other in one direction, and
It's easier to understand (aka - maintain) a tier's responsibilities which have been physically separated from other tiers.

Moral of the story: take necessary prefactoring steps to make applications easier to unit test and maintain...and to make it very hard for you to shoot yourself in the foot!

As a working example, due to these reasons, S#arp Architecture projects have a core domain layer which physically cannot have concrete dependencies on the project's data access layer. Likewise, the controllers layer doesn't have a concrete reference to the data layer or to NHibernate. In addition to separating concerns, this physical layout of the layers, and the direction of dependencies, acts as a form of implicit documentation to the developers how the layers should be used. E.g., YourProject.Controllers knows nothing about the implementation details found within YourProject.Data; YourProject.Core has no concrete clue what the persistence mechanism is; and YourProject.Controllers could care less about which IoC mechanism you're using or what static properties Global.asax.cs might be tracking.

Contrastly (is that a word?), moving the controllers layer into the physical web assembly automatically gives it automatic access to all the references that a web project typically has; references such as your IoC implementation, NHibernate and YourProject.Data. Likewise, mashing any other layers together makes it that much easier for a developer to bleed concerns from one layer into another, inadvertently as it may be. Certainly, there's a lot to be said for discipline, team agreement, and tools such as NDepend to make sure your team is following the rules, but I feel it's beneficial to go a bit further to make it that much more difficult to make a mess of things. When considering the wide breadth of skill levels of developers who may ever be touching a project that you're leading, I'd lean towards enforcing a separation of concerns by default, and make it that much harder for developers to void the warranty. ;)

If you'd like to rebut, it's one pound for a five minute argument, but only eight pounds for a course of ten.

Billy McCafferty

Refactoring Service Dependencies to Separated Interface

Billy McCafferty — Fri, 31 Oct 2008 00:06:00 GMT

There are two factors which have a tremendous impact on a team's likelihood to abandon unit testing:

Fragile tests which break often and require regular maintenance; and
Slow tests which add excruciating seconds, if not minutes, to the total time of unit test runs.

I find that fragile tests are often those that depend on data within a database, which can become out of synch with the assertions in the unit test, and those that depend on external services. I use the term "services" loosely to define anything that represents an external resource; examples include web services (including RESTful services), file repositories, databases, and remote procedure calls. But these dependencies on services aren't just bad for keeping unit tests running fast and stable; they can often lead to maintenance problems due to tight coupling. This post presents a common scenario wherein business logic is tightly coupled to a service and provides instruction for refactoring the concrete dependency to a more testable and loosely coupled configuration.

Separated Interface & Motivations for its Inclusion

The design pattern known as "Separated Interface" (coined by Martin Fowler; aka "Dependency Inversion" by Robert Martin) is a technique for reducing coupling to concrete dependencies; it achieves this by coding to the interface of the dependency while maintaining the implementation details of the dependency within a separate application layer. You'll find that the trick of using separated interface, as with any design pattern, is knowing when to use it appropriately, rather than how to use it, as the underlying mechanism is rather straight forward. I find it best to use on most external services, as defined earlier, but should still be considered on a case by case basis. You should ask yourself if introducing Separated Interface will make the overall application more maintainable and testable while keeping complexity to a minimum. When used appropriately, the benefits of this decoupling include:

Improving the ability to unit test "around" the dependency using mocks/stubs,
Greatly increasing the performance of domain oriented unit tests as a side effect of using mocks/stubs,
Consolidating dependency communication details to a separate tier,
Providing a plug-in architecture for external dependencies to be easily swapped without recompiling (e.g., when that 3rd party tool gets upgraded), and
Allowing developers to develop and compile the domain logic without having all the dependencies in place (e.g., not having to install 3rd party tools A, B, and C just to develop and compile unrelated code).

To illustrate, the following diagram shows two separate assemblies within the project solution.

The Project.Core assembly contains all of the domain logic for the application. In addition to domain objects, such as Customer and Order, this example assembly also contains an interface to an external service; in this case, IOrderDao, which represents an interface to a data-access object. Note that this is only the interface of that service; the domain logic has no idea (or dependency) on the underlying implementation details outside of its conformance to the interface.
The Project.Data assembly contains all of the implementation details for the interface and contains an assembly reference back to Project.Core. This is the fundamental key to Separated Interface. In most applications, the data communications and external dependencies are depended on by the business logic. With Separated Interface, the reverse is true wherein the service implementation depends on the interfaces within the domain layer - the true core of the application.

This pattern typically presents two challenges. The first is, how does the domain logic get passed a reference to the actual concrete dependency if all it knows about is an interface? The dependency can get passed to the domain object via its constructor or a setter either manually or with an IoC container, such as Castle Windsor or Ninject. (See http://www.codeproject.com/KB/architecture/DependencyInjection.aspx for an example of doing so.) The second and more challenging problem is, how can we get the external resource to depend on our domain layer interface when it's a third party tool? Recall that we want the service to depend on the domain, not the other way around. In these cases, it's appropriate to create a facade which wraps the complicated details of communicating with the dependency; then, we simply add an interface for the facade to our domain layer. The following example will walk through looking at a real world smell of a concrete dependency on a third party API - exposed as a RESTful service - and making appropriate modifications to introduce Separated Interface.

Real World Example (aka "the smell")

To set the appropriate context, assume that (smelly) code has been developed to fulfill the following user story: On a nightly basis, the application will download any new Observations added during the previous day, input into ExternalApp, so that they may be copied locally. (An "observation" is the domain name of the record we're retrieving.) The idea is that an external application exists, aptly called ExternalApp, which exposes a RESTful service to retrieve newly added records. Our nightly process ties into the service, retrieves the appropriate records, parses the response, and copies the appropriate information locally.

Our application currently has three tiers:

The MySynch.Tests assembly contains unit tests to verify these processes. (No, of course we didn't call it "MySynch," but that'll work for now.)
The MySynch.Core assembly contains all of the business logic for communicating with the RESTful service and processing the results. Assume it contains one object called ObservationMigrator which encapsulates this logic.
The MySynch.Console application which is the nightly process, which we won't concern ourselves with here.

The following unit tests, found in the folder MySynch.Tests/Core, verify that the records can be retrieved and that the data migration is successful:

[TestFixture]
public class ObservationMigratorTests
{
    [Test]
    public void CanRetrieveObservationRecords() {
        ObservationMigrator migrator = new ObservationMigrator();
        IList<Observation> observations = migrator.GetNewObservations();
        Assert.That(observations.Count, Is.GreaterThan(0));
    }
    [Test]
    public void CanMigrateObservationRecords() {
        ObservationMigrator migrator = new ObservationMigrator();
        Result result = migrator.MigrateRecords();
        Assert.That(result.CompletedSuccefully);
    }
}

The first test is really verifying if the communications with the RESTful service - the third party tool - are successful. The second test is verifying if the data migration occurs successfully, assuming the communications with the RESTful service are successful. Without even looking at the underlying code, these tests are already unveiling a number of smells:

It's obvious that the ObservationMigrator isn't adhering to the Single Responsibility Principle (SRP). It's providing means to communicate with the service, via GetNewObservations, and it's responsible for migrating those records to whatever destination. Consequently, it's likely that it's inherently complex and that it's likely to be touched often during maintenance for different reasons.
The second test is really just trying to make sure that the migration occurs successfully without necessarily wanting to retest proper communications to the RESTful service; that was what the first test was doing. The problem with this is that if the service goes down, in addition to breaking the first test, it'll start breaking the second test which is really domain-oriented in nature. It would be great if we could test the migration process without having to retest the communications to the service.
Finally, communicating with any external resource via unit tests, especially web-based services, adds seconds to running the unit tests. This can add minutes with hundreds of unit tests. Again, if all we really want to test in the second test is the domain logic for completing the migration, then we shouldn't be reconfirming communications are working and adding wasted time to running the tests.

Indeed, if we look under the covers at the ObservationMigrator class, we confirm our concerns with respect to SRP and HTTP requests embedded into the business logic:

public class ObservationMigrator
{
    public IList<Observation> GetNewObservations() {
        WebClient webClient = new WebClient();
        byte[] response = webClient
            .DownloadData("http://www.example.com/RESTfulServiceToRetrieveRecords");
        string responseContent = Encoding.ASCII.GetString(response);
        IList<Observation> observations = new List<Observation>();
        // Lots of complicated parsing...like, crazy complicated
        return observations;
    }
    // Result is a DTO which let's the caller know if everything succeeded
    public Result MigrateRecords() {
        IList<Observation> observations = GetNewObservations();
        foreach (Observation observation in observations) {
            // Migrate each observation to the appropriate repository
        }
        return new Result(...);
    }
}

Refactoring Mechanics

In refactoring this code, we'll want to follow the steps below to reduce the amount of work done between tests and to minimize the amount of breaking code in the system at any given point in time. Our goal is to always be very close to a check-in...the "don't anybody check anything out for the next two days" won't fly here.

Refactor with Extract Class to pull the RESTful communication and parsing logic into it's own class. This extracted class becomes the facade to the underlying RESTful API.
Refactor with Extract Interface to create an interface for the new API facade.
Refactor with Introduce Constructor Injection to replace the creation of the dependency with a constructor parameter.
Refactor with Introduce Stub Object to modify the testing of the migration test to focus on the domain logic rather than on retesting communications with the API.
Refactor Architecture by Tiers to move the implementation details to a separate tier.

Step 1: Extract Class

So without further ado, let's start with step 1, extracting a class to act as a facade to the underlying RESTful API. As always, we begin with a test; let's do so by adding a new test as follows:

[TestFixture]
[Category("ExternalApp Integration")]
public class ObservationRetrieverTests
{
    [Test]
    public void CanRetrieveRecordsToImport() {
        ObservationRetriever observationRetriever = new ObservationRetriever();
        IList<Observation> observations = observationRetriever.GetNewObservations();
        Assert.That(observations.Count, Is.GreaterThan(0));
    }
}

Note that we've added this fixture to a category called "ExternalApp Integration." Doing so, we're able to conveniently turn off this slow-running category of unit tests while we're working on other areas of the application. Compiling this breaks, so the next step is to add just enough code to MySynch.Core to get the test to compile:

public class ObservationRetriever
{
    public IList<Observation> GetNewObservations() {
        throw new NotImplementedException();
    }
}

You should now be able to run the test and see it fail with a NotImplementedException. Yes, you want it to fail...a failing test is your next goal to fix. So now let's write enough code to get it to pass by copying the GetNewObservations() method from ObservationMigrator into ObservationRetriever:

public class ObservationRetriever
{
    public IList<Observation> GetNewObservations() {
        WebClient webClient = new WebClient();
        byte[] response = webClient
            .DownloadData("http://www.example.com/RESTfulServiceToRetrieveRecords");
        string responseContent = Encoding.ASCII.GetString(response);
        IList<Observation> observations = new List<Observation>();
        // Lots of complicated parsing...like, crazy complicated
        return observations;
    }
}

All the unit tests should now be passing again. But we've introduced a problem...the smell of duplicated code. We can remove this smell by replacing the ObservationMigrator.GetNewObservations() method with the creation of an ObservationRetriever object and the invocation of the method therein:

public class ObservationMigrator
{
    public Result MigrateRecords() {
        ObservationRetriever observationRetriever = new ObservationRetriever();
        IList<Observation> observations = observationRetriever.GetNewObservations();
        foreach (Observation observation in observations) {
            // Migrate each observation to the appropriate repository
        }
        return new Result(...);
    }
}

You'll need to drop ObservationMigratorTests.CanRetrieveObservationRecords() to get it to compile; but all the tests should still be passing. We've officially completed step 1 by extracting a class from the ObservationMigrator class into a facade class which only concerns itself with communicating with the RESTful API and parsing the results.

Step 2: Extract Interface

Step 2 is introducing the interface to our service. Instead of creating a new test, we simply modify the ObservationRetrieverTests.CanRetrieveRecordsToImport() method to invoke GetNewObservations() via an interface rather than the concrete object itself:

[TestFixture]
[Category("ExternalApp Integration")]
public class ObservationRetrieverTests
{
    [Test]
    public void CanRetrieveRecordsToImport() {
        // Note the "I" that's been introduced below
        IObservationRetriever observationRetriever = new ObservationRetriever();
        IList<Observation> observations = observationRetriever.GetNewObservations();
        Assert.That(observations.Count, Is.GreaterThan(0));
    }
}

Since a quick compilation shows that this isn't compilable (and it shouldn't be), let's add an interface to MySynch.Core which reflects the method on our facade class, and have ObservationRetriever then implement that interface. First, the interface that we need to add to MySynch.Core:

public interface IObservationRetriever
{
    IList<Observation> GetNewObservations();
}

Then, simply have the ObservationRetriever class implement this interface: public class ObservationRetriever : IObservationRetriever { ...

All unit tests should be passing again...oh, happy days again.

Step 3: Introduce Constructor Injection

The ObservationMigrator class still has a concrete dependency on the ObservationRetriever...damn that concrete dependency!! So let's now introduce constructor injection to remove this tight coupling. Guess where we're going to start...that's right, back in a unit test. But here again, we don't need to add a new test, we simply need to alter an existing one, ObservationMigratorTests.CanMigrateObservationRecords(). The modified test should be as follows:

[Test]
public void CanMigrateObservationRecords() {
    IObservationRetriever observationRetriever = new ObservationRetriever();
    ObservationMigrator migrator = new ObservationMigrator(observationRetriever);
    Result result = migrator.MigrateRecords();
    Assert.That(result.CompletedSuccefully);
}

All we're intending to do here is to pass an instance of IObservationRetriever to the migration utility rather than having it create its own. Tying to compile breaks the build, so now let's write just enough code to get this puppy to compile...usually we'd write just enough to compile and then just enough to pass, but I'm getting tired of writing, so we'll combine the two here:

public class ObservationMigrator
{
    public ObservationMigrator(IObservationRetriever observationRetriever) {
        // Let's do a design-by-contract (DbC) check to make sure we're not 
        // given a null service dependency. For more about this, see 
        // http://devlicio.us/blogs/billy_mccafferty/archive/2006/09/22/Design_2D00_by_2D00_Contract_3A00_-A-Practical-Introduction.aspx
        Check.Require(observationRetriever != null, 
            "observationRetriever may not be null");
        this.observationRetriever = observationRetriever;
    }
    public Result MigrateRecords() {
        IList<Observation> observations = observationRetriever.GetNewObservations();
        foreach (Observation observation in observations) {
            // Migrate each observation to the appropriate repository
        }
        return new Result(...);
    }
    private IObservationRetriever observationRetriever;
}

With these changes, everything should now compile and the tests should be passing again.

Step 4: Introduce Stub Object

As mentioned in the previous gripes against the original code, the ObservationMigratorTests.CanMigrateObservationRecords() test shouldn't be worried about communicating with the RESTful service; it should only be concerned with ensuring the migration occurs assuming the RESTful service is working as expected. The ObservationRetrieverTests.CanRetrieveRecordsToImport() test is already verifying that the service is working, so it's just adding extra time and complexity to the ObservationMigratorTests.CanMigrateObservationRecords() test. Therefore, let's now introduce a stub object to simulate communications with the RESTful service. Keep in mind that this modification isn't being done to test new functionality; instead, it's a refactoring to an existing unit test to properly focus the test's attention on the domain logic. Accordingly, the ObservationMigratorTests now reflects the following:

[TestFixture]
public class ObservationMigratorTests
{
    [Test]
    public void CanMigrateObservationRecords() {
        IObservationRetriever observationRetriever = new ObservationRetrieverStub();
        ObservationMigrator migrator = new ObservationMigrator(observationRetriever);
        Result result = migrator.MigrateRecords();
        Assert.That(result.CompletedSuccefully);
    }
    private class ObservationRetrieverStub : IObservationRetriever
    {
        public IList<Observation> GetNewObservations() {
            IList<Observation> observations = new List<Observation>();
            observations.Add(new Observation(...));
            observations.Add(new Observation(...));
            observations.Add(new Observation(...));
            return observations;
        }
    }
}

In the unit test above, a stub object has been created which implements IObservationRetriever and fakes communications with the external service to retrieve three new Observation records. The ObservationMigrator.MigrateRecords() method happily uses this stub, not knowing that it's actually not talking to the external RESTful service. We're now focusing this unit test on testing the domain logic, outside of communicating with the RESTful service. Again, the ObservationRetrieverTests fixture of tests is already testing the communications with this service and related parsing functionality...no need to retest it here.

In such a simple case, where the interface only has one method to implement, a stub is perfectly adequate. But we're passing three observations to the migration step without verifying that all three were processed...we might as well have just passed one, or none at all for that matter. This test could be extended in two ways to verify the underlying migration processed each and every Observation appropriately. The first is that we could include the status of how many observations were migrated within the Result object returned from the migration step. The other way is to use a mock object, instead of a stub, which can verify that the expected behavior is occurring under the scenes. Although mocking is beyond the scope of this post, I encourage you to take a look at http://xunitpatterns.com/ and Rhino Mocks for more information.

Step 5: Refactor Architecture by Tiers
(i.e., add the "Separated" part of "Separated Interface")

After all of this, we're finally at the point of culmination: the introduction of the Separated Interface. But by now, it's rather anticlimactic as the hard work has already been done. Nonetheless...on with the anticlimactic conclusion! A problem with the solution as it stands is that the service facade still physically resides in the MySynch.Core assembly. Consequently, there's nothing we can do to prevent developers from bypassing our elegant interface and go straight to the ObservationRetriever class itself. This is a wonderful side benefit of introducing Separated Interface; it forces developers to adhere to certain design decisions. To mitigate this concern, and to remove all coupling from MySynch.Core to the implementation details of ObservationRetriever, we'll refactor the architecture itself to move the implementation details to a separate tier. Let's head back to the tests assembly and add a new folder called ExternalAppIntegrator; recall that "ExternalApp" is the name of our 3rd party tool which exposes the RESTful service. Now move the ObservationRetrieverTests class to this new folder. This new folder represents the new class library that we'll be introducing. The ObservationRetrieverTests class should then be modified to reflect the change in namespace and a using statement to pull in the class library which we have not yet created (remember...write the test and then write the code to get the test to pass):

using NUnit.Framework;
using NUnit.Framework.SyntaxHelpers;
using System.Collections.Generic;
// The compiler will throw an error on the following line since 
// the ExternalAppIntegrator.Core class library doesn't exist yet
using ExternalAppIntegrator.Core;
namespace Tests.ExternalAppIntegrator.Core
{
    [TestFixture]
    [Category("ExternalApp Integration")]
    public class ObservationRetrieverTests
    {
        [Test]
        public void CanRetrieveRecordsToImport() {
            IObservationRetriever observationRetriever = 
                new ObservationRetriever();
            IList<Observation> observations = 
                observationRetriever.GetNewObservations();
            Assert.That(observations.Count, Is.GreaterThan(0));
        }
    }
}

We've introduced some work for us here, but we will overcome! Firstly, create a new class library called "ExternalAppIntegrator.Core" and add a reference to it from our MySynch.Tests assembly. Next, move the class MySynch.Core/ObservationRetriever.cs to the ExternalAppIntegrator.Core class library...be sure you move it completely by deleting the original. Ack...a new problem now! We've moved the class but it depended upon IObservationRetriever. Fear not! Simply add a reference to MySynch.Core to the ExternalAppIntegrator.Core class library. Since we've removed all other dependencies to the ObservationRetriever from MySynch.Core, all the unit tests will still pass. As a matter of fact, we're done!

But wait, how do we know it's working? Although not necessary, since the unit testing has proven that all of the inner workings are in order, we can make sure our Separated Interface is working as expected with the rest of the migration process by going back to ObservationMigratorTests.CanMigrateObservationRecords() and replacing the creation of the stub object with our concrete implementation: IObservationRetriever observationRetriever = new ObservationRetriever(); With that said, I'd quickly change it back to using the stub so that we can keep that unit test focused on the domain rather than communications with the RESTful service.

In Conclusion

We've taken some rather smelly dependencies and moved them to a dedicated class library which concerns itself with the management of a facade over the external API. We finished by having this facade implement an interface found without our domain layer so that the domain layers could communicate to the external API without having a direct, concrete dependency on the implmentation details. The hope is that this has made our code more testable, less coupled, and more maintainable down the road. The cost has been the introduction of increased complexity. Accordingly, care should be taken before the introduction of any design pattern to ensure that the pattern itself is "pulling its weight," so to speak.

I have found immense value from this design pattern; it has been particularly handy for removing direct dependencies on data access objects. The sample code that comes along with S#arp Architecture has a full example of just such an instance. Happy coding!

Billy McCafferty

S#arp Architecture: a new home, upgrades and a logo!

Billy McCafferty — Fri, 08 Aug 2008 20:19:00 GMT

To facilitate better integration with SVN clients, S#arp Architecture has been moved to Google Code at http://code.google.com/p/sharp-architecture. Additionally, a discussion group has just been setup on Google Groups at http://groups.google.com/group/sharp-architecture to support use of the architecture, discuss the ideas and patterns behind it, offer suggestions for improvement, and exchange ideas for using it in real-world applications.

So why a bonsai tree on the logo? Bonsai trees are small, have years of practice trained into their shape, and have a solid core...all the attributes that I hope S#arp Architecture exhibits. Besides, if they're cool enough for Mr. Miyagi, then the choice is obvious!

By the way, S#arp Architecture 0.7.3 currently supports ASP.NET MVC Preview 4 and NHibernate 2.0 CR 1.

Enjoy!
Billy McCafferty