End-to-End UML Case Study for a Stock Broker

The problem with many Unified Modeling Language (UML) educational texts is that they present the various concepts each in isolation; so you see a use case diagram for one problem domain, a class diagram for an entirely different problem domain, and you never get to see the important traceability between the diagrams.

In this case study we aim to put it right by working through a single problem from use cases and activity diagrams, through sequence diagrams and state diagrams, to class diagrams and component diagrams. We have arranged the case study as three distinct perspectives or aspects as follows.

The functional aspect: comprising UML use case diagrams and activity diagrams.

The behavioral or dynamic aspect: comprising UML sequence diagrams and a state diagram.

The logical or static aspect: comprising UML class diagrams and a component diagram.

The challenge with any such case study is to find a problem that is sufficiently challenging, sufficiently realistic, yet self-contained and simple enough to present in a single document. We hope to have met this challenge with our presentation of the “Stock Broker” case study. The problem domain should be familiar to most readers while providing sufficient scope for us to explore a range of UML concepts and constructs.

In this section we decompose the problem into a number of ‘functions’ that the system will perform for (and on behalf of) the users of the system; i.e. the actors. Each function will be represented as a UML activity, and will then be further decomposed where appropriate into a number if inter-related UML use cases.

THE ACTIVITY DIAGRAM

So as to keep things manageable yet realistic, in this case study we focus on just two actors who participate in the ‘stock brokerage’ process: the Investor and the Stock Broker. At its simplest level we can visualize the process as two parallel streams (or swim lanes) of activities as shown in the partial activity shown below.

The Investor is able repeatedly to Place [an] Order Instruction to buy or sell shares, with each one of the order instructions being recorded in the Order Book. Separately and in parallel, the Stock Broker repeats the activity to Execute Orders from the Order Book.

It is debatable whether this overarching process is infinite or whether the two parallel streams of activities must at some point be synchronized and must lead to a final activity. This moot point adds little or nothing to our understanding of the process, and we can make best use of our time by moving to the next stage of our analysis: the use case diagram.

THE USE CASE DIAGRAM

In the use case diagram shown below, you can see how the names of our actors – Investor and Stock Broker – mirror the titles of the swim lanes shown on the earlier activity diagram. You can also see how the significant use cases – Place Order Instruction and Execute Orders – tie up with the key activities shown on the activity diagram. Such traceability between UML diagrams is important yet often overlooked.

While the Execute Orders use case may be regarded as somewhat trivial at this point, the Place Order Instruction use case deserves some further explanation in terms of the other use cases it <<uses>> or which <<extend[s]>> it.

Whenever an Investor decides to Place [an] Order Instruction, he (or she) must Select [a] Stock to trade, and this is irrespective of the specific kind of order instruction that will be placed. Therefore, we specify a <<uses>> relationship between the Place Order Instruction and Select Stock use cases.

Stockbrokers typically allow their clients to buy or sell stocks on the following conditions:

• At Best instructs the broker to execute the buy or sell instruction at the next available market price.
• Stop Order instructs the broker to buy when the price rises to a specified level, or to sell (the more common case) when the price falls to a specified level.
• Limit Order instructs the broker to buy when the price falls to a specified level (or immediately if the required buying price can already be achieved), or to sell when the price rises to a specified level (or immediately if the required selling price can already be achieved).

We can think of these variations as extensions – or possibly specializations – of the Place Order Instruction use case; hence their representations as extension use cases in the diagram above.

The Place “Stop Order” Instruction and Place “Limit Order” Instruction extension use cases (but not the Place “At Best” Order extension use case) both require the Investor to specify a target price at which the order should be executed; therefore each of these extension use cases <<uses>> a Specify Target Price use case.

We should stress that this example has been contrived somewhat to show off the <<uses>> and <<extends>> relationships between use cases. While this helps to clarify our understanding, and may be technically “correct”, in some situations it may be considered to be overkill to decompose the use case structure to this extent. Each use case will be described ultimately by a use case specification written in prose, and we should guard against decomposing the functionality to the extent that there are numerous use case specifications with each one containing just a single sentence.

THE USE CASE SPECIFICATIONS

Here we present the written use case specifications using a standardized use case specification template. Notice how certain key terms have been emboldened with a view to these becoming candidate object entities and data items.

