DD2456 - Laboratory Exercise 1.

Mobile Phone Requirements.

(Last updated 05-05-11)

This series of exercises is designed to take you through the process of

object-oriented requirements analysis.

leading to a set of live sequence charts (LSCs).

This exercise replaces the previous lab exercise on the Security Controller, which has been withdrawn for technical reasons.

It will give you the chance to put into practise the analysis and modelling ideas you have learned on the course. We assume by now that you are familiar with how to use the Play-Engine, by following the tutorial contained in the Play-Engine User Manual.

1. Getting Started

As with the original lab exercise, you will be developing your design solutions to this exercise as a hyper-linked set of web pages,

such as would be suitable to store on a companies intranet, allowing you to share your solution

with business colleagues. Also since your diagrams will be in colour, and you don't have easy access to a colour printer, this is the easiest way to convey your results to me. You will need to have access to a piece of software that can take screen shots and save these in .gif or .jpeg (.jpg) format.

 

To prepare for this lab exercise begin by carrying out the following tasks.

  1. Create a new folder for this lab exercise, you may call it something like "2D1455-lab1".

  2. Within this folder, create an html file, you may call it something like "project1_catalog.html".
    This file will contain the contents page of your lab work. It will name each section, in an
    index, and contain a hyperlink to that section. Each lab exercise will be contained in a
    separate html file.

  3. Add the following text to your catalog file, which includes your personal details for marking:

    2D1455 Laboratory Exercise 1

    Mobile Phone Requirements

    <name of lab partner 1>, <e-mail address of lab partner 1>
    <name of lab partner 2>, <e-mail address of lab partner 2>

    Contents

    1. Requirements Analysis
    <a href= "informal_req.html">Exercise 1.1:</a> Informal Requirements.
    <a href= "data_dictionary.html">Exercise 1.2:</a> Data Dictionary.
    <a href= "use_cases.html">Exercise 1.3:</a> Use Cases.
    <a href= "req_object_model.html">Exercise 1.4:</a> Requirements Object Model.


  4. Since the Play-Engine is Windows based, you will need access to a graphics tool which can take a screen shot of a window and save the result as a JPEG or GIF file. Personally I use Paintshop Pro for this task, but you may find another solution. Currently I know of no other way to export the graphics from the Play-Engine.

  5. Open up the Play-Engine and open the workspace of the mobile phone smaple. You should find this at \Program Files\Play Engine\Samples\Phone\Phone.ews. Open up this workspace and then creata a copy using Save As. You can call the new workspace something like MyPhone.ews. *Important* save your new workspace in the same directory, i.e. \Phone. Otherwise (in my experience) obscure errors can arise. Basically, you are taking a copy at this stage in case you corrupt the orginal files somehow. It is also wise to repeat this practise with new versions of your solution to protect them against corruption too.


  6. You are now ready to begin the laboratory exercises.


 

 

1. Requirements Analysis Phase

1.1. Learning Events

1.2. Introduction to Exercise 1

1.3. The Informal End User Requirements

1.4. Marking up the Informal End-User Requirements

1.5. Creating the Data Dictionary

1.6. Creating the Use Case Model

1.7. Creating the Requirements Object Model


 

1.1. Learning Events

In lab exercise 1 you will learn how to:

  1. identify important O-O requirements components, from an informal requirements document
  2. construct a data dictionary from requirements components
  3. identify actors and use cases and to compile the information into text documents
  4. create a text use case
  5. formalise an LSC use case from a text use case
  6. automatically generate a UML object model using the Play-Engine

 

1.2. Introduction to Exercise 1

In Exercise 1 you will carry out the requirements analysis phase of an O-O design. The aim of the requirements analysis phase is to:

We will guide you through the initial steps of each exercise part. Your task will be to continue and
complete the missing information.

Therefore you should have a clear pattern of work to follow at each stage.


 

1.3. The Informal End User Requirements

Your end user has asked you to produce a requirements analysis for

mobile phone software.

The purpose of this application is to have flexible and upgradeable control of an intelligent microprocessor equipped mobile phone that makes good use of available telecommunications services.


The mobile phone is a clam shell model. On opening the clam shell the antenna extends, and the phone is powered up ready to use. When the clam shell is folded again, the antenna retracts, any current phone activity is abandoned, and any network resources currently used are given up in a safe and timely manner. The phone is powered down to a lower power consumption, but not switched off.

There is a manual power off button for switching off power. If the phone is powered off, it must deregister itself from the base station before total shutdown. The phone will also power off when the battery level reaches zero. In the case of low power, the screen should flash at regular intervals as a warning of low power.

