Revision as of 01:08, 1 October 2010

Background

My design study is related to my part time job, where I am developing an application that can retrieve and plot data from a device that monitors air quality. The application runs on the user's PC and connects to the device via a USB to serial bridge. The following features of the application/device combination are of interest to this study:

Handling Device Registrations

• When the device is connected to the app, internet connectivity can be used to electronically register the device.
• If a user has problems with registering a device, they can use the app to send an assistance request to the manufacturer.
• Lastly, a user can view the registration details of the current device, if they know the e-mail address the device was registered with.

Handling Device Calibrations

• The application allows the user to calibrate a device using an automated process. Only authenticated users may perform calibrations.
• Further, the manufacturer stores a complete copy of the calibration process, and final calibration parameters.
• Lastly, a device may only be calibrated (new parameters applied) after automated approval. The manufacturer is notified when the new parameters are applied to the device.

All notifications/data exchanges with the manufacturer are via HTTPS POST traffic to a webserver. The focus of this design study is the design of the application-side model for the various requests needed to interact with the server in handling registration and calibration requirements as above. In the initial design, the server request necessary for each of these bullet points is modelled as a class. In the revised design, I look at improving that model by using objects to represent the different requests instead of a class-per-request approach.

Requirements

Practically, for the purposes of my work on the application the requirements are largely generic and as follows:

• something that works
• is as nicely designed as practical
• is as easy to understand and maintain as practical
• is flexible so that new server requests can be added without much hassle

Of course, for the purposes of this design study the goal is additionally to:

• achieve a good balance of flexibility, practicality, and a decent level of adherence to good-OO principles

Deliverables

• Classes that model the different request types
• Classes that allow requests to be sent over the network

Initial Design

I built this design over a short period a few months ago. At the time I had just read a bunch of articles that didn't clearly define the advantages of using composition over inheritance, so I proceeded and made a mess of interfaces/composition and created the following design. It doesn't feel elegant, but it works and is what has been running app-server interactions since. Here I have renamed some of the classes to more general names.

How it Works

Representing Requests

The IRequest interface is the most generic representation of a server request. In the style of HTTP POST/GET requests, a request is defined simply as something which can return a list of name-value pairs (i.e. something that has a GetPOSTParameters() method), representing the request parameters and their names (in particular a .NET 2.0 NameValueCollection). In the context of the application, the children of XRequest define exactly which parameters are required/optional for a particular request and their types.

XRequest is the abstract implementation of IRequest, implementing the shared functionality (send/get response) for all child classes. Each concrete request is then defined by a particular implementation of GetPOSTParameters() method - returning a list with different name-value parameter contents.

The requests represented by the classes in the diagram above are as follows:

• CalibrationAuthReq - represents an authentication request; POST data: username, password, device serial number;
• CalibrationUploadReq - represents an attempt to upload calibration data to the server; POST data: username, password, serial, calibration log-1, calibration log-2, calibration value-1, calibration value-2; This request returns a confirmation code, which must be re-sent to the server to confirm that calibration parameters were applied to a device.
• CalibrationConfirmationReq - represents the request that notifies the server that calibration parameters have been applied to a device. POST data: username, password, serial, calibration confirmation code;
• RegistrationAssistanceReq - the request which submits an assistance request to the server; POST data: user's name, user's phone, user's email, device serial, user notes;
• RegistrationDataReq - used to request the details of an existing registration; POST data: email the device was registered under, device serial;
• RegistrationSubmitReq - used to submit data for registration. POST data: company name, contact name, address, country, email, phone, distributor, distributor phone, serial, user notes;

Sending Requests

Server requests are sent, and responses received using concrete insteances of IRequestSender. HttpPOSTRequestSender is the most generic concrete implementation of this interface - its methods implement the actual sending/receiving mechanisms. XRequestSender is a class with a specific implementation of the IRequestSender interface for the application's purpose. It uses a composition relationship, containing an HttpPOSTRequestSender instance. Functionally, after computing and attaching a checksum to a given IRequest, the class is used to delegate Send/Receive calls to the contained HttpPOSTRequestSender.

Using the classes together

The application creates concrete instances of the request classes, and interacts with them using the Send/GetResponse methods. The individual request objects then interact with the server using supplied instances of IRequestSender (concretely, XRequestSender). The application does not need knowledge of the IRequestSender family of objects, except for creating them and supplying them to request objects. Perhaps a factory method/class could tidy this up slightly.

Design Flaws