USE CASE SPECIFICATION: SELECT STOCK

This use case allows the actor to select a stock from an alphabetical list.

Actor(s)

Investor

Basic Flow

1. Upon being invoked from another use case, the Select Stock use case (controller) displays a list of stocks in alphabetical order.
2. The actor selects a stock.
3. The stock’s unique identifier (stock symbol) is returned to the invoking use case.

Alternative Flow

At step 2, the actor can click the Cancel button, in which case a NULL stock symbol is returned in step 3.

USE CASE SPECIFICATION: PLACE ORDER INSTRUCTION

This use case allows the Investor actor to place an order instruction in the order book, to be executed subsequently by the Stock Broker.

Actor(s)

Investor

Basic Flow

1. The Place Order Instruction use case (Controller) invokes the Select Stock use case (Controller) and receives the stock symbol of the chosen stock.
2. The Order Form is displayed, allowing the actor to enter the number of shares to be bought or sold, to choose whether to buy or sell, and to choose an order type from “At Best”, “Stop Order”, or “Limit Order”.
3. Extension Point (see below)

Alternative Flow

If the actor fails to choose a stock (i.e. a NULL stock symbol is returned in step 1) the use case ends.

Extension #1

If the actor has selected the “At Best” order type in step 2, then step 3 will be replaced by invocation of the Place “At Best” Instruction (extension) use case.

Extension #2

If the actor has selected the “Stop Order” order type in step 2, then step 3 will be replaced by invocation of the Place “Stop Order” Instruction (extension) Use Case.

Extension #3

If the actor has selected the “Limit Order” order type in step 2, then step 3 will be replaced by invocation of the Place “Limit Order” Instruction (extension) use case.

Post-Conditions

Upon completion, a new Order instruction must have been added to the Order Book.

USE CASE SPECIFICATION: PLACE “AT BEST” INSTRUCTION

This extension use case allows the actor to place an “at best” order instruction with the stockbroker. Since no additional actor interaction is required, it is debatable whether a specific (and trivial) extension use case is required rather than simply including this step in the Place Order Instruction main flow. This use case has been included in our case study, both to stimulate such debate and for consistency with the other extension use cases – i.e. each order type has its own extension use case.

Actor(s)

Investor

Basic Flow

1. An At Best order is created.
2. The Order is added to the Order Book.

USE CASE SPECIFICATION: PLACE “STOP ORDER” INSTRUCTION

This extension use case has been factored out to show that it – in common with the “Limit Order” extension detailed below, and unlike the “At Best” extension detailed above -- <<uses>> the functionality provided by the reusable Specify Target Price use case detailed later.

Actor(s)

Investor

Basic Flow

1. The Specify Target Price use case (controller) is invoked and a target price is obtained.
2. A Stop Order is created with the target price.
3. The Order is added to the Order Book.

USE CASE SPECIFICATION: PLACE “LIMIT ORDER” INSTRUCTION

This extension use case has been factored out to show that it – in common with the “Stop Order” extension detailed below, and unlike the “At Best” extension detailed earlier -- <<uses>> the functionality provided by the reusable Specify Target Price use case detailed below.

Actor(s)

Investor

Basic Flow

1. The Specify Target Price use case (controller) is invoked and a target price is obtained.
2. A Limit Order is created with the target price.
3. The Order is added to the Order Book.

USE CASE SPECIFICATION: SPECIFY TARGET PRICE

This reusable use case is invoked by the Place “Stop Order” Instruction and Place “Limit Order” Instruction use cases, and in the future may be invoked by as-yet-unknown use cases that require the actor to enter a ‘target price’.

Note that a use case need not be aware of the other use cases that <<use>> it.

Actor(s)

Investor

Basic Flow

1. When invoked, this use case first displays the Target Price Form with a custom message such as “Enter a Stop Order target price” or “Enter a Limit Order target price”.
2. The actor enters a target price into the form and accepts it.
3. The entered target price is returned to the invoking use case.

USE CASE SPECIFICATION: EXECUTE ORDERS

This use case allows the Stock Broker – which may be a system actor, timer, or process rather than a real person – to run through the Order Book on a periodic basis and execute the outstanding stock trading instructions / orders it contains… if the required price criteria have been reached.

Actor(s)

Stock Broker

Basic Flow