On opening the clam shell, the phone will establish contact with a base station and register its presence with the base station. On closing the clam shell it will maintain registration with the same base station so long as the phone is not powered off. This allows incoming calls to be received.

The most basic functionality of the phone is to make and receive a call.

The phone can receive a call as long as it is registered at a base station and has power. Otherwise, the caller is notified that the number is currently not available. However, the caller can leave a message. The phone will be notified of a waiting message at the base station the next time that power is restored.

If an incoming call is not answered within 5 seconds, the caller is notified that the number is not currently available. The mobile phone must indicate to the user that a call has been missed, and the phone number of the caller should be made available.

The phone can make a call as long as it is registered at a base station and has power. Note that if the reception level falls low, there is a small probability that the mobile phone will lose registration at the base station. Reception level and registration must be restored before any more calls can be made.

To make a call, the user dials the number, that should appear on the screen, and places the call using the send button. When keying in a number, if a mistake is made, the user can clear the screen and start again. The phone must contact the base station. If the network is busy the call cannot be routed and the user should be notified. If the phone destination of the call is busy the user should also be notified.


 

1.4. Creating and Marking up the Informal End-User Requirements

To begin a formal requirements analysis you will need to create an informal end-user requirements text from scratch. The description in 1.3 is quite short (intentionally) and leaves open various questions. You can use the Play-Engine to explore different approaches to filling in any missing information.

By inspecting the current mobile phone GUI (see below) you will have to write more detailed requirements for the address book before you can proceed.

You should perform the following steps.

  1. Cut and paste Section 1.3 into its own html file in your file area. This text should be given a new header "Requirements Summary" You should call your document something like "informal_req.html". You may do this for example using a web browser, by taking the text from the course homepage using the browser "view source" control. (This will save you some retyping.)

  2. Link the file "informal_req.html" to the hyperlink "Exercise 1: Informal Requirements" on the homepage of your project. It is now accessable from the table of contents for your project.

  3. Start up your Play-Engine. Under "File", select "Open Workspace" Wherever the Play-Engine directory is located on your machine (for example on mine it is under "Program Files") open the subdirectory ..\Play Engine\Samples\Phone. Select "Phone.ews" and open this workspace. You should now see something like the following image.


    Phone Workspace



  4. Now click on the clam shell in the mobile phone GUI. It should open up, so that you see something like the following image.


    Phone Workspace


    As you can see, the GUI of this mobile phone is somewhat limited. You can inspect the properties of each GUI component by right clicking on any GUI object in the Project Explorer and selecting "properties". Take your time to familiarise yourself with the existing GUI. Be aware that you can add any new types, internal objects or GUI object attributes or methods that you wish.

  5. Before you start to modify the existing specification, save the current workspace. Under "File", select "Save Workspace As ..". In the pop-up menu enter a filename such as "MyPhone" and save. Now close the workspace "Phone.ews" and open your own workspace "MyPhone.ews". Reopen the clam-shell and continue with inspecting the current interface.

  6. The use of non-digit keys for executing phone functionality is up to you, but we make one suggestion. Notice that the keys "*" and "#" are spare keys that can be used as control keys. On the other hand PWR and CLR seem to have predefined meanings that you should be able to guess.

  7. Write a careful text description of how the mobile phone functions described in 1.3 will work from the end-users point of view, and with reference to the keys used on the keypad. This text may be about 1-2 pages long. Add this text to your file "informal_req.html". You should give the text a title like "Detailed Requirements."

  8. Now carry out a markup exercise on the file "informal_req.html". By reading carefully through the document and marking up every: noun (e.g. digit key, "*"-key ... ), and verb phrase (e.g. click ... ). (In this exercise we will ignore relation phrases e.g. registered with base station.) Markup each kind of concept (e.g. "digit-key") the first time it occurs with hyperlinks (an anchor) <a href= "data_dictionary.html#digit-key"> </a> around the concept or phrase. In the next exercise you will create the file "data_dictionary.html" and place a named anchor <a name="digit-key"></a> in it, after which you will define the concept "digit-key".

  9. Effectively you are marking up all relevant concepts in the informal user requirements document, and linking them to a data dictionary. It is usually not necessary to create a dictionary link more than once (this is distracting for the reader). However, recall that you might find that the same word has different meanings in different contexts. Thus the same word may have different dictionary references in different places of the text. So the occurence of two hyperlinks would make this immediately clear to the designers.

  10. When you have isolated the important requirements concepts you should begin to think through carefully what they mean.

Here is how your document might look after marking up the requirements concepts. (Note: the text below
is not a complete markup as it stands.)

 

'

Requirements Summary

Your end user has asked you to produce a requirements analysis for

mobile phone software.