At a very superficial glance this does not feel right. The following are the issues & violated heuristics that I can verbalize about the bad feeling:

• Model classes not roles - Many small classes with the same behaviour, just work on different values of the particular data. Better suited as objects.
• Define classes by behavior, not state pattern - Similar point as above. Classes should model behaviour (or an interface) more so than different type of data (state).
• Class hierarchies should be deep and narrow - Possile to have overly specialized classes at few instead of multiple layers of the inheritance hierarchy.
• Lazy class smell - The numerous small classes inheriting from XRequest could be considered lazy. They don't do much extra from the superclass.
• Violates Acyclic dependencies principle, nearly has Circular dependency between IRequestSender and XRequest - from their replationship, it is unclear which actually performs the sending.
• A client consumes the services of the request classes by directly instatiating instances of the concrete classes, because there is no creation mechanism. This violates the Stable abstractions principle and Program to the interface not the implementation, and couples the client to specific derived class implementations. Additionally this also violates Avoid inheritance for implementation - the XRequest class is used only to factor out common functionality for its children.
• Sequential coupling exists in both hierarchies of IRequestSender and IRequest.

Use of Patterns

The use of patterns was very restricted (I didn't have patterns in mind when designing this initial version). The following are roughly present:

• Bridge pattern used to separate interface/implementation dependencies between IRequest and IRequestSender instances.

• A distorted Proxy for composition: XRequestSender is composed of, and forwards most method calls to an HttpPOSTRequestSender, additionally containing (private) methods for calculating & adding a checksum.

Improved Design

With the improved design I tried to produce a more general and more elegant representation for request and the sending system. The approach I took focussed on trying to create a design that reduces many of the flaws listed above. The largest design differences are in:

• The addition of creation mechanisms that decouple a client from having to deal with concrete classes, and maintain the strength of the design's abstractions.
• Moving to a generic Request class to represent behaviour common to all requests, and can be used to represent the different requests as variations in data/state instead of by needing separate classes.

The UML diagram of the revised design follows. ClientApp is a fictituous class I invented to generally summarize the kind of operations the application performs. It is during and as a result of these operations that the classes here are used. In addition, ClientApp shows the dependency replationships between the application and the abstractions of the class model.

Design Diescription

I split up the design in two parts - the transport mechanism, and the modelling the requests to be transmitted through the transport mechanism. This section gives a tour of the design.

Request transport mechanism

Since the requirement is to use HTTP POST requests, the obvious choice was to create a set of better wrappers for the useful components of the .NET Web API than the initial design offered. On a functional level, the original design functioned, so the revised version restructures the structure of the interaction between the required classes. The transport mechanism occupies the left hand side of the UML diagram.

• HttpPOSTRequestSender is the abstract base class for concrete implementations of classes capable of sending POST requests to a server. For our purposes, POST requests are sent through POST query strings forming a chain of name-value pairs. An example query string might be "param1=value1&param2=value2&paramN=valueN". For the purposes of this class, name-value data defining a query string is stored as entries in a NameValueCollection. This is the parameter the Send() method receives, and it returns a boolean indicating whether the POST string was sent successfully. The ReceiveResponse() method represents the means of obtaining the server response to a POST request, and has the most generic return type allowable - an array of bytes containing the response. Thus, the HttpPOSTRequestSender class acts as a base for a generic way of sending HTTP POST query strings to a server.

• BasicSender is the simplest concrete implementation of HttpPOSTRequestSender. It is constructed with a url string which specifies the server location instances will transfer data to/from. It can send any request that is presented as a NameValueCollection as described above.

a NameValue collection (similar to Dictionary<string,string>) which represents a collection of name-value pairs 

Code & Installation

Since my study concerns server requests, testing it out depends on interaction with an actual server/server pages. I've provided a heavily stubbed set of pages that return sample data. A local web-server has to be installed in order to test my design. The code implementation is not 100% complete and I have taken some shortcuts for demo purposes, but most of the expected functionality is there and it largely resembles the UML design above.

Steps:

• Download and install Xampp - http://www.apachefriends.org/en/xampp-windows.html
• Run the Xampp control application (xampp-control.exe) from the install directory
• Ensure the Apache module is running
• Create a directory called "requests" inside xampp_install_dir\htdocs (e.g. C:\xampp\htdocs\requests)
• Copy the php pages from the following archive to the "requests" directory
• The source and VS2008 solution are available in this archive. Open the solution and run the program. The program tries to connect to pages in "http://localhost/requests/", so you must have completed the above steps successfully.