1. For each Order in the Order Book, perform steps 2 and 3.
2. Check that the target price of the Order has been reached, and mark the order as executable*
3. Execute the Order and remove it from the Order Book.

* Note that a non-trivial algorithm or business rule is required here, as detailed in the Special Requirements below.

Special Requirements

In step 2 of the basic flow: not only must the price be crossed in the right direction depending on the type of order (stop order to buy, stop order to sell, limit order to buy, or limit order to sell) but also there may be regulatory requirements or an order execution policy that dictates when an order should or should not be marked for execution. For example, should the order be cancelled rather than executed in the event that the price has ‘gapped’ way beyond the intended execution price? These matters do not affect the basic flow, but do impact the coding of whatever object method is used to implement step 2.

CONCLUSION AND SUMMARY

In this section we have devised a UML activity diagram to represent a simplified version of a typical stock brokerage process; and in doing so we have identified the main actors (Investor and Stock Broker) and their activities (Place Order Instruction and Execute Orders).

We have further decomposed the functionality into a set of UML use cases that are related using the <<uses>> and <<extends>> relationship stereotypes.

For each use case, we have written a use case specification using a standardized template. We have used a range of optional template sections including Alternative Flow, Extension, Post-Conditions and Special Requirements where appropriate.

While some aspects of this case study have been contrived to show off the range of analysis tools at our disposal, it is nonetheless representative of a system that realistically could be implemented… and which we will go some way towards implementing in subsequent sections.

In this section we describe how the system will behave in terms of dynamic events or messages exchanged by business entities and / or software objects (including user interface elements). Whereas use cases are inherently non-object-oriented, the state diagram(s) and sequence diagrams presented here are object-oriented.

UML state diagrams document the non-use-case-specific behavior of certain ‘stateful’ objects, and this behavior must be placed into context by showing how and when those objects engage in such behavior through their participations in use case flows.

THE STATE DIAGRAM(S)

While it is perhaps more usual to draw UML sequence diagrams that realize use cases before drawing state diagrams for individual objects, this is not mandatory. For the purposes of this case study, it is useful for us to present a UML state diagram in the first instance so that in due course we can highlight the important traceability between this diagram and the first of our use case realizations.

We only need to draw state diagrams for entities or objects that have meaningful stateful behavior, and which respond to events in different ways according to their states. The Order Book has meaningful stateful behavior, and it responds to events in different ways according to its states as you can see here…

This state diagram was devised by taking a step back and thinking in a use-case-independent way about how we would expect an Order Book entity or object to behave. We concluded the following:

• The OrderBook can be in Empty state (with no orders awaiting execution) or in Populated state (with pending orders to be executed).
• It should be possible to addOrder to the OrderBook when is it Empty (thus changing its state to Populated), and also to addOrder when it is Populated (thus leaving it in the same state).
• It is only possible to executeOrder when the OrderBook is Populated; at which point we must test the [condition] as to whether we are executing the last order (so that the OrderBook can transition to its Empty state) and in any event we must perform the removeOrder action so that this particular order will not be executed again.

In terms of traceability, this use-case-independent assessment of the Order Book expected behavior has already highlighted a potential correction to our original use case specifications. Since we can only execute orders when the Order Book is Populated, should this not be a pre-condition of the Execute Orders use case specification?

THE USE CASE REALIZATIONS

It is usual to use UML sequence diagrams (or their counterpart collaboration diagrams) to “realize” each use case as a series of object interactions; and so here we present the set of use case realizations for this case study as a collection of sequence diagrams.

Since we have already begun discussing the execution of orders from the order book, let’s begin with the realization of the Execute Orders use case.

“EXECUTE ORDERS” USE CASE REALIZATION

The software architect has told us that each use case will be represented in code by a Controller class, so our realization begins with the StockBroker actor notionally running the ExecuteOrders controller. The remainder of the use case realization follows the use case specification text. Step 1 of the basic flow tells us that steps 2 and 3 will be repeated, and in this case we indicate the repetition using a simple note alongside the executeOrder(orderN) message that we intend will execute the Nth order in the OrderBook. The remaining two steps are to check that the Nth order (let’s refer to it as orderN) isExecutable and to actually execute the Order. According to the use case specification, and the state diagram we drew earlier, we mustn’t forget to removeOrder(orderN) from the OrderBook.