The purpose of this application is to have flexible and upgradeable control of an intelligent microprocessor equipped mobile phone that makes good use of available telecommunications services.


Detailed Requirements

A <a href= "data_dictionary.html#mobile phone">mobile phone</a> can have three different modes:

  1. <a href= "data_dictionary.html#normal_mode"> normal mode </a> when the clam shell is open
  2. <a href= "data_dictionary.html#power_down_mode"> powered down mode </a> when calls can be received but not made.
  3. <a href= "data_dictionary.html#power_off_mode"> powered off mode </a> when battery supply is zero.

The user switches between these three modes by ....


 

1.5. Creating the Data Dictionary

Now it is time to create a data dictionary. As in lab exercise 1, this is a text document that serves as a reference document for all technical requirements concepts. It provides a common and agreed vocabulary between the end users and the requirements analysists. It is important that non-expert programmers understand the necessary domain knowledge sufficiently well on a project.

 

It is important to:

All the important nouns, relations and verbs that you found in the "Detailed Requirements" section of your file "informal_req.html" in Section 1.4 should be included in the data dictionary.

 

  1. Create a new file called something like "data_dictionary.html".

  2. Link the file "data_dictionary.html" to the hyperlink "Exercise 2: Data Dictionary" on the homepage of your project. It is now accessable from the table of contents for your project.

  3. Create named subsections of the file called: (1) Nouns/Objects, (2) Verb Phrases.

  4. Place each noun and verb phrase found in under the appropriate subsection. Add them in alphabetical order. Add a named anchor e.g. <a name="digit-key"></a> just before the start of the dictionary entry.

  5. Give a text description of the concept, with an appropriate level of detail.

  6. Be prepared to repeat steps 1.4 and 1.5 again later, should you need to add missing concepts, or redefine a concept.

Here is how you entries might look: try to reproduce the entries below without simply copying them.

Data Dictionary

1. Nouns/Objects

<a name="digit_key"></a> Digit-key The mobile phone interface has the digit keys 0 .. 9. In normal mode, these are used to enter digits.

2. Verb Phrases

<a name="click-send-key"></a> Click-send-key - In normal mode, clicking the send key will attempt to place a call to the number currently visible in the phone window.


1.6. Creating the Use Case Model

The aim of the use case model is to capture the requirements and present them from the users point of view, thus making it easier for the end user to validate the correctness of the requirements analysis.

 

The use case model consists of:

There are three different ways to describe a use case:

  1. a text description of the use case using natural language
  2. a graphical description of the use case using an LSC
  3. A combination of both 1 and 2.

Describing a use case using text makes it easier to model exceptions and alternative paths of action sequences. Describing a use case using an LSC will make the use case more formal and easier for validation of the requirement and verification of the subsequent design and implementation.

 

We will develop both text and graphical descriptions of use cases, to explore and compare the two.

 

  1. Start by creating a new file called (something like) "use_cases.html".

  2. Link the file "use_cases.html" to the hyperlink "Exercise 3: Use Cases" on the homepage of your project. It is now accessable from the table of contents for your project.

  3. Create named subsections of the file called: (1) Actor List, (2) Use Case Summary, (3) Text Use Cases (4) LSC Use Cases.

  4. Create the list of actors alphabetically by name, under Actor List. For each actor, describe its responsibilities. You will find actors by studying the informal requirements document of Section 1.3. Important questions to ask are:

    - which users will need services from the system to perform their tasks?

    - which users are needed by the system to perform its tasks?

    - are there any external systems that use, or are being used, by our system?

    In practise, the activity of defining actors should be performed iteratively. try to find as many actors as possible to begin with. If you are not sure you have found them all, start trying to create some LSC use cases. This often forces you into discovering missing actors. Then you can go back and complete the list of actors.

  5. Create a summary of use cases alphabetically under Use Case Summary. Separate the list into two sub-headings "Normal Cases" and "Exceptional Cases". Give each use case a meaningful name, and a brief one sentence description of its functionality. (You will add much more detail shortly.) At this point you just want to distinguish cases easily.

    It is usually easy to identify use cases by looking at the purpose of the system. To verify that you have identified most of the important use cases, you should:

    - look at the list of actors, and for each actor:

    - identify the tasks that the actor should be able to perform and the tasks which the system needs the actor to perform. Each such task is a candidate for a new use case. It is often very useful to check the informal requirements document or the data dictionary for verb phrases. These are possible candidates for use cases.

    For example, starting with with the mobile phone end-user, try to determine which activities he/she needs to perform. There are more or less standard ways to use an address book. Consult your own mobile phone, if you are unsure.

    You should try to make the use cases as complete as possible, i.e. make one complete use case rather than several minor ones.

    When you have found the "normal" use cases, refine them by examining the exceptions that are possible for each use case. Again look in the informal requirements document 1.2 to try to find any exceptions which occur. Notice that this document is not necessarily a complete description. (This is one of the commonest and most difficult problems of requirements analysis. In practise it must be solved iteratively by many discussions with the end user.) Therefore you may have to use your common sense, to "fill in any missing information", if you believe it is missing.

    For example, if a name is restricted to 10 characters, then an exception case is when an 11th character is entered.

  6. Create a list of text use case descriptions ordered alphabetically by use case name (see 5) under Text Use Cases. Each such use case description will give a detailed description of a scenario. A text use case consists of natural language text structured into text fields. These are:

    - Name: the name of the use case according to the Use Case Summary

    - Actors: a complete list of all actors involved in the use case

    - Preconditions: a list of properties or conditions that must be true for this use case to take place

    - Postconditions: a list of properties or conditions that must be true when the use case is finished

    - Description: a text description of the normal sequence of events that describes the interaction between the actors of the system

    - Exceptions: a list of exceptional interactions that complement the normal flow of events described in the Description field. If an exception leads to a different postcondition than the normal sequence of events, then this should be noted.

    The description field should describe what happens when everything takes place as expected (also known as the "sunny day scenario"). The exception field should describe what happens when various things go wrong (also known as the "rainy day scenario"). Thus there should be no overlap between the Description and Exceptions fields. Furthermore, (ideally) they should together cover all possibilities.

  7. Create a list of LSC use case descriptions ordered alphabetically by use case name (see 5) under LSC Use Cases. Each such use case description will give a translation of the informal text use case into the more formal LSC language. An LSC use case makes use of the LSC language notations which you have learned in class.

    You will have to convert each LSC use case drawn using the Play-Engine into .gif or .jpeg format in order to include it into your web pages. One way to achieve this is to use a tool such as Paintshop Pro to take screen shots, and save these in either format, in order to include it them your html files through anchors.

    To draw an LSC for a given text use case, remember that:

    - each actor should be represented by a separate object instance, (timeline).

    - actions, displayed messages, input, outputs, etc should be drawn as LSC messages between the instances.

    - if a use case becomes too long for the page, break it into two or more LSCs and connect these by using some form of vertical composition. You could also add some text which clarifies the relationship between the LSCs.
    The collection of LSCs obtained this way should be pasted close together in your final document for easy reading.

  8. Finally, tidy up the file "use_cases.html", by adding hyperlinks and named anchors which allow you to jump between: (1) every entry in the Use Case Summary, (2) its corresponding entry in the Text Use Cases, (3) its corresponding set of LSC diagrams in the LSC Use Cases, and finally from (3) back to (1) in a cycle. This will dramatically improve the traceability of your document. (Requirements traceability is a major issue in requirements analysis.)

Here is a part of how your document should look when finished:

 

Use Case Document

1. Actor List.

End User: someone who uses the mobile phone to make calls and store information.

2. Use Case Summary.

Normal Cases:

Make a call Describes the interaction necessary to make an outgoing call.

Receive a call Describes the interaction necessary to receive a call.

Exceptional Cases:

Network busy: ...

3. Text Use Cases.

Name: Receive a call

Actors: End User, Base Station,


Precondition The mobile phone is in normal or power down mode or power off mode.

Postcondition ???????.

Description The Base Station ??? ...

Exceptions

(1) If the mobile phone is in power off mode ... ??.

4. LSC Use Cases.

Draw your LSCs for this use case here.


1.7. Creating the Requirements Object Model

The requirements object model is meant to capture:

which are important for the application that is being built. Relations between objects will

be expressed through associations, aggregations and inheritance. In this final part of the exercise you need simply

display the internal object model for the security control system which the Play-Engine automatically creates.

This will help both the examiner and you understand the static structure of your requirements model.

 

  1. Start by creating a new file called (something like) "req_object_model.html".

  2. Link the file "req_object_model.html" to the hyperlink "Exercise 4: Requirements Object Model" on the homepage of your project. It is now accessable from the table of contents for your project.

  3. Produce a .jpg of .gif image of the internal object map produced by the Play-Engine, and embed this image in the page "req_object_model.html".

  4. With reference to the relational phrases defined in your data dictionary. Consider how these could be added as instances of associations within the object diagram. You may use the UML formalism to draw sketch such associations, by hand on a hard copy of the diagram. You can discuss your solutions with the examiner, but you do not need to submit these to complete the exercise.

  5. Congratulations! You have just completed your first substantial exercise using the Play-Engine This calls for a mighty celebration!