A picture is worth a thousand words, and here is the pictorial representation of the sequence just described.

Notice how we used the name ‘orderN’ in the object lifeline labeled orderN : Order to tie together the specific Order instance with the orderN parameter of the executeOrder and removeOrder messages. We are not merely executing and removing any old order, but specifically the Nth one.

Sequence diagrams are usually kept simple and linear, with little or no use of conditional behavior. In this case, we have shown the scenario in which it is true that the Order isExecutable so that we can execute it. The alternative scenario is trivial and would not normally require an entirely separate sequence diagram, although it would not be wrong to draw one.

In our statement that “According to… and the state diagram we drew earlier, we mustn’t forget to removeOrder(orderN) from the OrderBook” we have already hinted at cross-referencing this sequence diagram against the state diagram from the OrderBook entity. By taking this further we can note that while this use case realization takes account of the executeOrder event and the removeOrder action shown on the state diagram, it does not account for the addOrder event. This is okay because the state diagram is use-case-independent, but it means that at least one of our subsequent use case realizations / sequence diagrams must show the context in which the addOrder event occurs. Let’s find out by sketching out some more use case realizations.

“PLACE ORDER INSTRUCTION” USE CASE REALIZATION

In our case study, the only use case that is initiated directly by the Investor actor is the Place Order Instruction use case that we realize using a sequence diagram as follows. You should see how the interactions reflect the steps of the basic flow within the use case specification.

Important things to note are:

• How, when the SelectStock use case controller is run, we do not see any of the internal workings here because they will be described in a separate use case realization.
• How the stockSymbol that is returned from the Select Stock use case controller is then passed in as a parameter when we display the OrderForm.
• How in this particular scenario we assume that the actor selects the “buy” option and the “Limit” order type when interacting with the OrderForm.
• How it is necessary to pass in the stockSymbol, numberOfShares, and buyOrSell indicator when we run the PlaceLimitOrderInstruction extension use case.

For completeness we could go on to draw (at least) two further realization sequence diagrams to represent the other possible scenarios; the ones in which the actor chooses a different order type leading to EXTENSION #1 or EXTENSION #2. In reality, we – and crucially the software developers – can infer the other realizations from this single model realization.

“SELECT STOCK” USE CASE REALIZATION

The Place Order Instruction use case, just described, < <uses>> the Select Stock use case that is realized by the sequence diagram below. While we see this linkage as the first message in the sequence, we should keep in mind that the reusable Select Stock use case controller might be invoked by other use case controllers in future scenarios.

The sequence proceeds according to the use case specification such that the StockList is displayed, the Investor (in this case) actor selects [a] stock from the list, and the relevant stockSymbol is returned to the SelectStock use case controller which in turn passes it back to the invoking use case.

PLACE “AT BEST” INSTRUCTION USE CASE REALIZATION

The Place “At Best” Instruction (extension) use case realization shown below illustrates once again the important traceability between UML state diagrams and sequence diagrams. It shows the context in which the addOrder message (or event) will be sent to the OrderBook object; this linkage having been unresolved up to this point.

This realization is also useful in helping us to determine what information needs to be passed as parameters in the run(…) operation of the PlaceAtBestInstruction controller and the constructor of the AtBestOrder entity.

PLACE “STOP ORDER” INSTRUCTION USE CASE REALIZATION

The Place “Stop Order” Instruction use case realization differs from the more basic “At Best” realization because it involves the SpecifyTargetPrice use case controller being run, the Investor actor entering a target price (which is returned to the controller), and StopOrder being created with a targetPrice in addition to the same three parameters as the AtBestOrder. Once the Stop Order is created, it is added to the OrderBook in the final step.

As in the “At Best” use case realization, by sending a generic addOrder message to the OrderBook in the final step rather than sending a more specific addStopOrder message, we are already implying that the three different types of orders – AtBestOrder, StopOrder and LimitOrder – may be generalized as an all-encompassing Order type. We will return to this idea when discussing the logical or static aspect of our case study in the next section.

PLACE “LIMIT ORDER” INSTRUCTION USE CASE REALIZATION

The Place Limit Order Instruction use case realization would be almost identical to the Place “Stop Order” Instruction realization, so we have chosen not to draw it in this case study. The only difference is that a LimitOrder instance rather than a StopOrder instance would be created in the penultimate step, but would once again be added to the OrderBook as a generic Order object.

SPECIFY TARGET PRICE USE CASE REALIZATION

The Specify Target Price use case is used by both the Place Stop Order Instruction use case and the Place Limit Order Instruction use case, and the use case realization below includes the PlaceLimitOrderInstruction controller for demonstration purposes.

Challenge for the reader: do you notice anything missing from this diagram? The clue to what is missing is in the first step of the basic flow of the Specify Target Price use case, which was…

1. When invoked, this use case first displays the Target Price Form with a custom message such as “Enter a Stop Order target price” or “Enter a Limit Order target price”.

In a further refinement of this sequence diagram, the analyst should clarify that the display() operation of the TargetPriceForm takes a custom message as a parameter; like this…

display(customMessage)

CONCLUSION AND SUMMARY

In this section we have used UML state diagrams and sequence diagrams to model the behavioral or dynamic aspects of our case study. Most importantly we have highlighted the fact that each event shown on a state diagram must be present on at least one sequence diagram; otherwise there is no context (i.e. scenario) in which the event or message will actually be sent or received. This traceability may be important in helping us to determine if all of the systems functions (i.e. use cases) have been modeled.

The purpose of drawing the use case realizations is to make the important transition from the non-object-oriented world of the process analyst or functional analyst to the object-oriented world of the software development team. UML state diagrams and sequence diagrams may be drawn at various levels of abstraction, with the ultimate aim being to provide a set of artifacts that programmers can use to code the behavioral aspects of the system.

In this section we describe the logical relationships and dependencies between the business entities and other object classes (such as user interface elements) that will implement our software solution. We use UML class diagrams to show which combinations of object classes participate in each use case, and we further use class diagrams to show the static structure and relationships in a use-case-independent way. We use the UML component diagram to show how classes will be packaged for deployment.

THE CLASS DIAGRAM(S)

In the course of devising the use case realizations as sequence diagrams (previous section) we have gained a significant head start in identifying the object classes that the software development team will need to code in order to implement the software solution. We can capitalize on this head start by drawing UML class diagrams known as ‘participating classes’ diagrams as follows – one for each use case realization.

PARTICIPATING CLASSES DIAGRAMS

For each of the use case realizations we can draw a corresponding “participating classes” class diagram to show the static interrelationships between the objects that interact. For the purposes of this case study we will construct a selection of participating class diagrams that complement the more involved (i.e. less trivial) use cases.

These class diagrams are also intended to show off various UML constructs including association, aggregation, dependency and generalization.

“Execute Orders” Participating Classes

Whenever a message is sent from one object to another in a sequence diagram, it implies either a transient dependency (dashed line) or a persistent association (solid line) between the two object classes. In the participating classes diagram below, you can see that the ExecuteOrders controller class is dependent on the OrderBook class to the extent that it cannot function without the second class, but there is no persistent relationship (as might be recorded in a database) between the two classes. In contrast: the OrderBook class is related to the Order class via the strong form of association known as aggregation (shown as a hollow diamond), such that we must record in a database the fact that the OrderBook contains a specific set of Orders.

The multiplicities on the aggregation line indicate that the OrderBook can contain zero or more Orders (i.e. it could be empty) and that each Order can be listed in only one OrderBook.

While constructing this participating classes diagram we have taken the opportunity to add more detail. So whereas the original sequence diagram included an executeOrder message with an un-typed orderN parameter, in the class representation of the OrderBook we have now assigned the parameter the type of int (integer, or whole number) to yield the complete operation signature of executeOrder(in orderN : int).

“Place Stop Order Instruction” Participating Classes

The diagram that follows is the ‘participating classes’ diagram for the Place Stop Order Instruction use case. As well as showing dependency relationships, this diagram also shows a dependency between the specific Stop Order class (mentioned in step 2 of the use case basic flow) and its more generic Order representation (mentioned in step 3). Whereas this generalization relationship was implied in the use case text and the use case sequence diagram, here we formalize it using UML.

We have also used this particular class diagram to illustrate something else. Whereas in the previous class diagram we introduced the notion of including operations within the bodies of classes on a class diagram, on this diagram we have introduced the notion of including attributes. Whereas all stock Order instructions must record a stockSymbol, a numberOfShares, and a buyOrSell indicator, not all order types include the targetPrice attribute that is specific to a StopOrder and – as it happens, and although it is not shown here – a LimitOrder. By default, all of the attributes are prefixed with a minus sign (“-“) to indicate that they are private attributes accessible only from within the Order class.

Our mentioning of the various order classes, and their relationships to the generic StopOrder class, causes us to think about additional class diagrams that show interdependencies and relationships in a use-case-independent context. This is our next theme.

The Missing ‘Participating Classes’ Diagrams

While it would be usual to draw a complete set of ‘participating classes’ diagrams, one per use case, in this case study we have purposefully left out the additional diagrams that would add little or no value from an educational perspective. For example, the class diagram for the Place Limit Order Instruction use case would be practically identical to that of the Place Stop Order Instruction use case.

OTHER CLASS DIAGRAMS

Our use of UML class diagrams need not be limited to ‘participating classes’ diagrams at all. In the two examples that follow, we use class diagrams respectively to clarify the generalization (inheritance) structure of an individual class and to document the interdependencies between user interface classes (controllers and forms) in a use-case-independent context.

Class Diagram for the “Order” class

We already know from the “Execute Orders” participating classes diagram that the OrderBook contains a set of zero or more of Order instances; and we show this again on the following class diagram for the Order class. We already know from the “Place Stop Order Instruction” participating classes diagram that a generic Order class and a more specialized StopOrder class are related through a generalization relationship. Additional ‘participating classes’ diagrams would show the other specializations of the Order class, but none of these diagrams would show all of the Order class specializations in one place as on this diagram:

UI Dependencies Class Diagram

In the following class diagram we provide a useful use-case-independent view of the interconnectedness of the user interface controllers and forms. On this diagram we have chosen to suppress the displaying of each class’s operations and attributes so that the focus is on the interdependencies; and we have done so safe in the knowledge that these operations and attributes have not actually been removed from the underlying UML model.

Notice how the ExecuteOrders use case controller has no dependencies whatsoever on user interface elements. This use case will likely be initiated periodically by a timer or other system actor, and it requires no user interaction.

THE COMPONENT DIAGRAM

In the final phase of this case study we map the object classes onto components for deployment, and we show the dependencies between the deployable components by drawing a UML component diagram like the one that follows.

We have decided to deploy the solution as three distinct components:

An Entities <<library>> component, which may be a .NET assembly DLL or a Java ARchive and which will contain all of the business entities or objects that implement the domain model.

A StockBrokerClient <<executable>> component, which will likely by a Windows .EXE file that will run as a program on the Stockbroker’s desktop computer.

An InvestorWeb component, the exact for of which we have not yet determined using a UML <<stereotype>> but which we suppose will be some kind of packed web application containing the forms and controller classes that implement the Investor use cases.

Although it is not apparent in our component diagram, we have used the UML tool to map the various object classes onto the deployable components according to the following matrix. Each class should be mapped to at least one component, and this matrix helps us determine if there are any gaps in our class-to-component mappings.

Note that this is just one possible scheme for mapping our classes onto components. It would have been perfectly possible to have mapped the order entity classes onto both the InvestorWeb component and the StockBrokerClient component. While this would eliminate the need for the separate Entities component, it would also create a configuration headache (duplicate deployment) and would not lend itself to a typical three-tier deployment.

CONCLUSION AND SUMMARY

In the course of documenting the logical or static aspects of this case study we have demonstrated various uses for UML class diagrams:

• As ‘participating classes’ diagrams; one for each use case.
• To show the generalization (inheritance) structure of a single object class.
• To show the interdependencies between user interface (UI) classes.

This is not an exhaustive list of the uses for class diagrams, but these various uses serve to illustrate the fact that a class diagram is merely a view of the underlying UML model.

We have also documented the mapping of classes onto software components for deployment.

Upon completion of the case study, the development team should now have pretty much all the information they need in order to understand:

• The proposed functionality that they will be developing
• The dynamic behavior of the software objects they will be coding
• The static definitions of the classes and components to be implemented

In a nutshell: the developers now have a clear end-to-end blueprint for development expressed in the industry-standard Unified Modeling Language (UML).

Author: Tony Loton, Author

Tony Loton has authored and co-authored the books “Professional UML with Visual Studio .NET”, “Professional Visual Studio 2005 Team System”, and “UML Software Design with Visual Studio 2010”